2 Copyright (C) Cavium, Inc. 2017.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Cavium, Inc nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 OCTEONTX Poll Mode driver
32 =========================
34 The OCTEONTX ETHDEV PMD (**librte_pmd_octeontx**) provides poll mode ethdev
35 driver support for the inbuilt network device found in the **Cavium OCTEONTX**
36 SoC family as well as their virtual functions (VF) in SR-IOV context.
38 More information can be found at `Cavium, Inc Official Website
39 <http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
44 Features of the OCTEONTX Ethdev PMD are:
46 - Packet type information
48 - Port hardware statistics
50 - Link state information
52 - Multiple queues for TX
54 - HW offloaded `ethdev Rx queue` to `eventdev event queue` packet injection
56 Supported OCTEONTX SoCs
57 -----------------------
64 The features supported by the device and not yet supported by this PMD include:
66 - Receive Side Scaling (RSS)
67 - Scattered and gather for TX and RX
68 - Ingress classification support
69 - Egress hierarchical scheduling, traffic shaping, and marking
74 There are three main pre-perquisites for executing OCTEONTX PMD on a OCTEONTX
77 1. **OCTEONTX Linux kernel PF driver for Network acceleration HW blocks**
79 The OCTEONTX Linux kernel drivers (including the required PF driver for the
80 all network acceleration blocks) are available on GitHub at
81 `octeontx-kmod <https://github.com/caviumnetworks/octeontx-kmod>`_
82 along with build, install and dpdk usage instructions.
84 2. **ARM64 Tool Chain**
86 For example, the *aarch64* Linaro Toolchain, which can be obtained from
87 `here <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
89 3. **Rootfile system**
91 Any *aarch64* supporting filesystem can be used. For example,
92 Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
93 from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
95 As an alternative method, OCTEONTX PMD can also be executed using images provided
96 as part of SDK from Cavium. The SDK includes all the above prerequisites necessary
97 to bring up a OCTEONTX board.
99 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.
101 Follow the DPDK :ref:`Getting Started Guide for Linux <linux_gsg>` to setup the basic DPDK environment.
103 Pre-Installation Configuration
104 ------------------------------
109 The following options can be modified in the ``config`` file.
110 Please note that enabling debugging options may affect system performance.
112 - ``CONFIG_RTE_LIBRTE_OCTEONTX_PMD`` (default ``y``)
114 Toggle compilation of the ``librte_pmd_octeontx`` driver.
116 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_DRIVER`` (default ``n``)
118 Toggle display of generic debugging messages
120 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_INIT`` (default ``n``)
122 Toggle display of initialization related messages.
124 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_RX`` (default ``n``)
126 Toggle display of receive path message
128 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_TX`` (default ``n``)
130 Toggle display of transmit path message
132 - ``CONFIG_RTE_LIBRTE_OCTEONTX_DEBUG_MBOX`` (default ``n``)
134 Toggle display of mbox related message
137 Driver compilation and testing
138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
143 To compile the OCTEONTX PMD for Linux arm64 gcc target, run the
144 following ``make`` command:
146 .. code-block:: console
148 cd <DPDK-source-directory>
149 make config T=arm64-thunderx-linuxapp-gcc install
153 Follow instructions available in the document
154 :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
159 .. code-block:: console
161 ./arm64-thunderx-linuxapp-gcc/app/testpmd -c 700 \
162 --base-virtaddr=0x100000000000 \
163 --mbuf-pool-ops-name="octeontx_fpavf" \
164 --vdev='event_octeontx' \
165 --vdev='eth_octeontx,nr_port=2' \
166 -- --rxq=1 --txq=1 --nb-core=2 --total-num-mbufs=16384 \
167 --disable-hw-vlan-filter -i
169 EAL: Detected 24 lcore(s)
170 EAL: Probing VFIO support...
171 EAL: VFIO support initialized
173 EAL: PCI device 0000:07:00.1 on NUMA socket 0
174 EAL: probe driver: 177d:a04b octeontx_ssovf
176 EAL: PCI device 0001:02:00.7 on NUMA socket 0
177 EAL: probe driver: 177d:a0dd octeontx_pkivf
179 EAL: PCI device 0001:03:01.0 on NUMA socket 0
180 EAL: probe driver: 177d:a049 octeontx_pkovf
182 PMD: octeontx_probe(): created ethdev eth_octeontx for port 0
183 PMD: octeontx_probe(): created ethdev eth_octeontx for port 1
185 Configuring Port 0 (socket 0)
186 Port 0: 00:0F:B7:11:94:46
187 Configuring Port 1 (socket 0)
188 Port 1: 00:0F:B7:11:94:47
190 Checking link statuses...
191 Port 0 Link Up - speed 40000 Mbps - full-duplex
192 Port 1 Link Up - speed 40000 Mbps - full-duplex
200 The octeontx ethdev pmd is exposed as a vdev device which consists of a set
201 of PKI and PKO PCIe VF devices. On EAL initialization,
202 PKI/PKO PCIe VF devices will be probed and then the vdev device can be created
203 from the application code, or from the EAL command line based on
204 the number of probed/bound PKI/PKO PCIe VF device to DPDK by
206 * Invoking ``rte_vdev_init("eth_octeontx")`` from the application
208 * Using ``--vdev="eth_octeontx"`` in the EAL options, which will call
209 rte_vdev_init() internally
213 Each ethdev port is mapped to a physical port(LMAC), Application can specify
214 the number of interesting ports with ``nr_ports`` argument.
218 ``eth_octeontx`` pmd is depend on ``event_octeontx`` eventdev device and
219 ``octeontx_fpavf`` external mempool handler.
223 .. code-block:: console
225 ./your_dpdk_application --mbuf-pool-ops="octeontx_fpavf" \
226 --vdev='event_octeontx' \
227 --vdev="eth_octeontx,nr_port=2"
232 ``octeontx_fpavf`` external mempool handler dependency
233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234 The OCTEONTX SoC family NIC has inbuilt HW assisted external mempool manager.
235 This driver will only work with ``octeontx_fpavf`` external mempool handler
236 as it is the most performance effective way for packet allocation and Tx buffer
237 recycling on OCTEONTX SoC platform.
242 The OCTEONTX SoC family NICs strip the CRC for every packets coming into the
243 host interface. So, CRC will be stripped even when the
244 ``rxmode.hw_strip_crc`` member is set to 0 in ``struct rte_eth_conf``.
246 Maximum packet length
247 ~~~~~~~~~~~~~~~~~~~~~
249 The OCTEONTX SoC family NICs support a maximum of a 32K jumbo frame. The value
250 is fixed and cannot be changed. So, even when the ``rxmode.max_rx_pkt_len``
251 member of ``struct rte_eth_conf`` is set to a value lower than 32k, frames
252 up to 32k bytes can still reach the host interface.