[v2,06/11] eventdev: improve doxygen comments on configure struct
Checks
Commit Message
General rewording and cleanup on the rte_event_dev_config structure.
Improved the wording of some sentences and created linked
cross-references out of the existing references to the dev_info
structure.
Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++------------------
1 file changed, 24 insertions(+), 23 deletions(-)
Comments
On 2024-01-19 18:43, Bruce Richardson wrote:
> General rewording and cleanup on the rte_event_dev_config structure.
> Improved the wording of some sentences and created linked
> cross-references out of the existing references to the dev_info
> structure.
>
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
> lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++------------------
> 1 file changed, 24 insertions(+), 23 deletions(-)
>
> diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> index c57c93a22e..4139ccb982 100644
> --- a/lib/eventdev/rte_eventdev.h
> +++ b/lib/eventdev/rte_eventdev.h
> @@ -599,9 +599,9 @@ rte_event_dev_attr_get(uint8_t dev_id, uint32_t attr_id,
> struct rte_event_dev_config {
> uint32_t dequeue_timeout_ns;
> /**< rte_event_dequeue_burst() timeout on this device.
> - * This value should be in the range of *min_dequeue_timeout_ns* and
> - * *max_dequeue_timeout_ns* which previously provided in
> - * rte_event_dev_info_get()
> + * This value should be in the range of @ref rte_event_dev_info.min_dequeue_timeout_ns and
> + * @ref rte_event_dev_info.max_dequeue_timeout_ns returned by
> + * @ref rte_event_dev_info_get()
> * The value 0 is allowed, in which case, default dequeue timeout used.
> * @see RTE_EVENT_DEV_CFG_PER_DEQUEUE_TIMEOUT
> */
> @@ -609,40 +609,41 @@ struct rte_event_dev_config {
> /**< In a *closed system* this field is the limit on maximum number of
> * events that can be inflight in the eventdev at a given time. The
> * limit is required to ensure that the finite space in a closed system
> - * is not overwhelmed. The value cannot exceed the *max_num_events*
> - * as provided by rte_event_dev_info_get().
> + * is not overwhelmed.
"overwhelmed" -> "exhausted"
> + * Once the limit has been reached, any enqueues of NEW events to the
> + * system will fail.
While this is true, it's also a bit misleading. RTE_EVENT_OP_NEW events
being backpressured is controlled by new_event_threshold on the level of
the port.
> + * The value cannot exceed @ref rte_event_dev_info.max_num_events
> + * returned by rte_event_dev_info_get().
> * This value should be set to -1 for *open system*.
> */
> uint8_t nb_event_queues;
> /**< Number of event queues to configure on this device.
> - * This value cannot exceed the *max_event_queues* which previously
> - * provided in rte_event_dev_info_get()
> + * This value cannot exceed @ref rte_event_dev_info.max_event_queues
> + * returned by rte_event_dev_info_get()
> */
> uint8_t nb_event_ports;
> /**< Number of event ports to configure on this device.
> - * This value cannot exceed the *max_event_ports* which previously
> - * provided in rte_event_dev_info_get()
> + * This value cannot exceed @ref rte_event_dev_info.max_event_ports
> + * returned by rte_event_dev_info_get()
> */
> uint32_t nb_event_queue_flows;
> - /**< Number of flows for any event queue on this device.
> - * This value cannot exceed the *max_event_queue_flows* which previously
> - * provided in rte_event_dev_info_get()
> + /**< Max number of flows needed for a single event queue on this device.
> + * This value cannot exceed @ref rte_event_dev_info.max_event_queue_flows
> + * returned by rte_event_dev_info_get()
> */
> uint32_t nb_event_port_dequeue_depth;
> - /**< Maximum number of events can be dequeued at a time from an
> - * event port by this device.
> - * This value cannot exceed the *max_event_port_dequeue_depth*
> - * which previously provided in rte_event_dev_info_get().
> + /**< Max number of events that can be dequeued at a time from an event port on this device.
> + * This value cannot exceed @ref rte_event_dev_info.max_event_port_dequeue_depth
> + * returned by rte_event_dev_info_get().
> * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable.
> - * @see rte_event_port_setup()
> + * @see rte_event_port_setup() rte_event_dequeue_burst()
> */
> uint32_t nb_event_port_enqueue_depth;
> - /**< Maximum number of events can be enqueued at a time from an
> - * event port by this device.
> - * This value cannot exceed the *max_event_port_enqueue_depth*
> - * which previously provided in rte_event_dev_info_get().
> + /**< Maximum number of events can be enqueued at a time to an event port on this device.
> + * This value cannot exceed @ref rte_event_dev_info.max_event_port_enqueue_depth
> + * returned by rte_event_dev_info_get().
> * Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable.
> - * @see rte_event_port_setup()
> + * @see rte_event_port_setup() rte_event_enqueue_burst()
> */
> uint32_t event_dev_cfg;
> /**< Event device config flags(RTE_EVENT_DEV_CFG_)*/
> @@ -652,7 +653,7 @@ struct rte_event_dev_config {
> * queues; this value cannot exceed *nb_event_ports* or
> * *nb_event_queues*. If the device has ports and queues that are
> * optimized for single-link usage, this field is a hint for how many
> - * to allocate; otherwise, regular event ports and queues can be used.
> + * to allocate; otherwise, regular event ports and queues will be used.
> */
> };
>
On Tue, Jan 23, 2024 at 10:46:00AM +0100, Mattias Rönnblom wrote:
> On 2024-01-19 18:43, Bruce Richardson wrote:
> > General rewording and cleanup on the rte_event_dev_config structure.
> > Improved the wording of some sentences and created linked
> > cross-references out of the existing references to the dev_info
> > structure.
> >
> > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> > lib/eventdev/rte_eventdev.h | 47 +++++++++++++++++++------------------
> > 1 file changed, 24 insertions(+), 23 deletions(-)
> >
> > diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> > index c57c93a22e..4139ccb982 100644
> > --- a/lib/eventdev/rte_eventdev.h
> > +++ b/lib/eventdev/rte_eventdev.h
> > @@ -599,9 +599,9 @@ rte_event_dev_attr_get(uint8_t dev_id, uint32_t attr_id,
> > struct rte_event_dev_config {
> > uint32_t dequeue_timeout_ns;
> > /**< rte_event_dequeue_burst() timeout on this device.
> > - * This value should be in the range of *min_dequeue_timeout_ns* and
> > - * *max_dequeue_timeout_ns* which previously provided in
> > - * rte_event_dev_info_get()
> > + * This value should be in the range of @ref rte_event_dev_info.min_dequeue_timeout_ns and
> > + * @ref rte_event_dev_info.max_dequeue_timeout_ns returned by
> > + * @ref rte_event_dev_info_get()
> > * The value 0 is allowed, in which case, default dequeue timeout used.
> > * @see RTE_EVENT_DEV_CFG_PER_DEQUEUE_TIMEOUT
> > */
> > @@ -609,40 +609,41 @@ struct rte_event_dev_config {
> > /**< In a *closed system* this field is the limit on maximum number of
> > * events that can be inflight in the eventdev at a given time. The
> > * limit is required to ensure that the finite space in a closed system
> > - * is not overwhelmed. The value cannot exceed the *max_num_events*
> > - * as provided by rte_event_dev_info_get().
> > + * is not overwhelmed.
>
> "overwhelmed" -> "exhausted"
>
> > + * Once the limit has been reached, any enqueues of NEW events to the
> > + * system will fail.
>
> While this is true, it's also a bit misleading. RTE_EVENT_OP_NEW events
> being backpressured is controlled by new_event_threshold on the level of the
> port.
>
Right. Will remove this statement, and instead add a cross-reference to the
new_event_threshold setting at the end of the comment.
/Bruce
@@ -599,9 +599,9 @@ rte_event_dev_attr_get(uint8_t dev_id, uint32_t attr_id,
struct rte_event_dev_config {
uint32_t dequeue_timeout_ns;
/**< rte_event_dequeue_burst() timeout on this device.
- * This value should be in the range of *min_dequeue_timeout_ns* and
- * *max_dequeue_timeout_ns* which previously provided in
- * rte_event_dev_info_get()
+ * This value should be in the range of @ref rte_event_dev_info.min_dequeue_timeout_ns and
+ * @ref rte_event_dev_info.max_dequeue_timeout_ns returned by
+ * @ref rte_event_dev_info_get()
* The value 0 is allowed, in which case, default dequeue timeout used.
* @see RTE_EVENT_DEV_CFG_PER_DEQUEUE_TIMEOUT
*/
@@ -609,40 +609,41 @@ struct rte_event_dev_config {
/**< In a *closed system* this field is the limit on maximum number of
* events that can be inflight in the eventdev at a given time. The
* limit is required to ensure that the finite space in a closed system
- * is not overwhelmed. The value cannot exceed the *max_num_events*
- * as provided by rte_event_dev_info_get().
+ * is not overwhelmed.
+ * Once the limit has been reached, any enqueues of NEW events to the
+ * system will fail.
+ * The value cannot exceed @ref rte_event_dev_info.max_num_events
+ * returned by rte_event_dev_info_get().
* This value should be set to -1 for *open system*.
*/
uint8_t nb_event_queues;
/**< Number of event queues to configure on this device.
- * This value cannot exceed the *max_event_queues* which previously
- * provided in rte_event_dev_info_get()
+ * This value cannot exceed @ref rte_event_dev_info.max_event_queues
+ * returned by rte_event_dev_info_get()
*/
uint8_t nb_event_ports;
/**< Number of event ports to configure on this device.
- * This value cannot exceed the *max_event_ports* which previously
- * provided in rte_event_dev_info_get()
+ * This value cannot exceed @ref rte_event_dev_info.max_event_ports
+ * returned by rte_event_dev_info_get()
*/
uint32_t nb_event_queue_flows;
- /**< Number of flows for any event queue on this device.
- * This value cannot exceed the *max_event_queue_flows* which previously
- * provided in rte_event_dev_info_get()
+ /**< Max number of flows needed for a single event queue on this device.
+ * This value cannot exceed @ref rte_event_dev_info.max_event_queue_flows
+ * returned by rte_event_dev_info_get()
*/
uint32_t nb_event_port_dequeue_depth;
- /**< Maximum number of events can be dequeued at a time from an
- * event port by this device.
- * This value cannot exceed the *max_event_port_dequeue_depth*
- * which previously provided in rte_event_dev_info_get().
+ /**< Max number of events that can be dequeued at a time from an event port on this device.
+ * This value cannot exceed @ref rte_event_dev_info.max_event_port_dequeue_depth
+ * returned by rte_event_dev_info_get().
* Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable.
- * @see rte_event_port_setup()
+ * @see rte_event_port_setup() rte_event_dequeue_burst()
*/
uint32_t nb_event_port_enqueue_depth;
- /**< Maximum number of events can be enqueued at a time from an
- * event port by this device.
- * This value cannot exceed the *max_event_port_enqueue_depth*
- * which previously provided in rte_event_dev_info_get().
+ /**< Maximum number of events can be enqueued at a time to an event port on this device.
+ * This value cannot exceed @ref rte_event_dev_info.max_event_port_enqueue_depth
+ * returned by rte_event_dev_info_get().
* Ignored when device is not RTE_EVENT_DEV_CAP_BURST_MODE capable.
- * @see rte_event_port_setup()
+ * @see rte_event_port_setup() rte_event_enqueue_burst()
*/
uint32_t event_dev_cfg;
/**< Event device config flags(RTE_EVENT_DEV_CFG_)*/
@@ -652,7 +653,7 @@ struct rte_event_dev_config {
* queues; this value cannot exceed *nb_event_ports* or
* *nb_event_queues*. If the device has ports and queues that are
* optimized for single-link usage, this field is a hint for how many
- * to allocate; otherwise, regular event ports and queues can be used.
+ * to allocate; otherwise, regular event ports and queues will be used.
*/
};