Note: please feel free to fix any error in those pages, since these instructions may be inaccurate, wrong for your platform, or obsolete by code updates. If you need any help or would like to let us know about any error drop us a note at the developer list (spice-devel _AT_ lists.freedesktop.org).
- Building Instructions - from source, for those who want bleeding edge.
- This doesn't include the drivers
- WinQXL - Windows driver building
- TODO - linux driver building. Generally, the sources are at git://anongit.freedesktop.org/xorg/driver/xf86-video-qxl, it's a normal Xorg driver, so you could find building help on http://www.x.org//
Additional building help
- TODO: git rule for coding style patch check. see qemu's and linux's checkpatch.pl
- Smartcard Building Instructions - instructions on building (TODO: a repeat of the main page, should be merged) plus usage instructions for smartcard, both using real hardware (currently tested successfully with CAC, known to not work with AET), and with file based certificates.
Lines are 100 chars max, not 80. For the rest see spice_style.pdf.
Overview of Spice code
The architecture is described fully in spice for newbies.pdf, this is just an overview to get any one interested in developing or just in spice up to speed on the codebase.
To recap, spice is a paravirtual 2d graphics device with both host and client based rendering. It has components at the Guest, the Host and the Client:
- Guest code: qxl driver, vdagent
- Host: qxl device + spice-server, using virtio and chardevs
- Client: spice client.
Graphic drawing in the guest is done using the guest qxl driver. This driver talks to the qxl device exposed by qemu. Then, these qxl drawing commands are fed into the spice-server code which is part of qemu process and runs on the host. Finally, the (possibly remote) spice client talks to the spice-server code and then do the drawing or actions the guest requested.
Other interactions (for example clipboard sharing) between the guest and the client are done in a similar way, except that instead of a qxl device/driver, the communication is done using virtio or chardevs.
spice consists of the following binary components:
- qemu - The primary use of spice is via vms, with qemu, which contains the device emulation. This is the primary use case for Spice.
- spiceqxl_drv.so - This is an xorg driver module. This can be used in a Linxu Guest vm inside of qemu, and it can also be used without qemu as part of a virtual X Server. Together, that last combination is referred to as Xspice.
- libspice-server.so - this is linked with the guest. contains all the rendering and client sockets handling.
- spicec / spicy / vinagre with libspice-client-gtk.so - spice clients (spicec is standalone, the old client, the rest are based on libspice-client-gtk.so, the new client).
The main route is the display:
- Guest driver <->> Host device <->> Host Server <->> Client
The double arrow is to emphasize that most of the communication is from left to right, but it is bidirectional:
- client sends back acks
- host releases guest resources
- server and device are connected with a bi-directional vdi, virtual device interface.
The guest agent data takes a different route:
- Guest vdagent <-> Guest virtio-serial driver <-> Host virtio-serial device <-> spice chardev <-> spice chardev interface <-> spice server <-> client
The various code components:
- qemu: this is the virtual machine emulator. spice is available upstream since qemu 0.14.0. This includes
- hw/qxl.c - the qxl device
- ui/spice* - the implementation of the various vdi interfaces, creating a spice server instance and registering the interfaces
- spice-qemu-char.c - the spice chardev, used for vdagent and smartcard
- hw/*ccid* - smartcard implementation (this is independant of spice but useful in conjunction with it)
- spice repository:
- server - this is the spice server. The server code is non trivial and often difficult to follow. However, this is the heart of the entire infrastructure, particularly the file red_worker.c. The spice server manages all clients, and all of their associated devices and displays.
- common -
- client - this is the old spice client. It is still supported but is being phased out in favor of a new widgetized gtk/glib based implementation called spice-gtk (currently in a separate repository)
- spice-gtk repository:
- this contains the new spice client
- vdagent - windows
- vdagent - linux
- qxl driver - windows
- qxl driver - X (linux)
- src/qxl_driver.c - Is the bulk of the interesting X device driver initialization code.
- src/uxa/* - Is UXA code from Keith Packard's implementation which provides an accelerated graphics architecture for X. This also has the nice side effect of simplifying the X driver code into a very small number of operations, which are all listed in qxl_driver.c/setup_uxa().
Wireshark dissector is merged into Wireshark itself since 1.8 release.
How you can help
We have a list of planned features. Some are in progress, many are not spoken for.