其他分享
首页 > 其他分享> > Spice Vdagent协议

Spice Vdagent协议

作者:互联网

Spice Guest Agent是运行在Guest OS内部的增强spice协议性能的重要组件。主要实现了:鼠标客户端模式,自动调节分辨率,剪切板复制,文件拖拽等重要功能。如果没有dagent程序,那么spice协议体检是无法接受的。

vdgent程序

协议头

1.VDIChunkHeader

vdagent 通过virtio串行端口与spice 服务端连接,可以发送数据到spice服务器和spice客户端,也可以接收它们发过来的数据。VDIChunkHeader作为消息头。

typedef struct SPICE_ATTR_PACKED VDIChunkHeader {
  uint32_t port; //vdagent接收消息时:port是消息来源,dagent发送消息时:port是接收方
  uint32_t size; //size是发送或接收到的数据的大小,包括可变数据部分的大小, size=sizeof(VDAgentMessage)+variable_data_len
} VDIChunkHeader;

元素port的值:

enum {
    VDP_CLIENT_PORT = 1,
    VDP_SERVER_PORT,
};

当要发送的消息是对已接收消息的应答消息,port的值应与已接收到的消息中的port值一致。

当spice server收到一条消息时,会判断VDIChunkHeader中的port数据,来决定是将数据直接发给客户端还是自己进行处理(如果是无效的value则丢弃)。目前还没有来自Agent的消息是针对spice server的,因此所有port值为VDP_SERVER_PORT的消息都会被服务器默默的丢弃。

2.VDAgentMessage

Agent发送或接收到的消息都被封装到一个叫VDAgentMessage的结构体中:

typedef struct SPICE_ATTR_PACKED VDAgentMessage {
  uint32_t protocol; //固定值VD_AGENT_PROTOCOL
  uint32_t type; //消息类型,在一个enum中
  uint64_t opaque; //opaque是消息类型的占位符,只需要将单个整数作为消息数据传递,对于具有更多数据的消息类型,opaque值始终设置为0.
  uint32_t size; // 可变长度数据的大小,值为:sizeof(VDIChunkHeader) + sizeof(VDAgentMessage) + variable_data_len.
  uint8_t data[0]; //可变长度数据的起始地址,可变长度数据的内容取决于数据类型,对于大多数消息,它是一种数据类型特定的结构体,如VDAgentMouseSate。
} VDAgentMessage;

消息类型:即VDAgentMessage的type字段,每个元素代表一条协议

enum {
    VD_AGENT_MOUSE_STATE = 1,
    VD_AGENT_MONITORS_CONFIG,
    VD_AGENT_REPLY,
    VD_AGENT_CLIPBOARD,
    VD_AGENT_DISPLAY_CONFIG,
    VD_AGENT_ANNOUNCE_CAPABILITIES,
    VD_AGENT_CLIPBOARD_GRAB,
    VD_AGENT_CLIPBOARD_REQUEST,
    VD_AGENT_CLIPBOARD_RELEASE,
    VD_AGENT_FILE_XFER_START,
    VD_AGENT_FILE_XFER_STATUS,
    VD_AGENT_FILE_XFER_DATA,
    VD_AGENT_CLIENT_DISCONNECTED,
    VD_AGENT_MAX_CLIPBOARD,
    VD_AGENT_END_MESSAGE,
};

协议详细信息

1.鼠标模式(VD_AGENT_MOUSE_STATE)

spice server ---> vdagent

typedef struct SPICE_ATTR_PACKED VDAgentMouseState {
  uint32_t x;
  uint32_t y;
  uint32_t buttons;
  uint8_t display_id;
} VDAgentMouseState;

spice支持两种鼠标模式,server和client。
在server模式下,QEMU ps/2鼠标仿真用于向客户机(Guest)发送鼠标状态。鼠标进入客户端窗口时候,俘获鼠标,客户端将鼠标移动增量坐标发送到客户机(Guest)。效果极差。
在client模式下,鼠标在显示器中的坐标位置作为绝对值发送给客户机。这需要使用usb表仿真,或将它们发送给vdagent,vdagent将通知客户机操作系统鼠标位置(和按钮单击)。

当鼠标处于client模式时,spice server端通过agent协议VD_AGENT_MOUSE_STATE,发送VDAgentMouseState消息给vdagent,由vagent调整guest os的鼠标位置。

注意:这些消息是由spice server发送的,不是由spice 客户端发送的,因为spice server执行所有的鼠标处理(如在vdagent连接/断开连接时切换client模式或server模式)。

2.显示器配置(VD_AGENT_MONITORS_CONFIG)

spice client ---> vdagent

typedef struct SPICE_ATTR_PACKED VDAgentMonitorsConfig {
  uint32_t num_of_monitors;
  uint32_t flags;
  VDAgentMonConfig monitors[0];
} VDAgentMonitorsConfig

紧跟着该消息后面的是num_of_moniters个以下结构体:

typedef struct SPICE_ATTR_PACKED VDAgentMonConfig {
  uint32_t height;
  uint32_t width;
  uint32_t depth;
  int32_t x;
  int32_t y;
} VDAgentMonConfig;

当客户端以全屏自动配置模式运行时,客户端会将此消息发送给vdagent。此消息包含连接到客户端计算机的显示器的信息。收到此消息后,vdagent应重新配置来宾中qxl vga设备的输出,以尽可能匹配消息中的输出。

当vdagent完成了配置,agent应该返回VD_AGENT_REPLY消息,该消息中的type值设置为VD_AGENT_MONITORS_CONFIG,error值设置为VD_AGENT_SUCCESS或者VD_AGENT_ERROR,以指示配置是成功或是错误。

3.消息应答(VD_AGENT_REPLY)

vdagent ---> spice client

typedef struct SPICE_ATTR_PACKED VDAgentReply {
  uint32_t type;
  uint32_t error;
} VDAgentReply;
其中:error值为:
enum {
  VD_AGENT_SUCCESS = 1,
  VD_AGENT_ERROR,
};

该消息由vdagent发送给client,表示vdagent已经完成了对VD_AGENT_MONITORS_CONFIG 或者 VD_AGENT_DISPLAY_CONFIG消息的处理,以及处理成功还是失败。

4.通知自己支持的功能(VD_AGENT_ANNOUNCE_CAPABILITIES)

spice client ---> vdagent
vdagent ---> spice client
这条协议由spice client和vdagent通知自己支持的功能。此消息的目的是允许不同版本的客户端和vdagent能一起工作。

typedef struct SPICE_ATTR_PACKED VDAgentAnnounceCapabilities {
  uint32_t  request; 
  uint32_t caps[0];
} VDAgentAnnounceCapabilities;

request字段是一个布尔值,指示了信息的接收者是否需要回复一个 VD_AGENT_ANNOUNCE_CAPABILITIES 的信息,因为发送者可能也想知道接收者的capabilities。在最开始发起capabilities交换时这个应该设置为true,当发送一个宣告capabilities作为对所接收到的信息的应答时,该值设置为false。

caps成员是一个可变长度数组的首地址。该数组的长度可以使用VDAgentMessage结构体中的size成员上的VD_AGENT_CAPS_SIZE_FROM_MSG_SIZE 宏来确定。不同capabilities 的索引位于定义在VD_AGENT_CAP 常量的枚举中。并且有VD_AGENT_HAS_CAPABILITY和VD_AGENT_SET_CAPABILITY宏来测试/设置数组中的capability 位。

5. 显示效果优化(VD_AGENT_DISPLAY_CONFIG)

spice client ---> vdagent

typedef struct SPICE_ATTR_PACKED VDAgentDisplayConfig {
  uint32_t flags;
  uint32_t depth;
} VDAgentDisplayConfig;

enum {
  VD_AGENT_DISPLAY_CONFIG_FLAG_DISABLE_WALLPAPER = (1 << 0),
  VD_AGENT_DISPLAY_CONFIG_FLAG_DISABLE_FONT_SMOOTH = (1 << 1),
  VD_AGENT_DISPLAY_CONFIG_FLAG_DISABLE_ANIMATION = (1 << 2),
  VD_AGENT_DISPLAY_CONFIG_FLAG_SET_COLOR_DEPTH = (1 << 3),
};

spice客户端发送给vdagent,来通知vdagent一些特殊性能的相关设置。客户端可以要求vdagent禁用客户机系统的的许多功能,如字体反混叠等,以提高性能。vdagent可以在这些方面做一些努力,尤其是因为大多数设置都是以windows为中心的。应该使用VD_AGENT_REPLY 返回成功状态,除非出现问题。

6.剪切板相关协议

客户机上的agent和客户端起着对称的作用:它们都可以声明拥有权(GRAB),释放拥有权(RELEASE),请求剪贴板数据(REQUEST)以及发送剪贴板数据。当剪贴板清空时,grab信息必须被释放(release)掉。

另一端在grab处于活动状态时可以请求数据,之后会收到对方回复的带有剪贴板信息的CLIPBOARD消息。

剪贴板数据类型如下:

enum {
  VD_AGENT_CLIPBOARD_NONE = 0,
  VD_AGENT_CLIPBOARD_UTF8_TEXT,
  VD_AGENT_CLIPBOARD_IMAGE_PNG,  /* All clients with image support should support this one */
  VD_AGENT_CLIPBOARD_IMAGE_BMP,  /* optional */
  VD_AGENT_CLIPBOARD_IMAGE_TIFF, /* optional */
  VD_AGENT_CLIPBOARD_IMAGE_JPG,  /* optional */
};

如果双方都实现了VD_AGENT_CAP_CLIPBOARD_SELECTION的功能,clipboard信息前面都要带有一个uint8_t的值,指示要操作的clipboard selection。

VD_AGENT_CLIPBOARD
struct VDAgentClipboard {
if VD_AGENT_CAP_CLIPBOARD_SELECTION capability
  uint8_t selection;
  uint8_t __reserved[3];
endif
  uint32_t type; //type值是剪贴板数据类型,即前面剪贴板数据枚举类型中的一个。
  uint8_t data[0]; //可变长度数据的起始地址
};

VD_AGENT_CLIPBOARD 用于发送剪贴板数据。除非接收到VD_AGENT_CLIPBOARD_REQUEST 的数据请求,否则这个数据不会被发送,以避免浪费宽带。被传送的剪贴板数据通常来说都挺大的,在这种情况下,可以预期到,要传送的数据是要分割成多个VD_AGENT_MESSAGE发送的。

VD_AGENT_CLIPBOARD_REQUEST
struct VDAgentClipboardRequest {
if VD_AGENT_CAP_CLIPBOARD_SELECTION capability
  uint8_t selection;
  uint8_t __reserved[3];
endif
  uint32_t type; //剪贴板数据类型,即前面剪贴板数据枚举类型中的一个。
};

请求具有指定类型的剪贴板数据。

VD_AGENT_CLIPBOARD_GRAB
struct VDAgentClipboardGrab {
if VD_AGENT_CAP_CLIPBOARD_SELECTION capability
  uint8_t selection;
  uint8_t __reserved[3];
endif
  uint32_t types[0];
};

抓取剪贴板数据。任何抓取类型的数据请求都应该成功。

VD_AGENT_CLIPBOARD_RELEASE
struct VDAgentClipboardRelease {
if VD_AGENT_CAP_CLIPBOARD_SELECTION capability
  uint8_t selection;
  uint8_t __reserved[3];
endif
};

释放剪贴板。注意:如果一条GRAB信息已被发送并且在当前处于活动状态,然后又从对方那里接收到连续的GRAB信息,这时不应该发送RELEASE信息给对方来取消上一条发过去的grab。因为那条处于活动状态的grab已经被对方暗中释放掉了。如果给对方发送额外的RELEASE信息,只会使对方感到困惑。

VD_AGENT_CAP_CLIPBOARD_SELECTION

当客户端和服务器都具有selection capability,VDAgentClipboard信息必须在前面加上一个uint8_t,该uint8_t指示哪个 clipboard selection 可以操作+3个字节填充以供未来功能或扩展使用。

根据X11 / Gtk方案定义了几个剪贴板选择:

以spice client ---> vdagent为例:

7.文件传输相关协议

spice协议支持把文件从spice client拖拽到虚拟机内部。但是不支持反向操作。

VD_AGENT_FILE_XFER_START
typedef struct SPICE_ATTR_PACKED VDAgentFileXferStartMessage {
   uint32_t id;
   uint8_t data[0];
} VDAgentFileXferStartMessage;

VD_AGENT_FILE_XFER_STATUS

typedef struct SPICE_ATTR_PACKED VDAgentFileXferStatusMessage {
   uint32_t id;
   uint32_t result;
   /* Used to send additional data for detailed error messages
    * to clients with VD_AGENT_CAP_FILE_XFER_DETAILED_ERRORS capability.
    * Type of data varies with the result:
    * result : data type (NULL if no data)
    * VD_AGENT_FILE_XFER_STATUS_NOT_ENOUGH_SPACE : uint64_t
    * VD_AGENT_FILE_XFER_STATUS_SESSION_LOCKED : NULL
    * VD_AGENT_FILE_XFER_STATUS_VDAGENT_NOT_CONNECTED : NULL
    * VD_AGENT_FILE_XFER_STATUS_DISABLED : NULL
    */
   uint8_t data[0];
} VDAgentFileXferStatusMessage;

VD_AGENT_FILE_XFER_DATA

typedef struct SPICE_ATTR_PACKED VDAgentFileXferDataMessage {
   uint32_t id;
   uint64_t size;
   uint8_t data[0];
} VDAgentFileXferDataMessage;

标签:协议,VD,Vdagent,AGENT,uint32,CLIPBOARD,spice,vdagent,Spice
来源: https://blog.51cto.com/14207158/2675202