[PATCH v2] virtio-gpu: support blob alignment information

[PATCH v2] virtio-gpu: support blob alignment information

[Sergio Lopez]

Allow the device to require certain alignment constrains for blob
resources by extending the device configuration with the field
"blob_alignment" and introducing the VIRTIO_GPU_F_BLOB_ALIGNMENT
feature.

v2:
 - Clarify blob_alignment valid values (thanks Michael).
 - Rephrase feature negotiation (thanks Michael).

Signed-off-by: Sergio Lopez <slp@redhat.com>
---
 device-types/gpu/description.tex | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex
index 4435248..b3e75d3 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_BLOB_ALIGNMENT (5)] configuration field
+  \field{blob_alignment} is valid. Requires VIRTIO_GPU_F_RESOURCE_BLOB.
 \end{description}
 
 \subsection{Device configuration layout}\label{sec:Device Types / GPU Device / Device configuration layout}
@@ -52,6 +54,7 @@ \subsection{Device configuration layout}\label{sec:Device Types / GPU Device / D
         le32 events_clear;
         le32 num_scanouts;
         le32 num_capsets;
+        le32 blob_alignment;
 };
 \end{lstlisting}
 
@@ -67,6 +70,9 @@ \subsubsection{Device configuration fields}
   supported by the device.  Minimum value is 1, maximum value is 16.
 \item[\field{num_capsets}] specifies the maximum number of capability
   sets supported by the device.  The minimum value is zero.
+\item[\field{blob_alignment}] specifies the minimal alignment, in bytes,
+  required by the device for resource blobs.  The value must a power of
+  two.  Minimum value is 1, maximum value is 4294967296.
 \end{description}
 
 \subsubsection{Events}
@@ -672,6 +678,9 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device /
 resource. There is no restriction on the image/buffer view the driver
 has on the blob resource.
 
+If VIRTIO_GPU_F_BLOB_ALIGNMENT has been negotiated, \field{size} must be
+aligned to \field{blob_alignment} as defined in the device configuration.
+
 \item[VIRTIO_GPU_CMD_SET_SCANOUT_BLOB] sets scanout parameters for a
    blob resource. Request data is
   \field{struct virtio_gpu_set_scanout_blob}. Response type is
@@ -776,6 +785,10 @@ \subsubsection{Device Operation: controlq (3d)}\label{sec:Device Types / GPU Dev
 };
 \end{lstlisting}
 
+If VIRTIO_GPU_F_BLOB_ALIGNMENT has been negotiated, \field{padding} and
+\field{offset} must be aligned to \field{blob_alignment} as defined in the
+device configuration.
+
 \item[VIRTIO_GPU_CMD_RESOURCE_UNMAP_BLOB] unmaps a
   host-only blob resource from the host visible memory region. Request data
   is \field{struct virtio_gpu_resource_unmap_blob}.  Response type is
-- 
2.49.0

Re: [PATCH v2] virtio-gpu: support blob alignment information

[Michael S. Tsirkin]

On Wed, Apr 09, 2025 at 05:23:24PM -0400, Sergio Lopez wrote:
> Allow the device to require certain alignment constrains for blob
> resources by extending the device configuration with the field
> "blob_alignment" and introducing the VIRTIO_GPU_F_BLOB_ALIGNMENT
> feature.

could you add a bit more info about the use-case here?

> v2:
>  - Clarify blob_alignment valid values (thanks Michael).
>  - Rephrase feature negotiation (thanks Michael).


versioning after --- please.

> 
> Signed-off-by: Sergio Lopez <slp@redhat.com>
> ---
>  device-types/gpu/description.tex | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/device-types/gpu/description.tex b/device-types/gpu/description.tex
> index 4435248..b3e75d3 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_BLOB_ALIGNMENT (5)] configuration field
> +  \field{blob_alignment} is valid. Requires VIRTIO_GPU_F_RESOURCE_BLOB.
>  \end{description}
>  
>  \subsection{Device configuration layout}\label{sec:Device Types / GPU Device / Device configuration layout}
> @@ -52,6 +54,7 @@ \subsection{Device configuration layout}\label{sec:Device Types / GPU Device / D
>          le32 events_clear;
>          le32 num_scanouts;
>          le32 num_capsets;
> +        le32 blob_alignment;
>  };
>  \end{lstlisting}
>  
> @@ -67,6 +70,9 @@ \subsubsection{Device configuration fields}
>    supported by the device.  Minimum value is 1, maximum value is 16.
>  \item[\field{num_capsets}] specifies the maximum number of capability
>    sets supported by the device.  The minimum value is zero.
> +\item[\field{blob_alignment}] specifies the minimal alignment, in bytes,
> +  required by the device for resource blobs.  The value must a power of

is a power

> +  two.  Minimum value is 1, maximum value is 4294967296.
>  \end{description}
>  
>  \subsubsection{Events}
> @@ -672,6 +678,9 @@ \subsubsection{Device Operation: controlq}\label{sec:Device Types / GPU Device /
>  resource. There is no restriction on the image/buffer view the driver
>  has on the blob resource.
>  
> +If VIRTIO_GPU_F_BLOB_ALIGNMENT has been negotiated, \field{size} must be
> +aligned to \field{blob_alignment} as defined in the device configuration.

is aligned here. And add a cnformance statement using MUST.

> +
>  \item[VIRTIO_GPU_CMD_SET_SCANOUT_BLOB] sets scanout parameters for a
>     blob resource. Request data is
>    \field{struct virtio_gpu_set_scanout_blob}. Response type is
> @@ -776,6 +785,10 @@ \subsubsection{Device Operation: controlq (3d)}\label{sec:Device Types / GPU Dev
>  };
>  \end{lstlisting}
>  
> +If VIRTIO_GPU_F_BLOB_ALIGNMENT has been negotiated, \field{padding} and
> +\field{offset} must be aligned to \field{blob_alignment} as defined in the
> +device configuration.

same. here just a statement "are aligned". and add a conformance
statement.

> +
>  \item[VIRTIO_GPU_CMD_RESOURCE_UNMAP_BLOB] unmaps a
>    host-only blob resource from the host visible memory region. Request data
>    is \field{struct virtio_gpu_resource_unmap_blob}.  Response type is
> -- 
> 2.49.0

Re: [PATCH v2] virtio-gpu: support blob alignment information

[Daniel Verkamp]

On Thu, Apr 10, 2025 at 6:38 AM Sergio Lopez <slp@redhat.com> wrote:
>
> Allow the device to require certain alignment constrains for blob
> resources by extending the device configuration with the field
> "blob_alignment" and introducing the VIRTIO_GPU_F_BLOB_ALIGNMENT
> feature.
>
> v2:
>  - Clarify blob_alignment valid values (thanks Michael).
>  - Rephrase feature negotiation (thanks Michael).
[...]
> +If VIRTIO_GPU_F_BLOB_ALIGNMENT has been negotiated, \field{padding} and
> +\field{offset} must be aligned to \field{blob_alignment} as defined in the
> +device configuration.

What does it mean for padding to be aligned? It seems like the padding
field in struct virtio_gpu_resource_map_blob is only present so that
the following 64-bit offset field is naturally aligned; the existing
spec doesn't assign any meaning to the value of padding itself. (It
should probably be specified as "caller must fill with 0" or just
reserved, but that's a separate issue.)

Thanks,
-- Daniel