[Spice-devel] [RFC 2/2] add shared memory display channel support

[Alon Levy]

The new protocol is an extension optionally supported by the client if setting this capability bit.

It includes 4 new messages, 3 are new messages (SHM_OFFER, SHM_REPLY,
SHM_DAMAGE) and one replaces an existing message (SURFACE_CREATE_SHM replaces
SURFACE_CREATE), plus a capability bit that both server and client advertise
(SPICE_DISPLAY_CAP_SHARED_MEMORY).

If the server sees the client capability, it will send MSG_DISPLAY_SHM_OFFER right after the display channel handshake.

client replies with MSGC_DISPLAY_SHM_REPLY
 - accepted = 0
  - nothing changes, return to normal behavior
 - accepted = 1
  - shared memory behavior commences as described below.

In shared memory mode:
1. every message read from the qxl device (via the qxl interface interface_get_command) is:
1.1 immediately rendered into the framebuffer
    * since the framebuffer is a shared memory segment, the client can immediately use it.
1.2 server will send a MSG_DISPLAY_SHM_DAMAGE message with the clips buffer from the render command
2. no offscreen surfaces will ever be sent
3. all messages creating/destroying the primary surface (i.e. resolution changes) will be sent as usual, with SURFACE_CREATE_SHM being used, it includes a new field, shm_offset, which allows having multiple primary surfaces on the qemu side being switched between. This is useful for the vga mode where the qxl framebuffer has bpp != 32 and there exists a shadow framebuffer at 32 bpp which will then be used as the primary surface for the spice client.
4. the cursor channel is unaffected (possible future optimization).

Future: preventing tearing by adding a MSGC_DISPLAY_SHM_DAMAGE_HANDLED:

Server      render DAMAGE\              /render DAMAGE\
Client                    \     HANDLED/               \ ...
-------->------->------->------->------->------->------->------->
---
 spice/enums.h    | 4 ++++
 spice/protocol.h | 1 +
 2 files changed, 5 insertions(+)

diff --git a/spice/enums.h b/spice/enums.h
index 7be34eb..720dcf5 100644
--- a/spice/enums.h
+++ b/spice/enums.h
@@ -472,6 +472,9 @@ enum {
     SPICE_MSG_DISPLAY_MONITORS_CONFIG,
     SPICE_MSG_DISPLAY_DRAW_COMPOSITE,
     SPICE_MSG_DISPLAY_STREAM_ACTIVATE_REPORT,
+    SPICE_MSG_DISPLAY_SHM_OFFER,
+    SPICE_MSG_DISPLAY_SHM_DAMAGE,
+    SPICE_MSG_DISPLAY_SURFACE_CREATE_SHM,
 
     SPICE_MSG_END_DISPLAY
 };
@@ -479,6 +482,7 @@ enum {
 enum {
     SPICE_MSGC_DISPLAY_INIT = 101,
     SPICE_MSGC_DISPLAY_STREAM_REPORT,
+    SPICE_MSGC_DISPLAY_SHM_REPLY,
 
     SPICE_MSGC_END_DISPLAY
 };
diff --git a/spice/protocol.h b/spice/protocol.h
index e11f384..cc69892 100644
--- a/spice/protocol.h
+++ b/spice/protocol.h
@@ -131,6 +131,7 @@ enum {
     SPICE_DISPLAY_CAP_COMPOSITE,
     SPICE_DISPLAY_CAP_A8_SURFACE,
     SPICE_DISPLAY_CAP_STREAM_REPORT,
+    SPICE_DISPLAY_CAP_SHARED_MEMORY,
 };
 
 enum {
-- 
1.8.3.1