app/testpmd: Document what the application does.

  I could not find anything in the documentation that says what
testpmd does.  This should save other people time trying to
figure that out in the future.

Signed-off-by: Ben Pfaff <blp@ovn.org>
---
 doc/guides/testpmd_app_ug/run_app.rst | 6 ++++++
 1 file changed, 6 insertions(+)
  

10/09/2021 19:57, Ben Pfaff:
> I could not find anything in the documentation that says what
> testpmd does.  This should save other people time trying to
> figure that out in the future.

Good move indeed :)

> --- a/doc/guides/testpmd_app_ug/run_app.rst
> +++ b/doc/guides/testpmd_app_ug/run_app.rst
> @@ -15,6 +15,12 @@ a list of available EAL command-line options.
>  Testpmd Command-line Options
>  ----------------------------
>  
> +By default, testpmd receives packets on each configured port and
> +forwards the received packets to its paired port.  Ports 0 and 1 are
> +paired, as are ports 2 and 3, and so on.  With an odd number of ports,
> +the last port is paired with itself: packets received on the port are
> +sent back out on the same port.

So the intent is to say what is the default behaviour?

We could also update the introduction which is outdated:
"
The testpmd application can be used to test the DPDK
in a packet forwarding mode and also to access NIC hardware features
such as Flow Director.
It also serves as a example of how to build a more fully-featured
application using the DPDK SDK.
"

The last sentence should be removed.
The first sentence is a bit outdated.
We should say "testpmd is a tool to test ethdev NIC features".

May I take the opportunity of this patch to improve this intro as well?
  

On Fri, Sep 10, 2021 at 11:14:26PM +0200, Thomas Monjalon wrote:
> 10/09/2021 19:57, Ben Pfaff:
> > I could not find anything in the documentation that says what
> > testpmd does.  This should save other people time trying to
> > figure that out in the future.
> 
> Good move indeed :)
> 
> > --- a/doc/guides/testpmd_app_ug/run_app.rst
> > +++ b/doc/guides/testpmd_app_ug/run_app.rst
> > @@ -15,6 +15,12 @@ a list of available EAL command-line options.
> >  Testpmd Command-line Options
> >  ----------------------------
> >  
> > +By default, testpmd receives packets on each configured port and
> > +forwards the received packets to its paired port.  Ports 0 and 1 are
> > +paired, as are ports 2 and 3, and so on.  With an odd number of ports,
> > +the last port is paired with itself: packets received on the port are
> > +sent back out on the same port.
> 
> So the intent is to say what is the default behaviour?

I am not sure of the full extent of the program's possible behavior,
because it has many, many options.  I didn't want to try to go beyond
what I understood it to do.

> We could also update the introduction which is outdated:
> "
> The testpmd application can be used to test the DPDK
> in a packet forwarding mode and also to access NIC hardware features
> such as Flow Director.
> It also serves as a example of how to build a more fully-featured
> application using the DPDK SDK.
> "
> 
> The last sentence should be removed.
> The first sentence is a bit outdated.
> We should say "testpmd is a tool to test ethdev NIC features".
> 
> May I take the opportunity of this patch to improve this intro as well?

I would rather have updated the introduction, but I wasn't sure that it
was wrong.  Thanks for the help.  I'll post a v2.
  

On 9/10/2021 6:57 PM, Ben Pfaff wrote:
> I could not find anything in the documentation that says what
> testpmd does.  This should save other people time trying to
> figure that out in the future.
> 
> Signed-off-by: Ben Pfaff <blp@ovn.org>
> ---
>  doc/guides/testpmd_app_ug/run_app.rst | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst
> index 6061674239..7c3406f72b 100644
> --- a/doc/guides/testpmd_app_ug/run_app.rst
> +++ b/doc/guides/testpmd_app_ug/run_app.rst
> @@ -15,6 +15,12 @@ a list of available EAL command-line options.
>  Testpmd Command-line Options
>  ----------------------------
>  
> +By default, testpmd receives packets on each configured port and
> +forwards the received packets to its paired port.  Ports 0 and 1 are
> +paired, as are ports 2 and 3, and so on.  With an odd number of ports,
> +the last port is paired with itself: packets received on the port are
> +sent back out on the same port.
Hi Ben,

testpmd has the concept of 'forwarding engine' (struct fwd_engine), which is
decoupled from testpmd logic and can be changed in the runtime. What you
described above is the 'io' (default) forwarding engine.
There are forwarding engines like 'flowgen' that generates and send L3 packets,
so behaves like a very simple packet generator, etc...

And even for the 'io' forwarding engine, the paired port description above is
controlled by "--port-topology=<paired|chained|loop>", so for example if the
'chained' topology is selected, packets will be forwarded as 0 -> 1 -> 2 -> 3 ..


Overall, I understand the intention to briefly describe the testpmd, but I think
it is not correct to reduce the description to packet forwarding, although that
is an important function of testpmd, it is not only function and testpmd does
much more, it has many control path functions.

Cheers,
ferruh


> +
>  The following are the command-line options for the testpmd applications.
>  They must be separated from the EAL options, shown in the previous section, with a ``--`` separator:
>  
>
  

On Tue, Sep 14, 2021 at 08:58:31AM +0100, Ferruh Yigit wrote:
> On 9/10/2021 6:57 PM, Ben Pfaff wrote:
> > I could not find anything in the documentation that says what
> > testpmd does.  This should save other people time trying to
> > figure that out in the future.
> > 
> > Signed-off-by: Ben Pfaff <blp@ovn.org>
> > ---
> >  doc/guides/testpmd_app_ug/run_app.rst | 6 ++++++
> >  1 file changed, 6 insertions(+)
> > 
> > diff --git a/doc/guides/testpmd_app_ug/run_app.rst b/doc/guides/testpmd_app_ug/run_app.rst
> > index 6061674239..7c3406f72b 100644
> > --- a/doc/guides/testpmd_app_ug/run_app.rst
> > +++ b/doc/guides/testpmd_app_ug/run_app.rst
> > @@ -15,6 +15,12 @@ a list of available EAL command-line options.
> >  Testpmd Command-line Options
> >  ----------------------------
> >  
> > +By default, testpmd receives packets on each configured port and
> > +forwards the received packets to its paired port.  Ports 0 and 1 are
> > +paired, as are ports 2 and 3, and so on.  With an odd number of ports,
> > +the last port is paired with itself: packets received on the port are
> > +sent back out on the same port.
> Hi Ben,
> 
> testpmd has the concept of 'forwarding engine' (struct fwd_engine), which is
> decoupled from testpmd logic and can be changed in the runtime. What you
> described above is the 'io' (default) forwarding engine.
> There are forwarding engines like 'flowgen' that generates and send L3 packets,
> so behaves like a very simple packet generator, etc...
> 
> And even for the 'io' forwarding engine, the paired port description above is
> controlled by "--port-topology=<paired|chained|loop>", so for example if the
> 'chained' topology is selected, packets will be forwarded as 0 -> 1 -> 2 -> 3 ..
> 
> 
> Overall, I understand the intention to briefly describe the testpmd, but I think
> it is not correct to reduce the description to packet forwarding, although that
> is an important function of testpmd, it is not only function and testpmd does
> much more, it has many control path functions.

I think that someone who maintains testpmd needs to take this patch
over, then.  I don't know it well enough.