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

  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(-)
  

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.
  

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
  

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