Spice Guest Agent是运行在Guest OS内部的增强spice协议性能的重要组件。主要实现了：鼠标客户端模式，自动调节分辨率，剪切板复制，文件拖拽等重要功能。如果没有dagent程序，那么spice协议体检是无法接受的。
vdgent程序
- 在Linux上使用串口：
/dev/virtio-ports/com.redhat.spice.0 - 在Windows上使用串口：
\\\\.\\Global\\com.redhat.spice.0 - qemu启动参数：
device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 -chardev spicevmc,name=vdagent,id=vdagent -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,name=com.redhat.spice.0
协议头
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方案定义了几个剪贴板选择：
- (1)VD_AGENT_CLIPBOARD_SELECTION_CLIPBOARD: 默认剪贴板，由大多数操作系统实现，以处理显式的复制/粘贴操作。
- (2)VD_AGENT_CLIPBOARD_SELECTION_PRIMARY: PRIMARY剪贴板，用于鼠标选择。
- (3)VD_AGENT_CLIPBOARD_SELECTION_SECONDARY: the SECONDARY clipboard.
以spice client ---> vdagent为例：
- spice client发送VD_AGENT_CLIPBOARD_GRAB消息，告诉spice client数据已经更改。
- vdagent受到VD_AGENT_CLIPBOARD_GRAB消息，将剪切板owner设为spice client，并发送VD_AGENT_CLIPBOARD_REQUEST消息给spice client
- spice client收到D_AGENT_CLIPBOARD_REQUEST消息，发送回包，带：VDagentClipboard结构体数据
- vdagent接收到DagentClipboard结构体，获取剪切板数据，更新guest os的剪切板
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;
