[PATCH v1 7/7] eventdev: fix documentation for counting single-link ports

[PATCH v1 7/7] eventdev: fix documentation for counting single-link ports

[Bruce Richardson]

The documentation of how single-link port-queue pairs were counted in
the rte_event_dev_config structure did not match the actual
implementation and, if following the documentation, certain valid
port/queue configurations would have been impossible to configure. Fix
this by changing the documentation to match the implementation - however
confusing that implementation ends up being.

Bugzilla ID:  1368
Fixes: 75d113136f38 ("eventdev: express DLB/DLB2 PMD constraints")
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 lib/eventdev/rte_eventdev.h | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 4139ccb982..3b8f5b8101 100644
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -490,7 +490,10 @@ struct rte_event_dev_info {
 	uint32_t dequeue_timeout_ns;
 	/**< Configured global dequeue timeout(ns) for this device */
 	uint8_t max_event_queues;
-	/**< Maximum event queues supported by this device */
+	/**< Maximum event queues supported by this device.
+	 * This excludes any queue-port pairs covered by the
+	 * *max_single_link_event_port_queue_pairs* value in this structure.
+	 */
 	uint32_t max_event_queue_flows;
 	/**< Maximum number of flows within an event queue supported by this device*/
 	uint8_t max_event_queue_priority_levels;
@@ -506,7 +509,10 @@ struct rte_event_dev_info {
 	 * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST.
 	 */
 	uint8_t max_event_ports;
-	/**< Maximum number of event ports supported by this device */
+	/**< Maximum number of event ports supported by this device
+	 * This excludes any queue-port pairs covered by the
+	 * *max_single_link_event_port_queue_pairs* value in this structure.
+	 */
 	uint8_t max_event_port_dequeue_depth;
 	/**< Maximum number of events that can be dequeued at a time from an event port
 	 * on this device.
@@ -618,13 +624,23 @@ struct rte_event_dev_config {
 	 */
 	uint8_t nb_event_queues;
 	/**< Number of event queues to configure on this device.
-	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues
-	 * returned by rte_event_dev_info_get()
+	 * This value *includes* any single-link queue-port pairs to be used.
+	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues +
+	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
+	 * returned by rte_event_dev_info_get().
+	 * The number of non-single-link queues i.e. this value less
+	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
+	 * @ref rte_event_dev_info.max_event_queues
 	 */
 	uint8_t nb_event_ports;
 	/**< Number of event ports to configure on this device.
-	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports
-	 * returned by rte_event_dev_info_get()
+	 * This value *includes* any single-link queue-port pairs to be used.
+	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports +
+	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
+	 * returned by rte_event_dev_info_get().
+	 * The number of non-single-link ports i.e. this value less
+	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
+	 * @ref rte_event_dev_info.max_event_ports
 	 */
 	uint32_t nb_event_queue_flows;
 	/**< Max number of flows needed for a single event queue on this device.
--
2.40.1

[PATCH v2 07/11] eventdev: fix documentation for counting single-link ports

[Bruce Richardson]

The documentation of how single-link port-queue pairs were counted in
the rte_event_dev_config structure did not match the actual
implementation and, if following the documentation, certain valid
port/queue configurations would have been impossible to configure. Fix
this by changing the documentation to match the implementation - however
confusing that implementation ends up being.

Bugzilla ID:  1368
Fixes: 75d113136f38 ("eventdev: express DLB/DLB2 PMD constraints")
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 lib/eventdev/rte_eventdev.h | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 4139ccb982..3b8f5b8101 100644
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -490,7 +490,10 @@ struct rte_event_dev_info {
 	uint32_t dequeue_timeout_ns;
 	/**< Configured global dequeue timeout(ns) for this device */
 	uint8_t max_event_queues;
-	/**< Maximum event queues supported by this device */
+	/**< Maximum event queues supported by this device.
+	 * This excludes any queue-port pairs covered by the
+	 * *max_single_link_event_port_queue_pairs* value in this structure.
+	 */
 	uint32_t max_event_queue_flows;
 	/**< Maximum number of flows within an event queue supported by this device*/
 	uint8_t max_event_queue_priority_levels;
@@ -506,7 +509,10 @@ struct rte_event_dev_info {
 	 * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST.
 	 */
 	uint8_t max_event_ports;
-	/**< Maximum number of event ports supported by this device */
+	/**< Maximum number of event ports supported by this device
+	 * This excludes any queue-port pairs covered by the
+	 * *max_single_link_event_port_queue_pairs* value in this structure.
+	 */
 	uint8_t max_event_port_dequeue_depth;
 	/**< Maximum number of events that can be dequeued at a time from an event port
 	 * on this device.
@@ -618,13 +624,23 @@ struct rte_event_dev_config {
 	 */
 	uint8_t nb_event_queues;
 	/**< Number of event queues to configure on this device.
-	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues
-	 * returned by rte_event_dev_info_get()
+	 * This value *includes* any single-link queue-port pairs to be used.
+	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues +
+	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
+	 * returned by rte_event_dev_info_get().
+	 * The number of non-single-link queues i.e. this value less
+	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
+	 * @ref rte_event_dev_info.max_event_queues
 	 */
 	uint8_t nb_event_ports;
 	/**< Number of event ports to configure on this device.
-	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports
-	 * returned by rte_event_dev_info_get()
+	 * This value *includes* any single-link queue-port pairs to be used.
+	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports +
+	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
+	 * returned by rte_event_dev_info_get().
+	 * The number of non-single-link ports i.e. this value less
+	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
+	 * @ref rte_event_dev_info.max_event_ports
 	 */
 	uint32_t nb_event_queue_flows;
 	/**< Max number of flows needed for a single event queue on this device.
-- 
2.40.1

Re: [PATCH v2 07/11] eventdev: fix documentation for counting single-link ports

[Mattias Rönnblom]

On 2024-01-19 18:43, Bruce Richardson wrote:
> The documentation of how single-link port-queue pairs were counted in
> the rte_event_dev_config structure did not match the actual
> implementation and, if following the documentation, certain valid

What "documentation" and what "implementation" are you talking about here?

I'm confused. An DLB2 fix in the form of Eventdev API documentation update.

> port/queue configurations would have been impossible to configure. Fix
> this by changing the documentation to match the implementation - however
> confusing that implementation ends up being.
> 
> Bugzilla ID:  1368
> Fixes: 75d113136f38 ("eventdev: express DLB/DLB2 PMD constraints")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> ---
>   lib/eventdev/rte_eventdev.h | 28 ++++++++++++++++++++++------
>   1 file changed, 22 insertions(+), 6 deletions(-)
> 
> diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> index 4139ccb982..3b8f5b8101 100644
> --- a/lib/eventdev/rte_eventdev.h
> +++ b/lib/eventdev/rte_eventdev.h
> @@ -490,7 +490,10 @@ struct rte_event_dev_info {
>   	uint32_t dequeue_timeout_ns;
>   	/**< Configured global dequeue timeout(ns) for this device */
>   	uint8_t max_event_queues;
> -	/**< Maximum event queues supported by this device */
> +	/**< Maximum event queues supported by this device.
> +	 * This excludes any queue-port pairs covered by the
> +	 * *max_single_link_event_port_queue_pairs* value in this structure.
> +	 */
>   	uint32_t max_event_queue_flows;
>   	/**< Maximum number of flows within an event queue supported by this device*/
>   	uint8_t max_event_queue_priority_levels;
> @@ -506,7 +509,10 @@ struct rte_event_dev_info {
>   	 * @ref RTE_EVENT_DEV_PRIORITY_HIGHEST and @ref RTE_EVENT_DEV_PRIORITY_LOWEST.
>   	 */
>   	uint8_t max_event_ports;
> -	/**< Maximum number of event ports supported by this device */
> +	/**< Maximum number of event ports supported by this device
> +	 * This excludes any queue-port pairs covered by the
> +	 * *max_single_link_event_port_queue_pairs* value in this structure.
> +	 */
>   	uint8_t max_event_port_dequeue_depth;
>   	/**< Maximum number of events that can be dequeued at a time from an event port
>   	 * on this device.
> @@ -618,13 +624,23 @@ struct rte_event_dev_config {
>   	 */
>   	uint8_t nb_event_queues;
>   	/**< Number of event queues to configure on this device.
> -	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues
> -	 * returned by rte_event_dev_info_get()
> +	 * This value *includes* any single-link queue-port pairs to be used.
> +	 * This value cannot exceed @ref rte_event_dev_info.max_event_queues +
> +	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
> +	 * returned by rte_event_dev_info_get().
> +	 * The number of non-single-link queues i.e. this value less
> +	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
> +	 * @ref rte_event_dev_info.max_event_queues
>   	 */
>   	uint8_t nb_event_ports;
>   	/**< Number of event ports to configure on this device.
> -	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports
> -	 * returned by rte_event_dev_info_get()
> +	 * This value *includes* any single-link queue-port pairs to be used.
> +	 * This value cannot exceed @ref rte_event_dev_info.max_event_ports +
> +	 * @ref rte_event_dev_info.max_single_link_event_port_queue_pairs
> +	 * returned by rte_event_dev_info_get().
> +	 * The number of non-single-link ports i.e. this value less
> +	 * *nb_single_link_event_port_queues* in this struct, cannot exceed
> +	 * @ref rte_event_dev_info.max_event_ports
>   	 */
>   	uint32_t nb_event_queue_flows;
>   	/**< Max number of flows needed for a single event queue on this device.

Re: [PATCH v2 07/11] eventdev: fix documentation for counting single-link ports

[Bruce Richardson]

On Tue, Jan 23, 2024 at 10:48:47AM +0100, Mattias Rönnblom wrote:
> On 2024-01-19 18:43, Bruce Richardson wrote:
> > The documentation of how single-link port-queue pairs were counted in
> > the rte_event_dev_config structure did not match the actual
> > implementation and, if following the documentation, certain valid
> 
> What "documentation" and what "implementation" are you talking about here?
> 
> I'm confused. An DLB2 fix in the form of Eventdev API documentation update.
> 

The documentation in the header file did not match the implementation in
the rte_eventdev.c file.

The current documentation states[1] that "This value cannot exceed the
max_event_queues which previously provided in rte_event_dev_info_get()",
but if you check the implementation in the C file[2], it actually checks
the passed value against 
"info.max_event_queues + info.max_single_link_event_port_queue_pairs".


[1] https://doc.dpdk.org/api/structrte__event__dev__config.html#a703c026d74436b05fc656652324101e4
[2] https://git.dpdk.org/dpdk/tree/lib/eventdev/rte_eventdev.c#n402

Re: [PATCH v2 07/11] eventdev: fix documentation for counting single-link ports

[Bruce Richardson]

On Tue, Jan 23, 2024 at 09:56:23AM +0000, Bruce Richardson wrote:
> On Tue, Jan 23, 2024 at 10:48:47AM +0100, Mattias Rönnblom wrote:
> > On 2024-01-19 18:43, Bruce Richardson wrote:
> > > The documentation of how single-link port-queue pairs were counted in
> > > the rte_event_dev_config structure did not match the actual
> > > implementation and, if following the documentation, certain valid
> > 
> > What "documentation" and what "implementation" are you talking about here?
> > 
> > I'm confused. An DLB2 fix in the form of Eventdev API documentation update.
> > 
> 
> The documentation in the header file did not match the implementation in
> the rte_eventdev.c file.
> 
> The current documentation states[1] that "This value cannot exceed the
> max_event_queues which previously provided in rte_event_dev_info_get()",
> but if you check the implementation in the C file[2], it actually checks
> the passed value against 
> "info.max_event_queues + info.max_single_link_event_port_queue_pairs".
> 
> 
> [1] https://doc.dpdk.org/api/structrte__event__dev__config.html#a703c026d74436b05fc656652324101e4
> [2] https://git.dpdk.org/dpdk/tree/lib/eventdev/rte_eventdev.c#n402
>

Dropping this as a separate patch for v3, and just including the necessary
doc corrections in the previous patches for the info and config structs.

/Bruce

[PATCH v4 12/12] eventdev: fix doxygen processing of event vector struct

[Bruce Richardson]

The event vector struct was missing comments on two members, and also
was inadvertently creating a local variable called "__rte_aligned" in
the doxygen output.

Correct the comment markers to fix the former issue, and fix the latter
by putting "#ifdef __DOXYGEN" around the alignment constraint.

Fixes: 1cc44d409271 ("eventdev: introduce event vector capability")
Fixes: 3c838062b91f ("eventdev: introduce event vector Rx capability")
Fixes: 699155f2d4e2 ("eventdev: fix clang C++ include")
Cc: stable@dpdk.org

Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
---
 lib/eventdev/rte_eventdev.h | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
index 03748eb437..cf7d103a6c 100644
--- a/lib/eventdev/rte_eventdev.h
+++ b/lib/eventdev/rte_eventdev.h
@@ -1358,10 +1358,8 @@ struct rte_event_vector {
 		 * port and queue of the mbufs in the vector
 		 */
 		struct {
-			uint16_t port;
-			/* Ethernet device port id. */
-			uint16_t queue;
-			/* Ethernet device queue id. */
+			uint16_t port;   /**< Ethernet device port id. */
+			uint16_t queue;  /**< Ethernet device queue id. */
 		};
 	};
 	/**< Union to hold common attributes of the vector array. */
@@ -1390,7 +1388,11 @@ struct rte_event_vector {
 	 * vector array can be an array of mbufs or pointers or opaque u64
 	 * values.
 	 */
+#ifndef __DOXYGEN__
 } __rte_aligned(16);
+#else
+};
+#endif
 
 /* Scheduler type definitions */
 #define RTE_SCHED_TYPE_ORDERED          0
-- 
2.40.1

RE: [EXT] [PATCH v4 12/12] eventdev: fix doxygen processing of event vector struct

[Pavan Nikhilesh Bhagavatula]

> The event vector struct was missing comments on two members, and also
> was inadvertently creating a local variable called "__rte_aligned" in
> the doxygen output.
> 
> Correct the comment markers to fix the former issue, and fix the latter
> by putting "#ifdef __DOXYGEN" around the alignment constraint.
> 
> Fixes: 1cc44d409271 ("eventdev: introduce event vector capability")
> Fixes: 3c838062b91f ("eventdev: introduce event vector Rx capability")
> Fixes: 699155f2d4e2 ("eventdev: fix clang C++ include")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>

Acked-by: Pavan Nikhilesh <pbhagavatula@marvell.com>

> ---
>  lib/eventdev/rte_eventdev.h | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/lib/eventdev/rte_eventdev.h b/lib/eventdev/rte_eventdev.h
> index 03748eb437..cf7d103a6c 100644
> --- a/lib/eventdev/rte_eventdev.h
> +++ b/lib/eventdev/rte_eventdev.h
> @@ -1358,10 +1358,8 @@ struct rte_event_vector {
>  		 * port and queue of the mbufs in the vector
>  		 */
>  		struct {
> -			uint16_t port;
> -			/* Ethernet device port id. */
> -			uint16_t queue;
> -			/* Ethernet device queue id. */
> +			uint16_t port;   /**< Ethernet device port id. */
> +			uint16_t queue;  /**< Ethernet device queue id. */
>  		};
>  	};
>  	/**< Union to hold common attributes of the vector array. */
> @@ -1390,7 +1388,11 @@ struct rte_event_vector {
>  	 * vector array can be an array of mbufs or pointers or opaque u64
>  	 * values.
>  	 */
> +#ifndef __DOXYGEN__
>  } __rte_aligned(16);
> +#else
> +};
> +#endif
> 
>  /* Scheduler type definitions */
>  #define RTE_SCHED_TYPE_ORDERED          0
> --
> 2.40.1

Re: [PATCH v4 12/12] eventdev: fix doxygen processing of event vector struct

[Thomas Monjalon]

21/02/2024 11:32, Bruce Richardson:
> The event vector struct was missing comments on two members, and also
> was inadvertently creating a local variable called "__rte_aligned" in
> the doxygen output.
> 
> Correct the comment markers to fix the former issue, and fix the latter
> by putting "#ifdef __DOXYGEN" around the alignment constraint.
[..]
> +#ifndef __DOXYGEN__
>  } __rte_aligned(16);
> +#else
> +};
> +#endif

Would it be possible to make __rte_aligned empty in rte_common.h
instead of each call? Does it fix Doxygen bug?

Re: [PATCH v4 12/12] eventdev: fix doxygen processing of event vector struct

[Bruce Richardson]

On Mon, Mar 04, 2024 at 04:35:41PM +0100, Thomas Monjalon wrote:
> 21/02/2024 11:32, Bruce Richardson:
> > The event vector struct was missing comments on two members, and also
> > was inadvertently creating a local variable called "__rte_aligned" in
> > the doxygen output.
> > 
> > Correct the comment markers to fix the former issue, and fix the latter
> > by putting "#ifdef __DOXYGEN" around the alignment constraint.
> [..]
> > +#ifndef __DOXYGEN__
> >  } __rte_aligned(16);
> > +#else
> > +};
> > +#endif
> 
> Would it be possible to make __rte_aligned empty in rte_common.h
> instead of each call? Does it fix Doxygen bug?
> 
I think that should be fixed globally by Tyler's series for "alignas"[1]
With the new placement for the alignment macro, I don't think this doxygen
issue will occur again.

[1] https://patches.dpdk.org/project/dpdk/list/?series=31229