Doxygen updates for data structures

Improved doxygen formatting and consistency for data structures.
Signed-off-by: Tammy Leino <tammy.leino@siemens.com>

Doxyfile

@@ -1144,7 +1144,7 @@ FORTRAN_COMMENT_AFTER  = 72
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = YES
+SOURCE_BROWSER         = NO
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.

lib/include/openamp/remoteproc_loader.h

@@ -54,50 +54,53 @@ extern "C" {
 /* Remoteproc loader reserved mask */
 #define RPROC_LOADER_RESERVED_MASK  0x0F000000L
 
-/**
- * struct image_store_ops - user defined image store operations
- * @open: user defined callback to open the "firmware" to prepare loading
- * @close: user defined callback to close the "firmware" to clean up
- *         after loading
- * @load: user defined callback to load the firmware contents to target
- *        memory or local memory
- * @features: loader supported features. e.g. seek
- */
+/** @brief User-defined image store operations */
 struct image_store_ops {
+	/** User-defined callback to open the "firmware" to prepare loading */
 	int (*open)(void *store, const char *path, const void **img_data);
+
+	/** User-defined callback to close the "firmware" to clean up after loading */
 	void (*close)(void *store);
+
+	/** User-defined callback to load the firmware contents to target memory or local memory */
 	int (*load)(void *store, size_t offset, size_t size,
 		    const void **data,
 		    metal_phys_addr_t pa,
 		    struct metal_io_region *io, char is_blocking);
+
+	/** Loader supported features. e.g. seek */
 	unsigned int features;
 };
 
-/**
- * struct loader_ops - loader operations
- * @load_header: define how to get the executable headers
- * @load_data: define how to load the target data
- * @locate_rsc_table: define how to get the resource table target address,
- *                    offset to the ELF image file and size of the resource
- *                    table.
- * @release: define how to release the loader
- * @get_entry: get entry address
- * @get_load_state: get load state from the image information
- */
+/** @brief Loader operations */
 struct loader_ops {
+	/** Define how to get the executable headers */
 	int (*load_header)(const void *img_data, size_t offset, size_t len,
 			   void **img_info, int last_state,
 			   size_t *noffset, size_t *nlen);
+
+	/** Define how to load the target data */
 	int (*load_data)(struct remoteproc *rproc,
 			 const void *img_data, size_t offset, size_t len,
 			 void **img_info, int last_load_state,
 			 metal_phys_addr_t *da,
 			 size_t *noffset, size_t *nlen,
 			 unsigned char *padding, size_t *nmemsize);
+
+	/**
+	 * Define how to get the resource table target address, offset to the ELF
+	 * image file and size of the resource table
+	 */
 	int (*locate_rsc_table)(void *img_info, metal_phys_addr_t *da,
 				size_t *offset, size_t *size);
+
+	/** Define how to release the loader */
 	void (*release)(void *img_info);
+
+	/** Get entry address */
 	metal_phys_addr_t (*get_entry)(void *img_info);
+
+	/** Get load state from the image information */
 	int (*get_load_state)(void *img_info);
 };
 

lib/include/openamp/remoteproc_virtio.h

@@ -39,21 +39,24 @@ extern "C" {
 /* define vdev notification function user should implement */
 typedef int (*rpvdev_notify_func)(void *priv, uint32_t id);
 
-/**
- * struct remoteproc_virtio
- * @priv pointer to private data
- * @vdev_rsc address of vdev resource
- * @vdev_rsc_io metal I/O region of vdev_info, can be NULL
- * @notify notification function
- * @vdev virtio device
- * @node list node
- */
+/** @brief Virtio structure for remoteproc instance */
 struct remoteproc_virtio {
+	/** Pointer to private data */
 	void *priv;
+
+	/** Address of vdev resource */
 	void *vdev_rsc;
+
+	/** Metal I/O region of vdev_info, can be NULL */
 	struct metal_io_region *vdev_rsc_io;
+
+	/** Notification function */
 	rpvdev_notify_func notify;
+
+	/** Virtio device */
 	struct virtio_device vdev;
+
+	/** List node */
 	struct metal_list node;
 };
 

lib/include/openamp/rpmsg.h

@@ -55,76 +55,90 @@ typedef void (*rpmsg_ns_bind_cb)(struct rpmsg_device *rdev,
 				 const char *name, uint32_t dest);
 
 /**
- * struct rpmsg_endpoint - binds a local rpmsg address to its user
- * @name: name of the service supported
- * @rdev: pointer to the rpmsg device
- * @addr: local address of the endpoint
- * @dest_addr: address of the default remote endpoint binded.
- * @cb: user rx callback, return value of this callback is reserved
- *      for future use, for now, only allow RPMSG_SUCCESS as return value.
- * @ns_unbind_cb: end point service unbind callback, called when remote
- *                ept is destroyed.
- * @node: end point node.
- * @priv: private data for the driver's use
+ * @brief Structure that binds a local RPMsg address to its user
  *
- * In essence, an rpmsg endpoint represents a listener on the rpmsg bus, as
- * it binds an rpmsg address with an rx callback handler.
+ * In essence, an RPMsg endpoint represents a listener on the RPMsg bus, as
+ * it binds an RPMsg address with an rx callback handler.
  */
 struct rpmsg_endpoint {
+	/** Name of the service supported */
 	char name[RPMSG_NAME_SIZE];
+
+	/** Pointer to the RPMsg device */
 	struct rpmsg_device *rdev;
+
+	/** Local address of the endpoint */
 	uint32_t addr;
+
+	/** Address of the default remote endpoint binded */
 	uint32_t dest_addr;
+
+	/**
+	 * User rx callback, return value of this callback is reserved for future
+	 * use, for now, only allow RPMSG_SUCCESS as return value
+	 */
 	rpmsg_ept_cb cb;
+
+	/** Endpoint service unbind callback, called when remote ept is destroyed */
 	rpmsg_ns_unbind_cb ns_unbind_cb;
+
+	/** Endpoint node */
 	struct metal_list node;
+
+	/** Private data for the driver's use */
 	void *priv;
 };
 
-/**
- * struct rpmsg_device_ops - RPMsg device operations
- * @send_offchannel_raw: send RPMsg data
- * @hold_rx_buffer: hold RPMsg RX buffer
- * @release_rx_buffer: release RPMsg RX buffer
- * @get_tx_payload_buffer: get RPMsg TX buffer
- * @send_offchannel_nocopy: send RPMsg data without copy
- * @release_tx_buffer: release RPMsg TX buffer
- */
+/** @brief RPMsg device operations */
 struct rpmsg_device_ops {
+	/** Send RPMsg data */
 	int (*send_offchannel_raw)(struct rpmsg_device *rdev,
 				   uint32_t src, uint32_t dst,
 				   const void *data, int len, int wait);
+
+	/** Hold RPMsg RX buffer */
 	void (*hold_rx_buffer)(struct rpmsg_device *rdev, void *rxbuf);
+
+	/** Release RPMsg RX buffer */
 	void (*release_rx_buffer)(struct rpmsg_device *rdev, void *rxbuf);
+
+	/** Get RPMsg TX buffer */
 	void *(*get_tx_payload_buffer)(struct rpmsg_device *rdev,
 				       uint32_t *len, int wait);
+
+	/** Send RPMsg data without copy */
 	int (*send_offchannel_nocopy)(struct rpmsg_device *rdev,
 				      uint32_t src, uint32_t dst,
-				       const void *data, int len);
+				      const void *data, int len);
+
+	/** Release RPMsg TX buffer */
 	int (*release_tx_buffer)(struct rpmsg_device *rdev, void *txbuf);
 };
 
-/**
- * struct rpmsg_device - representation of a RPMsg device
- * @endpoints: list of endpoints
- * @ns_ept: name service endpoint
- * @bitmap: table endpoint address allocation.
- * @lock: mutex lock for rpmsg management
- * @ns_bind_cb: callback handler for name service announcement without local
- *              endpoints waiting to bind.
- * @ns_unbind_cb: callback handler for name service announcement, called when
- *                remote ept is destroyed.
- * @ops: RPMsg device operations
- * @support_ns: create/destroy namespace message
- */
+/** @brief Representation of a RPMsg device */
 struct rpmsg_device {
+	/** List of endpoints */
 	struct metal_list endpoints;
+
+	/** Name service endpoint */
 	struct rpmsg_endpoint ns_ept;
+
+	/** Table endpoint address allocation */
 	unsigned long bitmap[metal_bitmap_longs(RPMSG_ADDR_BMP_SIZE)];
+
+	/** Mutex lock for RPMsg management */
 	metal_mutex_t lock;
+
+	/** Callback handler for name service announcement without local epts waiting to bind */
 	rpmsg_ns_bind_cb ns_bind_cb;
+
+	/** Callback handler for name service announcement, called when remote ept is destroyed */
 	rpmsg_ns_bind_cb ns_unbind_cb;
+
+	/** RPMsg device operations */
 	struct rpmsg_device_ops ops;
+
+	/** Create/destroy namespace message */
 	bool support_ns;
 };
 

lib/include/openamp/rpmsg_rpc_client_server.h

@@ -47,77 +47,70 @@ struct rpmsg_rpc_request {
 	unsigned char params[MAX_BUF_LEN];
 };
 
-/**
- * struct rpmsg_rpc_answer - rpc request message
- *
- * @id: service id
- * @status: status of rpc
- * @params: answer params
- *
- */
+/** @brief RPC request message */
 METAL_PACKED_BEGIN
 struct rpmsg_rpc_answer {
+	/** Service ID */
 	uint32_t id;
+
+	/** Status of RPC */
 	int32_t status;
+
+	/** Answer params */
 	unsigned char params[MAX_BUF_LEN];
 } METAL_PACKED_END;
 
-/**
- * struct rpmsg_rpc_services - table for services
- *
- * @id: service id
- * @cb_function: id callback
- *
- */
+/** @brief Table for services */
 struct rpmsg_rpc_services {
+	/** Service ID */
 	uint32_t id;
+
+	/** ID callback */
 	rpmsg_rpc_syscall_cb cb_function;
 };
 
-/**
- * struct rpmsg_rpc_client_services - table for client services
- *
- * @id: service id
- * @app_cb: id callback
- *
- */
+/** @brief Table for client services */
 struct rpmsg_rpc_client_services {
+	/** Service ID */
 	uint32_t id;
+
+	/** ID callback */
 	app_cb cb;
 };
 
 /**
- * struct rpmsg_rpc_svr - server remote procedure call data
+ * @brief Server remote procedure call data
  *
  * RPMsg RPC will send request to endpoint
- *
- * @ept: rpmsg_endpoint structure
- * @services: service table
- * @n_services: number of services
- *
  */
 struct rpmsg_rpc_svr {
+	/** RPMsg destination endpoint structure */
 	struct rpmsg_endpoint ept;
+
+	/** Service table */
 	const struct rpmsg_rpc_services *services;
+
+	/** Number of services */
 	unsigned int n_services;
 };
 
 /**
- * struct rpmsg_rpc_clt - client remote procedure call data
+ * @brief Client remote procedure call data
  *
  * RPMsg RPC will send request to remote and
  * wait for callback.
- *
- * @ept: rpmsg_endpoint structure
- * @shutdown_cb: shutdown callback function
- * @services: service table
- * @n_services: number of services
- *
  */
 struct rpmsg_rpc_clt {
+	/** RPMsg endpoint associated with the call */
 	struct rpmsg_endpoint ept;
+
+	/** Shutdown callback function */
 	rpmsg_rpc_shutdown_cb shutdown_cb;
+
+	/** Service table */
 	const struct rpmsg_rpc_client_services *services;
+
+	/** Number of services */
 	unsigned int n_services;
 };
 

lib/include/openamp/rpmsg_virtio.h

@@ -41,54 +41,62 @@ extern "C" {
 #define BUFFER_INVALIDATE(x, s)		do { } while (0)
 #endif /* VIRTIO_CACHED_BUFFERS || VIRTIO_USE_DCACHE */
 
-/**
- * struct rpmsg_virtio_shm_pool - shared memory pool used for rpmsg buffers
- * @base: base address of the memory pool
- * @avail: available memory size
- * @size: total pool size
- */
+/** @brief Shared memory pool used for RPMsg buffers */
 struct rpmsg_virtio_shm_pool {
+	/** Base address of the memory pool */
 	void *base;
+
+	/** Available memory size */
 	size_t avail;
+
+	/** Total pool size */
 	size_t size;
 };
 
 /**
- * struct rpmsg_virtio_config - configuration of rpmsg device based on virtio
+ * @brief Configuration of RPMsg device based on virtio
  *
- * This structure is used by the rpmsg virtio host to configure the virtiio
+ * This structure is used by the RPMsg virtio host to configure the virtiio
  * layer.
- *
- * @h2r_buf_size: the size of the buffer used to send data from host to remote
- * @r2h_buf_size: the size of the buffer used to send data from remote to host
- * @split_shpool: the flag that splitting share memory pool to TX and RX
  */
 struct rpmsg_virtio_config {
+	/** The size of the buffer used to send data from host to remote */
 	uint32_t h2r_buf_size;
+
+	/** The size of the buffer used to send data from remote to host */
 	uint32_t r2h_buf_size;
+
+	/** The flag for splitting shared memory pool to TX and RX */
 	bool split_shpool;
 };
 
-/**
- * struct rpmsg_virtio_device - representation of a rpmsg device based on virtio
- * @rdev: rpmsg device, first property in the struct
- * @config: structure containing virtio configuration
- * @vdev: pointer to the virtio device
- * @rvq: pointer to receive virtqueue
- * @svq: pointer to send virtqueue
- * @shbuf_io: pointer to the shared buffer I/O region
- * @shpool: pointer to the shared buffers pool
- * @reclaimer: Rpmsg buffer reclaimer that contains buffers released by
- *             the rpmsg_virtio_release_tx_buffer function.
- */
+/** @brief Representation of a RPMsg device based on virtio */
 struct rpmsg_virtio_device {
+	/** RPMsg device */
 	struct rpmsg_device rdev;
+
+	/** Structure containing virtio configuration */
 	struct rpmsg_virtio_config config;
+
+	/** Pointer to the virtio device */
 	struct virtio_device *vdev;
+
+	/** Pointer to receive virtqueue */
 	struct virtqueue *rvq;
+
+	/** Pointer to send virtqueue */
 	struct virtqueue *svq;
+
+	/** Pointer to the shared buffer I/O region */
 	struct metal_io_region *shbuf_io;
+
+	/** Pointer to the shared buffers pool */
 	struct rpmsg_virtio_shm_pool *shpool;
+
+	/**
+	 * RPMsg buffer reclaimer that contains buffers released by the
+	 * \ref rpmsg_virtio_release_tx_buffer function
+	 */
 	struct metal_list reclaimer;
 };
 

lib/include/openamp/virtio.h

@@ -169,36 +169,48 @@ struct virtio_feature_desc {
 	const char *vfd_str;
 };
 
-/**
- * struct virtio_vring_info
- * @vq virtio queue
- * @info vring alloc info
- * @notifyid vring notify id
- * @io metal I/O region of the vring memory, can be NULL
- */
+/** @brief Virtio vring data structure */
 struct virtio_vring_info {
+	/** Virtio queue */
 	struct virtqueue *vq;
+
+	/** Vring alloc info */
 	struct vring_alloc_info info;
+
+	/** Vring notify id */
 	uint32_t notifyid;
+
+	/** Metal I/O region of the vring memory, can be NULL */
 	struct metal_io_region *io;
 };
 
-/*
- * Structure definition for virtio devices for use by the
- * applications/drivers
- */
-
+/** @brief Structure definition for virtio devices for use by the applications/drivers */
 struct virtio_device {
-	uint32_t notifyid; /**< unique position on the virtio bus */
-	struct virtio_device_id id; /**< the device type identification
-				      *  (used to match it with a driver
-				      */
-	uint64_t features; /**< the features supported by both ends. */
-	unsigned int role; /**< if it is virtio backend or front end. */
-	virtio_dev_reset_cb reset_cb; /**< user registered device callback */
-	const struct virtio_dispatch *func; /**< Virtio dispatch table */
-	void *priv; /**< TODO: remove pointer to virtio_device private data */
-	unsigned int vrings_num; /**< number of vrings */
+	/** Unique position on the virtio bus */
+	uint32_t notifyid;
+
+	/** The device type identification used to match it with a driver */
+	struct virtio_device_id id;
+
+	/** The features supported by both ends. */
+	uint64_t features;
+
+	/** If it is virtio backend or front end. */
+	unsigned int role;
+
+	/** User-registered device callback */
+	virtio_dev_reset_cb reset_cb;
+
+	/** Virtio dispatch table */
+	const struct virtio_dispatch *func;
+
+	/** Private data */
+	void *priv;
+
+	/** Number of vrings */
+	unsigned int vrings_num;
+
+	/** Pointer to the virtio vring structure */
 	struct virtio_vring_info *vrings_info;
 };
 

lib/include/openamp/virtio_mmio.h

@@ -128,37 +128,42 @@ extern "C" {
 /* Data buffer size for preallocated buffers before vring */
 #define VIRTIO_MMIO_MAX_DATA_SIZE 128
 
-/**
- * struct virtio_mmio_dev_mem: VIRTIO MMIO memory area
- * @base memory region physical address
- * @size memory region size
- */
+/** @brief VIRTIO MMIO memory area */
 struct virtio_mmio_dev_mem {
+	/** Memory region physical address */
 	void *base;
+
+	/** Memory region size */
 	size_t size;
 };
 
-/**
- * struct virtio_mmio_device: representation of a VIRTIO MMIO device
- * @vdev	base virtio device struct
- * @cfg_io	device configuration space metal_io_region
- * @shm_io	pre-shared memory space metal_io_region
- * @shm_device	shared memory device
- * @cfg_mem	VIRTIO device configuration space
- * @shm_mem	VIRTIO device pre-shared memory
- * @device_mode	VIRTIO_DEV_DRIVER or VIRTIO_DEV_DEVICE
- * @irq		interrupt number
- * @user_data	custom user data
- */
+/** @brief A VIRTIO MMIO device */
 struct virtio_mmio_device {
+	/** Base virtio device structure */
 	struct virtio_device vdev;
+
+	/** Device configuration space metal_io_region */
 	struct metal_io_region *cfg_io;
+
+	/** Pre-shared memory space metal_io_region */
 	struct metal_io_region *shm_io;
+
+	/** Shared memory device */
 	struct metal_device shm_device;
+
+	/** VIRTIO device configuration space */
 	struct virtio_mmio_dev_mem cfg_mem;
+
+	/** VIRTIO device pre-shared memory */
 	struct virtio_mmio_dev_mem shm_mem;
+
+	/** VIRTIO_DEV_DRIVER or VIRTIO_DEV_DEVICE */
 	unsigned int device_mode;
+
+	/** Interrupt number */
 	unsigned int irq;
+
+	/** Custom user data */
 	void *user_data;
 };
 

lib/include/openamp/virtio_ring.h

@@ -33,25 +33,49 @@ extern "C" {
  */
 #define VRING_AVAIL_F_NO_INTERRUPT      1
 
-/* VirtIO ring descriptors: 16 bytes.
- * These can chain together via "next".
+/**
+ * @brief VirtIO ring descriptors.
+ *
+ * The descriptor table refers to the buffers the driver is using for the
+ * device. addr is a physical address, and the buffers can be chained via \ref next.
+ * Each descriptor describes a buffer which is read-only for the device
+ * (“device-readable”) or write-only for the device (“device-writable”), but a
+ * chain of descriptors can contain both device-readable and device-writable
+ * buffers.
  */
 METAL_PACKED_BEGIN
 struct vring_desc {
-	/* Address (guest-physical). */
+	/** Address (guest-physical) */
 	uint64_t addr;
-	/* Length. */
+
+	/** Length */
 	uint32_t len;
-	/* The flags as indicated above. */
+
+	/** Flags relevant to the descriptors */
 	uint16_t flags;
-	/* We chain unused descriptors via this, too. */
+
+	/** We chain unused descriptors via this, too */
 	uint16_t next;
 } METAL_PACKED_END;
 
+/**
+ * @brief Used to offer buffers to the device.
+ *
+ * Each ring entry refers to the head of a descriptor chain. It is only
+ * written by the driver and read by the device.
+ */
 METAL_PACKED_BEGIN
 struct vring_avail {
+	/** Flag which determines whether device notifications are required */
 	uint16_t flags;
+
+	/**
+	 * Indicates where the driver puts the next descriptor entry in the
+	 * ring (modulo the queue size)
+	 */
 	uint16_t idx;
+
+	/** The ring of descriptors */
 	uint16_t ring[0];
 } METAL_PACKED_END;
 
@@ -67,18 +91,49 @@ struct vring_used_elem {
 	uint32_t len;
 } METAL_PACKED_END;
 
+/**
+ * @brief The device returns buffers to this structure when done with them
+ *
+ * The structure is only written to by the device, and read by the driver.
+ */
 METAL_PACKED_BEGIN
 struct vring_used {
+	/** Flag which determines whether device notifications are required */
 	uint16_t flags;
+
+	/**
+	 * Indicates where the driver puts the next descriptor entry in the
+	 * ring (modulo the queue size)
+	 */
 	uint16_t idx;
+
+	/** The ring of descriptors */
 	struct vring_used_elem ring[0];
 } METAL_PACKED_END;
 
+/**
+ * @brief The virtqueue layout structure
+ *
+ * Each virtqueue consists of; descriptor table, available ring, used ring,
+ * where each part is physically contiguous in guest memory.
+ *
+ * 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
+ * index into the available ring. It then notifies the device. When the device
+ * has finished a buffer, it writes the descriptor index into the used ring,
+ * and sends an interrupt.
+ */
 struct vring {
+	/** The number of descriptors in the virtqueue */
 	unsigned int num;
 
+	/** The actual descriptors, 16 bytes each */
 	struct vring_desc *desc;
+
+	/** A ring of available descriptor heads with free-running index */
 	struct vring_avail *avail;
+
+	/** A ring of used descriptor heads with free-running index */
 	struct vring_used *used;
 };
 

lib/rpmsg/rpmsg_internal.h

@@ -48,40 +48,46 @@ enum rpmsg_ns_flags {
 };
 
 /**
- * struct rpmsg_hdr - common header for all rpmsg messages
- * @src: source address
- * @dst: destination address
- * @reserved: reserved for future use
- * @len: length of payload (in bytes)
- * @flags: message flags
+ * @brief Common header for all RPMsg messages
  *
- * Every message sent(/received) on the rpmsg bus begins with this header.
+ * Every message sent(/received) on the RPMsg bus begins with this header.
  */
 METAL_PACKED_BEGIN
 struct rpmsg_hdr {
+	/** Source address */
 	uint32_t src;
+
+	/** Destination address */
 	uint32_t dst;
+
+	/** Reserved for future use */
 	uint32_t reserved;
+
+	/** Length of payload (in bytes) */
 	uint16_t len;
+
+	/** Message flags */
 	uint16_t flags;
 } METAL_PACKED_END;
 
 /**
- * struct rpmsg_ns_msg - dynamic name service announcement message
- * @name: name of remote service that is published
- * @addr: address of remote service that is published
- * @flags: indicates whether service is created or destroyed
+ * @brief Dynamic name service announcement message
  *
  * This message is sent across to publish a new service, or announce
  * about its removal. When we receive these messages, an appropriate
- * rpmsg channel (i.e device) is created/destroyed. In turn, the ->probe()
- * or ->remove() handler of the appropriate rpmsg driver will be invoked
+ * RPMsg channel (i.e device) is created/destroyed. In turn, the ->probe()
+ * or ->remove() handler of the appropriate RPMsg driver will be invoked
  * (if/as-soon-as one is registered).
  */
 METAL_PACKED_BEGIN
 struct rpmsg_ns_msg {
+	/** Name of the remote service that is being published */
 	char name[RPMSG_NAME_SIZE];
+
+	/** Endpoint address of the remote service that is being published */
 	uint32_t addr;
+
+	/** Indicates whether service is created or destroyed */
 	uint32_t flags;
 } METAL_PACKED_END;