This page is intended to document the different areas where we have to keep an eye on compatibility in spice. Since we can't guarantee that all the parts of spice come from the same source at the same time, we need to be extremely careful about all the interactions between the various parts.
It's generally a work in progress. The hope is to break this out into a more strict set of practices and culture over time.
Our basic goal is to provide backwards compat to at least one previous release of spice. This is to allow for piecemeal upgrading of a cluster of servers and clients running spice. It is very hard to upgrade everything at once, so the goal is to upgrade each individual component and run it in a compat mode for the previous release. Once everything is updated, the admin can switch the epoch across the systems.
For major changes, we should make sure that both versions can be parallel installable, so that you can run an epoch of spice appropriate to the environment.
FIXME: exact mechanism defining the epoch internally here needs documenting in greater detail.
host and client: The wire protocol
Communication between the virtual host and the spice client happens at the wire protocol level. As a principle, it would be good to have as much flexibility as possible, as it is harder to drive an upgrade of clients than hosts/guests.
host and guest: The PCI compat layer
The QXL device is fully backward compatible. The old QXL device has PCI Revision 1, the new QXL device has PCI Revision 2. Both old and new guest drivers should work without problems.
Additionally the QXL device has a compatibility mode. It can be activated using '-global qxl.revision=1' on the qemu command line for upstream qemu. With the compatibility mode activated the new QXL device pretends to be a old QXL device, i.e. it has the PCI revision set to 1 and the vram pci bar (the one for the surfaces) is one page (4k) in size like it used to be with the old QXL device.
Live migration between old QXL device and new QXL device in compatibility mode is supposed to work (both ways). Not implemented yet.
host and host: Live-migration
As a basic principle, we need to define an epoch, or machine type per release. This is used by libvirt to define the capability of that particular release, and is important for determining system compatibility in things like migration. Right now, we expect to be able to piggy back off of the qemu version. So when qemu defines a type of 'pc-0.13', that will imply a certain version of spice and libvirt. Some documentation for this can be found here and here.
client and guest: The user agents
The vdagent protocol between the client and the agent running inside the guest defines an announce capabilities message. Both sides can discover through this message which messages types the other side supports.