[dpdk-dev,v3,3/4] doc: add mrvl net pmd documentation
Checks
Commit Message
Add documentation for the MRVL NET PMD driver.
Signed-off-by: Jacek Siuda <jck@semihalf.com>
Signed-off-by: Tomasz Duszynski <jck@semihalf.com>
---
doc/guides/nics/features/mrvl.ini | 24 ++++++
doc/guides/nics/index.rst | 1 +
doc/guides/nics/mrvl.rst | 151 ++++++++++++++++++++++++++++++++++++++
3 files changed, 176 insertions(+)
create mode 100644 doc/guides/nics/features/mrvl.ini
create mode 100644 doc/guides/nics/mrvl.rst
Comments
On 10/3/2017 12:51 PM, Tomasz Duszynski wrote:
> Add documentation for the MRVL NET PMD driver.
>
> Signed-off-by: Jacek Siuda <jck@semihalf.com>
> Signed-off-by: Tomasz Duszynski <jck@semihalf.com>
<...>
> +;
> +[Features]
> +Speed capabilities = Y
This doesn't seems correct please check doc/guides/nics/features.rst
> +Link status = Y
> +MTU update = Y
> +Jumbo frame = Y
> +Promiscuous mode = Y
> +Allmulticast mode = Y
> +Unicast MAC filter = Y
> +Multicast MAC filter = Y
> +RSS hash = Y
> +VLAN filter = Y
> +CRC offload = Y
> +L3 checksum offload = Y
> +L4 checksum offload = Y
> +Packet type parsing = Y
> +Basic stats = Y
> +Stats per queue = Y
> +ARMv8 = Y
Is other architecture not supported or not tested?
> +Usage doc = Y
<...>
> +Prerequisites
> +-------------
> +
> +- MUSDK (Marvell User-Space SDK) sources available
> + `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`_.
Is this 17.08 by change related to DPDK version, I mean is there any
relation between DPDK version and musdk library version?
> +
> + MUSDK is a light-weight library that provides direct access to Marvell's
> + PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
> + requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
> + approval has been granted, library can be found by typing ``musdk`` in
> + search box.
What is the condition of having an approval?
> +
> +- DPDK environment
> +
> + Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
> + DPDK environment.
> +
> +
<...>
> +Building DPDK
> +-------------
> +
> +Driver needs precompiled MUSDK library during compilation. Detailed build
> +process is described in library's documentation under ``doc`` directory.
> +
> +Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
> +the path to the MUSDK installation directory needs to be exported.
> +
> +Usage Example
> +-------------
> +
> +MRVL PMD requires extra kernel modules to function properly:
> +
> +.. code-block:: console
> +
> + insmod musdk_uio.ko
> + insmod mv_pp_uio.ko
> + insmod mvpp2x_sysfs.ko
Why these kernel modules are required and how one can obtain them?
These are out of tree kernel modules right?
<...>
On Wed, Oct 04, 2017 at 01:29:01AM +0100, Ferruh Yigit wrote:
+cc Shlomi.
> On 10/3/2017 12:51 PM, Tomasz Duszynski wrote:
> > Add documentation for the MRVL NET PMD driver.
> >
> > Signed-off-by: Jacek Siuda <jck@semihalf.com>
> > Signed-off-by: Tomasz Duszynski <jck@semihalf.com>
>
> <...>
>
> > +;
> > +[Features]
> > +Speed capabilities = Y
>
> This doesn't seems correct please check doc/guides/nics/features.rst
Right, speed capabilities are not returned via rte_eth_dev_info. Thanks
for pointing this out. Will fix that in v4.
>
> > +Link status = Y
> > +MTU update = Y
> > +Jumbo frame = Y
> > +Promiscuous mode = Y
> > +Allmulticast mode = Y
> > +Unicast MAC filter = Y
> > +Multicast MAC filter = Y
> > +RSS hash = Y
> > +VLAN filter = Y
> > +CRC offload = Y
> > +L3 checksum offload = Y
> > +L4 checksum offload = Y
> > +Packet type parsing = Y
> > +Basic stats = Y
> > +Stats per queue = Y
> > +ARMv8 = Y
>
> Is other architecture not supported or not tested?
Currently that NIC comes integrated into Armada 7k/8k SoCs and they are based
on ARMv8.
>
> > +Usage doc = Y
>
> <...>
>
> > +Prerequisites
> > +-------------
> > +
> > +- MUSDK (Marvell User-Space SDK) sources available
> > + `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`_.
>
> Is this 17.08 by change related to DPDK version, I mean is there any
> relation between DPDK version and musdk library version?
No relation except similar versioning convention that is used. Musdk
library version needed by DPDK driver is mentioned explicitly in
documentation.
>
> > +
> > + MUSDK is a light-weight library that provides direct access to Marvell's
> > + PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
> > + requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
> > + approval has been granted, library can be found by typing ``musdk`` in
> > + search box.
>
> What is the condition of having an approval?
I think Marvell team would be more helpful here.
>
> > +
> > +- DPDK environment
> > +
> > + Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
> > + DPDK environment.
> > +
> > +
>
> <...>
>
> > +Building DPDK
> > +-------------
> > +
> > +Driver needs precompiled MUSDK library during compilation. Detailed build
> > +process is described in library's documentation under ``doc`` directory.
> > +
> > +Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
> > +the path to the MUSDK installation directory needs to be exported.
> > +
> > +Usage Example
> > +-------------
> > +
> > +MRVL PMD requires extra kernel modules to function properly:
> > +
> > +.. code-block:: console
> > +
> > + insmod musdk_uio.ko
> > + insmod mv_pp_uio.ko
> > + insmod mvpp2x_sysfs.ko
>
> Why these kernel modules are required and how one can obtain them?
Kernel modules are used to map device memory regions to userspace.
musdk_uio and mv_pp_uio both come with MUSDK library. As for mvpp2x_sysfs
I think Marvell team could be more helpful here.
> These are out of tree kernel modules right?
Right. You have to either build them yourself or get precompiled from
Marvell-extranet.
>
> <...>
>
--
- Tomasz Duszyński
new file mode 100644
@@ -0,0 +1,24 @@
+;
+; Supported features of the 'mrvl' network poll mode driver.
+;
+; Refer to default.ini for the full list of available PMD features.
+;
+[Features]
+Speed capabilities = Y
+Link status = Y
+MTU update = Y
+Jumbo frame = Y
+Promiscuous mode = Y
+Allmulticast mode = Y
+Unicast MAC filter = Y
+Multicast MAC filter = Y
+RSS hash = Y
+VLAN filter = Y
+CRC offload = Y
+L3 checksum offload = Y
+L4 checksum offload = Y
+Packet type parsing = Y
+Basic stats = Y
+Stats per queue = Y
+ARMv8 = Y
+Usage doc = Y
@@ -55,6 +55,7 @@ Network Interface Controller Drivers
liquidio
mlx4
mlx5
+ mrvl
nfp
qede
sfc_efx
new file mode 100644
@@ -0,0 +1,151 @@
+.. BSD LICENSE
+ Copyright(c) 2017 Semihalf. All rights reserved.
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+ distribution.
+ * Neither the name of Semihalf nor the names of its
+ contributors may be used to endorse or promote products derived
+ from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+MRVL Poll Mode Driver
+======================
+
+The MRVL PMD (librte_pmd_mrvl) provides poll mode driver support
+for the Marvell PPv2 (Packet Processor v2) 1/10 Gbps adapter.
+
+.. Note::
+
+ Due to external dependencies, this driver is disabled by default. It must
+ be enabled manually by setting relevant configuration option manually.
+ Please refer to `Config File Options`_ section for further details.
+
+
+Features
+--------
+
+Features of the MRVL PMD are:
+
+- Speed capabilities
+- Link status
+- Queue start/stop
+- MTU update
+- Jumbo frame
+- Promiscuous mode
+- Allmulticast mode
+- Unicast MAC filter
+- Multicast MAC filter
+- RSS hash
+- VLAN filter
+- CRC offload
+- L3 checksum offload
+- L4 checksum offload
+- Packet type parsing
+- Basic stats
+- Stats per queue
+
+
+Limitations
+-----------
+
+- Number of lcores is limited to 9 by MUSDK internal design. If more lcores
+ need to be allocated, locking will have to be considered. Number of available
+ lcores can be changed via ``MRVL_MUSDK_HIFS_RESERVED`` define in
+ ``mrvl_ethdev.c`` source file.
+
+- Flushing vlans added for filtering is not possible due to MUSDK missing
+ functionality. Current workaround is to reset board so that PPv2 has a
+ chance to start in a sane state.
+
+
+Prerequisites
+-------------
+
+- MUSDK (Marvell User-Space SDK) sources available
+ `here <https://github.com/MarvellEmbeddedProcessors/musdk-marvell/tree/musdk-armada-17.08>`_.
+
+ MUSDK is a light-weight library that provides direct access to Marvell's
+ PPv2 (Packet Processor v2). Alternatively prebuilt MUSDK library can be
+ requested from `Marvell Extranet <https://extranet.marvell.com>`_. Once
+ approval has been granted, library can be found by typing ``musdk`` in
+ search box.
+
+- DPDK environment
+
+ Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup
+ DPDK environment.
+
+
+Config File Options
+-------------------
+
+The following options can be modified in the ``config`` file.
+
+- ``CONFIG_RTE_LIBRTE_MRVL_PMD`` (default ``n``)
+
+ Toggle compilation of the librte_pmd_mrvl driver.
+
+- ``CONFIG_RTE_LIBRTE_MRVL_DEBUG`` (default ``n``)
+
+ Toggle display of debugging messages.
+
+- ``CONFIG_RTE_MRVL_MUSDK_DMA_MEMSIZE`` (default ``41943040``)
+
+ Size in bytes of the contiguous memory region that MUSDK will allocate
+ for run-time DMA-able data buffers.
+
+
+Building DPDK
+-------------
+
+Driver needs precompiled MUSDK library during compilation. Detailed build
+process is described in library's documentation under ``doc`` directory.
+
+Before the DPDK build process the environmental variable ``LIBMUSDK_PATH`` with
+the path to the MUSDK installation directory needs to be exported.
+
+Usage Example
+-------------
+
+MRVL PMD requires extra kernel modules to function properly:
+
+.. code-block:: console
+
+ insmod musdk_uio.ko
+ insmod mv_pp_uio.ko
+ insmod mvpp2x_sysfs.ko
+
+Additionally interfaces used by DPDK application need to be put up:
+
+.. code-block:: console
+
+ ip link set eth0 up
+ ip link set eth1 up
+
+In order to run testpmd example application following command can be used:
+
+.. code-block:: console
+
+ ./testpmd --vdev=eth_mrvl,iface=eth0,iface=eth2 -c 7 -- \
+ --burst=128 --txd=2048 --rxd=1024 --rxq=2 --txq=2 --nb-cores=2 \
+ -i -a --disable-hw-vlan-strip --rss-udp