[PATCH v1] virtio-gpu: Document new fence-passing feature

[Dmitry Osipenko <dmitry.osipenko@collabora.com>]

Document new virtio-gpu protocol fence-passing feature that extends 3d
submit command with support of in-fences which are passed from guest to
host for waiting. This feature allows to offload waiting for in-fences
from guest to host, where it can be done more efficiently.

Signed-off-by: Dmitry Osipenko <dmitry.osipenko@collabora.com>
---
 device-types/gpu/description.tex | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex
index 443524851a05..e5e23b5c9072 100644
--- a/device-types/gpu/description.tex
+++ b/device-types/gpu/description.tex
@@ -37,6 +37,8 @@ \subsection{Feature bits}\label{sec:Device Types / GPU Device / Feature bits}
   resources is supported.
 \item[VIRTIO_GPU_F_CONTEXT_INIT (4)] multiple context types and
   synchronization timelines supported.  Requires VIRTIO_GPU_F_VIRGL.
+\item[VIRTIO_GPU_F_FENCE_PASSING (5)] passing fence IDs from guest to host
+  for waiting supported.  Requires VIRTIO_GPU_F_VIRGL.
 \end{description}
 
 \subsection{Device configuration layout}\label{sec:Device Types / GPU Device / Device configuration layout}
@@ -746,7 +748,25 @@ \subsubsection{Device Operation: controlq (3d)}\label{sec:Device Types / GPU Dev
 
 \item[VIRTIO_GPU_CMD_SUBMIT_3D]
   Submit an opaque command stream.  The type of the command stream is
-  determined when creating a context.
+  determined when creating a context.  Request data is
+  \field{struct virtio_gpu_cmd_submit}.  The \field{size} field describes
+  the size of \field{cmd_data} array in bytes.  The \field{num_in_fences}
+  field is active only if VIRTIO_GPU_F_FENCE_PASSING is enabled, otherwise
+  \field{num_in_fences} is treated as zero.  The array of \field{in_fences}
+  IDs is placed in between the \field{num_in_fences} field and the
+  \field{cmd_data} array.  The \field{in_fences} array contains virtio-gpu
+  \field{fence_id}'s corresponding to the out-fence IDs of a previous
+  3d submits.
+
+\begin{lstlisting}
+struct virtio_gpu_cmd_submit {
+        struct virtio_gpu_ctrl_hdr hdr;
+        le32 size;
+        le32 num_in_fences;
+        le64 in_fences[num_in_fences];
+        u32 cmd_data[size/4];
+};
+\end{lstlisting}
 
 \item[VIRTIO_GPU_CMD_RESOURCE_MAP_BLOB] maps a host-only
   blob resource into an offset in the host visible memory region. Request
-- 
2.43.0