[v2,05/11] eventdev: improve function documentation for query fns
Checks
Commit Message
General improvements to the doxygen docs for eventdev functions for
querying basic information:
* number of devices
* id for a particular device
* socket id of device
* capability information for a device
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
lib/eventdev/rte_eventdev.h | 22 +++++++++++++---------
1 file changed, 13 insertions(+), 9 deletions(-)
Comments
On 2024-01-19 18:43, Bruce Richardson wrote:
> General improvements to the doxygen docs for eventdev functions for
> querying basic information:
> * number of devices
> * id for a particular device
> * socket id of device
> * capability information for a device
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
> lib/eventdev/rte_eventdev.h | 22 +++++++++++++---------
> 1 file changed, 13 insertions(+), 9 deletions(-)
>
> diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> index 872f241df2..c57c93a22e 100644
> --- a/lib/eventdev/rte_eventdev.h
> +++ b/lib/eventdev/rte_eventdev.h
> @@ -440,8 +440,7 @@ struct rte_event;
> */
>
> /**
> - * Get the total number of event devices that have been successfully
> - * initialised.
> + * Get the total number of event devices available for application use.
Does "for application use" add information? If they aren't for
application use, I would argue such are "unavailable".
"Get the total number of available event devices" or just "Get the total
number of event devices".
> *
> * @return
> * The total number of usable event devices.
> @@ -456,8 +455,10 @@ rte_event_dev_count(void);
> * Event device name to select the event device identifier.
> *
> * @return
> - * Returns event device identifier on success.
> - * - <0: Failure to find named event device.
> + * Event device identifier (dev_id >= 0) on success.
> + * Negative error code on failure:
> + * - -EINVAL - input name parameter is invalid
> + * - -ENODEV - no event device found with that name
"."?
> */
> int
> rte_event_dev_get_dev_id(const char *name);
> @@ -470,7 +471,8 @@ rte_event_dev_get_dev_id(const char *name);
> * @return
> * The NUMA socket id to which the device is connected or
> * a default of zero if the socket could not be determined.
> - * -(-EINVAL) dev_id value is out of range.
> + * -EINVAL on error, where the given dev_id value does not
> + * correspond to any event device.
> */
> int
> rte_event_dev_socket_id(uint8_t dev_id);
> @@ -539,18 +541,20 @@ struct rte_event_dev_info {
> };
>
> /**
> - * Retrieve the contextual information of an event device.
> + * Retrieve details of an event device's capabilities and configuration limits.
> *
> * @param dev_id
> * The identifier of the device.
> *
> * @param[out] dev_info
> * A pointer to a structure of type *rte_event_dev_info* to be filled with the
> - * contextual information of the device.
> + * information about the device's capabilities.
> *
> * @return
> - * - 0: Success, driver updates the contextual information of the event device
> - * - <0: Error code returned by the driver info get function.
> + * - 0: Success, information about the event device is present in dev_info.
> + * - <0: Failure, error code returned by the function.
> + * - -EINVAL - invalid input parameters, e.g. incorrect device id
> + * - -ENOTSUP - device does not support returning capabilities information
> */
> int
> rte_event_dev_info_get(uint8_t dev_id, struct rte_event_dev_info *dev_info);
@@ -440,8 +440,7 @@ struct rte_event;
*/
/**
- * Get the total number of event devices that have been successfully
- * initialised.
+ * Get the total number of event devices available for application use.
*
* @return
* The total number of usable event devices.
@@ -456,8 +455,10 @@ rte_event_dev_count(void);
* Event device name to select the event device identifier.
*
* @return
- * Returns event device identifier on success.
- * - <0: Failure to find named event device.
+ * Event device identifier (dev_id >= 0) on success.
+ * Negative error code on failure:
+ * - -EINVAL - input name parameter is invalid
+ * - -ENODEV - no event device found with that name
*/
int
rte_event_dev_get_dev_id(const char *name);
@@ -470,7 +471,8 @@ rte_event_dev_get_dev_id(const char *name);
* @return
* The NUMA socket id to which the device is connected or
* a default of zero if the socket could not be determined.
- * -(-EINVAL) dev_id value is out of range.
+ * -EINVAL on error, where the given dev_id value does not
+ * correspond to any event device.
*/
int
rte_event_dev_socket_id(uint8_t dev_id);
@@ -539,18 +541,20 @@ struct rte_event_dev_info {
};
/**
- * Retrieve the contextual information of an event device.
+ * Retrieve details of an event device's capabilities and configuration limits.
*
* @param dev_id
* The identifier of the device.
*
* @param[out] dev_info
* A pointer to a structure of type *rte_event_dev_info* to be filled with the
- * contextual information of the device.
+ * information about the device's capabilities.
*
* @return
- * - 0: Success, driver updates the contextual information of the event device
- * - <0: Error code returned by the driver info get function.
+ * - 0: Success, information about the event device is present in dev_info.
+ * - <0: Failure, error code returned by the function.
+ * - -EINVAL - invalid input parameters, e.g. incorrect device id
+ * - -ENOTSUP - device does not support returning capabilities information
*/
int
rte_event_dev_info_get(uint8_t dev_id, struct rte_event_dev_info *dev_info);