[dpdk-dev,v2,4/5] doc: add documentation for szedata2 PMD

  Signed-off-by: Matej Vido <matejvido@gmail.com>
Reviewed-by: Jan Viktorin <viktorin@rehivetech.com>
---
 doc/guides/nics/index.rst            |   1 +
 doc/guides/nics/szedata2.rst         | 105 +++++++++++++++++++++++++++++++++++
 doc/guides/prog_guide/source_org.rst |   1 +
 3 files changed, 107 insertions(+)
 create mode 100644 doc/guides/nics/szedata2.rst
  

2015-09-18 10:32, Matej Vido:
> Signed-off-by: Matej Vido <matejvido@gmail.com>
> Reviewed-by: Jan Viktorin <viktorin@rehivetech.com>

Please John, could you review this new doc?
Thanks
  

Hi Matej,

Thanks for providing a documentation.
I'm sorry to give a late feedback and I would like that other contributors
have reviewed it. There are a lot of PMD developers around. Please help.


2015-09-18 10:32, Matej Vido:
> +- **libsze2**
> +
> +  This library provides API for initialization of sze2 transfers, receiving and
> +  transmitting data segments.

Please provide more information to help installing the dependencies.

> +SZEDATA2 PMD can be created by passing --vdev= option to EAL in the following
> +format:
> +
> +.. code-block:: console
> +
> +    --vdev 'DEVICE_NAME,dev_path=PATH_TO_SZEDATA2_DEVICE,rx_ifaces=RX_MASK,tx_ifaces=TX_MASK'

SZEDATA2 is not a vdev. Is it possible to probe it as a standard PCI device?
  

Hi Thomas,

thank you for feedback.

2015-10-26 16:09 GMT+01:00 Thomas Monjalon <thomas.monjalon@6wind.com>:

> Hi Matej,
>
> Thanks for providing a documentation.
> I'm sorry to give a late feedback and I would like that other contributors
> have reviewed it. There are a lot of PMD developers around. Please help.
>
>
> 2015-09-18 10:32, Matej Vido:
> > +- **libsze2**
> > +
> > +  This library provides API for initialization of sze2 transfers,
> receiving and
> > +  transmitting data segments.
>
> Please provide more information to help installing the dependencies.
>

Dependencies can be installed from RPM packages. I will add those
information in new patch version.


>
> > +SZEDATA2 PMD can be created by passing --vdev= option to EAL in the
> following
> > +format:
> > +
> > +.. code-block:: console
> > +
> > +    --vdev
> 'DEVICE_NAME,dev_path=PATH_TO_SZEDATA2_DEVICE,rx_ifaces=RX_MASK,tx_ifaces=TX_MASK'
>
> SZEDATA2 is not a vdev. Is it possible to probe it as a standard PCI
> device?
>
>
 It would be possible to probe it as a standard PCI device, but as this
szedata2 driver uses libsze2 library it needs to pass some parameters to
the library and we thought that using vdev would be the easiest solution.
Is there a way how to provide parameters to pdev driver?
We also work on a new PMD which will eliminate dependencies on kernel
modules and libsze2, and using this PMD COMBO card will be probed as a
standard PCI device.

Best regards,
Matej Vido
  

2015-10-27 18:33, Matej Vido:
> 2015-10-26 16:09 GMT+01:00 Thomas Monjalon <thomas.monjalon@6wind.com>:
> > SZEDATA2 is not a vdev. Is it possible to probe it as a standard PCI
> > device?
> >
> It would be possible to probe it as a standard PCI device, but as this
> szedata2 driver uses libsze2 library it needs to pass some parameters to
> the library and we thought that using vdev would be the easiest solution.
> Is there a way how to provide parameters to pdev driver?

No, but it could be added by working on unifying pdev and vdev.

> We also work on a new PMD which will eliminate dependencies on kernel
> modules and libsze2, and using this PMD COMBO card will be probed as a
> standard PCI device.

I think it's better to wait for your new implementation.
It would be nice to have it in the release 2.2.
Do you think it could be submitted in the coming weeks?
  

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Matej Vido
> Sent: Friday, September 18, 2015 9:33 AM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v2 4/5] doc: add documentation for szedata2 PMD
> 
> Signed-off-by: Matej Vido <matejvido@gmail.com>
> Reviewed-by: Jan Viktorin <viktorin@rehivetech.com>

Hi,

Thanks for the new PMD and the documentation.

The DPDJ documentation guidelines provide some guidance on how to format and build the DPDK documentation:

    http://dpdk.org/doc/guides/contributing/documentation.html

In terms of documentation for a PMD the Mellanox MLX4 docs are a good example:

    http://dpdk.org/doc/guides/nics/mlx4.html

Some other comments below:




> +SZEDATA2 PMD
> +============

No need for an acronym in the title. Follow the MLX4 example and use something like " SZEDATA2 poll mode driver library".



> +SZEDATA2 PMD is virtual PMD which uses sze2 layer to communicate with
> +COMBO cards (COMBO-80G, COMBO-100G) using interface provided by libsze2
> library.

The introduction can be brief but should include enough information to explain the PMD for someone encountering it for the first time.

Some links would help with this. See the MLX4 doc as an example:


> +
> +.. note::
> +
> +   This driver has external dependencies. Therefore it is disabled in
> default
> +   configuration files. It can be enabled by setting
> CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y

Format configuration items as verbatim text with  double backquotes:`` CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y ``


> +
> +Using PMD
> +---------

Better: Using the Szedata PMD



> +
> +SZEDATA2 PMD can be created by passing --vdev= option to EAL in the

Again format --vdev as ``--vdev``. Also apply to other similar cases.



> +following format:
> +
> +.. code-block:: console
> +
> +    --vdev
> 'DEVICE_NAME,dev_path=PATH_TO_SZEDATA2_DEVICE,rx_ifaces=RX_MASK,tx_ifaces=
> TX_MASK'

This code line exceeds 80 chars and will exceed the page width in the PDF docs. If possible see if it can be shortened. Maybe use DEVICE instead of DEVICE_NAME and PATH instead of PATH_TO. The next section has an explanation anyway.


> +
> +DEVICE_NAME and options dev_path, rx_ifaces, tx_ifaces are mandatory
> +and must be separated by commas.

Use the ```` quotes again.


> +
> +*   DEVICE_NAME: contains prefix eth_szedata2 followed by numbers or
> letters,
> +    must be unique for each virtual device
> +
> +*   dev_path: Defines path to szedata2 device.
> +    Value is valid path to szedata2 device.
> +
> +        dev_path=/dev/szedataII0

Code blocks should be prefixed by :: to render them correctly. See the guidelines and also view the output from "make doc-guides-html".

Same for the other items below.


> +
> +Example of usage
> +^^^^^^^^^^^^^^^^

The convention is to use ~~~~~ for third level headings (see the guidelines). However, this could probably be a second level heading.


> +
> +Read packets from 0. and 1. receive channel and write them to 0. and 1.
> +transmit channel
> +
> +.. code-block:: console
> +
> +    $RTE_TARGET/app/testpmd -c 0xf -n 2 --vdev
> + 'eth_szedata20,dev_path=/dev/szedataII0,rx_ifaces=0x3,tx_ifaces=0x3'
> + -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2


Again this code line is >80 chars and won't look good in the PDF. I'd suggest the following:

testpmd -c 0xf -n 2 \
 --vdev 'eth_szedata20,dev_path=/dev/szedataII0,rx_ifaces=3,tx_ifaces=3' \
 -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2



> diff --git a/doc/guides/prog_guide/source_org.rst
> b/doc/guides/prog_guide/source_org.rst
> index ae11b3b..2393002 100644
> --- a/doc/guides/prog_guide/source_org.rst
> +++ b/doc/guides/prog_guide/source_org.rst
> @@ -106,6 +106,7 @@ The drivers directory has a *net* subdirectory which
> contains::
>      +-- null               # NULL poll mode driver for testing
>      +-- pcap               # PCAP poll mode driver
>      +-- ring               # Ring poll mode driver
> +    +-- szedata2           # szedata2 poll mode driver
>      +-- virtio             # Virtio poll mode driver
>      +-- vmxnet3            # VMXNET3 poll mode driver
>      +-- xenvirt            # Xen virtio poll mode driver

It isn't necessary to update this section. It is meant to be representative rather than comprehensive (at least to me). However if you leave it in then captilize the name like the others.


Thanks,

John
  

Hi Thomas,

2015-10-27 19:00 GMT+01:00 Thomas Monjalon <thomas.monjalon@6wind.com>:

> 2015-10-27 18:33, Matej Vido:
> > 2015-10-26 16:09 GMT+01:00 Thomas Monjalon <thomas.monjalon@6wind.com>:
> > > SZEDATA2 is not a vdev. Is it possible to probe it as a standard PCI
> > > device?
> > >
> > It would be possible to probe it as a standard PCI device, but as this
> > szedata2 driver uses libsze2 library it needs to pass some parameters to
> > the library and we thought that using vdev would be the easiest solution.
> > Is there a way how to provide parameters to pdev driver?
>
> No, but it could be added by working on unifying pdev and vdev.
>
> > We also work on a new PMD which will eliminate dependencies on kernel
> > modules and libsze2, and using this PMD COMBO card will be probed as a
> > standard PCI device.
>
> I think it's better to wait for your new implementation.
> It would be nice to have it in the release 2.2.
> Do you think it could be submitted in the coming weeks?
>


We will not manage to submit the new driver implementation in the release
2.2. Any chance to get this virtual driver into 2.2?

Matej Vido
  

Hi John,

Thank you for your comments and advice. I will follow them in the new
version.

Regards,
Matej Vido


2015-10-30 13:16 GMT+01:00 Mcnamara, John <john.mcnamara@intel.com>:

> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Matej Vido
> > Sent: Friday, September 18, 2015 9:33 AM
> > To: dev@dpdk.org
> > Subject: [dpdk-dev] [PATCH v2 4/5] doc: add documentation for szedata2
> PMD
> >
> > Signed-off-by: Matej Vido <matejvido@gmail.com>
> > Reviewed-by: Jan Viktorin <viktorin@rehivetech.com>
>
> Hi,
>
> Thanks for the new PMD and the documentation.
>
> The DPDJ documentation guidelines provide some guidance on how to format
> and build the DPDK documentation:
>
>     http://dpdk.org/doc/guides/contributing/documentation.html
>
> In terms of documentation for a PMD the Mellanox MLX4 docs are a good
> example:
>
>     http://dpdk.org/doc/guides/nics/mlx4.html
>
> Some other comments below:
>
>
>
>
> > +SZEDATA2 PMD
> > +============
>
> No need for an acronym in the title. Follow the MLX4 example and use
> something like " SZEDATA2 poll mode driver library".
>
>
>
> > +SZEDATA2 PMD is virtual PMD which uses sze2 layer to communicate with
> > +COMBO cards (COMBO-80G, COMBO-100G) using interface provided by libsze2
> > library.
>
> The introduction can be brief but should include enough information to
> explain the PMD for someone encountering it for the first time.
>
> Some links would help with this. See the MLX4 doc as an example:
>
>
> > +
> > +.. note::
> > +
> > +   This driver has external dependencies. Therefore it is disabled in
> > default
> > +   configuration files. It can be enabled by setting
> > CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y
>
> Format configuration items as verbatim text with  double backquotes:``
> CONFIG_RTE_LIBRTE_PMD_SZEDATA2=y ``
>
>
> > +
> > +Using PMD
> > +---------
>
> Better: Using the Szedata PMD
>
>
>
> > +
> > +SZEDATA2 PMD can be created by passing --vdev= option to EAL in the
>
> Again format --vdev as ``--vdev``. Also apply to other similar cases.
>
>
>
> > +following format:
> > +
> > +.. code-block:: console
> > +
> > +    --vdev
> >
> 'DEVICE_NAME,dev_path=PATH_TO_SZEDATA2_DEVICE,rx_ifaces=RX_MASK,tx_ifaces=
> > TX_MASK'
>
> This code line exceeds 80 chars and will exceed the page width in the PDF
> docs. If possible see if it can be shortened. Maybe use DEVICE instead of
> DEVICE_NAME and PATH instead of PATH_TO. The next section has an
> explanation anyway.
>
>
> > +
> > +DEVICE_NAME and options dev_path, rx_ifaces, tx_ifaces are mandatory
> > +and must be separated by commas.
>
> Use the ```` quotes again.
>
>
> > +
> > +*   DEVICE_NAME: contains prefix eth_szedata2 followed by numbers or
> > letters,
> > +    must be unique for each virtual device
> > +
> > +*   dev_path: Defines path to szedata2 device.
> > +    Value is valid path to szedata2 device.
> > +
> > +        dev_path=/dev/szedataII0
>
> Code blocks should be prefixed by :: to render them correctly. See the
> guidelines and also view the output from "make doc-guides-html".
>
> Same for the other items below.
>
>
> > +
> > +Example of usage
> > +^^^^^^^^^^^^^^^^
>
> The convention is to use ~~~~~ for third level headings (see the
> guidelines). However, this could probably be a second level heading.
>
>
> > +
> > +Read packets from 0. and 1. receive channel and write them to 0. and 1.
> > +transmit channel
> > +
> > +.. code-block:: console
> > +
> > +    $RTE_TARGET/app/testpmd -c 0xf -n 2 --vdev
> > + 'eth_szedata20,dev_path=/dev/szedataII0,rx_ifaces=0x3,tx_ifaces=0x3'
> > + -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2
>
>
> Again this code line is >80 chars and won't look good in the PDF. I'd
> suggest the following:
>
> testpmd -c 0xf -n 2 \
>  --vdev 'eth_szedata20,dev_path=/dev/szedataII0,rx_ifaces=3,tx_ifaces=3' \
>  -- --port-topology=chained --rxq=2 --txq=2 --nb-cores=2
>
>
>
> > diff --git a/doc/guides/prog_guide/source_org.rst
> > b/doc/guides/prog_guide/source_org.rst
> > index ae11b3b..2393002 100644
> > --- a/doc/guides/prog_guide/source_org.rst
> > +++ b/doc/guides/prog_guide/source_org.rst
> > @@ -106,6 +106,7 @@ The drivers directory has a *net* subdirectory which
> > contains::
> >      +-- null               # NULL poll mode driver for testing
> >      +-- pcap               # PCAP poll mode driver
> >      +-- ring               # Ring poll mode driver
> > +    +-- szedata2           # szedata2 poll mode driver
> >      +-- virtio             # Virtio poll mode driver
> >      +-- vmxnet3            # VMXNET3 poll mode driver
> >      +-- xenvirt            # Xen virtio poll mode driver
>
> It isn't necessary to update this section. It is meant to be
> representative rather than comprehensive (at least to me). However if you
> leave it in then captilize the name like the others.
>
>
> Thanks,
>
> John
>