Re: [dpdk-dev] [WARNING: UNSCANNABLE EXTRACTION FAILED][WARNING: UNSCANNABLE EXTRACTION FAILED] [PATCH v5] doc: mtr: add API walk through

[Jerin Jacob <jerinjacobk@gmail.com>]

On Fri, Aug 6, 2021 at 11:16 PM Dumitrescu, Cristian
<cristian.dumitrescu@intel.com> wrote:
>
> Hi Jerin,

Hi Cristian,

I will next version with your suggestions.

>
> > +API Walk-through
> > +----------------
> > +
> > +.. _figure_rte_mtr_chaining:
> > +
> > +.. figure:: img/rte_mtr_meter_chaining.*
> > +
> > +   Meter components
> > +
> > +This section will introduce the reader to the critical APIs to use
> > +the traffic meter and policing library.
> > +
> > +In general, the application performs the following steps to configure the
> > +traffic meter and policing library.
> > +
> > +#. Application gets the meter driver capabilities using
> > ``rte_mtr_capabilities_get()``.
> > +#. The application creates the required meter profiles by using the
> > +   ``rte_mtr_meter_profile_add()`` API function.
> > +#. The application creates the required meter policies by using the
> > +   ``rte_mtr_meter_policy_add()`` API function.
> > +#. One of the previously created meter profile
> > +   (``struct rte_mtr_params::meter_profile_id``) and meter policy
> > +   (``struct rte_mtr_params::meter_policy_id``) are provided as arguments
> > +   at this step.
>
> You somehow dropped the first statement from this last bullet:
>
>         The application creates a meter object using the rte_mtr_create() API function.
>
> > +#. The application enables the meter object execution as part of the flow
> > action
> > +   processing by calling the ``rte_flow_create()`` API function with one of the
> > +   flow action set to ``RTE_FLOW_ACTION_TYPE_METER`` and the associated
> > +   meter object ID set to this meter object.
> > +#. The API allows chaining the meter objects to create complex metering
> > topology
> > +   by the following methods.
> > +
> > +   * Stacking multiple ``rte_flow_action`` as
> > +     ``RTE_FLOW_ACTION_TYPE_METER`` with ``struct
> > rte_flow_action_meter::mtr_id``
> > +     as meter ID. The last added RTE_FLOW_ACTION_TYPE_METER object
> > represent as
> > +     leaf node (closest to ethdev receive queue)
> > +
>
> Stacking might point people to reverse order execution of actions, which is not the case, as the flow actions are executed sequentially from first to last. Also the last meter action is not the last flow action (your reference to leaf node?), as the last flow action must be the END action, right?
>
> How about:
>         * Adding multiple flow actions of the type ``RTE_FLOW_ACTION_TYPE_METER`` to the same flow. Each of the meter action typically refers to a different meter object.
>
> I was suggesting a similar diagram for this case, but it might be too much to ask for :)
>
> > +   * As show in :numref:`figure_rte_mtr_chaining` specify
> > +     ``struct rte_mtr_meter_policy_params::actions`` action as
> > +     ``RTE_FLOW_ACTION_TYPE_METER`` per color.
>
> I would add a high level statement before yours, something like:
>         * Adding one (or multiple) actions of the type ``RTE_FLOW_ACTION_TYPE_METER`` to the list of meter actions specified per color.
>
> Regards,
> Cristian