-.. BSD LICENSE
- Copyright (C) Cavium networks Ltd. 2016.
- 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 Cavium networks 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.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2016 Cavium, Inc
ThunderX NICVF Poll Mode Driver
===============================
support for the inbuilt NIC found in the **Cavium ThunderX** SoC family
as well as their virtual functions (VF) in SR-IOV context.
-More information can be found at `Cavium Networks Official Website
+More information can be found at `Cavium, Inc Official Website
<http://www.cavium.com/ThunderX_ARM_Processors.html>`_.
Features
- SR-IOV VF
- NUMA support
- Multi queue set support (up to 96 queues (12 queue sets)) per port
+- Skip data bytes
Supported ThunderX SoCs
-----------------------
The following options can be modified in the ``config`` file.
Please note that enabling debugging options may affect system performance.
-- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_PMD`` (default ``n``)
+- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_PMD`` (default ``y``)
- By default it is enabled only for defconfig_arm64-thunderx-* config.
Toggle compilation of the ``librte_pmd_thunderx_nicvf`` driver.
-- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_INIT`` (default ``n``)
-
- Toggle display of initialization related messages.
-
- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_RX`` (default ``n``)
- Toggle display of receive fast path run-time message
+ Toggle asserts of receive fast path.
- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_TX`` (default ``n``)
- Toggle display of transmit fast path run-time message
-
-- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_DRIVER`` (default ``n``)
-
- Toggle display of generic debugging messages
-
-- ``CONFIG_RTE_LIBRTE_THUNDERX_NICVF_DEBUG_MBOX`` (default ``n``)
+ Toggle asserts of transmit fast path.
- Toggle display of PF mailbox related run-time check messages
-
-Driver Compilation
-~~~~~~~~~~~~~~~~~~
-
-To compile the ThunderX NICVF PMD for Linux arm64 gcc target, run the
-following “make” command:
+Driver compilation and testing
+------------------------------
-.. code-block:: console
+Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+for details.
- cd <DPDK-source-directory>
- make config T=arm64-thunderx-linuxapp-gcc install
+To compile the ThunderX NICVF PMD for Linux arm64 gcc,
+use arm64-thunderx-linux-gcc as target.
Linux
-----
-.. _thunderx_testpmd_example:
-
-Running testpmd
-~~~~~~~~~~~~~~~
-
-This section demonstrates how to launch ``testpmd`` with ThunderX NIC VF device
-managed by ``librte_pmd_thunderx_nicvf`` in the Linux operating system.
-
-#. Load ``vfio-pci`` driver:
-
- .. code-block:: console
-
- modprobe vfio-pci
-
- .. _thunderx_vfio_noiommu:
-
-#. Enable **VFIO-NOIOMMU** mode (optional):
-
- .. code-block:: console
-
- echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
-
- .. note::
-
- **VFIO-NOIOMMU** is required only when running in VM context and should not be enabled otherwise.
- See also :ref:`SR-IOV: Prerequisites and sample Application Notes <thunderx_sriov_example>`.
-
-#. Bind the ThunderX NIC VF device to ``vfio-pci`` loaded in the previous step:
-
- Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
-
- .. code-block:: console
-
- ./usertools/dpdk-devbind.py --bind vfio-pci 0002:01:00.2
-
-#. Start ``testpmd`` with basic parameters:
-
- .. code-block:: console
-
- ./arm64-thunderx-linuxapp-gcc/app/testpmd -l 0-3 -n 4 -w 0002:01:00.2 \
- -- -i --disable-hw-vlan-filter --crc-strip --no-flush-rx \
- --port-topology=loop
-
- Example output:
-
- .. code-block:: console
-
- ...
-
- PMD: rte_nicvf_pmd_init(): librte_pmd_thunderx nicvf version 1.0
-
- ...
- EAL: probe driver: 177d:11 rte_nicvf_pmd
- EAL: using IOMMU type 1 (Type 1)
- EAL: PCI memory mapped at 0x3ffade50000
- EAL: Trying to map BAR 4 that contains the MSI-X table.
- Trying offsets: 0x40000000000:0x0000, 0x10000:0x1f0000
- EAL: PCI memory mapped at 0x3ffadc60000
- PMD: nicvf_eth_dev_init(): nicvf: device (177d:11) 2:1:0:2
- PMD: nicvf_eth_dev_init(): node=0 vf=1 mode=tns-bypass sqs=false
- loopback_supported=true
- PMD: nicvf_eth_dev_init(): Port 0 (177d:11) mac=a6:c6:d9:17:78:01
- Interactive-mode selected
- Configuring Port 0 (socket 0)
- ...
-
- PMD: nicvf_dev_configure(): Configured ethdev port0 hwcap=0x0
- Port 0: A6:C6:D9:17:78:01
- Checking link statuses...
- Port 0 Link Up - speed 10000 Mbps - full-duplex
- Done
- testpmd>
-
-.. _thunderx_sriov_example:
-
SR-IOV: Prerequisites and sample Application Notes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unless ``thunder-nicvf`` driver is in use make sure your kernel config includes ``CONFIG_THUNDER_NIC_VF`` setting.
-#. Verify PF/VF bind using ``dpdk-devbind.py``:
-
- .. code-block:: console
-
- ./usertools/dpdk-devbind.py --status
-
- Example output:
-
- .. code-block:: console
-
- ...
- 0002:01:00.0 'Device a01e' if= drv=thunder-nic unused=vfio-pci
- 0002:01:00.1 'Device 0011' if=eth0 drv=thunder-nicvf unused=vfio-pci
- 0002:01:00.2 'Device 0011' if=eth1 drv=thunder-nicvf unused=vfio-pci
- ...
-
-#. Load ``vfio-pci`` driver:
-
- .. code-block:: console
-
- modprobe vfio-pci
-
-#. Bind VF devices to ``vfio-pci`` using ``dpdk-devbind.py``:
-
- .. code-block:: console
-
- ./usertools/dpdk-devbind.py --bind vfio-pci 0002:01:00.1
- ./usertools/dpdk-devbind.py --bind vfio-pci 0002:01:00.2
-
-#. Verify VF bind using ``dpdk-devbind.py``:
-
- .. code-block:: console
-
- ./usertools/dpdk-devbind.py --status
-
- Example output:
-
- .. code-block:: console
-
- ...
- 0002:01:00.1 'Device 0011' drv=vfio-pci unused=
- 0002:01:00.2 'Device 0011' drv=vfio-pci unused=
- ...
- 0002:01:00.0 'Device a01e' if= drv=thunder-nic unused=vfio-pci
- ...
-
#. Pass VF device to VM context (PCIe Passthrough):
The VF devices may be passed through to the guest VM using qemu or
virt-manager or virsh etc.
- ``librte_pmd_thunderx_nicvf`` or ``thunder-nicvf`` should be used to bind
- the VF devices in the guest VM in :ref:`VFIO-NOIOMMU <thunderx_vfio_noiommu>` mode.
Example qemu guest launch command:
-serial stdio \
-mem-path /dev/huge
-#. Refer to section :ref:`Running testpmd <thunderx_testpmd_example>` for instruction
- how to launch ``testpmd`` application.
+#. Enable **VFIO-NOIOMMU** mode (optional):
+
+ .. code-block:: console
+
+ echo 1 > /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
+
+ .. note::
+
+ **VFIO-NOIOMMU** is required only when running in VM context and should not be enabled otherwise.
+
+#. Running testpmd:
+
+ Follow instructions available in the document
+ :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
+ to run testpmd.
+
+ Example output:
+
+ .. code-block:: console
+
+ ./arm64-thunderx-linux-gcc/app/testpmd -l 0-3 -n 4 -w 0002:01:00.2 \
+ -- -i --no-flush-rx \
+ --port-topology=loop
+
+ ...
+
+ PMD: rte_nicvf_pmd_init(): librte_pmd_thunderx nicvf version 1.0
+
+ ...
+ EAL: probe driver: 177d:11 rte_nicvf_pmd
+ EAL: using IOMMU type 1 (Type 1)
+ EAL: PCI memory mapped at 0x3ffade50000
+ EAL: Trying to map BAR 4 that contains the MSI-X table.
+ Trying offsets: 0x40000000000:0x0000, 0x10000:0x1f0000
+ EAL: PCI memory mapped at 0x3ffadc60000
+ PMD: nicvf_eth_dev_init(): nicvf: device (177d:11) 2:1:0:2
+ PMD: nicvf_eth_dev_init(): node=0 vf=1 mode=tns-bypass sqs=false
+ loopback_supported=true
+ PMD: nicvf_eth_dev_init(): Port 0 (177d:11) mac=a6:c6:d9:17:78:01
+ Interactive-mode selected
+ Configuring Port 0 (socket 0)
+ ...
+
+ PMD: nicvf_dev_configure(): Configured ethdev port0 hwcap=0x0
+ Port 0: A6:C6:D9:17:78:01
+ Checking link statuses...
+ Port 0 Link Up - speed 10000 Mbps - full-duplex
+ Done
+ testpmd>
Multiple Queue Set per DPDK port configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The nicvf thunderx driver will make use of attached secondary VFs automatically during the interface configuration stage.
+
+Module params
+--------------
+
+skip_data_bytes
+~~~~~~~~~~~~~~~
+This feature is used to create a hole between HEADROOM and actual data. Size of hole is specified
+in bytes as module param("skip_data_bytes") to pmd.
+This scheme is useful when application would like to insert vlan header without disturbing HEADROOM.
+
+Example:
+ .. code-block:: console
+
+ -w 0002:01:00.2,skip_data_bytes=8
+
Limitations
-----------
~~~~~~~~~~~~
The ThunderX SoC family NICs strip the CRC for every packets coming into the
-host interface. So, CRC will be stripped even when the
-``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
+host interface irrespective of the offload configuration.
Maximum packet length
~~~~~~~~~~~~~~~~~~~~~
The ThunderX SoC family NICs support up to 12 segments per packet when working
in scatter/gather mode. So, setting MTU will result with ``EINVAL`` when the
frame size does not fit in the maximum number of segments.
+
+skip_data_bytes
+~~~~~~~~~~~~~~~
+
+Maximum limit of skip_data_bytes is 128 bytes and number of bytes should be multiple of 8.