[1/4] doc: clarify RTE flow behaviour on port stop/start

  It is now clearly stated that RTE flow rules can be
created only after the port is started.

Signed-off-by: Martin Havlik <xhavli56@stud.fit.vutbr.cz>
---
 doc/guides/nics/mlx5.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)
  

On 7/21/21 6:55 PM, Martin Havlik wrote:
> It is now clearly stated that RTE flow rules can be
> created only after the port is started.
> 
> Signed-off-by: Martin Havlik <xhavli56@stud.fit.vutbr.cz>
> ---
>   doc/guides/nics/mlx5.rst | 6 +++++-
>   1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
> index f5b727c1ee..119d537adf 100644
> --- a/doc/guides/nics/mlx5.rst
> +++ b/doc/guides/nics/mlx5.rst
> @@ -1790,21 +1790,25 @@ Notes for rte_flow
>   ------------------
>   
>   Flows are not cached in the driver.
>   When stopping a device port, all the flows created on this port from the
>   application will be flushed automatically in the background.
>   After stopping the device port, all flows on this port become invalid and
>   not represented in the system.
>   All references to these flows held by the application should be discarded
>   directly but neither destroyed nor flushed.
>   
> -The application should re-create the flows as required after the port restart.
> +The application should re-create the flows as required after the port is
> +started again.
> +
> +Creating flows before port start is not permitted. All flows the application
> +wants to create have to be created after the port is started.

I'm not 100% sure that it is always OK for applications, but in an
attempt to make it OK we should:
  - mention isolated mode if application dislikes default flow rules and
    would like to control it
  - mention what happens if restart happens internally, e.g. in order to
    recover from broken state. I guess in this case we need an event and
    application must register callback and handle it.

>   
>   Notes for testpmd
>   -----------------
>   
>   Compared to librte_net_mlx4 that implements a single RSS configuration per
>   port, librte_net_mlx5 supports per-protocol RSS configuration.
>   
>   Since ``testpmd`` defaults to IP RSS mode and there is currently no
>   command-line parameter to enable additional protocols (UDP and TCP as well
>   as IP), the following commands must be entered from its CLI to get the same
>
  

2021-07-22 13:32 (UTC+0300), Andrew Rybchenko:
> On 7/21/21 6:55 PM, Martin Havlik wrote:
> > It is now clearly stated that RTE flow rules can be
> > created only after the port is started.
> > 
> > Signed-off-by: Martin Havlik <xhavli56@stud.fit.vutbr.cz>
> > ---
> >   doc/guides/nics/mlx5.rst | 6 +++++-
> >   1 file changed, 5 insertions(+), 1 deletion(-)
> > 
> > diff --git a/doc/guides/nics/mlx5.rst b/doc/guides/nics/mlx5.rst
> > index f5b727c1ee..119d537adf 100644
> > --- a/doc/guides/nics/mlx5.rst
> > +++ b/doc/guides/nics/mlx5.rst
> > @@ -1790,21 +1790,25 @@ Notes for rte_flow
> >   ------------------
> >   
> >   Flows are not cached in the driver.
> >   When stopping a device port, all the flows created on this port from the
> >   application will be flushed automatically in the background.
> >   After stopping the device port, all flows on this port become invalid and
> >   not represented in the system.
> >   All references to these flows held by the application should be discarded
> >   directly but neither destroyed nor flushed.
> >   
> > -The application should re-create the flows as required after the port restart.
> > +The application should re-create the flows as required after the port is
> > +started again.
> > +
> > +Creating flows before port start is not permitted. All flows the application
> > +wants to create have to be created after the port is started.  
> 
> I'm not 100% sure that it is always OK for applications, but in an
> attempt to make it OK we should:
>   - mention isolated mode if application dislikes default flow rules and
>     would like to control it
>   - mention what happens if restart happens internally, e.g. in order to
>     recover from broken state. I guess in this case we need an event and
>     application must register callback and handle it.

I think this callback would be an unnecessary complication.
What is the notion of internal restart or recovery event, in the first place?

Port can move to some "inconsistent state" (from rte_flow_flush description).
What this means is unspecified, I guess in this state the port can only be
stopped or closed if it's not started. Which brings the port to a consistent
state where the behavior is already specified.