Re: [PATCH v2 2/4] ethdev: add siblings iterators

[Ferruh Yigit <ferruh.yigit@intel.com>]

On 2/20/2019 10:10 PM, Thomas Monjalon wrote:
> If multiple ports share the same hardware device (rte_device),
> they are siblings and can be found thanks to the new functions
> and loop macros.
> One iterator takes a port id as reference,
> while the other one directly refers to the parent device.
> 
> The ownership is not checked because siblings may have
> different owners.
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>  lib/librte_ethdev/rte_ethdev.c           | 20 +++++++++++
>  lib/librte_ethdev/rte_ethdev.h           | 46 ++++++++++++++++++++++++
>  lib/librte_ethdev/rte_ethdev_version.map |  2 ++
>  3 files changed, 68 insertions(+)
> 
> diff --git a/lib/librte_ethdev/rte_ethdev.c b/lib/librte_ethdev/rte_ethdev.c
> index b3b2fb1dba..42154787f8 100644
> --- a/lib/librte_ethdev/rte_ethdev.c
> +++ b/lib/librte_ethdev/rte_ethdev.c
> @@ -340,6 +340,26 @@ rte_eth_find_next(uint16_t port_id)
>  	return port_id;
>  }
>  
> +uint16_t __rte_experimental

Do we need _rte_experimental on function definitions? I guess only in .h file,
function declaration is enough.

> +rte_eth_find_next_of(uint16_t port_id, const struct rte_device *parent)

Out of curiosity, what '_of' refers to?

> +{
> +	while (port_id < RTE_MAX_ETHPORTS &&
> +			rte_eth_devices[port_id].state == RTE_ETH_DEV_UNUSED &&
> +			rte_eth_devices[port_id].device != parent)
> +		port_id++;

Is this logic correct, or am I missing something.
When port status is ATTACHED, check will return false and exit from loop without
checking if the 'device' is same.
+1 to Gaetan's suggestion to use 'rte_eth_find_next()', which moves status
concern to that function.

> +
> +	if (port_id >= RTE_MAX_ETHPORTS)
> +		return RTE_MAX_ETHPORTS;
> +
> +	return port_id;
> +}
> +
> +uint16_t __rte_experimental
> +rte_eth_find_next_sibling(uint16_t port_id, uint16_t ref)

I think better to say 'ref_port_id' to clarify what we expect here is a port_id

> +{
> +	return rte_eth_find_next_of(port_id, rte_eth_devices[ref].device);

This is a public API, shouldn't we check if 'ref' if valid port_id value, before
accessing the '.device' field?

> +}
> +
>  static void
>  rte_eth_dev_shared_data_prepare(void)
>  {
> diff --git a/lib/librte_ethdev/rte_ethdev.h b/lib/librte_ethdev/rte_ethdev.h
> index a3c864a134..a7c5c36277 100644
> --- a/lib/librte_ethdev/rte_ethdev.h
> +++ b/lib/librte_ethdev/rte_ethdev.h
> @@ -1383,6 +1383,52 @@ uint16_t rte_eth_find_next(uint16_t port_id);
>  #define RTE_ETH_FOREACH_DEV(p) \
>  	RTE_ETH_FOREACH_DEV_OWNED_BY(p, RTE_ETH_DEV_NO_OWNER)
>  
> +/**
> + * Iterates over ethdev ports of a specified device.
> + *
> + * @param port_id_start
> + *   The id of the next possible valid port.
> + * @param parent
> + *   The generic device behind the ports to iterate.
> + * @return
> + *   Next port id of the device, RTE_MAX_ETHPORTS if there is none.

Can return 'port_id_start', right? Should it be documented as it is done in
below 'next_sibling' one?

> + */
> +__rte_experimental
> +uint16_t rte_eth_find_next_of(uint16_t port_id_start,
> +		const struct rte_device *parent);
> +
> +/**
> + * Macro to iterate over all ethdev ports sharing the same rte_device
> + * as the specified port.

'specified port'? No port specified, a device pointer is specified.

> + * Note: the specified port is part of the loop iterations.
> + */

Does it make sense to clarify what 'p' is and what 'parent' is as we do in
function doxygen comments? Since these are macros, harder to grasp the types, I
think better to describe more in macro documentation.

> +#define RTE_ETH_FOREACH_DEV_OF(p, parent) \
> +	for (p = rte_eth_find_next_of(0, parent); \
> +		p < RTE_MAX_ETHPORTS; \
> +		p = rte_eth_find_next_of(p + 1, parent))
> +
> +/**
> + * Iterates over sibling ethdev ports (i.e. sharing the same rte_device).
> + *
> + * @param port_id_start
> + *   The id of the next possible valid sibling port.
> + * @param ref
> + *   The id of a reference port to compare rte_device with.
> + * @return
> + *   Next sibling port id (or ref itself), RTE_MAX_ETHPORTS if there is none.
> + */
> +__rte_experimental
> +uint16_t rte_eth_find_next_sibling(uint16_t port_id_start, uint16_t ref);
> +
> +/**
> + * Macro to iterate over all ethdev ports sharing the same rte_device
> + * as the specified port.
> + * Note: the specified port is part of the loop iterations.
> + */
> +#define RTE_ETH_FOREACH_DEV_SIBLING(p, ref) \
> +	for (p = rte_eth_find_next_sibling(0, ref); \
> +		p < RTE_MAX_ETHPORTS; \
> +		p = rte_eth_find_next_sibling(p + 1, ref))
>  
>  /**
>   * @warning
> diff --git a/lib/librte_ethdev/rte_ethdev_version.map b/lib/librte_ethdev/rte_ethdev_version.map
> index 92ac3de250..b37a4167d7 100644
> --- a/lib/librte_ethdev/rte_ethdev_version.map
> +++ b/lib/librte_ethdev/rte_ethdev_version.map
> @@ -245,6 +245,8 @@ EXPERIMENTAL {
>  	rte_eth_dev_owner_set;
>  	rte_eth_dev_owner_unset;
>  	rte_eth_dev_rx_intr_ctl_q_get_fd;
> +	rte_eth_find_next_of;
> +	rte_eth_find_next_sibling;
>  	rte_eth_switch_domain_alloc;
>  	rte_eth_switch_domain_free;
>  	rte_flow_conv;
>