Quick start

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//

[edit]

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.

[edit]

Coding Conventions

Lines are 100 chars max, not 80. For the rest see spice_style.pdf.

[edit]

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.

[edit]

Architecture

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.

[edit]

Binaries

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).
spice-html5 - The pure Javascript spice client.

[edit]

Flows

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

[edit]

Code Breakdown

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
- TODO
vdagent - linux
- TODO
qxl driver - windows
- TODO
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().