qemu/docs/interop/vhost-user-gpu.rst
Peter Maydell 4e0b15c252 docs: Move licence/copyright from HTML output to rST comments
Our built HTML documentation now has a standard footer which
gives the license for QEMU (and its documentation as a whole).
In almost all pages, we either don't bother to state the
copyright/license for the individual rST sources, or we put
it in an rST comment. There are just three pages which render
copyright or license information into the user-visible HTML.

Quoting a specific (different) license for an individual HTML
page within the manual is confusing. Downgrade the license
and copyright info to a comment within the rST source, bringing
these pages in line with the rest of our documents.

Suggested-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Acked-by: Michael S. Tsirkin <mst@redhat.com>
Message-id: 20210722192016.24915-3-peter.maydell@linaro.org
2021-08-02 11:42:38 +01:00

244 lines
6.2 KiB
ReStructuredText

=======================
Vhost-user-gpu Protocol
=======================
..
Licence: This work is licensed under the terms of the GNU GPL,
version 2 or later. See the COPYING file in the top-level
directory.
.. contents:: Table of Contents
Introduction
============
The vhost-user-gpu protocol is aiming at sharing the rendering result
of a virtio-gpu, done from a vhost-user slave process to a vhost-user
master process (such as QEMU). It bears a resemblance to a display
server protocol, if you consider QEMU as the display server and the
slave as the client, but in a very limited way. Typically, it will
work by setting a scanout/display configuration, before sending flush
events for the display updates. It will also update the cursor shape
and position.
The protocol is sent over a UNIX domain stream socket, since it uses
socket ancillary data to share opened file descriptors (DMABUF fds or
shared memory). The socket is usually obtained via
``VHOST_USER_GPU_SET_SOCKET``.
Requests are sent by the *slave*, and the optional replies by the
*master*.
Wire format
===========
Unless specified differently, numbers are in the machine native byte
order.
A vhost-user-gpu message (request and reply) consists of 3 header
fields and a payload.
+---------+-------+------+---------+
| request | flags | size | payload |
+---------+-------+------+---------+
Header
------
:request: ``u32``, type of the request
:flags: ``u32``, 32-bit bit field:
- Bit 2 is the reply flag - needs to be set on each reply
:size: ``u32``, size of the payload
Payload types
-------------
Depending on the request type, **payload** can be:
VhostUserGpuCursorPos
^^^^^^^^^^^^^^^^^^^^^
+------------+---+---+
| scanout-id | x | y |
+------------+---+---+
:scanout-id: ``u32``, the scanout where the cursor is located
:x/y: ``u32``, the cursor position
VhostUserGpuCursorUpdate
^^^^^^^^^^^^^^^^^^^^^^^^
+-----+-------+-------+--------+
| pos | hot_x | hot_y | cursor |
+-----+-------+-------+--------+
:pos: a ``VhostUserGpuCursorPos``, the cursor location
:hot_x/hot_y: ``u32``, the cursor hot location
:cursor: ``[u32; 64 * 64]``, 64x64 RGBA cursor data (PIXMAN_a8r8g8b8 format)
VhostUserGpuScanout
^^^^^^^^^^^^^^^^^^^
+------------+---+---+
| scanout-id | w | h |
+------------+---+---+
:scanout-id: ``u32``, the scanout configuration to set
:w/h: ``u32``, the scanout width/height size
VhostUserGpuUpdate
^^^^^^^^^^^^^^^^^^
+------------+---+---+---+---+------+
| scanout-id | x | y | w | h | data |
+------------+---+---+---+---+------+
:scanout-id: ``u32``, the scanout content to update
:x/y/w/h: ``u32``, region of the update
:data: RGB data (PIXMAN_x8r8g8b8 format)
VhostUserGpuDMABUFScanout
^^^^^^^^^^^^^^^^^^^^^^^^^
+------------+---+---+---+---+-----+-----+--------+-------+--------+
| scanout-id | x | y | w | h | fdw | fwh | stride | flags | fourcc |
+------------+---+---+---+---+-----+-----+--------+-------+--------+
:scanout-id: ``u32``, the scanout configuration to set
:x/y: ``u32``, the location of the scanout within the DMABUF
:w/h: ``u32``, the scanout width/height size
:fdw/fdh/stride/flags: ``u32``, the DMABUF width/height/stride/flags
:fourcc: ``i32``, the DMABUF fourcc
C structure
-----------
In QEMU the vhost-user-gpu message is implemented with the following struct:
.. code:: c
typedef struct VhostUserGpuMsg {
uint32_t request; /* VhostUserGpuRequest */
uint32_t flags;
uint32_t size; /* the following payload size */
union {
VhostUserGpuCursorPos cursor_pos;
VhostUserGpuCursorUpdate cursor_update;
VhostUserGpuScanout scanout;
VhostUserGpuUpdate update;
VhostUserGpuDMABUFScanout dmabuf_scanout;
struct virtio_gpu_resp_display_info display_info;
uint64_t u64;
} payload;
} QEMU_PACKED VhostUserGpuMsg;
Protocol features
-----------------
None yet.
As the protocol may need to evolve, new messages and communication
changes are negotiated thanks to preliminary
``VHOST_USER_GPU_GET_PROTOCOL_FEATURES`` and
``VHOST_USER_GPU_SET_PROTOCOL_FEATURES`` requests.
Communication
=============
Message types
-------------
``VHOST_USER_GPU_GET_PROTOCOL_FEATURES``
:id: 1
:request payload: N/A
:reply payload: ``u64``
Get the supported protocol features bitmask.
``VHOST_USER_GPU_SET_PROTOCOL_FEATURES``
:id: 2
:request payload: ``u64``
:reply payload: N/A
Enable protocol features using a bitmask.
``VHOST_USER_GPU_GET_DISPLAY_INFO``
:id: 3
:request payload: N/A
:reply payload: ``struct virtio_gpu_resp_display_info`` (from virtio specification)
Get the preferred display configuration.
``VHOST_USER_GPU_CURSOR_POS``
:id: 4
:request payload: ``VhostUserGpuCursorPos``
:reply payload: N/A
Set/show the cursor position.
``VHOST_USER_GPU_CURSOR_POS_HIDE``
:id: 5
:request payload: ``VhostUserGpuCursorPos``
:reply payload: N/A
Set/hide the cursor.
``VHOST_USER_GPU_CURSOR_UPDATE``
:id: 6
:request payload: ``VhostUserGpuCursorUpdate``
:reply payload: N/A
Update the cursor shape and location.
``VHOST_USER_GPU_SCANOUT``
:id: 7
:request payload: ``VhostUserGpuScanout``
:reply payload: N/A
Set the scanout resolution. To disable a scanout, the dimensions
width/height are set to 0.
``VHOST_USER_GPU_UPDATE``
:id: 8
:request payload: ``VhostUserGpuUpdate``
:reply payload: N/A
Update the scanout content. The data payload contains the graphical bits.
The display should be flushed and presented.
``VHOST_USER_GPU_DMABUF_SCANOUT``
:id: 9
:request payload: ``VhostUserGpuDMABUFScanout``
:reply payload: N/A
Set the scanout resolution/configuration, and share a DMABUF file
descriptor for the scanout content, which is passed as ancillary
data. To disable a scanout, the dimensions width/height are set
to 0, there is no file descriptor passed.
``VHOST_USER_GPU_DMABUF_UPDATE``
:id: 10
:request payload: ``VhostUserGpuUpdate``
:reply payload: empty payload
The display should be flushed and presented according to updated
region from ``VhostUserGpuUpdate``.
Note: there is no data payload, since the scanout is shared thanks
to DMABUF, that must have been set previously with
``VHOST_USER_GPU_DMABUF_SCANOUT``.