lib: fix doxygen miscellaneous warnings

Remove warning reported by Doxygen on doc generation:
- rewrite enum documentation,
- replace @ by \ref for references,
- fix param names

Signed-off-by: Arnaud Pouliquen <arnaud.pouliquen@foss.st.com>

lib/include/openamp/remoteproc.h

@@ -79,34 +79,43 @@ struct fw_rsc_hdr {
 } METAL_PACKED_END;
 
 /**
- * enum fw_resource_type - types of resource entries
- *
- * @RSC_CARVEOUT:   request for allocation of a physically contiguous
- *          memory region.
- * @RSC_DEVMEM:     request to iommu_map a memory-based peripheral.
- * @RSC_TRACE:      announces the availability of a trace buffer into which
- *          the remote remoteproc will be writing logs.
- * @RSC_VDEV:       declare support for a virtio device, and serve as its
- *          virtio header.
- * @RSC_VENDOR_START: start of the vendor specific resource types range
- * @RSC_VENDOR_END  : end of the vendor specific resource types range
- * @RSC_LAST:       just keep this one at the end
+ * @brief Types of resource entries
  *
  * For more details regarding a specific resource type, please see its
  * dedicated structure below.
  *
  * Please note that these values are used as indices to the rproc_handle_rsc
- * lookup table, so please keep them sane. Moreover, @RSC_LAST is used to
+ * lookup table, so please keep them sane. Moreover, \ref RSC_LAST is used to
  * check the validity of an index before the lookup table is accessed, so
  * please update it as needed.
  */
 enum fw_resource_type {
+	/** carveout resource
+	 *
+	 *  Request for allocation of a physically contiguous memory region.
+	 */
 	RSC_CARVEOUT = 0,
+	/** device memory resource
+	 *
+	 *  Request to iommu_map a memory-based peripheral.
+	 */
 	RSC_DEVMEM = 1,
+	/** trace resource
+	 *
+	 *  Announces the availability of a trace buffer into which the remote remoteproc will be
+	 *  writing logs.
+	 */
 	RSC_TRACE = 2,
+	/** virtio device resource
+	 *
+	 *  Declare support for a virtio device, and serve as its virtio header.
+	 */
 	RSC_VDEV = 3,
+	/** end of the generic resources */
 	RSC_LAST = 4,
+	/** Start of the vendor specific resource types range */
 	RSC_VENDOR_START = 128,
+	/** End of the vendor specific resource types range */
 	RSC_VENDOR_END = 512,
 };
 
@@ -520,24 +529,24 @@ static inline void *RPROC_ERR_PTR(long error)
 }
 
 /**
- * enum rproc_state - remote processor states
- * @RPROC_OFFLINE:	remote is offline
- * @RPROC_CONFIGURED:	remote is configured
- * @RPROC_READY:	remote is ready to start
- * @RPROC_RUNNING:	remote is up and running
- * @RPROC_SUSPENDED:	remote is suspended
- * @RPROC_ERROR:	remote has error; need to recover
- * @RPROC_STOPPED:	remote is stopped
- * @RPROC_LAST:		just keep this one at the end
+ * @brief Remote processor states
  */
 enum remoteproc_state {
+	/** Remote is offline */
 	RPROC_OFFLINE		= 0,
+	/** Remote is configured */
 	RPROC_CONFIGURED	= 1,
+	/** Remote is ready to start */
 	RPROC_READY		= 2,
+	/** Remote is up and running */
 	RPROC_RUNNING		= 3,
+	/** Remote is suspended */
 	RPROC_SUSPENDED		= 4,
+	/** Remote is has error; need to recover */
 	RPROC_ERROR		= 5,
+	/** Remote is stopped */
 	RPROC_STOPPED		= 6,
+	/** Just keep this one at the end */
 	RPROC_LAST		= 7,
 };
 

lib/include/openamp/rpmsg_rpc_client_server.h

@@ -38,8 +38,8 @@ typedef int (*rpmsg_rpc_syscall_cb)(void *data, struct rpmsg_rpc_svr *rpcs);
 /**
  * struct rpmsg_rpc_request - rpc request message
  *
- * @id: service id
- * @params: request params
+ * @param id		service id
+ * @param params	request params
  *
  */
 struct rpmsg_rpc_request {

lib/include/openamp/virtio.h

@@ -300,7 +300,7 @@ static inline void virtio_delete_virtqueues(struct virtio_device *vdev)
 /**
  * @brief Get device ID.
  *
- * @param dev Pointer to device structure.
+ * @param vdev Pointer to device structure.
  *
  * @return Device ID value.
  */
@@ -314,7 +314,7 @@ static inline uint32_t virtio_get_devid(const struct virtio_device *vdev)
 /**
  * @brief Retrieve device status.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param status	Pointer to the virtio device status.
  *
  * @return 0 on success, otherwise error code.
@@ -334,7 +334,7 @@ static inline int virtio_get_status(struct virtio_device *vdev, uint8_t *status)
 /**
  * @brief Set device status.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param status	Value to be set as device status.
  *
  * @return 0 on success, otherwise error code.
@@ -354,7 +354,7 @@ static inline int virtio_set_status(struct virtio_device *vdev, uint8_t status)
 /**
  * @brief Retrieve configuration data from the device.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param offset	Offset of the data within the configuration area.
  * @param dst		Address of the buffer that will hold the data.
  * @param len		Length of the data to be retrieved.
@@ -377,7 +377,7 @@ static inline int virtio_read_config(struct virtio_device *vdev,
 /**
  * @brief Write configuration data to the device.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param offset	Offset of the data within the configuration area.
  * @param src		Address of the buffer that holds the data to write.
  * @param len		Length of the data to be written.
@@ -400,7 +400,7 @@ static inline int virtio_write_config(struct virtio_device *vdev,
 /**
  * @brief Get the virtio device features.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param features	Pointer to features supported by both the driver and
  *			the device as a bitfield.
  *
@@ -422,7 +422,7 @@ static inline int virtio_get_features(struct virtio_device *vdev,
 /**
  * @brief Set features supported by the VIRTIO driver.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param features	Features supported by the driver as a bitfield.
  *
  * @return 0 on success, otherwise error code.
@@ -443,7 +443,7 @@ static inline int virtio_set_features(struct virtio_device *vdev,
 /**
  * @brief Negotiate features between virtio device and driver.
  *
- * @param dev			Pointer to device structure.
+ * @param vdev			Pointer to device structure.
  * @param features		Supported features.
  * @param final_features	Pointer to the final features after negotiate.
  *

lib/include/openamp/virtio_mmio.h

@@ -170,7 +170,7 @@ struct virtio_mmio_device {
 /**
  * @brief Register a VIRTIO device with the VIRTIO stack.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param vq_num	Number of virtqueues the device uses.
  * @param vqs		Array of pointers to vthe virtqueues used by the device.
  */
@@ -179,11 +179,12 @@ void virtio_mmio_register_device(struct virtio_device *vdev, int vq_num, struct
 /**
  * @brief Setup a virtqueue structure.
  *
- * @param dev		Pointer to device structure.
+ * @param vdev		Pointer to device structure.
  * @param idx		Index of the virtqueue.
  * @param vq		Pointer to virtqueue structure.
  * @param cb		Pointer to virtqueue callback. Can be NULL.
  * @param cb_arg	Argument for the virtqueue callback.
+ * @param vq_name	Name of the virtqueue.
  *
  * @return pointer to virtqueue structure.
  */
@@ -197,10 +198,10 @@ struct virtqueue *virtio_mmio_setup_virtqueue(struct virtio_device *vdev,
 /**
  * @brief VIRTIO MMIO device initialization.
  *
- * @param vmdev			Pointer to virtio_mmio_device structure.
+ * @param vmdev		Pointer to virtio_mmio_device structure.
  * @param virt_mem_ptr	Guest virtio (shared) memory base address (virtual).
  * @param cfg_mem_ptr	Virtio device configuration memory base address (virtual).
- * @param user_data		Pointer to custom user data.
+ * @param user_data	Pointer to custom user data.
  *
  * @return int 0 for success.
  */

lib/rpmsg/rpmsg_internal.h

@@ -37,15 +37,12 @@ extern "C" {
 #define RPMSG_LOCATE_DATA(p) ((unsigned char *)(p) + sizeof(struct rpmsg_hdr))
 
 /**
- * enum rpmsg_ns_flags - dynamic name service announcement flags
- *
- * @RPMSG_NS_CREATE: a new remote service was just created
- * @RPMSG_NS_DESTROY: a known remote service was just destroyed
- * @RPMSG_NS_CREATE_WITH_ACK: a new remote service was just created waiting
- *                            acknowledgment.
+ * @brief dynamic name service announcement flags
  */
 enum rpmsg_ns_flags {
+	/** A new remote service was just created */
 	RPMSG_NS_CREATE = 0,
+	/** A known remote service was just destroyed */
 	RPMSG_NS_DESTROY = 1,
 };
 

lib/rpmsg/rpmsg_virtio.c

@@ -49,8 +49,8 @@
  * This structure is used by the rpmsg virtio to store unused virtio buffer, as the
  * virtqueue structure has been already updated and memory allocated.
  *
- * @node: node in reclaimer list.
- * @idx:  virtio descriptor index containing the buffer information.
+ * @param node	node in reclaimer list.
+ * @param idx	virtio descriptor index containing the buffer information.
  */
 struct vbuff_reclaimer_t {
 	struct metal_list node;