From 06a06d6689f9d2a005396c293bddb9db7f8ca288 Mon Sep 17 00:00:00 2001 From: Sipke Vriend Date: Mon, 8 Sep 2025 10:18:24 +1000 Subject: [PATCH 1/2] doxygen: add @code block to correct generation of vring code snippet the code snippet was missing a @code, @encode block so not generating the doxygen documentation correctly, so add @code{.c} block for highlighted c code of the vring struct. Signed-off-by: Sipke Vriend --- lib/include/openamp/virtio_ring.h | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/include/openamp/virtio_ring.h b/lib/include/openamp/virtio_ring.h index 60a9710dc..abeb3226b 100644 --- a/lib/include/openamp/virtio_ring.h +++ b/lib/include/openamp/virtio_ring.h @@ -126,6 +126,7 @@ struct vring_used { * The standard layout for the ring is a continuous chunk of memory which * looks like this. We assume num is a power of 2. * + * @code{.c} * struct vring { * // The actual descriptors (16 bytes each) * struct vring_desc desc[num]; @@ -145,6 +146,7 @@ struct vring_used { * struct vring_used_elem used[num]; * __u16 avail_event_idx; * }; + * @endcode * * NOTE: for VirtIO PCI, align is 4096. */ From cc876bd0718c625b9f5274c0a75227cb25279b92 Mon Sep 17 00:00:00 2001 From: Sipke Vriend Date: Mon, 29 Sep 2025 12:21:41 +1000 Subject: [PATCH 2/2] doxygen: define vring memory layout using table review requested to use a table rather than a code snippet to define the memory layout, so convert proposed struct to a table with definition, size and description. Signed-off-by: Sipke Vriend --- lib/include/openamp/virtio_ring.h | 41 +++++++++++++------------------ 1 file changed, 17 insertions(+), 24 deletions(-) diff --git a/lib/include/openamp/virtio_ring.h b/lib/include/openamp/virtio_ring.h index abeb3226b..ea57373fd 100644 --- a/lib/include/openamp/virtio_ring.h +++ b/lib/include/openamp/virtio_ring.h @@ -115,7 +115,8 @@ struct vring_used { * @brief The virtqueue layout structure * * Each virtqueue consists of; descriptor table, available ring, used ring, - * where each part is physically contiguous in guest memory. + * where each part is physically contiguous in guest memory, referenced + * by the pointers in this structure. * * When the driver wants to send a buffer to the device, it fills in a slot in * the descriptor table (or chains several together), and writes the descriptor @@ -123,30 +124,22 @@ struct vring_used { * has finished a buffer, it writes the descriptor index into the used ring, * and sends an interrupt. * - * The standard layout for the ring is a continuous chunk of memory which - * looks like this. We assume num is a power of 2. + * The standard layout for the ring, referenced by this structure, is a + * continuous chunk of memory exemplified by this table. The maximum number + * of buffer descriptors, num, is a power of 2. * - * @code{.c} - * struct vring { - * // The actual descriptors (16 bytes each) - * struct vring_desc desc[num]; - * - * // A ring of available descriptor heads with free-running index. - * __u16 avail_flags; - * __u16 avail_idx; - * __u16 available[num]; - * __u16 used_event_idx; - * - * // Padding to the next align boundary. - * char pad[]; - * - * // A ring of used descriptor heads with free-running index. - * __u16 used_flags; - * __u16 used_idx; - * struct vring_used_elem used[num]; - * __u16 avail_event_idx; - * }; - * @endcode + * |vring| definition | description + * |-----|-------------------------------- |------------ + * | desc| struct vring_desc desc[num] | All num descriptors + * |avail| uint16_t avail_flags | Device notification flags + * | | uint16_t avail_idx | Driver's next descriptor location + * | | uint16_t available[num] | The ring of descriptors + * | | uint16_t used_event_idx | Free running index + * | | char pad[] | Padding for memory alignment + * | used| uint16_t used_flags | Device notification flags + * | | uint16_t used_idx | Driver's next descriptor location + * | | struct vring_used_elem used[num]| The ring of descriptors + * | | uint16_t avail_event_idx | Free running index * * NOTE: for VirtIO PCI, align is 4096. */