[PATCH] virtio_snd.h: clarify that `controls` depends on VIRTIO_SND_F_CTLS

[PATCH] virtio_snd.h: clarify that `controls` depends on VIRTIO_SND_F_CTLS

[Stefano Garzarella]

As defined in the specification, the `controls` field in the configuration
space is only valid/present if VIRTIO_SND_F_CTLS is negotiated.

  From https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html:

  5.14.4 Device Configuration Layout
    ...
    controls
       (driver-read-only) indicates a total number of all available control
       elements if VIRTIO_SND_F_CTLS has been negotiated.

Let's use the same style used in virtio_blk.h to clarify this and to avoid
confusion as happened in QEMU (see link).

Link: https://gitlab.com/qemu-project/qemu/-/issues/2805
Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
---
 include/uapi/linux/virtio_snd.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/uapi/linux/virtio_snd.h b/include/uapi/linux/virtio_snd.h
index 5f4100c2cf04..a4cfb9f6561a 100644
--- a/include/uapi/linux/virtio_snd.h
+++ b/include/uapi/linux/virtio_snd.h
@@ -25,7 +25,7 @@ struct virtio_snd_config {
 	__le32 streams;
 	/* # of available channel maps */
 	__le32 chmaps;
-	/* # of available control elements */
+	/* # of available control elements (if VIRTIO_SND_F_CTLS) */
 	__le32 controls;
 };
 
-- 
2.48.1

Re: [PATCH] virtio_snd.h: clarify that `controls` depends on VIRTIO_SND_F_CTLS

[Eugenio Perez Martin]

On Thu, Feb 13, 2025 at 5:18 PM Stefano Garzarella <sgarzare@redhat.com> wrote:
>
> As defined in the specification, the `controls` field in the configuration
> space is only valid/present if VIRTIO_SND_F_CTLS is negotiated.
>
>   From https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html:
>
>   5.14.4 Device Configuration Layout
>     ...
>     controls
>        (driver-read-only) indicates a total number of all available control
>        elements if VIRTIO_SND_F_CTLS has been negotiated.
>
> Let's use the same style used in virtio_blk.h to clarify this and to avoid
> confusion as happened in QEMU (see link).
>
> Link: https://gitlab.com/qemu-project/qemu/-/issues/2805
> Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>

Acked-by: Eugenio Pérez <eperezma@redhat.com>

> ---
>  include/uapi/linux/virtio_snd.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/include/uapi/linux/virtio_snd.h b/include/uapi/linux/virtio_snd.h
> index 5f4100c2cf04..a4cfb9f6561a 100644
> --- a/include/uapi/linux/virtio_snd.h
> +++ b/include/uapi/linux/virtio_snd.h
> @@ -25,7 +25,7 @@ struct virtio_snd_config {
>         __le32 streams;
>         /* # of available channel maps */
>         __le32 chmaps;
> -       /* # of available control elements */
> +       /* # of available control elements (if VIRTIO_SND_F_CTLS) */
>         __le32 controls;
>  };
>
> --
> 2.48.1
>

Re: [PATCH] virtio_snd.h: clarify that `controls` depends on VIRTIO_SND_F_CTLS

[Takashi Iwai]

On Thu, 13 Feb 2025 17:18:25 +0100,
Stefano Garzarella wrote:
> 
> As defined in the specification, the `controls` field in the configuration
> space is only valid/present if VIRTIO_SND_F_CTLS is negotiated.
> 
>   From https://docs.oasis-open.org/virtio/virtio/v1.3/virtio-v1.3.html:
> 
>   5.14.4 Device Configuration Layout
>     ...
>     controls
>        (driver-read-only) indicates a total number of all available control
>        elements if VIRTIO_SND_F_CTLS has been negotiated.
> 
> Let's use the same style used in virtio_blk.h to clarify this and to avoid
> confusion as happened in QEMU (see link).
> 
> Link: https://gitlab.com/qemu-project/qemu/-/issues/2805
> Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>

Applied now.  Thanks.


Takashi