【Wayland】Wayland协议说明

Wayland基本概念

什么是wayland？

• 它是一种窗口管理协议。简单理解，wayland是一套Display Server与Display Client间通信的协议。Wayland定义了一套标准协议，并规定这套协议中的核心对象（https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces）。

Weston是什么？‘

• Wayland只是一套协议，一套规范。Weston是wayland官网给出的关于Wayland Compositor的一套参考实现。

不深究细节的话，可以稍微简单的把Weston直接理解为，wayland官方给出的，遵循Wayland协议的，一套了窗口管理的组件。

几个概念

• 异步面向对象的协议：wayland中所有的请求，都是对”对象“的方法调用。这里的请求，可以理解为Client对Server端的功能请求。
  
• 基于消息的协议：wayland是基于消息的协议。Server和Client两端间，通过消息交互。Wayland协议规定了消息的固定格式。详细请参考官网 (https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format)
  
  scanner代码生成
• 一般来讲，如果定义了某套协议规范。基本上都会有一套，与之相应的代码生成方式。Wayland协议代码生成，类似于AIDL、FIDL等接口协议。如下图，遵循协议规范的xml文件(文件内容，根据wayland协议接口规范编写)，利用wayland提供的工具，生成对应的源码文件。
  

Wayland协议

• wayland协议在表现上为，一系列Interface的组合。Interface包括Request和Event。
• 一系列的Interface分为两部分，Core和扩展两部分，其中Core为wayland协议规定，必须实现的Interface。
  

协议语义语法

代码生成

• 注意，下述生成的源文件，只是相关的Interface的定义。只是接口的定义，关于接口定义的实现，在另一部分（例如weston）。Interface功能的实现，不在这里介绍。

# 生成Client端文件
./scanner client-header wayland.xml wayland-client-protocol.h
# 生成Server端头文件
./scanner server-header wayland.xml wayland-server-protocol.h
# 生成共同代码
./scanner code  wayland.xml wayland-protocol.c

生成代码部分截取

• wayland-server-protocol.h

@ingroup iface_wl_display										
@struct wl_display_interface										
/										
struct wl_display_interface {		// wl_display +interface						
/**										
asynchronous roundtrip				// 这段注释跟上面xml写的是一样的						
The sync request asks the server to emit the ‘done’ event on										
the returned wl_callback object. Since requests are handled										
in-order and events are delivered in-order, this can be used as										
a barrier to ensure all previous requests and the resulting										
events have been handled.										
The object returned by this request will be destroyed by the										
compositor after the callback is fired and as such the client										
must not attempt to use it after that point.										
The callback_data passed in the callback is the event serial.										
/										
void (*sync)(struct wl_client *client,	// Server端的接口，以函数指针形式定义					
   struct wl_resource *resource,		// client +resource是wayland协议自动补全的					
   uint32_t callback);					// 其实就是类似于C++成员函数里，有一个隐含的this指针形参一样					
/**										
get global registry object										
This request creates a registry object that allows the client										
to list and bind the global objects available from the										
compositor.										
/										
void (*get_registry)(struct wl_client *client,										
       struct wl_resource *resource,										
       uint32_t registry);										
};										
										
										
										
#define WL_DISPLAY_ERROR 0 					// Event(Error)的宏定义					
										
#define WL_DISPLAY_ERROR_SINCE_VERSION  1										
										
										
#ifndef WL_DISPLAY_ERROR_ENUM					// Enmu的定义					
										
#define WL_DISPLAY_ERROR_ENUM										
/**										
										
@ingroup iface_wl_display										
global error values										
These errors are global and can be emitted in response to any										
server request.										
/										
enum wl_display_error {										
/**										
server couldn’t find object										
/										
WL_DISPLAY_ERROR_INVALID_OBJECT = 0,										
/**										
method doesn’t exist on the specified interface										
/										
WL_DISPLAY_ERROR_INVALID_METHOD = 1,										
/**										
server is out of memory										
/										
WL_DISPLAY_ERROR_NO_MEMORY = 2,										
};										
#endif /* WL_DISPLAY_ERROR_ENUM */										
										

• wayland-client-protocol.h

// define WL_DISPLAY_SYNC 0								// 方法定义的宏(OpeID)		
										
										
/**											
@ingroup iface_wl_display										
										
The sync request asks the server to emit the ‘done’ event										
										
on the returned wl_callback object. Since requests are										
										
handled in-order and events are delivered in-order, this can										
										
be used as a barrier to ensure all previous requests and the										
										
resulting events have been handled.										
										
The object returned by this request will be destroyed by the										
										
compositor after the callback is fired and as such the client must not										
										
attempt to use it after that point.										
										
The callback_data passed in the callback is the event serial.										
										
/										
static inline struct wl_callback *										
wl_display_sync(struct wl_display *wl_display)	// Client端 对应的接口										
{										
struct wl_proxy *callback;										
										
callback = wl_proxy_marshal_constructor((struct wl_proxy *) wl_display,										
       WL_DISPLAY_SYNC, &wl_callback_interface, NULL);										
return (struct wl_callback *) callback;										
}										
										
										
										
/**	
										
@ingroup iface_wl_display										
@struct wl_display_listener										
/										
struct wl_display_listener {	// Client端 Event接口								
/**										
fatal error event										
The error event is sent out when a fatal (non-recoverable)										
error has occurred. The object_id argument is the object where										
the error occurred, most often in response to a request to that										
object. The code identifies the error and is defined by the										
object interface. As such, each interface defines its own set of										
error codes. The message is an brief description of the error,										
for (debugging) convenience.										
/										
void (*error)(void *data,										
    struct wl_display *wl_display,										
    void *object_id,										
    uint32_t code,										
    const char *message);										
/**										
acknowledge object ID deletion										
This event is used internally by the object ID management										
logic. When a client deletes an object, the server will send										
this event to acknowledge that it has seen the delete request.										
When the client receive this event, it will know that it can										
safely reuse the object ID.										
/										
void (*delete_id)(void *data,										
    struct wl_display *wl_display,										
    uint32_t id);										
};					

• wayland-protocol.c

”static const struct wl_message wl_display_requests[] = { // request	
{ “sync”, “n”, types + 8 },							
{ “get_registry”, “n”, types + 9 },								
};								
								
static const struct wl_message wl_display_events[] = {	 // event	
{ “error”, “ous”, types + 0 },								
{ “delete_id”, “u”, types + 0 },								
};								
								
WL_EXPORT const struct wl_interface wl_display_interface = { // interface	
“wl_display”, 1,								
2, wl_display_requests,								
2, wl_display_events,								
};