[Spice-devel] RFC: spice vdagent protocol documentation

[Hans de Goede]

Hi,

Alon, Thanks for the feedback!

On 09/01/2010 04:42 PM, Alon Levy wrote:
>
> ----- "Hans de Goede"<hdegoede at redhat.com>  wrote:
>
>> Hi All,
>>
>> This is a first draft version / a first attempt to document the
>> spice vdagent protocol. This is meant to eventually go to the wiki.
>>
>> Question where on the wiki should I put this?
>>
>> spice vdagent protocol
>> -----------------------
>>
>> For certain features to work spice requires that the guest os is
>> running
>> the spice agent (vdagent). This document describes how vdagent
>> communicates
>> with the spice server and client.
>>
>>
>> 1. vdagent virtio serial port
>> -----------------------------
>>
>> All vdagent communications on the guest side run over a single pipe
>> which
>> gets presented to the guest os as a virtio serial port. Under windows
>> this
>> virtio serial port is identified by the following guid:
>> const GUID GUID_VIOSERIAL_PORT =
>>       {0x6fde7521, 0x1b65, 0x48ae, 0xb6, 0x28, 0x80, 0xbe, 0x62, 0x1,
>> 0x60, 0x26}
>>
>
> With newer drivers there is a symbolic link in windows as well, I think \\\\.\\com.redhat.spice.0,
> we just don't use it in vdservice because it wasn't there before and no one bothered to change it
> back to a simple filename. But the GUID should not be documented.
>

Ok changed to refer to \\\\.\\com.redhat.spice.0

>> Under Linux this virtio serial port has the following name:
>> /dev/virtio-ports/com.redhat.spice.0
>>
>>
>> 2. vdagent data chunks / ports
>> ------------------------------
>>
>> The vdagent is connect through the virtio serial port (vdagent
>> channel) with
>
> There is a confusion in terms here, some due to me not separating the channel
> concept out of the qemu code. Spice has channels which are basically a pipe
> that accepts a specific protocol (all channels share a basic subset of messages too).
> The vdagent doesn't actually have a channel of it's own, it has a number of messages
> that exist in the main channel I think.
>

Ok channel has been replaced with virtio port everywhere.

<snip>

>> 4.5 VD_AGENT_DISPLAY_CONFIG
>>
>> This message gets send by the spice client to the vdagent to notify it
>> of
>> any special performance related settings. The client can ask the
>> vdagent
>> to disable various features of the guest os like font anti aliasing to
>> improve
>> performance. vdagent should do a best effort here, esp. as most
>> settings
>> are rather windows centric and should return a success status using
>> VD_AGENT_REPLY unless something really went wrong.
>>
>
> That's kinda of a currently-we-dont-have-a-linux-vdagent issue, no? I mean,
> wallpaper - not os specific
> color depth - not os specific
> font-smooth - no idea if there is a X equivalent, but could be
> animation - not os specific (of course it becomes one for gnome, one for kde, etc, maybe there is a freedesktop standard way to change this somewhere).
>

Although not os specific it is very much written towards
Windows, also under Linux doing all this is non trivial
as it is desktop environment specific. So we could end up
disabling animations inside gnome apps, while kde apps
run in the same session will happily do animations, etc.

A fixed and wikified version of this doc is now available here:
http://spice-space.org/page/Whiteboard/AgentProtocol

Regards,

Hans