This brings explicit context initialization and different types
to virtio-gpu.
In the past, VIRTIO_GPU_F_VIRGL meant the virglrenderer support.
With VIRTIO_GPU_F_VIRGL + VIRTIO_GPU_F_CONTEXT_INIT, this means
generic 3D virtualization defined by the context type. It's
entirely possible the virglrenderer project isn't available on
the host in this scenario. The VIRTIO_GPU_F_VIRGL naming
convention is kept since it's easier to redefine the meaning
rather than changing header files.
The context type is associated an particular capset id. Virgl
has two capsets due a prior bug, but for other cases the 1:1
mapping between context type and capset id is valid.
In addition, fencing needs to be fixed to accomodate multiple
context types. In the past, there was one global timeline
associated witht the OpenGL rendering. Now, there are multiple
timelines which can be associated with GL, VK or even display
contexts.
v2: Correct number of bits
v3: le32 info --> {u8 ring_idx + u8 padding[3])
Don't require FLAG_FENCE and FLAG_RING_IDX
Signed-off-by: Gurchetan Singh <
gurchetansingh@chromium.org>
---
virtio-gpu.tex | 72 +++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 60 insertions(+), 12 deletions(-)
diff --git a/virtio-gpu.tex b/virtio-gpu.tex
index 35c129f..4435248 100644
--- a/virtio-gpu.tex
+++ b/virtio-gpu.tex
@@ -1,14 +1,10 @@
\section{GPU Device}\label{sec:Device Types / GPU Device}
virtio-gpu is a virtio based graphics adapter. It can operate in 2D
-mode and in 3D (virgl) mode. 3D mode will offload rendering ops to
+mode and in 3D mode. 3D mode will offload rendering ops to
the host gpu and therefore requires a gpu with 3D support on the host
machine.
-3D mode is not covered (yet) in this specification, even though it is
-mentioned here and there due to some details of the virtual hardware
-being designed with 3D mode in mind.
-
In 2D mode the virtio-gpu device provides support for ARGB Hardware
cursors and multiple scanouts (aka heads).
@@ -39,6 +35,8 @@ \subsection{Feature bits}\label{sec:Device Types / GPU Device / Feature bits}
to other virtio devices is supported.
\item[VIRTIO_GPU_F_RESOURCE_BLOB (3)] creating and using size-based blob
resources is supported.
+\item[VIRTIO_GPU_F_CONTEXT_INIT (4)] multiple context types and
+ synchronization timelines supported. Requires VIRTIO_GPU_F_VIRGL.
\end{description}
\subsection{Device configuration layout}\label{sec:Device Types / GPU Device / Device configuration layout}
@@ -214,7 +212,7 @@ \subsubsection{Device Operation: Request header}\label{sec:Device Types / GPU De
VIRTIO_GPU_CMD_RESOURCE_CREATE_BLOB,
VIRTIO_GPU_CMD_SET_SCANOUT_BLOB,
- /* 3d commands (OpenGL) */
+ /* 3d commands */
VIRTIO_GPU_CMD_CTX_CREATE = 0x0200,
VIRTIO_GPU_CMD_CTX_DESTROY,
VIRTIO_GPU_CMD_CTX_ATTACH_RESOURCE,
@@ -249,13 +247,15 @@ \subsubsection{Device Operation: Request header}\label{sec:Device Types / GPU De
};
#define VIRTIO_GPU_FLAG_FENCE (1 << 0)
+#define VIRTIO_GPU_FLAG_INFO_RING_IDX (1 << 1)
struct virtio_gpu_ctrl_hdr {
le32 type;
le32 flags;
le64 fence_id;
le32 ctx_id;
- le32 padding;
+ u8 ring_idx;
+ u8 padding[3];
};
\end{lstlisting}
@@ -275,6 +275,20 @@ \subsubsection{Device Operation: Request header}\label{sec:Device Types / GPU De
\item send the response only after command processing is complete.
\end{itemize*}
\item[\field{ctx_id}] Rendering context (used in 3D mode only).
+\item[\field{ring_idx}] If VIRTIO_GPU_F_CONTEXT_INIT is supported, then
+ the driver MAY set VIRTIO_GPU_FLAG_INFO_RING_IDX bit in the request
+ \field{flags}. In that case:
+ \begin{itemize*}
+ \item \field{ring_idx} indicates the value of a context-specific ring
+ index. The minimum value is 0 and maximum value is 63 (inclusive).
+ \item If VIRTIO_GPU_FLAG_FENCE is set, \field{fence_id} acts as a
+ sequence number on the synchronization timeline defined by
+ \field{ctx_idx} and the ring index.
+ \item If VIRTIO_GPU_FLAG_FENCE is set and when the command associated
+ with \field{fence_id} is complete, the device MUST send a response for
+ all outstanding commands with a sequence number less than or equal to
+ \field{fence_id} on the same synchronization timeline.
+ \end{itemize*}
\end{description}
On success the device will return VIRTIO_GPU_RESP_OK_NODATA in
@@ -516,6 +530,12 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device /
the first edition of Virgl (Gallium OpenGL) protocol.
\item \href{https://gitlab.freedesktop.org/virgl/virglrenderer/-/blob/master/src/virgl_hw.h#L550}{VIRTIO_GPU_CAPSET_VIRGL2} --
the second edition of Virgl (Gallium OpenGL) protocol after the capset fix.
+ \item \href{https://android.googlesource.com/device/generic/vulkan-cereal/+/refs/heads/master/protocols/}{VIRTIO_GPU_CAPSET_GFXSTREAM} --
+ gfxtream's (mostly) autogenerated GLES and Vulkan streaming protocols.
+ \item \href{https://gitlab.freedesktop.org/olv/venus-protocol}{VIRTIO_GPU_CAPSET_VENUS} --
+ Mesa's (mostly) autogenerated Vulkan protocol.
+ \item \href{https://chromium.googlesource.com/chromiumos/platform/crosvm/+/refs/heads/main/rutabaga_gfx/src/cross_domain/cross_domain_protocol.rs}{VIRTIO_GPU_CAPSET_CROSS_DOMAIN} --
+ protocol for display virtualization via Wayland proxying.
\end{itemize*}
\begin{lstlisting}
@@ -527,6 +547,9 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device /
#define VIRTIO_GPU_CAPSET_VIRGL 1
#define VIRTIO_GPU_CAPSET_VIRGL2 2
+#define VIRTIO_GPU_CAPSET_GFXSTREAM 3
+#define VIRTIO_GPU_CAPSET_VENUS 4
+#define VIRTIO_GPU_CAPSET_CROSS_DOMAIN 5
struct virtio_gpu_resp_capset_info {
struct virtio_gpu_ctrl_hdr hdr;
le32 capset_id;
@@ -684,21 +707,46 @@ \subsubsection{Device Operation: controlq (3d)}\label{sec:Device Types / GPU Dev
\begin{description}
-\item[VIRTIO_GPU_CMD_CTX_CREATE]
+\item[VIRTIO_GPU_CMD_CTX_CREATE] creates a context for submitting an opaque
+ command stream. Request data is \field{struct virtio_gpu_ctx_create}.
+ Response type is VIRTIO_GPU_RESP_OK_NODATA.
+
+\begin{lstlisting}
+#define VIRTIO_GPU_CONTEXT_INIT_CAPSET_ID_MASK 0x000000ff;
+struct virtio_gpu_ctx_create {
+ struct virtio_gpu_ctrl_hdr hdr;
+ le32 nlen;
+ le32 context_init;
+ char debug_name[64];
+};
+\end{lstlisting}
+
+The implementation MUST create a context for the given \field{ctx_id} in
+the \field{hdr}. For debugging purposes, a \field{debug_name} and it's
+length \field{nlen} is provided by the driver. If
+VIRTIO_GPU_F_CONTEXT_INIT is supported, then lower 8 bits of
+\field{context_init} MAY contain the \field{capset_id} associated with
+context. In that case, then the device MUST create a context that can
+handle the specified command stream.
+
+If the lower 8-bits of the \field{context_init} are zero, then the type of
+the context is determined by the device.
+
\item[VIRTIO_GPU_CMD_CTX_DESTROY]
\item[VIRTIO_GPU_CMD_CTX_ATTACH_RESOURCE]
\item[VIRTIO_GPU_CMD_CTX_DETACH_RESOURCE]
- Manage OpenGL contexts.
+ Manage virtio-gpu 3d contexts.
\item[VIRTIO_GPU_CMD_RESOURCE_CREATE_3D]
- Create OpenGL resources.
+ Create virtio-gpu 3d resources.
\item[VIRTIO_GPU_CMD_TRANSFER_TO_HOST_3D]
\item[VIRTIO_GPU_CMD_TRANSFER_FROM_HOST_3D]
- Transfer data from and to OpenGL resources.
+ Transfer data from and to virtio-gpu 3d resources.
\item[VIRTIO_GPU_CMD_SUBMIT_3D]
- Submit rendering commands (mesa gallium command stream).
+ Submit an opaque command stream. The type of the command stream is
+ determined when creating a context.
\item[VIRTIO_GPU_CMD_RESOURCE_MAP_BLOB] maps a host-only
blob resource into an offset in the host visible memory region. Request
--
2.31.0