[Spice-commits] 3 commits - AUTHORS cfg.mk docs/images docs/Makefile.am docs/Spice_for_newbies.odt docs/spice_for_newbies.txt docs/Spice_protocol.odt docs/spice_protocol.txt docs/Vd_interfaces.odt docs/vd_interfaces.txt
GitLab Mirror
gitlab-mirror at kemper.freedesktop.org
Fri May 31 14:09:53 UTC 2019
AUTHORS | 1
cfg.mk | 2
dev/null |binary
docs/Makefile.am | 20
docs/images/newbies/a_cmd_flow.png |binary
docs/images/newbies/cli_bsc_stc.png |binary
docs/images/newbies/g_cmd_flow.png |binary
docs/images/newbies/g_sub.png |binary
docs/images/newbies/srv_stc.png |binary
docs/spice_for_newbies.txt | 427 +++++
docs/spice_protocol.txt | 2728 ++++++++++++++++++++++++++++++++++++
docs/vd_interfaces.txt | 643 ++++++++
12 files changed, 3818 insertions(+), 3 deletions(-)
New commits:
commit 6470b537d6598750f7553efed5f25cb59d7c2e49
Author: Thiago Mendes <tribeirom at gmail.com>
Date: Thu Jul 6 17:28:55 2017 -0500
Converting Spice_for_newbies.odt to AsciiDoctor format
https://gitlab.freedesktop.org/spice/spice-server/issues/10
Acked-by: Frediano Ziglio <fziglio at redhat.com>
diff --git a/cfg.mk b/cfg.mk
index efcfaad8..ee291c9e 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -132,7 +132,7 @@ sc_check_author_list:
# XXX some of these tools/ programs probably ought to bindtextdomain ?
exclude_file_name_regexp--sc_bindtextdomain = ^server/tests|common/region.c|tools/(bitmap_to_c.c|icon_to_c.c|reds_stat.c)
-exclude_file_name_regexp--sc_prohibit_empty_lines_at_EOF = docs/.*.odt|server/tests/base_test.ppm|docs/manual/images/.*.png
+exclude_file_name_regexp--sc_prohibit_empty_lines_at_EOF = docs/.*.odt|server/tests/base_test.ppm|docs/manual/images/.*.png|docs/images/newbies/.*.png
exclude_file_name_regexp--sc_unmarked_diagnostics = ^.*\.(c|py|h)
diff --git a/docs/Makefile.am b/docs/Makefile.am
index e7c2b269..15fbbdc0 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -9,6 +9,12 @@ EXTRA_DIST = \
spice_threading_model.txt \
vd_interfaces.txt \
spice_protocol.txt \
+ spice_for_newbies.txt \
+ images/newbies/g_cmd_flow.png \
+ images/newbies/g_sub.png \
+ images/newbies/cli_bsc_stc.png \
+ images/newbies/srv_stc.png \
+ images/newbies/a_cmd_flow.png \
$(NULL)
HTML_FILES = \
@@ -16,6 +22,7 @@ HTML_FILES = \
spice_threading_model.html \
vd_interfaces.html \
spice_protocol.html \
+ spice_for_newbies.html \
$(NULL)
if BUILD_MANUAL
diff --git a/docs/Spice_for_newbies.odt b/docs/Spice_for_newbies.odt
deleted file mode 100644
index 1b05ee69..00000000
Binary files a/docs/Spice_for_newbies.odt and /dev/null differ
diff --git a/docs/images/newbies/a_cmd_flow.png b/docs/images/newbies/a_cmd_flow.png
new file mode 100644
index 00000000..5ce2a275
Binary files /dev/null and b/docs/images/newbies/a_cmd_flow.png differ
diff --git a/docs/images/newbies/cli_bsc_stc.png b/docs/images/newbies/cli_bsc_stc.png
new file mode 100644
index 00000000..4951162b
Binary files /dev/null and b/docs/images/newbies/cli_bsc_stc.png differ
diff --git a/docs/images/newbies/g_cmd_flow.png b/docs/images/newbies/g_cmd_flow.png
new file mode 100644
index 00000000..5c0ecf75
Binary files /dev/null and b/docs/images/newbies/g_cmd_flow.png differ
diff --git a/docs/images/newbies/g_sub.png b/docs/images/newbies/g_sub.png
new file mode 100644
index 00000000..398e856e
Binary files /dev/null and b/docs/images/newbies/g_sub.png differ
diff --git a/docs/images/newbies/srv_stc.png b/docs/images/newbies/srv_stc.png
new file mode 100644
index 00000000..d5c3e4df
Binary files /dev/null and b/docs/images/newbies/srv_stc.png differ
diff --git a/docs/spice_for_newbies.txt b/docs/spice_for_newbies.txt
new file mode 100644
index 00000000..4816babe
--- /dev/null
+++ b/docs/spice_for_newbies.txt
@@ -0,0 +1,427 @@
+= Spice for Newbies: Red Hat, Inc
+:revnumber: v1.0
+:revdate: 01.01.2009
+:revremark: Draft 1
+:imagesdir: ./images/newbies
+
+Copyright (C) 2009 Red Hat, Inc. +
+Licensed under a Creative Commons Attribution-Share Alike 3.0 +
+United States License (see http://creativecommons.org/licenses/by-sa/3.0/us/legalcode). +
+
+:toc:
+
+== Introduction
+
+Spice is an open remote computing solution, providing client access to remote
+machine display and devices (e.g., keyboard, mouse, audio, usb). Spice achieves
+a user experience similar to an interaction with a local machine, while trying
+to offload most of the intensive CPU and GPU tasks to the client. Spice is
+suitable for both LAN and WAN usage, without compromising on the user
+experience.
+
+== Basic Architecture
+
+Spice basic building blocks are the Spice protocol, Spice server and Spice
+client. Spice-related components include the QXL device and guest QXL driver.
+
+. Graphic Commands Flow
++
+[#img-sunset]
+.Graphic Commands Flow
+image::g_cmd_flow.png[align="center"]
++
+The above figure shows the basic Spice architecture and guest-to-client data
+flow of graphic commands, when using libspice with QEMU. libspice can be used by
+any other VDI footnoteref:[svdi,Spice VD Interfaces documentation] compatible
+host application as well. Graphic commands data flow starts by a user
+application requesting the OS graphic engine (X or GDI) to perform a rendering
+operation. The graphic engine passes the commands to the QXL driver, which
+translates the OS commands to QXL commands and pushes them into a command ring.
+The command ring resides in the device memory. libspice pulls the commands from
+the ring and adds them to graphic commands tree. The graphic commands tree
+contains the set of commands, whose execution will reproduce the display
+content. The tree is used by libspice to optimize commands transmission to the
+client by dropping commands hidden by other commands. The commands tree is also
+used for video stream detection. libspice also maintains a queue of commands to
+be sent to the client, for updating its display. When a command is pulled from
+the queue for transmission to the client, it is translated into Spice protocol
+messages. Commands removed from the tree, are removed from the send queue as
+well. When a command is no longer required by libspice, it is pushed into the
+device release ring. The driver uses this ring for releasing commands resources.
+When a client receives a graphic command it uses the command to update the
+display.
++
+. Agent Commands Flow
++
+[#img-sunset]
+.Agent Commands Flow
+image::a_cmd_flow.png[align="center"]
++
+Spice agent is a software module executed in the guest. Spice server and client
+use the agent for tasks that need to be performed in the guest context, such as
+configuring the guest display settings. The figure above shows the Spice client
+and server communication with the agent using VDIPort device and guest driver.
+Messages can be generated by the client (e.g., configuration of the guest
+display settings), the server (e.g., mouse motion), and the agent (e.g.,
+configuration ack). The driver communicates with the device using its input and
+output rings. Client and server generated messages are written to the same write
+queue in the server and are later written to the device output ring. Messages
+are read from the device input ring to the server read buffer. The message port
+determines whether the message should be handled by the server or forwarded to
+the client.
+
+== Spice Client
+
+Spice cross-platform (Linux & Windows) client is the interface for the end user.
+
+. Client Basic Structure
++
+[#img-sunset]
+.Client Basic Structure
+image::cli_bsc_stc.png[align="center"]
++
+. Client Classes
++
+Following is an introduction to the key classes of the Spice client. For having
+a clean cross-platform structure, Spice defines generic interfaces, keeping
+their platform-specific implementation in parallel directories. One such generic
+interface is the Platform class, defining many low-level services such as timer
+and cursor operations.
++
+*Application* is the main class, which contains and controls the client,
+monitors and screens. It handles general application functionality such as
+parsing command line arguments, running the main message loop, handling events
+(connection, disconnection, error, etc.), redirection of mouse events to input
+handler, toggling full screen mode, etc.
++
+.. Channels
++
+The client and server communicate via channels. Each channel type is dedicated
+to a specific type of data. Each channel uses a dedicated TCP socket, and it can
+be secured (using SSL) or unsecured. On the client side each channel has a
+dedicated thread, so different QoS can be given to each one by differentiating
+their thread priority.
++
+*RedClient* serves as the main channel. It owns all the other instantiated channels and controls
+them (creating channels using their factory, connecting, disconnecting, etc.), and handles control,
+configuration and migration (using the Migrate class).
++
+The ancestors of all the channels are:
++
+* RedPeer - socket wrapper for secured and unsecured communication, providing infrastructures such
+ as connect, disconnect, close, send, receive, and socket swapping for migration. It defines
+generic message classes: InMessages, CompoundInMessage and OutMessage. All messages include type,
+size and data.
+* RedChannelBase - inherits RedPeer, provides the basic functionality for establishing channel
+ connectivity with the server and support for channel capability exchange with the server.
+* RedChannel - inherits RedChannelBase. This class is the parent of all instantiated channels.
+ Handles sending outgoing messages and dispatching incoming messages. RedChannel thread runs an
+event loop with various event sources (e.g., send and abort triggers). The channel socket is added
+as an event source for triggering Spice messages sending and receiving.
++
+The available channels are:
++
+* Main - implemented by RedClient (see above).
+* DisplayChannel - handles graphic commands, images and video streams.
+* InputsChannel - keyboard and mouse inputs.
+* CursorChannel - pointer device position, visibility and cursor shape.
+* PlaybackChannel - audio received from the server to be played by the client .
+* RecordChannel - audio captured on the client side.
++
+ChannelFactory is the base class for all channel factories. Each channel registers its specific
+factory for enabling RedClient to create channels by channel type.
++
+.. Screens and Windows
++
+* ScreenLayer - screen layer is attached to specific screen, providing operations on rectangle areas
+ (set, clear, update, invalidate, etc.). Layers are z-ordered (e.g., cursor is above display).
+* RedScreen - implements the screen logic and controls the window, using the screen layers (e.g.,
+ display, cursor) for displaying its content
+* RedDrawable - platform-specific implementation of basic pixmap. It supports basic rendering
+ operations (e.g., copy, blend, combine).
+* RedWindow_p - platform-specific window data and methods.
+* RedWindow - inherits RedDrawable and RedWindow_p. Cross-platform implementation of basic window
+ state and functionality (e.g., show, hide, move, minimize, set title, set cursor etc.).
++
+. Spice Server
++
+Spice server is implemented in libspice, a Virtual Device Interface (VDI) pluggable library. VDI
+provides a standard way to publish interfaces of virtual devices by a software component. This
+enables other software components to interact with these devices. For more information, refer to
+footnoteref:[svdi]. From one side, the server communicates with a remote client using the Spice
+protocol. From the other side, it interacts with the VDI host application (e.g., QEMU).
+For display remoting purposes the server maintains a commands queue and a tree for managing the
+current objects dependencies and hidings. QXL commands are processed and translated to Spice
+protocol commands sent to the client.
+Spice always attempts to pass the rendering tasks to the client, thus leveraging its hardware
+acceleration abilities. Rendering on the host side, by software or GPU, is done as a last result.
+The Spice server keeps guest graphic commands that compose the current image. It releases a command
+only when it is completely covered by other commands and there are no dependencies on it, or when we
+need to render the command to the frame buffer. The two main reasons that trigger drawing to the
+frame buffer are (1) Running out of resources; (2) The guest needs to read from the frame buffer.
++
+.. Server Structure
++
+[#img-sunset]
+.Sever Structure
+image::srv_stc.png[align="center"]
++
+The server communicates with the client via channels. Each channel type is dedicated to a specific
+type of data. Each channel uses a dedicated TCP socket, and it can be secured (using SSL) or
+unsecured. The server channels are analogous of the client channels: Main, Inputs, Display, Cursor,
+Playback, and Record (for more information see Channels 2.3.2.1)
++
+The main and input channels are controlled by handler functions (implemented in reds.c). The display
+and cursor channels are handled by a red worker thread per display. The audio playback and record
+channels have their own handlers (snd_worker.c). Libspice and the VDI host application (e.g. QEMU)
+communicate via interfaces defined for each functionality (e.g., QXL, agent, keyboard, mouse,
+tablet, playback, record), as detailed in footnoteref:[svdi].
++
+As shown in the above figures, spice server consists of the following major components:
++
+... Red Server (reds.c)
++
+The server itself, which listens for client connections, accepts them and communicates with them.
+Reds is responsible for:
++
+* Channels
+** Owns and manages the channels (register, unregister, shutdown)
+** Informs the client about active channels, so that client can create them
+** Main and input channel handling
+** Links establishment (both main and the others)
+** Socket operations and connections management
+* Handles SSL and ticketing
+* VDI interfaces (e.g., core, migration, keyboard, mouse, tablet, agent) addition and removal
+* Migration process coordination
+* Handling of user commands (e.g., from Qemu monitor)
+* Communication with guest agent
+* Statistics
++
+... Graphics subsystem
++
+[#img-sunset]
+.Graphics subsystem
+image::g_sub.png[align="center"]
++
+Unlike other subsystems in Spice server, the graphics subsystem runs in parallel to the server
+execution, on a dedicated thread (i.e, red worker).This structure enables independency between QEMU
+flow and the processing and rendering of incoming graphic commands, which can consume a lot of CPU
+resources. The figure above shows Spice server graphics subsystem structure. Red server initiates a
+dispatcher on a new QXL interface (i.e., VDI). The dispatcher creates red worker for that interface.
+The commands processed by the worker can originate from three sources: (1) Synchronized QXL device
+commands, (2) red server commands, both (1 and 2) delivered by the dispatcher using a socket (i.e.,
+socket pair), (3) asynchronous QXL device commands, pulled by the worker from the QXL device rings
+using the interface.
++
+*_Red Worker (red_worker.c)_*
++
+Spice server holds a different instance of the red worker thread for each QXL device instance. The
+responsibilities of the red_worker are:
++
+* Processing QXL device commands (e.g. draw, update, cursor)
+* Handling messages received from the dispatcher
+* Channel pipes and pipe items
+* Display and cursor channels
+* Image compression (using quic, lz, glzencoding and jpeg)
+* Video streaming - identification, encoding and stream creation
+* Cache - client shared pixmap cache, cursor cache, palette cache
+* Graphic items removal optimization - using item tree, containers, shadows, excluded regions,
+ opaque items
+* Cairo and OpenGL (pbuf and pixmap) renderers - canvas, surfaces etc.
+* Ring operations
+
++
+*_Red Dispatcher (red_dispatcher.c)_*
++
+* Dispatcher, one per QXL device instance
+* Encapsulates the worker internals from the QXL device and reds
+* Initiates a worker for a QXL device instance and creates a worker thread
+* Dispatches the worker using a socketpair channel
+* QXL devices use the QXLWorker interface, implemented and attached by the red dispatcher, which
+ translates the device calls to messages transmitted through the red worker pipe. This way keeps
+the two separated and logically independent.
+* Reds uses the interface defined in red_dispatcher.h for dispatcher functions such as dispatcher
+ initialization, image compression change, video streaming state change, mouse mode setting and
+renderer addition.
++
+. Spice Protocol
++
+Spice protocol is used for client-server communication, i.e., for transferring graphical objects,
+keyboard and mouse events, cursor information, audio playback and record chunks, and control
+commands. Detailed documentation of the Spice protocol can be found in
+footnoteref:[spice_remote,Spice remote computing protocol definition].
++
+. QXL Device
++
+Spice server supports QXL VDI interface. When libspice is used with QEMU, a specific QEMU QXL PCI
+device can be used for improving the remote display performance and enhancing the graphic
+capabilities of the guest graphic system. QXL device requires guest QXL drivers for full
+functionality. However, standard VGA is supported when no driver exists. This mode also enables
+active display from the virtual machine (VM) boot stage. The device interacts with the driver using
+command and cursor rings, interrupts for display and cursor events, and I/O ports. Other
+responsibilities of the device include:
++
+* Initializing and map the device ROM, RAM and VRAM to physical memory
+* Mapping the I/O ports and handle reads and writes for managing: area updates, command and cursor
+ notifications, IRQ updates, mode set, device reset, logging, etc.
+* Rings - initialize and maintain command and cursor rings, get commands and cursor commands from
+ rings and wait for notifications. Maintain resources ring.
+* Communicating with the corresponding red worker using the QXLWorker interface, implemented and
+ attached by red dispatcher, which translates the device calls to messages written to and read from
+the red worker pipe.
+* Registering the QXLInterface for enabling the worker to communicate with the device. The interface
+ includes PCI information and functions for attaching a worker, getting display and cursor commands
+from rings, display and cursor notifications, mode change notification, etc.
+* Defining supported qxl modes and enabling modification of the current mode, including vga mode,
+ where all monitors mirror a single device (vga clients)
+* Handle display initialization, update, resize andrefresh in VGA mode
++
+. QXL Guest Drivers
++
+Platform-specific guest drivers are used to enable and communicate with the QXL device(s). The
+Windows drivers consist of a display driver that works with the graphics device interface (GDI)
+calls and structures, and a miniport driver that handles memory mapping, ports, and interrupts.
++
+. Spice Agent
++
+Spice agent is an optional component for enhancing user experience and performing guest-oriented
+tasks. For example, the agent injects mouse position and state to the guest when using client mouse
+mode. It also enabled copy/paste of text and images between the guest and the client. In addition,
+it is used for configuration of the guest display settings. The agent consists of a system service
+and a user process. There is a windows and a linux implementation.
+
+== Features
+
+. Graphic Commands
++
+Spice supports transmission and handling of 2D graphic commands (3D support is soon to come), as
+opposed to frame buffer updates, which are used in many other remote desktop solutions. The QXL
+device commands are generic and platform-independent, so both Windows and X drivers use them
+natively.
++
+. Hardware Acceleration
++
+The basic Spice client rendering is performed using Cairo, which is a cross-platform,
+device-independent library. Cairo provides vector graphics primitives for 2-dimensional drawing.
+Hardware acceleration is an additional rendering mode in which the rendering is performed on
+hardware by the client GPU and not by software, using the client CPU. Hardware acceleration is
+implemented using OpenGL (experimental) in Linux, and GDI in Windows. . Hardware acceleration
+advantages are:
++
+* High performance rendering - using OpenGL the Spice client is able to render much faster than
+ before. Heavy software operations such as stretching (used by video streaming) are much faster
+when preformed by hardware than by software. Therefore, Spice achieves a much smoother user
+experience.
+* Reducing client CPU usage - the client enjoys more CPU time, which can be used for other tasks
+ like audio.
++
+Unlike Cairo, which is an independent software library, OpenGL is a hardware library that depends on
+the driver and hardware implementation. As a result, Spice might suffer from incorrect rendering,
+heavy CPU usage, or client or host crash in the worst case. In addition, although OpenGL is a
+global standard, the implementation of hardware and drivers changes dramatically between vendors.
+Thus, on different GPUs, Spice might display different rendering output, and different performance
+might be detected. In addition, there are devices which do not support OpenGL at all.
++
+The server also uses OpenGL for hardware acceleration, sharing the same code as the Linux client.
++
+. Image Compression
++
+Spice offers several image compression algorithms, which can be chosen on server initiation, and
+dynamically at run-time. Quic is Spice proprietary image compression utility which is based on the
+SFALIC algorithm footnoteref:[sfalic,Starosolski, R.:
+http://sun.aei.polsl.pl/~rstaros/papers/s2006-spe-sfalic.pdf[Simple Fast and Adaptive Lossless Image
+Compression Algorithm], Software-Practice and Experience, 2007, 37(1):65-91, DOI 10.1002/spe.746.].
+The LZ (LZSS) footnoteref:[lzss,Lempel-Ziv-Storer-Szymanski: “Data compression via textual
+substitution” published in Journal of the ACM (pp. 928-951)] algorithm, adjusted to images, is
+another option. Both Quic and LZ are local algorithms, i.e., they encode each image independently.
+Global LZ (GLZ) is another Spice proprietary, that uses LZ with an history-based global dictionary.
+GLZ takes advantage of repeating patterns among images for shrinking the traffic and save bandwidth,
+which is critical in a WAN environment. Spice also offers an automatic mode for compression
+selection per-image, where the choice between LZ/GLZ and Quic is heuristically based on the image
+properties. Conceptually, artificial images are compressed better by LZ/GLZ, and real images are
+compressed better by Quic.
++
+. Video Compression
++
+Spice uses lossless compression for images sent to the client, and not lossy compression, in order
+to avoid disruption of important display objects . However, since (1) video streams can be major
+consumers of bandwith, as each video frame is an independent image, and (2) their content is mostly
+uncritical, Spice employs lossy video compression for such streams: Spice server heuristically
+identifies video areas by identifying regions that are updated with high rate. These areas updates
+are sent to the client as video streams coded using the loss-prone Motion JPEG algorithm (M-JPEG).
+This mechanism saves a lot of traffic, improving Spice performance, especially in WAN. Nevertheless,
+in some circumstances the heuristic behavior might cause low quality images (e.g., when identifying
+updated text area as a video stream). Video streaming can be chosen on server initiation and can be
+changed dynamically on run-time..
++
+. Caching
++
+Spice implements client image caching in order to avoid redundant transmissions to the client.
+Caching applies to any kind of image data sent to the client, including pixmaps, palettes and
+cursors. Each image arrives from the driver with a unique id and a cache hint. Non-identical images
+have different ids, while identical images share the same id. The cache hint recommends the server
+to cache the image. Pixmap cache is shared among all the displays. Cache is defined per connection
+and synchronized between the server and the client, i.e., in each moment the server knows exactly
+which images are in the client cache. Moreover, the server is the one to decide whether an item
+should be added or removed from the cache. The client cache size is set by the client and
+transferred to the server through the display channel initialization message. The server monitors
+the current cache capacity and when it lacks space it removes the least recently used cache items
+until there is enough available cache space. The server sends an invalidate command with these items
+and the client removes them.
++
+. Mouse Modes
++
+Spice supports two mouse modes, server and client. The mode can change dynamically and is negotiated
+between the client and the server.
++
+* Server mouse - use the QEMU ps/2 mouse emulation for enabling mouse in the guest. Upon user click
+ inside the Spice client window, client mouse is captured and set invisible. The client sends mouse
+moves as delta coordinates to the server. Therefore, client mouse is returned to the window center
+after each move. In this mode, the server controls mouse position on display, so it is always
+synchronized between the client and the guest. However, it might be problematic on WAN or a loaded
+server, where mouse cursor might have some latency or non-responsiveness.
+* Client mouse - client mouse is used as the effective pointing device. It is not captured and guest
+ cursor is set invisible. The client sends mouse moves as absolute coordinates to the server. Guest
+agent scales the coordinates for the guest virtual desktop and injects the appropriate cursor
+position. For a single monitor, client mouse can be used even without an agent if VDI host
+application registers an absolute pointing device (e.g., USB tablet in QEMU). In this case. the
+Spice server scales the coordinates. Client mode is appropriate for WAN or loaded server, since
+cursor has smooth motion and responsiveness. However, the cursor might loss sync (position and
+shape) for a while. The client mouse cursor is updated according to the guest mouse cursor.
++
+. Multiple Monitors
++
+Spice supports any number of monitors, constrained only by the guest, client, and server
+limitations. The number of monitors and their RAM size is set when launching the VM. Spice supports
+automatic configuration of the guest monitors resolution and display settings, according to the
+client machine settings. This is implemented by a client command to the guest agent.
++
+. 2-way Audio and Lip-sync
++
+Spice supports audio playback and recording. Playback is compressed using the CELT
+footnoteref:[celt,http://www.celt-codec.org/[The CELT ultra-low delay audio codec]] algorithm.
+Lip-sync between video and audio is achieved by time-stamping the video frames in the QXL device and
+injecting them in the client side, synchronized with the audio, which is independent.
++
+. Hardware Cursor
++
+The QXL device supports cursor hardware acceleration. Separating the cursor from the display enables
+prioritizing the cursor for better responsiveness. In addition, it reduces the network traffic.
++
+. Live Migration
++
+VM migration between servers is seamless to a connected client. The complete connection state,
+including the open channels and cursor, is saved on the source and restored on the destination.
++
+. WAN optimizations
++
+The server sends an initial ping message to determine latency and bandwidth. If they are worst then
+a threshold, the server tells the guest to reduce guest side features, currently implemented only in
+windows guests, reducing bit depth and disabling animations and wallpaper, and additionally images
+are compressed using lossless jpeg and zlib-glz. If an image is required for another operation such
+as or it is resent in lossless encoding.
++
+. Copy and Paste
++
+When a guest agent is running there is support for copying and pasting text and images in both
+directions between the client and the guest.
commit ddb2795b656a5ebc8f4398173bfbb26ad5d0bf2d
Author: Thiago Mendes <tribeirom at gmail.com>
Date: Mon Jul 10 13:56:18 2017 -0500
Converting Spice_protocol.odt to Asciidoc
https://gitlab.freedesktop.org/spice/spice-server/issues/10
Acked-by: Frediano Ziglio <fziglio at redhat.com>
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 3a04abfc..e7c2b269 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -8,12 +8,14 @@ EXTRA_DIST = \
spice_threading_model.html \
spice_threading_model.txt \
vd_interfaces.txt \
+ spice_protocol.txt \
$(NULL)
HTML_FILES = \
spice_style.html \
spice_threading_model.html \
vd_interfaces.html \
+ spice_protocol.html \
$(NULL)
if BUILD_MANUAL
diff --git a/docs/Spice_protocol.odt b/docs/Spice_protocol.odt
deleted file mode 100644
index 02a17a45..00000000
Binary files a/docs/Spice_protocol.odt and /dev/null differ
diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
new file mode 100644
index 00000000..58bc0166
--- /dev/null
+++ b/docs/spice_protocol.txt
@@ -0,0 +1,2728 @@
+= Spice remote computing protocol definition
+:revnumber: v1.0
+:revdate: 01.01.2009
+:revremark: Draft 1
+
+Copyright (C) 2009 Red Hat, Inc. +
+Licensed under a Creative Commons Attribution-Share Alike 3.0 +
+United States License (see
+http://creativecommons.org/licenses/by-sa/3.0/us/legalcode) +
+
+:toc:
+
+== Introduction
+
+Spice protocol defines a set of protocol messages for accessing, controlling,
+and receiving inputs from remote computing devices (e.g., keyboard, video,
+mouse) across networks, and sending output to them. A controlled device can
+reside on either side, client and/or server. In addition, the protocol defines
+a set of calls for supporting migration of a remote server from one network
+address to another. Encryption of transported data, with one exception, was
+kept out of the protocol for maximum flexibility in choosing an encryption
+method. Spice uses simple messaging and does not depend on any RPC standard or
+a specific transport layer.
+
+Spice communication session is split into multiple communication channels
+(e.g., every channel is a remote device) in order to have the ability to
+control communication and execution of messages according to the channel type
+(e.g. QoS encryption), and to add and remove communication channels during run
+time (which is supported by spice protocol definition). The following
+communication channels are defined in the current protocol definition: a). the
+main channel serves as the main spice session connection b). display channel
+for receiving remote display updates c). inputs channel for sending mouse and
+keyboard events d). cursor channel for receiving pointer shape and position e).
+Playback channel for receiving audio stream, and f). Record channel for sending
+audio capture. More channel types will be added as the protocol evolves. Spice
+also defines a set of protocol definitions for synchronizing channels`
+execution on the remote site.
+
+== Common Protocol definition
+
+. Endianness
++
+Unless stated otherwise, all data structures are packed and byte and bit order
+is in little endian format.
++
+. Data types
++
+.. UINT8 – 8 bits unsigned integer
+.. INT16 – 16 bits signed integer
+.. UINT16 – 16 bits unsigned integer
+.. UINT32 – 32 bits unsigned integer
+.. INT32 - 32 bits signed integer
+.. UINT64 – 64 bits unsigned integer
+.. ADDRESS - 64 bits unsigned integer, value is the offset of the addressed
+data from the beginning of spice protocol message body (i.e., data following
+RedDataHeader or RedSubMessage).
+.. FIXED28_4 – 32 bits fixed point number. 28 high bits are signed integer. Low
+4 bits is unsigned integer numerator of a fraction with denominator 16.
+.. POINT
++
+INT32 x +
+INT32 y +
++
+.. POINT16
++
+INT16 x +
+INT16 y +
++
+.. RECT
++
+INT32 top +
+INT32 left +
+INT32 bottom +
+INT32 right +
++
+.. POINTFIX
++
+FIXED28_4 x +
+FIXED28_4 y +
++
+. Protocol Magic number UINT8[4]
++
+RED_MAGIC = { 0x52, 0x45, 0x44, 0x51}
++
+. Protocol version
++
+Protocol version defined as two UINT32 values, major protocol version and
+minor protocol version. Server and client having the same major version must
+keep compatibility regardless of minor version (i.e., incrementing the major
+version brakes compatibility). Major protocol version with "huge" value are
+reserved for development purposes and are considered unsupported and
+unreliable. "huge" values are defined as having bit 31 set. The minor protocol
+version is incremented on every protocol change that does not break
+compatibility. It is set to zero on major protocol version increment.
++
+.. Current Protocol version
++
+[source,c]
+----
+RED_VERSION_MAJOR = 1
+RED_VERSION_MINOR = 0
+----
++
+. Compatibility – UINT32[]
++
+In order to allow some degree of flexibility in client and server
+implementation and in order to improve compatibility, spice protocol supports
+bidirectional exchange of channels compatibilities. Compatibilities are
+expressed in UINT32 vector that is split into two groups: common
+compatibilities and channels compatibilities. Common compatibilities stands for
+compatibilities shared by all channels, and channels compatibilities stands
+for channel specific compatibilities. Splitting the vector into two types
+allows us to add channel compatibilities independently. Each compatibility is
+expressed using one or more bits in the compatibilities vector.
++
+. Channel types – UINT8
++
+[source,c]
+----
+RED_CHANNEL_MAIN = 1
+RED_CHANNEL_DISPLAY = 2
+RED_CHANNEL_INPUTS = 3
+RED_CHANNEL_CURSOR = 4
+RED_CHANNEL_PLAYBACK = 5
+RED_CHANNEL_RECORD = 6
+----
++
+. Error codes UINT32
++
+[source,c]
+----
+RED_ERROR_OK = 0
+RED_ERROR_ERROR = 1
+RED_ERROR_INVALID_MAGIC = 2
+RED_ERROR_INVALID_DATA = 3
+RED_ERROR_VERSION_MISMATCH = 4
+RED_ERROR_NEED_SECURED = 5
+RED_ERROR_NEED_UNSECURED = 6
+RED_ERROR_PERMISSION_DENIED = 7
+RED_ERROR_BAD_CONNECTION_ID = 8
+RED_ERROR_CHANNEL_NOT_AVAILABLE = 9
+----
++
+. Warning codes
++
+[source,c]
+----
+RED_WARN_GENERAL = 0
+----
++
+. Information codes
++
+[source,c]
+----
+RED_INFO_GENERAL = 0
+----
++
+. public key buffer size.
++
+[source,c]
+----
+RED_TICKET_PUBKEY_BYTES = 162 /* size needed for holding 1024 bit RSA public
+key in X.509 SubjectPublicKeyInfo format. */
+----
++
+. Channel link: establishing a channel connection.
++
+.. Connection process
++
+The channel connection process is initiated by the client. The client sends
+RedLinkMess. In response, the server sends RedLinkReply. When the client
+receives RedLinkReply, it examines the error code and in case there is no
+error it encrypts its password with public key received in RedLinkReply and
+sends it to the server. The server receive the password and sends the link
+result to the client. The client examines the link result, and in case the
+result equals to RED_ERROR_OK, a valid connection is established.
++
+Channel connection for channel types other then RED_CHANNEL_MAIN is allowed
+only after the client has active RED_CHANNEL_MAIN channel connection. Only one
+RED_CHANNEL_MAIN connection is allowed, and this channel connection establishes
+spice session with the remote server.
++
+.. Ticketing
++
+Ticketing is a mechanism implemented in spice to ensure connections are opened
+only from authorized sources. To enable this mechanism a ticket is set in spice
+server consisting of a password and time validity. After time validity passes,
+the whole ticket is expired. The ticket is encrypted. To encrypt, server
+generates a 1024 bit RSA key and send the public part to the client (via
+RedLinkInfo). Client uses this key to encrypt the password and send it back to
+server (after RedLinkMess). Server decrypt the password, compare it to ticket
+and ensure it was received within the allowed time-frame.
++
+.. RedLinkMess definition.
++
+[source,c]
+----
+UINT32 magic
+----
++
+value of this fields must be equal to RED_MAGIC
++
+[cols="2*"]
+|===
+|UINT32 major_version
+| value of this fields must be equal to RED_VERSION_MAJOR
+
+|UINT32 minor_version
+|value of this fields must be equal to RED_VERSION_MINOR
+
+|UINT32 size
+|number of bytes following this field to the end of this message.
+
+|UINT32 connection_id
+|In case of a new session (i.e., channel type is RED_CHANNEL_MAIN) this field
+is set to zero, and in response the server will allocate session id and will
+send it via the RedLinkReply message. In case of all other channel types, this
+field will be equal to the allocated session id.
+
+|UINT8 channel_type
+|one of RED_CHANNEL_?
+
+|UINT8 channel_id
+|channel id to connect to. This enables having multiple channels of the same
+type.
+
+|UINT32 num_common_caps
+|number of common client channel capabilities words
+
+|UINT32 num_channel_caps
+|number of specific client channel capabilities words
+
+|UINT32 caps_offset
+|location of the start of the capabilities vector given by the bytes offset
+from the “ size” member (i.e., from the address of the “connection_id” member).
+|===
++
+.. RedLinkReply definition
++
+[cols="2*"]
+|===
+|UINT32 magic
+|value of this field must be equal to RED_MAGIC
+
+|UINT32 major_version
+|server major protocol version.
+
+|UINT32 minor_version
+|server minor protocol version.
+
+|UINT32 size
+|number of bytes following this field to the end of this message.
+
+|UINT32 error
+|Error codes (i.e., RED_ERROR_?)
+
+|UINT8[RED_TICKET_PUBKEY_BYTES] pub_key
+|1024 bit RSA public key in X.509 SubjectPublicKeyInfo format.
+
+|UINT32 num_common_caps
+|number of common server channel capabilities words
+
+|UINT32 num_channel_caps
+|number of specific server channel capabilities words
+
+|UINT32 caps_offset
+|location of the start of the capabilities vector given by the bytes offset
+from the “ size” member (i.e., from the address of
+the “connection_id” member)
+|===
++
+.. Encrypted Password
++
+Client sends RSA encrypted password, with public key received from server (in
+RedLinkReply). Format is EME-OAEP as described in PKCS#1 v2.0 with SHA-1, MGF1
+and an empty encoding parameter.
++
+.. Link Result UINT32
++
+The server sends link result error code (i.e., RED_ERROR_?)
++
+. Protocol message definition
++
+All messages transmitted after the link stage have a common message layout. It
+begins with RedDataHeader which describes one main message and an optional sub
+messages list.
++
+.. RedDataHeader
++
+[cols="2*"]
+|===
+|UINT64 serial
+|serial number of the message within the channel. Serial numbers start with a
+value of 1 and are incremented on every message transmitted.
+
+|UINT16 type
+|message type can be one that is accepted by all channel (e.g., RED_MIGRATE),
+or specific to a channel type (e.g., RED_DISPLAY_MODE for display channel).
+
+|UINT32 size
+|size of the message body in bytes. In case sub_list (see below) is not zero
+then the actual main message size is sub_list. The message body follows
+RedDataHeader
+
+|UINT32 sub_list
+|optional sub-messages list. If this field is not zero then sub_list is the
+offset in bytes to RedSubMessageList from the end of RedDataHeader. All
+sub-messages need to be executed before the main message, and in the order they
+appear in the sub-messageslist.
+|===
++
+.. RedSubMessageList
++
+[cols="2*"]
+|===
+|UINT16 size
+|number of sub-messages in this list.
+
+|UINT32[] sub_messages
+|array of offsets to sub message, offset is number of bytes from the end of
+RedDataHeader to start of RedSubMessage.
+|===
++
+.. RedSubMessage
++
+[cols="2*"]
+|===
+|UINT16 type
+|message type can be one that is accepted by all channel (e.g., RED_MIGRATE),
+or specific to a channel type (e.g., RED_DISPLAY_MODE for display channel).
+
+|UINT32 size
+|size of the message body in bytes. The message body follows RedSubMessage.
+|===
++
+. Common messages and messaging naming convention
++
+Messages types and message body structures are prefixed according to the
+source of the message. The prefixes for messages sent from the server to the
+client are RED for types and Red for structures. For messages sent from the
+client the prefixes are REDC and Redc.
++
+. Server messages that are common to all channels
++
+[source,c]
+----
+RED_MIGRATE = 1
+RED_MIGRATE_DATA = 2
+RED_SET_ACK = 3
+RED_PING = 4
+RED_WAIT_FOR_CHANNELS = 5
+RED_DISCONNECTING = 6
+RED_NOTIFY = 7
+
+RED_FIRST_AVAIL_MESSAGE = 101
+----
++
+Specific channel server messages start from RED_FIRST_AVAIL_MESSAGE. All
+message types from RED_NOTIFY + 1 to RED_FIRST_AVAIL_MESSAGE – 1 are reserved
+for further use.
++
+. Client messages that are common to all channels
++
+[source,c]
+----
+REDC_ACK_SYNC = 1
+REDC_ACK = 2
+REDC_PONG = 3
+REDC_MIGRATE_FLUSH_MARK = 4
+REDC_MIGRATE_DATA = 5
+REDC_DISCONNECTING = 6
+
+REDC_FIRST_AVAIL_MESSAGE = 101
+----
++
+Specific channel client messages start from REDC_FIRST_AVAIL_MESSAGE. All
+message types from REDC_ACK_SYNC+ 1 to REDC_FIRST_AVAIL_MESSAGE – 1 are
+reserved for further use.
++
+. Messages acknowledgment.
++
+Spice provides a set of messages for requesting an acknowledgment on every one
+or more messages that the client consumes. In order to request acknowledgment
+messages, the server sends RED_SET_ACK with the requested acknowledgment
+frequency – after how many received messages the client sends acknowledgment. .
+In response, the client sends REDC_ACK_SYNC. From this point, for every
+requested number of messages that the client receive, it will send a REDC_ACK
+message.
++
+.. RED_SET_ACK, RedSetAck
++
+[cols="2*"]
+|===
+|UINT32 generation
+|the generation of the acknowledgment sequence. This value will be sent back by
+REDC_ACK_SYNC. It is used for acknowledgment accounting synchronization.
+
+|UINT32 window
+|the window size. Spice client will send acknowledgment for every “window”
+messages. Zero window size will disable messages acknowledgment.
+|===
++
+.. REDC_ACK_SYNC, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|Spice client sends RedSetAck.generation in response to RED_SET_ACK
+|===
++
+.. REDC_ACK, VOID
++
+Spice client sends REDC_ACK message for every RedSetAck.window messages it
+consumes.
++
+. Ping
++
+Spice protocol provides ping messages for debugging purpose. Spice server sends
+RED_PING and the client responses with REDC_PONG. The server can measure round
+trip time by subtracting current time with the time that is returned in
+REDC_PONG message.
++
+.. RED_PING, RedPing
++
+[cols="2*"]
+|===
+|UINT32 id
+|the id of this message
+
+|UINT64 time
+|time stamp of this message
+|===
++
+.. REDC_PONG, RedPong
++
+[cols="2*"]
+|===
+|UINT32 id
+|Spice client copies it from RedPing.id
+
+|UINT64 time
+|Spice client copies it from RedPing.time
+|===
++
+. Channel migration
++
+Spice supports migration of Spice server. The following common messages
+combined with specific main channel messages is used for migrating channels
+connections between spice servers. We will refer these servers as source and
+destination. Main channel is used for initiating and controlling the migration
+process. The following describes the actual channel migration process.
++
+Channel migration process starts with sending RED_MIGRATE message from the
+server. The client receives the message, examine the attached flags and: if the
+server requests messages flush (i.e., RED_MIGRATE_NEED_FLUSH flag is on), the
+client sends REDC_MIGRATE_FLUSH_MARK message to the server. This procedure can
+be used to ensure safe delivery of all mid air messages before performing the
+migration action. if the server requests data transfer (i.e.,
+RED_MIGRATE_NEED_DATA_TRANSFER flag is on), the client expects to receive one
+last message from the server before migrating to destination. This message type
+must be RED_MIGRATE_DATA type. The content of the received message will be
+transmitted to the destination on connection swap.
++
+Afterward, the client swaps communication channels (i.e., starts using the
+connection with the destination server). The client can close connection with
+the source server only after all other channels also have finished the
+migration process. If the server side has requested data transfer, the client
+first transmits REDC_MIGRATE_DATA message containing the data received on
+RED_MIGRATE_DATA.
++
+.. Migration flags
++
+[source,c]
+----
+RED_MIGRATE_NEED_FLUSH = 1
+RED_MIGRATE_NEED_DATA_TRANSFER = 2
+----
++
+.. RED_MIGRATE, RedMigrate
++
+[cols="2*"]
+|===
+|UINT32 flags
+|combination of red migration flags.
+|===
++
+... RED_MIGRATE_DATA, UINT8[]
++
+Server migrate data, body of this message is variable length raw data that is
+determined by each channel type independently
++
+... REDC_MIGRATE_FLUSH_MARK, VOID
++
+This messages mark completion of client communication channel flushing.
++
+.. REDC_MIGRATE_DATA, UINT8[]
++
+Post migration data, sent by client to the destination, containing the data
+sent by the source using the RED_MIGRATE_DATA message.
++
+[[channel_sync]]
+. Channel synchronization
++
+Spice provides mechanism for synchronizing channels message execution on the
+client side. The server sends RED_WAIT_FOR_CHANNELS message which contains a
+list of channels messages to wait for (i.e., RedWaitForChannels). The Spice
+client will wait for completion of all the messages that are in that list
+before executing any more messages.
++
+.. RedWaitForChannel
++
+[cols="2*"]
+|===
+|UINT8 type
+|channel type (e.g., RED_CHANNEL_INPUTS)
+
+|UINT8 id
+|channel id.
+
+|UIN64 serial
+|message serial id (i.e, RedDataHeader.serial) to wait for
+|===
++
+... RED_WAIT_FOR_CHANNELS, RedWaitForChannels
++
+[cols="2*"]
+|===
+|UINT8 wait_count
+|number of items in wait_list
+
+|RedWaitForChannel[] wait_list
+|list of channels to wait for.
+|===
++
+. Disconnect reason
++
+The following messages are used for notification about orderly disconnection
+of the server or client.
++
+.. RED_DISCONNECTING, RedDisconnect
++
+[cols="2*"]
+|===
+|UINT64 time_stamp
+|time stamp of disconnect action on the server.
+
+|UINT32 reason
+|disconnect reason, RED_ERROR_?
+|===
++
+.. REDC_DISCONNECTING, RedcDisconnect
++
+[cols="2*"]
+|===
+|UINT64 time_stamp
+|time stamp of disconnect action on the client.
+
+|UINT32 reason
+|disconnect reason, RED_ERROR_?
+|===
++
+. Server notification
++
+Spice protocol defines message for delivering notifications to the client using
+RED_NOTIFY message. Messages are categorized by severity and visibility. The
+later can be used as hint for the way the message is displayed to the user. For
+example high visibility notifications will trigger message box and low
+visibility notifications will be directed to the log.
++
+.. RED_NOTIFY, RedNotify
++
+[cols="2*"]
+|===
+|UINT64 time_stamp
+|server side time stamp of this message.
+
+|UINT32 severity
+|one of RED_NOTIFY_SEVERITY_?
+
+|UINT32 visibility
+|one of RED_NOTIFY_VISIBILITY_?
+
+|UINT32 what
+|one of RED_ERROR_?, RED_WARN_? Or RED_INFO_?, depending on severity.
+
+|UINT32 message_len
+|size of message
+
+|UINT8[] message
+|message string in UTF8.
+
+|UINT8 0
+|string zero termination
+|===
+
+== Main Channel definition
+
+. Server messages
++
+[source,c]
+----
+RED_MAIN_MIGRATE_BEGIN = 101
+RED_MAIN_MIGRATE_CANCEL = 102
+RED_MAIN_INIT = 103
+RED_MAIN_CHANNELS_LIST = 104
+RED_MAIN_MOUSE_MODE = 105
+RED_MAIN_MULTI_MEDIA_TIME = 106
+
+RED_MAIN_AGENT_CONNECTED = 107
+RED_MAIN_AGENT_DISCONNECTED = 108
+RED_MAIN_AGENT_DATA = 109
+RED_MAIN_AGENT_TOKEN = 110
+----
++
+. Client messages
++
+[source,c]
+----
+REDC_MAIN_RESERVED = 101
+REDC_MAIN_MIGRATE_READY = 102
+REDC_MAIN_MIGRATE_ERROR = 103
+REDC_MAIN_ATTACH_CHANNELS = 104
+REDC_MAIN_MOUSE_MODE_REQUEST = 105
+
+REDC_MAIN_AGENT_START = 106
+REDC_MAIN_AGENT_DATA = 107
+REDC_MAIN_AGENT_TOKEN = 108
+----
++
+. Migration control
++
+Spice migration control is performed using the main channel messages. Spice
+server initiates migration process by sending RED_MAIN_MIGRATE_BEGIN message.
+Once the client has completed its pre-migrate procedure it notifies the server
+by transmitting REDC_MAIN_MIGRATE_READY message. In case of pre-migrate
+procedure error, the client sends REDC_MAIN_MIGRATE_ERROR. Once the server
+receives REDC_MAIN_MIGRATE_READY he can commence the migration process. The
+server can send RED_MAIN_MIGRATE_CANCEL in order to instruct the client to
+cancel the migration process.
++
+.. RED_MAIN_MIGRATE_BEGIN, RedMigrationBegin
++
+[cols="2*"]
+|===
+|UINT16 port
+|port of destination server
+
+|UINT16 sport
+|secure port of destination server
+
+|UINT8[] host_name
+|host name of destination server
+|===
++
+.. RED_MAIN_MIGRATE_CANCEL, VOID
++
+Instruct the client to cancel migration process
++
+.. REDC_MAIN_MIGRATE_READY, VOID
++
+Notify the server of successful completion of the pre-migrate stage
++
+.. REDC_MAIN_MIGRATE_ERROR, VOID
++
+Notify the server of pre-migrate stage error
++
+[[mouse_modes]]
+. Mouse modes
++
+Spice protocol specifies two mouse modes, client mode and server mode. In
+client mode, the affective mouse is the client side mouse: the client sends
+mouse position within the display and the server sends mouse shape messages. In
+server mode, the client sends relative mouse movements and the server sends
+position and shape commands. Spice main channel is used for mouse mode control.
++
+.. Modes
++
+[source,c]
+----
+RED_MOUSE_MODE_SERVER = 1
+RED_MOUSE_MODE_CLIENT = 2
+----
++
+.. RED_MAIN_MOUSE_MODE, RedMouseMode
++
+Spice server sends this message on every mouse mode change
++
+[cols="2*"]
+|===
+|UINT32 supported_modes
+|current supported mouse mode, this is any combination of RED_MOUSE_MODE_?
+
+|UINT32 current_mode
+|the current mouse mode. Can be one of RED_MOUSE_MODE_?
+|===
++
+.. REDC_MAIN_MOUSE_MODE_REQUEST, UINT32
++
+Spice client sends this message to request specific mouse mode. It is not
+guarantied that the server will accept the request. Only on receiving
+RED_MOUSE_MODE message, the client can know of actual mouse mode change.
++
+[cols="2*"]
+|===
+|UINT32
+|requested mode, one of RED_MOUSE_MODE_?
+|===
++
+. Main channel init message
++
+Spice server must send RedInit as the first transmitted message t and is
+disallowed to send it at any other point.
++
+.. RED_MAIN_INIT, RedInit
++
+[cols="2*"]
+|===
+|UINT32 session_id
+|session id is generated by the server. This id will be send on every new
+channel connection within this session (i.e., in RedLinkMess.connection_id).
+
+|UINT32 display_channels_hint
+|optional hint of expected number of display channels. Zero is defined as an
+invalid value
+
+|UINT32 supported_mouse_modes
+|supported mouse modes. This is any combination of RED_MOUSE_MODE_?
+
+|UINT32 current_mouse_mode
+|the current mouse mode, one of RED_MOUSE_MODE_?
+
+|UINT32 agent_connected
+|current state of Spice agent (see <<spice_agent,This Section>>), 0 and 1 stand
+for disconnected and connected state respectively.
+
+|UINT32 agent_tokens
+|number of available tokens for sending messages to Spice agent.
+
+|UINT32 multi_media_time
+|current server multimedia time. The multimedia time is used for synchronizing
+video (for more information see <<multimedia_time,Multimedia time>>)
+
+|UINT32 ram_hint
+|optional hint for help in determining global LZ compression dictionary size
+(for more information see section <<spice_image,Spice Image>> in “Display
+Channel”).
+|===
++
+. Server side channels notification
++
+In order to have the ability to dynamically attach to the server side channels,
+Spice protocol includes RED_MAIN_CHANNELS_LIST message. This massage informs
+the client of available channels in the server side. In response to this
+message the client can decide to link with the new available channel(s). The
+server must receive REDC_MAIN_ATTACH_CHANNELS before sending any
+RED_MAIN_CHANNELS_LIST message.
++
+.. RED_MAIN_CHANNELS_LIST, RedChannels
++
+[cols="2*"]
+|===
+|UINT32 num_of_channels
+|number of channels in this list
+
+|RedChanneID[] channels
+|vector of “num_of_channels” channel ids
+|===
++
+.. RedChanneID
++
+[cols="2*"]
+|===
+|UINT8 type
+|channel type, one of RED_CHANNEL_? channel types, except for RED_CHANNEL_MAIN
+
+|UINT8 id
+|channel id
+|===
++
+[[multimedia_time]]
+. Multimedia time
++
+Spice defines messages for setting multimedia time for synchronization of video
+and audio streams. Two methods for updating multimedia time are supported. The
+first method uses the time stamp of data that arrives on the playback
+channel.The second method uses the main channel RED_MAIN_MULTI_MEDIA_TIME
+message. The latter method is used when no active playback channel exist.
++
+.. RED_MAIN_MULTI_MEDIA_TIME, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|multimedia time
+|===
++
+[[spice_agent]]
+. Spice agent
++
+Spice protocol defines a set of messages for bidirectional communication
+channel between Spice client and spice client agent on the remote server. Spice
+provides a communication channel only, the actual transferred data content is
+opaque to the protocol. This channel can be used for various purposes, for
+example, client-guest clipboard sharing, authentication and display
+configuration.
++
+Spice client receives notifications of remote site agent connection as part of
+the RED_MAIN_INIT message or by a specific server RED_MAIN_AGENT_CONNECTED.
+Remote agent disconnection notification is delivered by
+RED_MAIN_AGENT_DISCONNECTED message. A bidirectional tokens mechanism is used
+in order to prevent blocking of the main channel with agent messages (e.g., in
+case the agent stops consuming the data). Each side is not allowed to send more
+messages than the tokens allocated to it by the other side. The number of
+tokens that are allocated for the client is initialized from RED_MAIN_INIT
+message, and farther allocation of tokens is done using RED_MAIN_AGENT_TOKEN.
+Server tokens initial count is delivered in REDC_MAIN_AGENT_START message. This
+message must be the first agent related message that the client sends to the
+server. Farther tokens allocation for the server is done using
+REDC_MAIN_AGENT_TOKEN. Actual data packets are delivered using
+RED_MAIN_AGENT_DATA and REDC_MAIN_AGENT_DATA.
++
+.. Although agent messages are opaque for the protocol, agent data stream is
+defined by Spice protocol in order to delineate messages. Still, the
+client-server communication is independent from the agent channel, e.g., agent
+protocol conflicts don't affect the rest of the channels. Agent stream is
+defined as a run of messages having the following format:
++
+[cols="2*"]
+|===
+|UINT32 protocol
+|unique protocol of this message. The protocol id must be registered in order
+to prevent conflicts.
+
+|UINT32 type
+|protocol dependent message type.
+
+|UINT64 opaque
+|protocol dependent opaque data.
+
+|UINT32 size
+|size of data in bytes.
+
+|UINT8 data[0]
+|data of this message.
+|===
++
+Client and server must continue processing unknown protocols messages or
+messages having unknown type (i.e., receive and dump).
++
+.. RED_MAIN_AGENT_CONNECTED, VOID
+.. RED_MAIN_AGENT_DISCONNECTED, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|disconnect error code RED_ERROR_?
+|===
++
+.. RED_AGENT_MAX_DATA_SIZE = 2048
+.. RED_MAIN_AGENT_DATA, UINT8[]
++
+Agent packet is the entire message body (i.e. RedDataHeader.size). The maximum
+packet size is RED_AGENT_MAX_DATA_SIZE.
++
+.. RED_MAIN_AGENT_TOKEN, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|allocated tokens count for the client
+|===
++
+.. REDC_MAIN_AGENT_START, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|allocated tokens count for the server
+|===
++
+.. REDC_MAIN_AGENT_DATA, UINT8[]
++
+Agent packet is the entire message body (i.e. RedDataHeader.size). The maximum
+packet size is RED_AGENT_MAX_DATA_SIZE.
++
+.. REDC_MAIN_AGENT_TOKEN, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|allocated tokens count for the server
+|===
+
+== Inputs channel definition
+
+Spice Inputs channel controls the server mouse and the keyboard.
+
+. Client messages
++
+[source,c]
+----
+REDC_INPUTS_KEY_DOWN = 101
+REDC_INPUTS_KEY_UP = 102
+REDC_INPUTS_KEY_MODIFAIERS = 103
+
+REDC_INPUTS_MOUSE_MOTION = 111
+REDC_INPUTS_MOUSE_POSITION = 112
+REDC_INPUTS_MOUSE_PRESS = 113
+REDC_INPUTS_MOUSE_RELEASE = 114
+----
++
+. Server Messages
++
+[source,c]
+----
+RED_INPUTS_INIT = 101
+RED_INPUTS_KEY_MODIFAIERS = 102
+
+RED_INPUTS_MOUSE_MOTION_ACK = 111
+----
++
+. Keyboard messages
++
+Spice supports sending keyboard key events and keyboard leds synchronization.
+The client sends key event using REDC_INPUTS_KEY_DOWN and REDC_INPUTS_KEY_UP
+messages. Key value is expressed using PC AT scan code (see
+<<key_code,KeyCode>>). Keyboard leds synchronization is done by sending
+RED_INPUTS_KEY_MODIFAIERS message by the server or by sending
+REDC_INPUTS_KEY_MODIFAIERS by the client, these messages contain keyboard leds
+state. Keyboard modifiers is also sent by the server using RED_INPUTS_INIT,
+this message must be sent as the first server message and the server mustn't
+send it at any other point.
++
+.. Keyboard led bits
++
+[source,c]
+----
+RED_SCROLL_LOCK_MODIFIER = 1
+RED_NUM_LOCK_MODIFIER = 2
+RED_CAPS_LOCK_MODIFIER = 4
+----
++
+.. RED_INPUTS_INIT, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|any combination of keyboard led bits. If bit is set then the led is on.
+|===
++
+.. RED_INPUTS_KEY_MODIFAIERS, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|any combination of keyboard led bits. If bit is set then the led is on.
+|===
++
+.. REDC_INPUTS_KEY_MODIFAIERS, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|any combination of keyboard led bits. If bit is set then the led is on.
+|===
++
+[[key_code]]
+.. KeyCode
++
+[cols="2*"]
+|===
+|UINT8[4]
+|the value of key code is a PC AT scan code. The code is composed by up to four
+bytes for supporting extended codes. A code is terminated by a zero byte.
+|===
++
+.. REDC_INPUTS_KEY_DOWN, KeyCode
++
+[cols="2*"]
+|===
+|KeyCode
+|client sends this message to notify of key press event.
+|===
++
+.. REDC_INPUTS_KEY_UP, KeyCode
++
+KeyCode – client sends this message to notify of key release event.
++
+. Mouse messages
++
+spice support two modes of mouse operation: client mouse and server mouse (for
+more information see <<mouse_modes,mouse modes>>). in server mouse mode the
+client sends mouse motion message (i.e., redc_inputs_mouse_motion), and in
+client mouse mode it sends position message (i.e., redc_inputs_mouse_position).
+position message holds the position of the client mouse on the display and the
+id of the display channel, which is derived from redlinkmess.channel_id. in
+order to prevent flood of mouse motion/position events, the server sends
+red_inputs_mouse_motion_ack message on every red_motion_ack_bunch messages it
+receive. this mechanism allows the client to keep track on the server's
+messages consumption rate and to change the event pushing policy according to
+it. mouse button events are sent to the server using redc_inputs_mouse_press
+and redc_inputs_mouse_release messages.
++
+.. Red Button ID
++
+[source,c]
+----
+REDC_MOUSE_LBUTTON = 1, left button
+REDC_MOUSE_MBUTTON = 2, middle button
+REDC_MOUSE_RBUTTON = 3, right button
+REDC_MOUSE_UBUTTON = 4, scroll up button
+REDC_MOUSE_DBUTTON = 5, scroll down button
+----
++
+.. Buttons masks
++
+[source,c]
+----
+REDC_LBUTTON_MASK = 1, left button mask
+REDC_MBUTTON_MASK = 2, middle button mask
+REDC_RBUTTON_MASK = 4, right button mask
+----
++
+.. RED_MOTION_ACK_BUNCH
++
+[source,c]
+----
+RED_MOTION_ACK_BUNCH = 4
+----
++
+.. REDC_INPUTS_MOUSE_MOTION, RedcMouseMotion
++
+[cols="2*"]
+|===
+|INT32 dx
+|number of pixels the mouse had moved on x axis
+
+|INT32 dy
+|number of pixels the mouse had moved on y axis
+
+|UINT32 buttons_state
+|any combination of buttons mask. Set bit describe pressed button and clear bit
+describe unpressed button.
+
+|===
++
+.. REDC_INPUTS_MOUSE_POSITION, RedcMousePosition
++
+[cols="2*"]
+|===
+|UINT32 x
+|position on x axis
+
+|UINT32 y
+|position on y axis
+
+|UINT32 buttons_state
+|any combination of buttons mask. Set bit describe pressed button and clear bit
+describe unpressed button.
+
+|UINT8 display_id
+|id of the display that client mouse is on.
+|===
++
+.. REDC_INPUTS_MOUSE_PRESS, RedcMousePress
++
+[cols="2*"]
+|===
+|UINT32 button_id
+|one of REDC_MOUSE_?BUTTON
+
+|UINT32 buttons_state
+|any combination of buttons masks. Set bit describes pressed button, and clear
+bit describes unpressed button.
+|===
++
+.. REDC_INPUTS_MOUSE_RELEASE, RedcMouseRelease
++
+[cols="2*"]
+|===
+|UINT32 button_id
+|one of REDC_MOUSE_?BUTTON
+
+|UINT32 buttons_state
+|any combination of buttons mask. Set bit describes pressed button and clear
+bit describes unpressed button.
+|===
+
+== Display channel definition
+
+Spice protocol defines a set of messages for supporting rendering of the remote
+display area on the client display. The protocol supports rendering of graphics
+primitives (e.g., lines, images) and video streams. The protocol also supports
+caching of images and color palettes on the client side. Spice display channel
+supports several images compression methods for reducing network traffic.
+
+. Server messages
++
+[source,c]
+----
+RED_DISPLAY_MODE = 101
+RED_DISPLAY_MARK = 102
+RED_DISPLAY_RESET = 103
+RED_DISPLAY_COPY_BITS = 104
+
+RED_DISPLAY_INVAL_LIST = 105
+RED_DISPLAY_INVAL_ALL_IMAGES = 106
+RED_DISPLAY_INVAL_PALETTE = 107
+RED_DISPLAY_INVAL_ALL_PALETTES = 108
+
+RED_DISPLAY_STREAM_CREATE = 122
+RED_DISPLAY_STREAM_DATA = 123
+RED_DISPLAY_STREAM_CLIP = 124
+RED_DISPLAY_STREAM_DESTROY = 125
+RED_DISPLAY_STREAM_DESTROY_ALL = 126
+
+RED_DISPLAY_DRAW_FILL = 302
+RED_DISPLAY_DRAW_OPAQUE = 303
+RED_DISPLAY_DRAW_COPY = 304
+RED_DISPLAY_DRAW_BLEND = 305
+RED_DISPLAY_DRAW_BLACKNESS = 306
+RED_DISPLAY_DRAW_WHITENESS = 307
+RED_DISPLAY_DRAW_INVERS = 308
+RED_DISPLAY_DRAW_ROP3 = 309
+RED_DISPLAY_DRAW_STROKE = 310
+RED_DISPLAY_DRAW_TEXT = 311
+RED_DISPLAY_DRAW_TRANSPARENT = 312
+RED_DISPLAY_DRAW_ALPHA_BLEND = 313
+----
++
+. Client messages
++
+[source,c]
+----
+REDC_DISPLAY_INIT = 101
+----
++
+. Operation flow
++
+Spice server sends to the client a mode message using RED_DISPLAY_MODE for
+specifying the current draw area size and format. In response the client
+creates a draw area for rendering all the followed rendering commands sent by
+the server. The client will expose the new remote display area content (i.e.,
+after mode command) only after it receives a mark command (i.e.,
+RED_DISPLAY_MARK) from the server. The server can send a reset command using
+RED_DISPLAY_RESET to instruct the client to drop its draw area and palette
+cache. Sending mode message is allowed only while no active draw area exists
+on the client side. Sending reset message is allowed only while active draw
+area exists on client side. Sending mark message is allowed only once, between
+mode and reset messages. Draw commands, copy bits command and stream commands
+are allowed only if the client have an active display area (i.e., between
+RED_DISPLAY_MODE to RED_DISPLAY_RESET).
++
+On channel connection, the client optionally sends an init message, using
+REDC_DISPLAY_INIT, in order to enable image caching and global dictionary
+compression. The message includes the cache id and its size and the size of the
+dictionary compression window. These sizes and id are determined by the client.
+It is disallowed to send more then one init message.
++
+Color pallets cache are manged by the server.
+Items cache insertion commands are sent as part of the rendering commands.
+Cache items removal are sent explicitly using RED_DISPLAY_INVAL_LIST or
+RED_DISPLAY_INVAL_LIST server messages. Resetting client caches is done by
+sending RED_DISPLAY_INVAL_ALL_IMAGES or RED_DISPLAY_INVAL_ALL_PALETTES server
+messages.
++
+. Draw area control
++
+.. RED_DISPLAY_MODE, RedMode
++
+[cols="2*"]
+|===
+|UINT32 width
+|width of the display area
+
+|UINT32 height
+|height of the display area
+
+|UINT32 depth
+|color depth of the display area. Valid values are 16bpp or 32bpp.
+|===
++
+.. RED_DISPLAY_MARK, VOID
++
+Mark the beginning of the display area visibility
++
+.. RED_DISPLAY_RESET, VOID
++
+Drop current display area of the channel and reset palette cache
++
+. Raster operation descriptor
++
+The following defines a set of flags for describing raster operations that can
+be applied on a source image, source brush, destination and the result during a
+rendering operation. Combination of those flags defines the necessary steps
+that are needed to be preformed during a rendering operation. In the
+following definitions of rendering commands this combination is referred to by
+'rop_descriptor'.
++
+[source,c]
+----
+ROPD_INVERS_SRC = 1
+----
++
+Source Image need to be inverted before rendering
++
+[source,c]
+----
+ROPD_INVERS_BRUSH = 2
+----
++
+Brush need to be inverted before rendering
++
+[source,c]
+----
+ROPD_INVERS_DEST = 4
+----
++
+Destination area need to be inverted before rendering
++
+[source,c]
+----
+ROPD_OP_PUT = 8
+----
++
+Copy operation should be used.
++
+[source,c]
+----
+ROPD_OP_OR = 16
+----
++
+OR operation should be used.
++
+[source,c]
+----
+ROPD_OP_AND = 32
+----
++
+AND operation should be used.
++
+[source,c]
+----
+ROPD_OP_XOR = 64
+----
++
+XOR operation should be used.
++
+[source,c]
+----
+ROPD_OP_BLACKNESS = 128
+----
++
+Destination pixel should be replaced by black
++
+[source,c]
+----
+ROPD_OP_WHITENESS = 256
+----
++
+Destination pixel should be replaced by white
++
+[source,c]
+----
+ROPD_OP_INVERS = 512
+----
++
+Destination pixel should be inverted
++
+[source,c]
+----
+ROPD_INVERS_RES = 1024
+----
++
+Result of the operation needs to be inverted
++
+OP_PUT, OP_OR, OP_AND, OP_XOR, OP_BLACKNESS, OP_WHITENESS, and OP_INVERS are
+mutually exclusive
++
+OP_BLACKNESS, OP_WHITENESS, and OP_INVERS are exclusive
++
+. Raw raster image
++
+The following section describes Spice raw raster image (Pixmap). Pixmap is one
+of several ways to transfer images in Spice protocol (for more information see
+<<spice_image,Spice Image>>).
++
+.. Pixmap format types
++
+[source,c]
+----
+PIXMAP_FORMAT_1BIT_LE = 1
+----
++
+1 bit per pixel and bits order is little endian. Each pixel value is an index
+in a color table. The color table size is 2.
++
+[source,c]
+----
+PIXMAP_FORMAT_1BIT_BE = 2
+----
++
+1 bit per pixel and bits order is big endian. Each pixel value is index in a
+color table. The color table size is 2.
++
+[source,c]
+----
+PIXMAP_FORMAT_4BIT_LE = 3
+----
++
+4 bits per pixel and nibble order inside a byte is little endian. Each pixel
+value is an index in a color table. The color table size is 16.
++
+[source,c]
+----
+PIXMAP_FORMAT_4BIT_BE = 4
+----
++
+4 bits per pixel and nibble order inside a byte is big endian. Each pixel value
+is an index in a color table. The color table size is 16.
++
+[source,c]
+----
+PIXMAP_FORMAT_8BIT = 5
+----
++
+8 bits per pixel. Each pixel value is an index in a color table. The color
+table size is 256.
++
+[source,c]
+----
+PIXMAP_FORMAT_16BIT = 6
+----
++
+pixel format is 16 bits RGB555.
++
+[source,c]
+----
+PIXMAP_FORMAT_24BIT = 7
+----
++
+pixel format is 24 bits RGB888.
++
+[source,c]
+----
+PIXMAP_FORMAT_32BIT = 8
+----
++
+pixel format is 32 bits RGB888.
++
+[source,c]
+----
+PIXMAP_FORMAT_RGBA = 9
+----
++
+pixel format is 32 bits ARGB8888.
++
+.. Palette
++
+[cols="2*"]
+|===
+|UINT64 id
+|unique id of the palette
+
+|UINT16 table_size
+|number of entries in the color table
+
+|UINT32[] color_table
+|each entry is RGB555 or RGB888 color depending on the current display area
+mode. If display area mode color depth is 32, the effective format is RGB888.
+If display area mode color depth is 16 the effective format is RGB555.
+|===
++
+.. Pixmap flags
++
+[source,c]
+----
+PIXMAP_FLAG_PAL_CACHE_ME = 1
+----
++
+Instruct the client to add the palette to cache
++
+[source,c]
+----
+PIXMAP_FLAG_PAL_FROM_CACHE = 2
+----
++
+Instruct the client to retrieve palette from cache.
++
+[source,c]
+----
+PIXMAP_FLAG_TOP_DOWN = 4
+----
++
+Pixmap lines are ordered from top to bottom (i.e., line 0 is the highest line).
++
+.. Pixmap
++
+[cols="2*"]
+|===
+|UINT8 format
+|one of PIXMAP_FORMAT_?
+
+|UINT8 flags
+|combination of PIXMAP_FLAG_?
+
+|UINT32 width
+|width of the pixmap
+
+|UINT32 height
+|height of the pixmap
+
+|UINT32 stride
+|number of bytes to add for moving from the beginning of line n to the
+beginning of line n+1
+|===
++
+[source,c]
+----
+union {
+ ADDRESS palette; /* address of the color palette. Must be zero if no
+color table is required for format */
+}
+----
++
+[cols="2*"]
+|===
+|UINT64 palette_id
+|id of the palette, valid if FLAG_PAL_FROM_CACHE is set
+
+|ADDRESS data
+|address of line 0 of the pixmap.
+|===
++
+. LZ with palette
++
+This section describes a data structure that is combination of a color palette
+and a compressed pixmap data. The pixmap is compressed using our implementation
+of LZSS algorithm (see next section). Each decoded pixel value is an index in
+the color palette.
++
+.. LZPalette Flags
++
+[source,c]
+----
+LZPALETTE_FLAG_PAL_CACHE_ME = 1
+----
++
+Instruct the client to add the palette to the cache
++
+[source,c]
+----
+LZPALETTE_FLAG_PAL_FROM_CACHE = 2
+----
++
+Instruct the client to retrieve palette from the cache.
++
+[source,c]
+----
+LZPALETTE_FLAG_TOP_DOWN = 4
+----
++
+pixmap lines are ordered from top to bottom (i.e. line 0 is the highest line).
++
+.. LZPalette
++
+[cols="2*"]
+|===
+|UINT8 flags
+|combination of LZPALETTE_FLAG_?
+
+|UINT32 data_size
+|size of compressed data
+|===
++
+[source,c]
+----
+union {
+ ADDRESS palette; /* address of the color palette (see Palette section
+in “Raw raster image”). Zero value is disallowed. */
+ UINT64 palette_id; /* id of the palette, valid if FLAG_PAL_FROM_CACHE
+is set. */
+}
+----
++
+[cols="2*"]
+|===
+|UINT8[] data
+|compressed pixmap
+|===
++
+[[spice_image]]
+. Spice Image
++
+The following section describes Spice image. Spice image is used in various
+commands and data structures for representing a raster image. Spice image
+supports several compression types in addition to the raw mode: Quic, LZ and
+GLZ. Quic is a predictive coding algorithm. It is a generalization of SFALIC
+from gray-scale to color images withe addition of RLE encoding. By LZ we refer
+to the our implementation of the LZSS algorithm, which was adjusted for images
+in different formats. By GLZ we refer to an extension of LZ that allows it to
+use a dictionary that is based on a set of images and not just on the image
+being compressed.
++
+.. Image types
++
+[source,c]
+----
+IMAGE_TYPE_PIXMAP = 0
+IMAGE_TYPE_QUIC = 1
+IMAGE_TYPE_LZ_PLT = 100
+IMAGE_TYPE_LZ_RGB = 101
+IMAGE_TYPE_GLZ_RGB = 102
+IMAGE_TYPE_FROM_CACHE = 103
+----
++
+.. Image flags
++
+IMAGE_FLAG_CACHE_ME = 1, this flag instruct the client to add the image to
+image cache, cache key is ImageDescriptor.id (see below).
++
+.. ImageDescriptor
++
+[cols="2*"]
+|===
+|UINT64 id
+|unique id of the image
+
+|UINT8 type
+|type of the image. One of IMAGE_TYPE_?
+
+|UINT8 flags
+|any combination of IMAGE_FLAG_?
+
+|UINT32 width
+|width of the image
+
+|UINT32 height
+|height of the image
+|===
++
+.. Image data
++
+Image data follows ImageDescriptor and its content depends on
+ImageDescriptor.type:
++
+* In case of PIXMAP – content is Pixmap.
+* In case of QUIC – content is Quic compressed image. Data begins with the
+size of the compressed data, represented by UINT32, followed by the compressed
+data.
+* In case of LZ_PLT – content is LZPalette.
+* In case of LZ_RGB – content is LZ_RGB – LZ encoding of an RGB image. Data
+begins with the size of the compressed data, represented by UINT32, followed
+by the compressed data.
+* In case of GLZ_RGB – content is GLZ_RGB – GLZ encoding of an RGB image. Data
+begins with the size of the compressed data, represented by UINT32, , followed
+by the compressed data.
+* In case of FROM_CACHE – No image data. The client should use
+ImageDescriptor.id to retrieve the relevant image from cache.
++
+. Glyph String
++
+Glyph string defines an array of glyphs for rendering. Glyphs in a string can
+be in A1, A4 or A8 format (i.e., 1bpp, 4bpp, or 8bpp alpha mask). Every glyph
+contains its rendering position on the destination draw area.
++
+.. RasterGlyph
++
+[cols="2*"]
+|===
+|POINT render_pos
+|location of the glyph on the draw area
+
+|POINT glyph_origin
+|origin of the glyph. The origin is relative to the upper left corner of the
+draw area. Positive value on x axis advances leftward and positive value on y
+axis advances upward.
+
+|UINT16 width
+|glyph's width
+
+|UINT16 height
+|glyph's height
+
+|UINT8[] data
+|alpha mask of the glyph. Actual mask data depends on the glyph string's flags.
+If the format is A1 then the line stride is ALIGN(width, 8) / 8. If the format
+is A4, the line stride is ALIGN(width, 2) / 2. If the format is A8, the line
+stride is width.
+|===
++
+.. Glyph String flags
++
+[source,c]
+----
+GLYPH_STRING_FLAG_RASTER_A1 = 1
+----
++
+Glyphs type is 1bpp alpha value (i.e., 0 is transparent 1 is opaque)
++
+[source,c]
+----
+GLYPH_STRING_FLAG_RASTER_A4 = 2
+----
++
+Glyphs type is 4bpp alpha value (i.e., 0 is transparent 16 is opaque)
++
+[source,c]
+----
+GLYPH_STRING_FLAG_RASTER_A8 = 4
+----
++
+Glyphs type is 4bpp alpha value (i.e., 0 is transparent 256 is opaque)
++
+[source,c]
+----
+GLYPH_STRING_FLAG_RASTER_TOP_DOWN = 8
+----
++
+Line 0 is the top line of the mask
++
+.. GlyphString
++
+[cols="2*"]
+|===
+|UINT16 length
+|number of glyphs
+
+|UINT16 flags
+|combination of GLYPH_STRING_FLAG_?
+
+|UINT8[] data
+|glyphs
+|===
++
+. Data Types
++
+.. RectList
++
+[cols="2*"]
+|===
+|UINT32 count
+|number of RECT items in rects
+
+|RECT[] rects
+|array of <count> RECT
+|===
++
+.. Path segment flags
++
+[source,c]
+----
+PATH_SEGMENT_FLAG_BEGIN = 1
+----
++
+this segment begins a new path
++
+[source,c]
+----
+PATH_SEGMENT_FLAG_END = 2
+----
++
+this segment ends the current path
++
+[source,c]
+----
+PATH_SEGMENT_FLAG_CLOSE = 8
+----
++
+this segment closes the path and is invalid if PATH_SEGMENT_FLAG_END is not set
++
+[source,c]
+----
+PATH_SEGMENT_FLAG_BEZIER = 16
+----
++
+this segment content is a Bezier curve
++
+.. PathSeg
++
+[cols="2*"]
+|===
+|UINT32 flags
+|any combination of PATH_SEGMENT_FLAG_?
+
+|UINT32 count
+|number of points in the segment
+
+|POINTFIX[] points
+|segment points
+|===
++
+.. PathSegList
++
+List of PathSeg items. End of the list is reached if the sum of all previous
+PathSegs' sizes is equal to list_size. Address of next segment is the address
+of PathSeg.points[PathSeg.count]
++
+[cols="2*"]
+|===
+|UINT32 list_size
+|total size of in bytes of all PathSegs in the list,
+|===
++
+PathSeg seg0 – first path segment.
++
+.. Clip types
++
+[source,c]
+----
+CLIP_TYPE_NONE = 0
+----
++
+no clipping
++
+[source,c]
+----
+CLIP_TYPE_RECTS = 1
+----
++
+data is RectList and union of all rectangles in RectList is the effective clip
++
+[source,c]
+----
+CLIP_TYPE_PATH = 2
+----
++
+data is PathSegList and the figure described by PathSegList is the effective
+clip
++
+.. Clip
++
+[cols="2*"]
+|===
+|UIN32 type
+|one of CLIP_TYPE_?
+
+|ADDRESS data
+|address of clip data. The content depends on <type>
+|===
++
+.. Mask flags
++
+[source,c]
+----
+MASK_FLAG_INVERS = 1, the effective mask is the inverse of the mask
+----
++
+.. Mask
++
+[cols="2*"]
+|===
+|UINT8 flags | flags of the mask, combination of MASK_FLAG_?
+
+|POINT position | origin of the mask in bitmap coordinates
+
+|ADDRESS bitmap | address of the mask's image, the format of the image must be
+1bpp. If the bitmap is zero then no masking operation needs to be preformed.
+|===
++
+In all rendering commands, the mask must be big enough to cover the destination
+rectangle
++
+.. Brush types
++
+[source,c]
+----
+BRUSH_TYPE_NONE = 0 /* the brush is invalid */
+BRUSH_TYPE_SOLID = 1 /* the brush is solid RGB color */
+BRUSH_TYPE_PATTERN = 2 /* the brush is a pattern */
+----
++
+.. Pattern
++
+[cols="2*"]
+|===
+|ADDRESS image
+|address of the pattern's Image
+
+|POINT position
+|origin coordinates of the pattern in the image
+|===
++
+.. Brush
++
+[cols="2*"]
+|===
+|UINT32 type
+|one of BRUSH_TYPE_?
+|===
++
+[source,c]
+----
+Union {
+ UINT32 color; */ RGB color. The format of the color depends on current
+draw area mode.*/
+ Pattern pattern;
+}
+----
++
+.. Image scale mode
++
+The following defines the method for scaling image
++
+[source,c]
+----
+IMAGE_SCALE_INTERPOLATE = 0
+----
++
+The client is allowed to INTERPOLATE pixel color.
++
+[source,c]
+----
+IMAGE_SCALE_NEAREST = 1
+----
++
+The client must use the nearest pixel.
++
+.. LineAtrr flags
++
+[source,c]
+----
+LINE_ATTR_FLAG_START_WITH_GAP = 4
+----
++
+first style segment if gap (i.e., foreground)
++
+[source,c]
+----
+LINE_ATTR_FLAG_STYLED = 8
+----
++
+style member of LineAtrr is valid and contains effective line style for the
+rendering operation.
++
+.. LineAtrr join style
++
+[source,c]
+----
+LINE_ATTR_JOIN_ROUND = 0
+LINE_ATTR_JOIN_BEVEL = 1
+LINE_ATTR_JOIN_MITER = 2
+----
++
+.. LineAtrr cap style
++
+[source,c]
+----
+LINE_ATTR_CAP_ROUND = 0
+LINE_ATTR_CAP_SQUARE = 1
+LINE_ATTR_CAP_BUTT = 2
+----
++
+.. LineAttr
++
+[cols="2*"]
+|===
+|UINT8 flags
+|combination of LINE_ATTR_?
+
+|UINT8 join_style
+|one of LINE_ATTR_JOIN_?
+
+|UINT8 cap_style
+|one of LINE_ATTR_CAP_?
+
+|UINT8 style_num_segments
+|number of style segments in line style
+
+|FIXED28_4 width
+|width of the line in pixels
+
+|FIXED28_4 miter_limit
+|miter limit in pixels
+
+| ADDRESS style
+|address of line style line style is array of FIXED28_4. The array defines
+segments that each represents length of foreground or background pixels in the
+style. If FLAG_START_WITH_GAP is defined then the first segment in the style is
+background, otherwise it is foreground. Renderer uses this array of segments
+repeatedly during rendering operation.
+|===
++
+. Rendering command
++
+.. RedDrawBase
++
+Common field to all rendering command
++
+[cols="2*"]
+|===
+|RECT bounding_box
+|the affected area on the display area
+
+|Clip clip
+|the effective clip to set before rendering a command
+|===
++
+.. RED_DISPLAY_COPY_BITS
++
+[source,c]
+----
+RedDrawBase
+POINT source_position
+----
++
+Copy bits from the draw area to bounding_box on the draw area. Source area left
+top corner is source_position and its height and width is equal to bounding_box
+height and width. Source and destination rectangles can overlap.
++
+.. RED_DISPLAY_DRAW_FILL
++
+[source,c]
+----
+RedDrawBase
+Brush brush
+UINT16 rop_descriptor
+Mask mask
+----
++
+Fill bounding_box using brush as the fill pattern and rop_descriptor
+instructions. If the mask is valid, it will limit the modified area (i.e., only
+pixels on the destination area that their corresponding bits are set will be
+affected).
++
+.. RED_DISPLAY_DRAW_OPAQUE
++
+[source,c]
+----
+RedDrawBase
+ADDRESS source_image
+RECT source_area
+Brush brush
+UINT16 rop_descriptor
+UINT8 scale_mode
+Mask mask
+----
++
+Combine pixels from source_area in source_image with the brush's pattern using
+rop_descriptor instructions. The result image will be rendered into
+bounding_box. In case scaling of source image is required it will be performed
+according to scale_mode and before the combination with brush pixels. If mask
+is valid it will limit the modified area.
++
+.. RED_DISPLAY_DRAW_COPY
++
+[source,c]
+----
+RedDrawBase
+ADDRESS source_image
+RECT source_area
+UINT16 rop_descriptor
+UINT8 scale_mode
+Mask mask
+----
++
+Copy pixels from source_area in source_image to bounding_box using
+rop_descriptor instructions. In case scaling of source image is required it
+will be performed according to scale_mode and before the copying to the draw
+area. If mask is valid it will limit the modified area.
++
+.. RED_DISPLAY_DRAW_BLEND
++
+[source,c]
+----
+RedDrawBase
+ADDRESS source_image
+RECT source_area
+UINT16 rop_descriptor
+UINT8 scale_mode
+Mask mask
+----
++
+Mixing pixels from source_area in source_image with bounding_box pixels on the
+draw area using rop_descriptor instructions. In case scaling of source image is
+required it will be performed according to scale_mode and before the mixing
+with the draw area. If mask is valid it will limit the modified area.
++
+.. RED_DISPLAY_DRAW_BLACKNESS
++
+[source,c]
+----
+RedDrawBase
+Mask mask
+----
++
+Fill bounding_box with black pixels. If mask is valid it will limit the
+modified area.
++
+.. RED_DISPLAY_DRAW_WHITENESS
++
+[source,c]
+----
+RedDrawBase
+Mask mask
+----
++
+Fill bounding_box with white pixels. If mask is valid it will limit the
+modified area.
++
+.. RED_DISPLAY_DRAW_INVERS
++
+[source,c]
+----
+RedDrawBase
+Mask mask
+----
++
+Inverse all pixels in bounding_box. If mask is valid it will limit the modified
+area.
++
+.. RED_DISPLAY_DRAW_ROP3
++
+[source,c]
+----
+RedDrawBase
+ADDRESS source_image
+RECT source_area
+Brush brush
+UINT8 rop3
+UINT8 scale_mode
+Mask mask
+----
++
+Mix pixels from source_area in source_image, bounding_box pixels in the draw
+area, and the brush pattern. The method for mixing three pixels into the
+destination area (i.e., bounding_box) is defined by rop3 (i.e., ternary raster
+operations). In case scaling of source image is required it will be performed
+according to scale_mode and before the mixing. If mask is valid it will limit
+the modified area.
++
+.. RED_DISPLAY_DRAW_TRANSPARENT
++
+[source,c]
+----
+RedDrawBase
+ADDRESS source_image
+RECT source_area
+UINT32 transparent_color
+UINT32 transparent _true_color
+----
++
+Copy pixels from source_area on source_image to bounding_box on the draw area.
+In case scaling of source image is required it will use IMAGE_SCALE_NEAREST.
+Pixels with value equal to the transparent color will be masked out.
+Transparent color is provided in two forms: true color (i.e., RGB888) and the
+color in the original format (i.e., before compression) .
++
+.. RED_DISPLAY_DRAW_ALPHA_BLEND
++
+[source,c]
+----
+RedDrawBase
+UINT8 alpha
+ADDRESS source_image
+RECT source_area
+----
++
+Alpha blend source_area of source_image on bounding_box of draw area using
+alpha value or alternatively per pixel alpha value. In case scaling of source
+image is required, it will use IMAGE_SCALE_INTERPOLATE mode. Alpha value is
+defined as 0 is full transparency and 255 is full opacity. Format of source
+image can be pre-multiplied ARGB8888 for per pixel alpha value.
++
+New RGB color is defined as:
++
+[source,c]
+----
+color' = (source_color * alpha) / 255
+alpha' = (source_alpha * alpha) / 255
+new_color = color' + ((255 - alpha' ) * destination_color) / 255
+----
++
+.. RED_DISPLAY_DRAW_STROKE
++
+[source,c]
+----
+RedDrawBase
+ADDRESS path – address of the PathSegList that defines the path to render
+LineAttr attr
+Bush brush
+UINT16 fore_mode - foreground rop_descriptor
+UINT16 back_mode – background rop_descriptor
+----
++
+Render path using brush line attribute and rop descriptors. If the line is
+styled (i.e., LINE_ATTR_FLAG_STYLED is set in attr.falgs) then background
+(i.e., inverse of the style) is drawn using back_mode and the foreground is
+drawn using fore_mode. If the line is not styled, the entire path is rendered
+using fore_mode.
++
+.. RED_DISPLAY_DRAW_TEXT
++
+[source,c]
+----
+RedDrawBase
+ADDRESS string – address of GlyphString
+RECT back_area
+Brush fore_brush
+Brush back_brush
+UINT16 fore_mode
+UINT16 back_mode
+----
++
+Render string of glyph on the display area using brush fore_brush and the
+rop_descriptor fore_mode. If back_area is not empty the renderer fill back_area
+on the display area prior to rendering the glyph string. back_area is filled
+using back_brush and the rop_descriptor back_mode.
++
+. Video streaming commands
++
+Spice supports the creation of video streams by the server for rendering video
+content on the client display area. Unlike other rendering commands, the
+stream data can be compressed using lossy or video specific compression
+algorithms. It is not required to render video frames as they arrive and it is
+also allowed to drop video frames. This enables using video frames buffering
+for having smoother playback and audio synchronization. Audio synchronization
+is achieved by using time stamp that is attached to audio and video streams.
+By using video streaming the network traffic can be dramatically reduced. When
+the stream is created, the server sends create message using
+RED_DISPLAY_STREAM_CREATE. After the server creates a stream he can send data
+using RED_DISPLAY_STREAM_DATA, or set new stream clipping by sending clip
+message using RED_DISPLAY_STREAM_CLIP. Once the server no longer needs the
+stream, he can send destroy command using RED_DISPLAY_STREAM_DESTROY. The
+server can also destroy all active streams by sending destroy all message using
+RED_DISPLAY_STREAM_DESTROY_ALL.
++
+.. Stream flags
++
+[source,c]
+----
+STREAM_FLAG_TOP_DOWN = 1 /* stream frame line order is from top to bottom */
+----
++
+.. Codec types
++
+[source,c]
+----
+STREAM_CODEC_TYPE_MJPEG = 1 /* this stream uses motion JPEG codec */
+----
++
+.. RED_DISPLAY_STREAM_CREATE, RedStreamCreate
++
+[cols="2*"]
+|===
+|UINT32 id
+|id of the new stream. It is the server's responsibility to manage stream ids
+
+|UINT32 flags
+|flags of the stream, any combination of STREAM_FLAG_?
+
+|UINT32 codec_type
+|type of codec used for this stream, one of STREAM_CODEC_TYPE_?
+
+|UINT64 reserved
+|must be zero
+
+|UINT32 stream_width
+|width of the source frame.
+
+|UINT32 stream_height
+|height of the source frame
+
+|UINT32 source_width
+|actual frame width to use, must be less or equal to stream_width.
+
+|UINT32 source_height
+|actual frame height to use, must be less or equal to stream_height.
+
+|RECT destination
+|area to render into on the client display area
+
+|Clip clip
+|clipping of the stream
+|===
++
+.. RED_DISPLAY_STREAM_DATA, RedStreamData
++
+[cols="2*"]
+|===
+|UINT32 id
+|stream id (i.e., RedStreamCreate.id)
+
+|UINT32 multimedia_time
+|frame time stamp
+
+|UINT32 data_size
+|stream data size to consume in bytes
+
+|UINT32 pad_size
+|additional data padding in bytes
+
+|UINT8[] data
+|stream data depending on RedStreamCreate.codec_type. Size of data is (
+data_size + pad_size)
+|===
++
+.. RED_DISPLAY_STREAM_CLIP, RedStreamClip
++
+[cols="2*"]
+|===
+|UINT32 id
+|stream id (i.e., RedStreamCreate.id)
+|===
++
+Clip clip – new clipping of the stream
++
+.. RED_DISPLAY_STREAM_DESTROY, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|id of stream to destroy
+|===
++
+.. RED_DISPLAY_STREAM_DESTROY_ALL, VOID
++
+Destroy all active streams
++
+. Cache control
++
+.. Resource type
++
+[source,c]
+----
+RED_RES_TYPE_IMAGE = 1
+----
++
+.. RedResourceID
++
+[cols="2*"]
+|===
+|UINT8 type
+|type of the resource, one of RED_RES_TYPE_?
+
+|UINT64 id
+|id of the resource
+|===
++
+.. RedResourceList
++
+[cols="2*"]
+|===
+|UINT16 count
+|number of items in resources
+
+|RedResourceID[] resources
+|list of resources id
+|===
++
+.. RED_DISPLAY_INVAL_LIST, RedResourceList
++
+[cols="2*"]
+|===
+|RedResourceList
+|list of resources to remove from cache
+|===
++
+.. RED_DISPLAY_INVAL_ALL_IMAGES, RedWaitForChannels
++
+Remove all images from the image cache. The client must use RedWaitForChannels
+(for more info see <<channel_sync,Channel synchronization>>) to synchronize
+with other channels before clearing the cache.
++
+.. RED_DISPLAY_INVAL_PALETTE, UINT64
++
+[cols="2*"]
+|===
+|UINT64 id of palette
+|client needs to remove palette with that id from the cache
+|===
++
+.. RED_DISPLAY_INVAL_ALL_PALETTES, VOID
++
+Remove all palettes from palette cache
+
+== Cursor channel definition
+
+Spice protocol defines a set of messages for controlling cursor shape and
+position on the remote display area, cursor position messages are irrelevant
+for client mouse mode (see <<mouse_modes,Mouse Modes>>). Spice protocol also
+defines a set of messages for managing cursor shape cache on the client site.
+Client must strictly obey all such instructions. The server sends
+RED_CURSOR_INIT to set current pointer state (i.e., shape, position, visibility
+etc.) and to clear shape cache. After the server sends init message it can send
+any other cursor command except for RED_CURSOR_INIT. The server can send
+RED_CURSOR_RESET message - this will disable the cursor and reset the cursor
+cache. After this message the only valid message the server can send is
+RED_CURSOR_INIT. The relevant remote display area for a cursor channel is the
+one of the display channel that has the same channel id (i.e.,
+RedLinkMess.channel_id).
+
+. Server messages
++
+[source,c]
+----
+RED_CURSOR_INIT = 101
+RED_CURSOR_RESET = 102
+RED_CURSOR_SET = 103
+RED_CURSOR_MOVE = 104
+RED_CURSOR_HIDE = 105
+RED_CURSOR_TRAIL = 106
+RED_CURSOR_INVAL_ONE = 107
+RED_CURSOR_INVAL_ALL = 108
+----
++
+.. Cursors types
++
+[source,c]
+----
+CURSOR_TYPE_ALPHA = 0
+CURSOR_TYPE_MONO = 1
+CURSOR_TYPE_COLOR4 = 2
+CURSOR_TYPE_COLOR8 = 3
+CURSOR_TYPE_COLOR16 = 4
+CURSOR_TYPE_COLOR24 = 5
+CURSOR_TYPE_COLOR32 = 6
+----
++
+.. CursorHeader
++
+[cols="2*"]
+|===
+|UINT64 unique
+|unique identifier of the corresponding cursor shape. It is used for storing
+and retrieving cursors from the cursor cache.
+
+|UINT16 type
+|type of the shape, one of CURSOR_TYPE_?
+
+|UINT16 width
+|width of the shape
+
+|UINT16 height
+|height of the shape
+
+|UINT16 hot_spot_x
+|position of hot spot on x axis
+
+|UINT16 hot_spot_y
+|position of hot spot on y axis
+|===
++
+.. Cursor flags
++
+[source,c]
+----
+CURSOR_FLAGS_NONE = 1
+----
++
+set when RedCursor (see below) is invalid
++
+[source,c]
+----
+CURSOR_CURSOR_FLAGS _CACHE_ME = 2
+----
++
+set when the client should add this shape to the shapes cache. The client will
+use CursorHeader.unique as cache key.
++
+[source,c]
+----
+CURSOR_FLAGS_FROM_CACHE = 4
+----
++
+set when the client should retrieve the cursor shape, using CursorHeader.unique
+as key, from the shapes cache. In this case all fields of CursorHeader except
+for 'unique' are invalid.
++
+.. RedCursor
++
+[cols="2*"]
+|===
+|UINT32 flags
+|any valid combination of RED_CURSOR_?
+
+|CursorHeader header
+|
+
+|UINT8[] data
+|actual cursor shape data, the size is determine by width, height and type from
+CursorHeader. Next we will describe in detail the shape data format according
+to cursor type:
+
+|ALPHA, alpha shape
+|data contains pre-multiplied ARGB8888 pixmap. Line stride is <width * 4>.
+
+|MONO, monochrome shape
+|data contains two bitmaps with size <width> * <height>. The first bitmap is
+AND mask and the second is XOR mask. Line stride is ALIGN(<width>, 8) / 8.
+Bits order within every byte is big endian.
+
+|COLOR4, 4 bits per pixel shape
+|First data region is pixmap: the stride of the pixmap is ALIGN(width , 2) / 2;
+every nibble is translated to a color usingthe color palette; Nibble order is
+big endian. Second data region contain 16 colors palette: each entry is 32 bit
+RGB color. Third region is a bitmap mask: line stride is ALIGN(<width>, 8) /
+8; bits order within every byte is big endian.
+
+|COLOR4, 8 bits per pixel shape
+|First data region is pixmap: the stride of the pixmap is <width>; every byte
+is translated to color using the color palette. Second data region contain 256
+colors palette: each entry is 32 bit RGB color. Third region is a bitmap mask:
+line stride is ALIGN(<width>, 8) / 8; bits order within every byte is big
+endian.
+
+|COLOR16, 16 bits per pixel shape
+|First data region is pixmap: the stride of the pixmap is <width * 2>; every
+UINT16 is RGB_555. Second region is a bitmap mask: line stride is
+ALIGN(<width>, 8) / 8; bits order within every byte is big endian.
+
+|COLOR24, 24 bits per pixel shape
+|First data region is pixmap: the stride of the pixmap is <width * 3>; every
+UINT8[3] is RGB_888. Second region is a bitmap mask: line stride is
+ALIGN(<width>, 8) / 8; bits order within every byte is big endian.
+
+|COLOR32, 32 bits per pixel shape
+|First data region is pixmap: the stride of the pixmap is <width * 4>,;every
+UINT32 is RGB_888. Second region is a bitmap mask: line stride is
+ALIGN(<width>, 8) / 8; bits order within every byte is big endian.
+|===
++
+For more deatails on drawing the cursor shape see <<cursor_shape, this
+section>>
++
+.. RED_CURSOR_INIT, RedCursorInit
++
+[cols="2*"]
+|===
+|POINT16 position
+|position of mouse pointer on the relevant display area. Not relevant in
+client mode.
+
+|UINT16 trail_length
+|number of cursors in the trail excluding main cursor.
+
+|UINT16 trail_frequency
+|millisecond interval between trail updates.
+
+|UIN8 visible
+|if 1, the cursor is visible. If 0, the cursor is invisible.
+
+|RedCursor cursor
+|current cursor shape
+|===
++
+.. RED_CURSOR_RESET, VOID
++
+.. RED_CURSOR_SET, RedCursorSet
++
+[cols="2*"]
+|===
+|POINT16 position
+|position of mouse pointer on the relevant display area. not relevant in client
+mode.
+
+|UINT8 visible
+|if 1, the cursor is visible. If 0, the cursor is invisible.
+
+|RedCursor cursor
+|current cursor shape
+|===
++
+.. RED_CURSOR_MOVE, POINT16
++
+[cols="2*"]
+|===
+|POINT16
+|new mouse position. Not relevant in client mode. This message also implicitly
+sets cursor visibility to 1.
+|===
++
+.. RED_CURSOR_HIDE, VOID
++
+Hide pointer on the relevant display area.
++
+.. RED_CURSOR_TRAIL
++
+[cols="2*"]
+|===
+|UINT16 length
+|number of cursors in the trail excluding main cursor.
+
+|UINT16 frequency
+|millisecond interval between trail updates
+|===
++
+.. RED_CURSOR_INVAL_ONE, UINT64
++
+[cols="2*"]
+|===
+|UINT64
+|id of cursor shape to remove from the cursor cache
+|===
++
+.. RED_CURSOR_INVAL_ALL, VOLD
++
+Clear cursor cache
++
+[[cursor_shape]]
+. Drawing the cursor shape according to the cursor type
++
+This section is relevant only for server mouse mode. Cursor shape positioning
+on the display area is done by placing cursor hot spot on the current cursor
+position.
++
+.. Alpha - no spacial handling, just bland the shape on the display area.
++
+.. Monochrome
++
+For each cleared bit in the AND mask clear the corresponding bits in the
+relevant pixel on the display area
+For each set bit in the XOR mask reverse the
+corresponding bits in the relevant pixel on the display area
++
+.. Color
++
+If the source color is black and mask bit is set, NOP.
+Else, if the source color is white and the mask bit is set, reverse all bits in
+the relevant pixel on the display area.
+Else, put source color.
+
+== Playback channel definition
+
+Spice supports sending audio streams for playback on the client side. An audio
+stream is sent by the server in an audio packet using RED_PLAYBACK_DATA
+message. The content of the audio packet is controlled by the playback mode
+that the server sends using RED_PLAYBACK_MODE message. The server can start and
+stop the stream using RED_PLAYBACK_START and RED_PLAYBACK_STOP messages.
+Sending audio packet is allowed only between start and stop messages. Sending
+start message is allowed only in stop state and after at least one mode message
+was sent. Sending a stop message is allowed only during a start state.
+
+. Server messages
++
+[source,c]
+----
+RED_PLAYBACK_DATA = 101
+RED_PLAYBACK_MODE = 102
+RED_PLAYBACK_START = 103
+RED_PLAYBACK_STOP = 104
+----
++
+. Audio format
++
+[source,c]
+----
+RED_PLAYBACK_FMT_S16 = 1 /* each channel sample is a 16 bit
+signed integer */
+----
++
+. Playback data mode
++
+Two types of data mode are available: (1) raw PCM data and (2) compressed data
+in CELT 0_5_1 format.
++
+[source,c]
+----
+RED_PLAYBACK_DATA_MODE_RAW = 1
+RED_PLAYBACK_DATA_MODE_CELT_0_5_1 = 2
+----
++
+. Playback channel capabilities
++
+[source,c]
+----
+RED_PLAYBACK_CAP_CELT_0_5_1 = 0
+----
++
+Spice client needs to declare support of CELT_5_1 in channel capabilities in
+order to allow the server to send playback packets in CELT_0_5_1 format.
++
+. RED_PLAYBACK_MODE, RedPlaybackMode
++
+[cols="2*"]
+|===
+|UINT32 time
+|server time stamp
+
+|UINT32 mode
+|one of RED_PLAYBACK_DATA_MODE_?
+
+|UINT8[] data
+|specific data, content depend on mode
+|===
++
+. RED_PLAYBACK_START, RedRecordStart
++
+[cols="2*"]
+|===
+|UINT32 channels
+|number of audio channels
+
+|UINT32 format
+|one of RED_PLAYBACK_FMT_?
+
+|UINT32 frequency
+|channel samples per second
+|===
++
+. RED_PLAYBACK_DATA, RedPlaybackPacket
++
+[cols="2*"]
+|===
+|UINT32 time
+|server time stamp
+
+|UINT8[] data
+|playback data , content depend on mode
+|===
++
+. RED_PLAYBACK_STOP, VOID
++
+Stop current audio playback
+
+== Record Channel definition
+
+Spice supports transmitting of audio captured streams from the client to the
+server. Spice server starts audio capturing using RED_RECORD_START message.
+This message instructs the client to start transmitting captured audio . In
+response, the client sends time stamp of the stream start using
+REDC_RECORD_START_MARK. After the client sends start mark it can start
+transmitting audio stream data using REDC_RECORD_DATA. One mode message must be
+sent by the client before any other message using REDC_RECORD_MODE. This, in
+order to inform the server on what type of data will be transferred. Mode
+message can also be transmitted at any other time in order to switch the data
+type delivered by REDC_RECORD_DATA. The Server can send RED_RECORD_STOP for
+stopping captured audio streaming. Sending a start message is allowed only
+while the stream is in stop state. Sending a stop message and data messages is
+allowed only while the stream is in start state. Sending mark message is
+allowed only between start message and the first data message.
+
+. Server messages
++
+[source,c]
+----
+RED_RECORD_START = 101
+RED_RECORD_STOP = 102
+----
++
+. Client messages
++
+[source,c]
+----
+REDC_RECORD_DATA = 101
+REDC_RECORD_MODE = 102
+REDC_RECORD_START_MARK = 103
+----
++
+. Audio format
++
+[source,c]
+----
+RED_RECORD_FMT_S16 = 1 /* each channel sample is a 16 bit
+signed integer */
+----
++
+. Record data mode
++
+Two types of data mode are available: (1) raw PCM data (2) compressed data in
+CELT 0.5.1 format.
++
+[source,c]
+----
+RED_RECORD_DATA_MODE_RAW = 1
+RED_RECORD_DATA_MODE_CELT_0_5_1 = 2
+----
++
+. Record channel capabilities
++
+[source,c]
+----
+RED_PLAYBACK_CAP_CELT_0_5_1 = 0
+----
++
+Spice server needs to declare support of CELT_5_1 in channel capabilities in
+order to allow the client to send recorded packets in CELT_0_5_1 format.
++
+. REDC_RECORD_MODE, RedcRecordMode
++
+[cols="2*"]
+|===
+|UINT32 time
+|client time stamp
+
+|UINT32 mode
+|one of RED_RECORD_DATA_MODE_?
+
+|UINT8[] data
+|specific data, content depend on mode
+|===
++
+. RED_RECORD_START, RedRecordStart
++
+[cols="2*"]
+|===
+|UINT32 channel
+|number of audio channels
+
+|UINT32 format
+|one of RED_AUDIO_FMT_?
+
+|UINT32 frequency
+|channel samples per second
+|===
++
+. REDC_RECORD_START_MARK, UINT32
++
+[cols="2*"]
+|===
+|UINT32
+|client time stamp of stream start
+|===
++
+. REDC_RECORD_DATA, RedcRecordPacket
++
+[cols="2*"]
+|===
+|UINT32 time
+|client time stamp
+
+|UINT8[] data
+|recorded data , content depend on mode
+|===
++
+. RED_RECORD_STOP, VOID
++
+Stop current audio capture
commit b052fb73b62cd38f165deb50e6c9d778cea10c86
Author: Thiago Mendes <tribeirom at gmail.com>
Date: Mon Jul 10 14:01:45 2017 -0500
Converting Vd_interfaces.odt to Asciidoc
https://gitlab.freedesktop.org/spice/spice-server/issues/10
Acked-by: Frediano Ziglio <fziglio at redhat.com>
diff --git a/AUTHORS b/AUTHORS
index 87478285..c7ccd433 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -71,5 +71,6 @@ Patches also contributed by
Benjamin Tissoires <benjamin.tissoires at redhat.com>
Olivier Fourdan <ofourdan at redhat.com>
worldofpeace <worldofpeace at protonmail.ch>
+ Thiago Mendes <tribeirom at gmail.com>
....send patches to get your name here...
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 8fa095de..3a04abfc 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -7,16 +7,23 @@ EXTRA_DIST = \
spice_style.txt \
spice_threading_model.html \
spice_threading_model.txt \
+ vd_interfaces.txt \
+ $(NULL)
+
+HTML_FILES = \
+ spice_style.html \
+ spice_threading_model.html \
+ vd_interfaces.html \
$(NULL)
if BUILD_MANUAL
SUBDIRS = manual
-all-local: spice_style.html spice_threading_model.html
+all-local: $(HTML_FILES)
%.html: %.txt
$(AM_V_GEN) $(ASCIIDOC) -n $(ASCIIDOC_FLAGS) -o $@ $<
endif
clean-local:
- rm -f spice_style.html spice_threading_model.html
+ rm -f $(HTML_FILES)
diff --git a/docs/Vd_interfaces.odt b/docs/Vd_interfaces.odt
deleted file mode 100644
index 71da117d..00000000
Binary files a/docs/Vd_interfaces.odt and /dev/null differ
diff --git a/docs/vd_interfaces.txt b/docs/vd_interfaces.txt
new file mode 100644
index 00000000..12ca2011
--- /dev/null
+++ b/docs/vd_interfaces.txt
@@ -0,0 +1,643 @@
+= VD Interfaces V0.1: Red Hat, Inc
+:revnumber: v1.0
+:revdate: 01.01.2009
+:revremark: Draft 1
+
+Copyright (C) 2009 Red Hat, Inc. +
+Licensed under a Creative Commons Attribution-Share Alike 3.0 +
+United States License (see
+http://creativecommons.org/licenses/by-sa/3.0/us/legalcode). +
+
+:toc:
+
+== Introduction
+
+Virtual Device Interfaces (VDI) provide a standard way to publish interfaces of
+virtual devices by a software component. This enables other software components
+to interact with these devices. This also enables other software components to
+interact with these devices. Going forward, the first component will be called
+the back-end and the second component will be called the front-end. An example
+for using Virtual Device Interfaces is as part of a virtual machine system,
+where the back-end will be the hardware emulation layer. The back-end will
+expose interfaces like display port, mouse input etc. The front-end will plug
+into the display output and will render its output according to it's specific
+implementation. The front-end will also plug into the mouse input and send
+mouse events to be processed by the back-end. In addition many other interface
+types can be exposed by the back-end. Another example of back-end is a remote
+display system in a physical machine environment. Here, the back-and is
+implemented using known techniques for interacting with the native OS for the
+purpose of receiving display updates and pushing inputs. The back-end exposes
+interfaces like display output, mouse input etc. The front-end can be exactly
+the same as in the previous example.
+
+By using VDI one back-end can use many types of front-ends without any special
+code modification. It is also possible for the back-end to dynamically switch
+front-ends, and improve back-end usability and flexibility. The use of
+front-ends by many back-ends allows for a better sharing of development,
+maintenance, and overall product quality.
+
+== Basic operation
+
+Back-end to front-end interaction is initiated by back-end. Back-end uses
+VDI_init symbol to pass its Core interface to the front-end. In addition to
+core interface, back-end also passes options argument to the front-end. Options
+argument is a string holding initialization argument specific to front-end
+implementation. Core interface, like every other interface in VDI, is
+represented as a data structure containing data members and member functions.
+Every interface starts with a common base structure “VDInterface”. The common
+structure contains information for identifying the type of the interface and
+the instance within the type group (i.e. The actual unique is {type, id}). Core
+interface provides basic functionality for attaching with other interfaces that
+the back-end implements. Core interface provides methods for receiving
+interface change events (i.e. interface added event and removing interface
+event) and for enumerating registers. Using these services, the front-end can
+find and interact with other interfaces that back-end publishes. The front-end
+uses VDI type for knowing what functionality the interface provides and the
+means to interact with the interface (i.e interface specific logic function and
+data members).
+
+== Front-end public symbols
+
+VDI defines a minimal set of external symbols for enabling back-end to initiate
+with the front-end. The back-end can load front-end and retrieve front-end
+external symbols dynamically at run-time using native platform services.
+Alternatively, the front-end static or shared library can be linked to the
+back-end during back-end build process.
+
+[source,c]
+----
+int VDI_init(const char *args, CoreInterface *core)
+----
+
+Front-and initialization function. The first parameter is options argument, the
+content of which depends on the specific front-end. The second parameter is
+core interface that provides the basic communication channel between front-end
+and back-end, core interface will be explained later on. VDI_init return value
+is VDI_ERROR_?
+
+[source,c]
+----
+const char **VDI_get_usage()
+----
+
+This function return array of strings in human readable form for displaying the
+available options argument that can be pass in args parameter of VDI_init call.
+
+== Front-end termination
+
+No explicit symbol is defined for front-end termination. Removing core
+interface by back-end implicitly instructs front end to terminate itself.
+
+== Common Definition
+
+[source,c]
+----
+VDI_ERROR_OK = 0
+VDI_ERROR_ERROR = -1
+VM_INTERFACE_VERSION = 2 /*Current VDI version, front-end an back-end must have
+the same VDI version for proper operation. */
+----
+----
+VDIObjectRef – opaque object reference that passes between back-end and
+front-end
+----
+[source,c]
+----
+VDI_INVALID_OBJECT_REF = 0
+----
+== Base structure of VD interface.
+
+The following is definition of VD Interface, all VDI interfaces are derived
+from VD Interface.
+
+[source,c]
+----
+UINT32 version; /* VDI version must be VM_INTERFACE_VERSION */
+CONST CHAR *type; /* type of the interface */
+UNSIGNED INT id; /* unique id of the interface */
+CONST CHAR *description; /* interface human readable interface description*
+UINT32 major_version; /* interface major version. Front-end and back-end
+interfaces having different major_version are not compatible. */
+UINT32 minor_version; /* interface minor version. Minor version increments on
+changes that add functionality but do not break compatible and will be reset on
+major version increment. */
+----
+
+== Core Interface
+
+Core interface is the main interface for front-end to back-end communication.
+It is not allowed to have more the one interface with this type. Removal of
+Core interface by the back-end is explicit front-end termination.
+
+. VDInterface members value
++
+----
+type = “core”
+major_version = 1
+minor_version = 0
+id = 0
+----
++
+. Types
++
+[source,c]
+----
+VDI_CHANGE_NEW = 0
+VDI_CHANGE_REMOVING = 1
+----
++
+[source,c]
+----
+void (*vdi_interface_change_notifier_t)(void *opaque, VDInterface *interface,
+VDInterfaceChangeType change)
+----
++
+Callback for receiving notification event on adding and removing VDI
+interfaces.
++
+* opaque – back-end passes front-end's opaque value that was passed during
+notifier registration.
+* interface - the relevant interface
+* change – type of change VDI_CHANGE_NEW or VDI_CHANGE_REMOVING
+
++
+[source,c]
+----
+void (*timer_callback_t)(void *opaque)
+----
++
+Callback for receiving timer event.
++
+* opaque – back-end passes front-end's opaque value that was passed during
+timer registration.
+
++
+----
+VDI_LOG_LEVEL_ERROR = 1
+VDI_LOG_LEVEL_WARN = 2
+VDI_LOG_LEVEL_INFO = 3
+----
++
+[source,c]
+----
+VDInterface specific extension
+VDInterface *(* next)(CoreInterface *core, VDInterface *prev)
+----
++
+Get next interface – return interface following prev. If prev is NULL return
+first interface. If next return NULL then prev is the last interface. The
+function is used for interfaces discovery.
++
+[source,c]
+----
+VDIObjectRef (*register_change_notifier)(CoreInterface *core, void *opaque,
+vdi_interface_change_notifier_t in_notifier)
+----
++
+Register in_notifier to be called on interface change events. opaque will be
+pushed back by back-end in notify call. On success the function return notifier
+object ref otherwise VDI_INVALID_OBJECT_REF is returned.
++
+[source,c]
+----
+void (*unregister_change_notifiers)(CoreInterface *core, VDObjectRef notifier)
+----
++
+Unregister interface change notifier hat was registered using
+register_change_notifiers.
++
+[source,c]
+----
+VDIObjectRef (*create_timer)(CoreInterface *core, timer_callback_t callback,
+void* opaque)
+----
++
+Create timer object. The timer handler will call callback on time expiration.
+opaque will be pushed back by back-end in callback call. On success the
+function return timer object ref otherwise VDI_INVALID_OBJECT_REF is returned
++
+[source,c]
+----
+void (*arm_timer)(CoreInterface *core, VDIObjectRef timer, uint32_t ms)
+----
++
+Schedule timer object to fire it's callback after ms. Timer is VDI ref object
+returned by create_timer and ms is time in millisecond.
++
+[source,c]
+----
+void (*disarm_timer)(CoreInterface *core, VDIObjectRef timer)
+----
++
+Cancel previous arm_timer scheduling. Timer is VDI ref object returned by
+create_timer
++
+[source,c]
+----
+void (*destroy_timer)(CoreInterface *core, VDIObjectRef timer)
+----
++
+Destroy timer object. Timer is vdi ref object returned by create_timer.
++
+[source,c]
+----
+int (*set_file_handlers)(CoreInterface *core, int fd, void (*on_read)(void *),
+void (*on_write)(void *), void *opaque)
+----
++
+Request notification on file descriptor for non blocking operation. Fd is the
+target file descriptor. Back-end will call on_read, if not NULL, on read events
+passing opaque as first argument. Back-end will call on_write, if not NULL, on
+write events passing opaque as first argument. On success VDI_ERROR_OK is
+return.
++
+[source,c]
+----
+void (*term_printf)(CoreInterface *core, const char* format, ...)
+----
++
+Send message to back-end interactive terminal if exist. format is printf
+format, following format are variable arguments list that are format
+arguments.
++
+[source,c]
+----
+void (*log)(CoreInterface *core, LogLevel level, const char* component, const
+char* format, ...)
+----
++
+Send message to be logged using back-end logging service. Level is one of
+VDI_LOG_LEVEL_?. Component is component name that will be attached as prefix
+to the message. Format is printf format, following format are variable
+arguments list that are format arguments.
+Callback
+
+== Other interfaces
+
+Core interface is the only interface that is an integral part of VDI
+specifications. Any other interface can be defined independently of this
+specification. It's required that both the back-and the front-end know specific
+interface definitions for proper operation. The only restriction for defining
+new interface is to ensure the uniqueness of VD Interface type. The following
+interfaces are known VD interfaces that discussed here as a reference for
+better understanding of the specification.
+
+== Keyboard interface
+
+Keyboard interface exposes standard keyboard functionally. It enables pushing
+scan-code set 1 codes and getting keyboard LED information by query or change
+notifications mechanism.
+
+. VDInterface members value
++
+[source,c]
+----
+type = “keyboard”
+major_version = 1
+minor_version = 0
+id = keyboard instance id
+----
++
+. Types
++
+[source,c]
+----
+VDI_KEYBOARD_LED_SCROLL_LOCK 0
+VDI_KEYBOARD_LED_NUM_LOCK 1
+VDI_KEYBOARD_LED_CAPS_LOCK 2
+----
++
+[source,c]
+----
+void (*keyboard_leads_notifier_t)(void *opaque, uint8_t leds)
+----
++
+Callback for receiving notification event on keyboard LED changes.
++
+* opaque – back-end passed front-end's opaque value that was passed during
+notifier registration.
+* leds – current LED state mask. LED X is on if bit VDI_KEYBOARD_LED_X is set.
+
++
+. VDInterface specific extension
++
+[source,c]
+----
+void (*push_scan_freg)(KeyboardInterface *keyboard, uint8_t frag)
+----
++
+Push scan-code code fragment to the keyboard. Frag is part of scan code.
+For example calling:
++
+[source,c]
+----
+push_scan_freg(0xe0);
+push_scan_freg(0x1d);
+----
++
+will result with Right CTRL.
++
+[source,c]
+----
+uint8_t (*get_leds)(KeyboardInterface *keyboard)
+----
++
+Get current keyboard lads mask. Return lads mask
++
+[source,c]
+----
+VDIObjectRef (*register_leds_notifier)(KeyboardInterface *keyboard,
+keyboard_leads_notifier_t notifier, void *opaque)
+----
++
+Register for LED notification. Back-end will call notifier on every keyboard
+LED change. Opaque will be pushed back as notifier argument. On success, the
+function return notifier object ref otherwise VDI_INVALID_OBJECT_REF is
+returned.
++
+[source,c]
+----
+void (*unregister_leds_notifier)(KeyboardInterface *keyboard, VDObjectRef
+notifier)
+----
++
+Unregister LED change notifier that was registered using
+register_leds_notifier.
+
+== Mouse interface
+
+Mouse interface for pushing mouse motion and mouse buttons state events.
+
+. VDInterface members value
++
+[source,c]
+----
+type = “mouse”
+major_version = 1
+minor_version = 0
+id = mouse instance id
+----
++
+. Types
++
+[source,c]
+----
+VDI_MOUSE_BUTTON_LEFT 0
+VDI_MOUSE_BUTTON_RIGHT 1
+VDI_MOUSE_BUTTON_MIDEL 2
+----
++
+. VDInterface specific extension
++
+[source,c]
+----
+void (*motion)(MouseInterface* mouse, int dx, int dy, int dz, uint32_t
+buttons_state)
+----
++
+Push mouse motion and buttons state. dx and dy are mouse motion in pixels in x
+and y axis, positive dx is rightward motion and positive dy is downward motion.
+dz is scroll wheel ticks, positive value is scroll down. buttons_state is
+buttons state mask. Button X is press if bit VDI_MOUSE_BUTTON_X is set.
++
+[source,c]
+----
+void (*buttons)(MouseInterface* mouse, uint32_t buttons_state)
+----
++
+Push mouse buttons state. buttons_state is the same as in the motion call
+
+== Tablet interface
+
+Tablet interface for supporting absolute mouse pointing.
+
+. Interface members value
++
+[source,c]
+----
+type = “tablet”
+major_version = 1
+minor_version = 0
+id = tablet instance id
+----
++
+. Types
++
+[source,c]
+----
+VDI_TABLET_BUTTON_LEFT 0
+VDI_TABLET_BUTTON_RIGHT 1
+VDI_TABLET_BUTTON_MIDEL 2
+----
++
+. VDInterface specific extension
++
+[source,c]
+----
+void (*set_logical_size)(TabletInterface* tablet, int width, int height)
+----
++
+Set logical dimension of the tablet. The logical dimension will be used by the
+tablet device for mapping position to local coordinate system.
++
+[source,c]
+----
+void (*position)(TabletInterface* tablet, int x, int y, uint32_t buttons_state)
+----
++
+Push mouse position and mouse button state. {x, y} position is relative to the
+upper left corner. Positive value on x axis advances rightward and positive
+value on y axis advances downward. buttons_state is buttons state mask. Button
+X is press if bit VDI_TABLET_BUTTON_X is set.
++
+[source,c]
+----
+void (*wheel)(TabletInterface* tablet, int wheel_motion, uint32_t
+buttons_state)
+----
++
+Push scroll wheel motion and buttons state. wheel_motion is scroll sicks.
+positive wheel_motion is for scroll down. buttons_state is as in “position”
++
+[source,c]
+----
+void (*buttons)(TabletInterface* tablet, uint32_t buttons_state)
+----
++
+Push buttons state. buttons_state is as in “position”
+
+== Playback interface
+
+Playback interface for receiving audio stream for playback. Playback use fix
+audio configuration, channels = 2, frequency = 44100 and channel sample
+format signed 16bit.
+
+. VDInterface members value
++
+[source,c]
+----
+type = “playback”
+major_version = 1
+minor_version = 0
+id = playback instance id
+----
++
+. PlaybackPlug
++
+[source,c]
+----
+uint32_t major_version
+----
++
+plug major version. Changing major version breaks compatibility.
++
+[source,c]
+----
+uint32_t minor_version
+----
++
+interface minor version. Minor version increments on changes that add
+functionality but do not break compatible and will be reset on major version
+increment.
++
+[source,c]
+----
+void (*start)(PlaybackPlug *plug)
+----
++
+back-end will call this callback while staring audio playback
++
+[source,c]
+----
+void (*stop)(PlaybackPlug *plug)
+----
++
+back-end will call this callback while stopping audio playback
++
+[source,c]
+----
+void (*get_frame)(PlaybackPlug *plug, uint32_t **frame, uint32_t *samples)
+----
++
+back-end will call this callback for getting audio frame. On return *frame will
+point to audio frame capable of holding *samples samples (i.e frame size is
+samples * 4). The frame will be pushed back filled with audio samples by the
+back-end. If no frame is available *frame will be NULL.
++
+[source,c]
+----
+void (*put_frame)(PlaybackPlug *plug, uint32_t *frame)
+----
++
+back-end will call this callback to deliver audio frame for playback. Frame is
+one that was returns by get_frame. This call also moves frame ownership back to
+the front-end.
+
+. VDInterface specific extension
++
+[source,c]
+----
+VDIObjectRef (*plug)(PlaybackInterface *playback, PlaybackPlug* plug, int
+*active)
+----
++
+Attach playback plug to playback interface instance. Plug is the plug to
+attach. On return, active will be 0 if playback is stopped and 1 if playback is
+running. On success, the function return object ref otherwise
+VDI_INVALID_OBJECT_REF is returned.
++
+[source,c]
+----
+void (*unplug)(PlaybackInterface *playback, VDIObjectRef)
+----
++
+Unplug playback that was plugged using plug.
+
+== Record interface
+
+Record interface for pushing audio capture to back-end. Record use fix audio
+configuration, channels = 2, frequency = 44100 and channel sample format
+signed 16bit.
+
+. VDInterface members value
++
+[source,c]
+----
+type = “record”
+major_version = 1
+minor_version = 0
+id = record instance id
+----
+
+. RecordPlug
++
+[source,c]
+----
+uint32_t minor_version
+----
++
+plug major version. Changing major version breaks compatibility.
++
+[source,c]
+----
+uint32_t major_version
+----
++
+interface minor version. Minor version increments on changes that add
+functionality but do not break compatible and will be reset on major version
+increment.
++
+[source,c]
+----
+void (*start)(RecordPlug *plug)
+----
++
+back-end will call this callback for staring audio capture
++
+[source,c]
+----
+void (*stop)(RecordPlug *plug)
+----
++
+back-end will call this callback to stop audio capture
++
+[source,c]
+----
+uint32_t (*read)(RecordPlug *plug, uint32_t num_samples, uint32_t *samples)
+----
++
+back-end will call this callback to receive audio capture samples. num_samples
+is the requested number samples. Samples is buffer for receiving samples (i.e
+samples size is num_samples * 4). Read return number of samples returned.
+
+. VDInterface specific extension
++
+[source,c]
+----
+VDIObjectRef (*plug)(RecordInterface *recorder, RecordPlug* plug, int *active)
+----
++
+Attach record plug to interface instance. Plug is the plug to attach. On
+return, active will be 0 if record is stopped and 1 if record is running. On
+success, the function return object ref otherwise VDI_INVALID_OBJECT_REF is
+returned.
++
+[source,c]
+----
+void (*unplug)(RecordInterface *recorder, VDIObjectRef)
+----
++
+Unplug record plug that was plugged using plug.
+
+== Additional registered interfaces
+
+* QXL interface "qxl" – QXL interface enable front-end to plug into QXL display
+device in order to receive QXL and to render it's output locally or remotely.
+* VDI port interface "vdi_port" – interface for plugging, reading and writing
+to vdi_port. vdi_port is used for communication with an agent residing on gust
+machine.
+* Migration interface "migration" - interface for integrating with back-end
+migration process. This interface enable registering for pre and post migration
+hooks.
+* Qemu terminal interface "qemu_terminal" – interface for integrating with
+QEMU style terminal.
More information about the Spice-commits
mailing list