Lets document some more of the core VirtIODevice structure.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 include/hw/virtio/virtio.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/include/hw/virtio/virtio.h b/include/hw/virtio/virtio.h
index 1ba7a9dd74..ef77e9ef0e 100644
--- a/include/hw/virtio/virtio.h
+++ b/include/hw/virtio/virtio.h
@@ -150,10 +150,18 @@ struct VirtIODevice
     VMChangeStateEntry *vmstate;
     char *bus_name;
     uint8_t device_endian;
+    /**
+     * @user_guest_notifier_mask: gate usage of ->guest_notifier_mask() callback.
+     * This is used to suppress the masking of guest updates for
+     * vhost-user devices which are asynchronous by design.
+     */
     bool use_guest_notifier_mask;
     AddressSpace *dma_as;
     QLIST_HEAD(, VirtQueue) *vector_queues;
     QTAILQ_ENTRY(VirtIODevice) next;
+    /**
+     * @config_notifier: the event notifier that handles config events
+     */
     EventNotifier config_notifier;
 };
 
-- 
2.39.2

On Tue, Apr 18, 2023 at 05:21:33PM +0100, Alex Bennée wrote:
> Lets document some more of the core VirtIODevice structure.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  include/hw/virtio/virtio.h | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/include/hw/virtio/virtio.h b/include/hw/virtio/virtio.h
> index 1ba7a9dd74..ef77e9ef0e 100644
> --- a/include/hw/virtio/virtio.h
> +++ b/include/hw/virtio/virtio.h
> @@ -150,10 +150,18 @@ struct VirtIODevice
>      VMChangeStateEntry *vmstate;
>      char *bus_name;
>      uint8_t device_endian;
> +    /**
> +     * @user_guest_notifier_mask: gate usage of ->guest_notifier_mask() callback.

s/user_/use_/

> +     * This is used to suppress the masking of guest updates for
> +     * vhost-user devices which are asynchronous by design.

What is the exact reason why masking is not supported by vhost-user?

Only vhost-user-net and vhost-user-crypto set use_guest_notifier_mask to
false. Do the other vhost-user devices need to set it to false too?

> +     */
>      bool use_guest_notifier_mask;
>      AddressSpace *dma_as;
>      QLIST_HEAD(, VirtQueue) *vector_queues;
>      QTAILQ_ENTRY(VirtIODevice) next;
> +    /**
> +     * @config_notifier: the event notifier that handles config events

Using VIRTIO spec terminology:
"the event notifier that sends Configuration Change Notifications"

> +     */
>      EventNotifier config_notifier;
>  };
>  
> -- 
> 2.39.2
> 

On 18/04/2023 17:21, Alex Bennée wrote:

> Lets document some more of the core VirtIODevice structure.
> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>   include/hw/virtio/virtio.h | 8 ++++++++
>   1 file changed, 8 insertions(+)
> 
> diff --git a/include/hw/virtio/virtio.h b/include/hw/virtio/virtio.h
> index 1ba7a9dd74..ef77e9ef0e 100644
> --- a/include/hw/virtio/virtio.h
> +++ b/include/hw/virtio/virtio.h
> @@ -150,10 +150,18 @@ struct VirtIODevice
>       VMChangeStateEntry *vmstate;
>       char *bus_name;
>       uint8_t device_endian;
> +    /**
> +     * @user_guest_notifier_mask: gate usage of ->guest_notifier_mask() callback.

Typo: @use_guest_notifier_mask

> +     * This is used to suppress the masking of guest updates for
> +     * vhost-user devices which are asynchronous by design.
> +     */
>       bool use_guest_notifier_mask;
>       AddressSpace *dma_as;
>       QLIST_HEAD(, VirtQueue) *vector_queues;
>       QTAILQ_ENTRY(VirtIODevice) next;
> +    /**
> +     * @config_notifier: the event notifier that handles config events
> +     */
>       EventNotifier config_notifier;e 
>   };

As before, I'm not overly familiar with the virtio code but the description makes 
sense to me so:

Acked-by: Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>


ATB,

Mark.