Re: [dpdk-dev] [PATCH v4 1/1] ethdev: introduce indirect action APIs

[Thomas Monjalon <thomas@monjalon.net>]

16/04/2021 19:33, Bing Zhao:
> --- a/doc/guides/rel_notes/release_21_05.rst
> +++ b/doc/guides/rel_notes/release_21_05.rst
> @@ -234,6 +234,9 @@ API Changes
>  * pci: The value ``PCI_ANY_ID`` is marked as deprecated
>    and can be replaced with ``RTE_PCI_ANY_ID``.
>  
> +* ethdev: The experimental shared action APIs in ``rte_flow.h`` has been

s/APIs/API/
An API may cover more than a function, it is an interface globally.

> +  replaced from ``rte_flow_shared_action_*`` to indirect action APIs named

s/APIs/API/

> +  ``rte_flow_action_handle_*``.

A blank line is missing here.

I propose a reword:

* ethdev: The experimental flow API for shared action has been generalized
  as a flow action handle used in rules through an indirect action.
  The functions ``rte_flow_shared_action_*`` manipulating the action object
  are replaced with ``rte_flow_action_handle_*``.
  The action ``RTE_FLOW_ACTION_TYPE_SHARED`` is deprecated and can be
  replaced with ``RTE_FLOW_ACTION_TYPE_INDIRECT``.

> --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst
> +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst
> +Creating indirect actions
> +~~~~~~~~~~~~~~~~~~~~~~~~~

empty line missing after title

> +``flow indirect_action {port_id} create`` creates indirect action with optional
> +indirect action ID. It is bound to ``rte_flow_action_handle_create()``::
[...]
> +Updating indirect actions
> +~~~~~~~~~~~~~~~~~~~~~~~~~

empty line

> +``flow indirect_action {port_id} update`` updates configuration of the indirect
> +action from its indirect action ID (as returned by
> +``flow indirect_action {port_id} create``). It is bound to
> +``rte_flow_action_handle_update()``::
[...]
> +Destroying indirect actions
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~

same here and other places

> +``flow indirect_action {port_id} destroy`` destroys one or more indirect actions
> +from their indirect action IDs (as returned by
> +``flow indirect_action {port_id} create``). It is bound to
> +``rte_flow_action_handle_destroy()``::

[...]
> --- a/lib/librte_ethdev/rte_flow.h
> +++ b/lib/librte_ethdev/rte_flow.h

We should add a comment to RTE_FLOW_ACTION_TYPE_SHARED,
that it is deprecated.

> +	/**
> +	 * Describe indirect action that could be used by a single flow rule
> +	 * or multiple flow rules.
> +	 *
> +	 * Allow flow rule(s) reference the same action by the indirect action
> +	 * handle (see struct rte_flow_action_handle), rules could be on the
> +	 * same port or across different ports.
> +	 */

Proposed reword:

An action handle is referenced in a rule through an indirect action.

The same action handle may be used in multiple rules for the same
or different ethdev ports.

@see rte_flow_action_handle

> +	RTE_FLOW_ACTION_TYPE_INDIRECT,
>  };
[...]
> - * Opaque type returned after successfully creating a shared action.
> + * Opaque type returned after successfully creating an indirect action object.
> + * The definition of the object handle will be different per driver or

s/will be/is/

> + * per immediate action type.
>   *
> - * This handle can be used to manage and query the related action:
> - * - share it across multiple flow rules
> - * - update action configuration
> - * - query action data
> - * - destroy action
> + * This handle can be used to manage and query the related immediate action:
> + * - referenced in single flow rule or across multiple flow rules
> + *   over multiple ports
> + * - update action object configuration
> + * - query action object data
> + * - destroy action object
>   */
> -struct rte_flow_shared_action;
> +struct rte_flow_action_handle;

[...]
> + * Create an indirect action object that can be used by flow create, and
> + * could also be shared by different flows.

Can be simpler:
Create an indirect action object that can be used in flow rules via its handle.