1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2018 Intel Corporation.
4 Soft NIC Poll Mode Driver
5 =========================
7 The Soft NIC allows building custom NIC pipelines in software. The Soft NIC pipeline
8 is DIY and reconfigurable through ``firmware`` (DPDK Packet Framework script).
10 The Soft NIC leverages the DPDK Packet Framework libraries (librte_port,
11 librte_table and librte_pipeline) to make it modular, flexible and extensible
12 with new functionality. Please refer to DPDK Programmer's Guide, Chapter
13 ``Packet Framework`` and DPDK Sample Application User Guide,
14 Chapter ``IP Pipeline Application`` for more details.
16 The Soft NIC is configured through the standard DPDK ethdev API (ethdev, flow,
17 QoS, security). The internal framework is not externally visible.
20 - Can be used to augment missing features to HW NICs.
21 - Allows consumption of advanced DPDK features without application redesign.
22 - Allows out-of-the-box performance boost of DPDK consumers applications simply by
23 instantiating this type of Ethernet device.
27 * ``Device creation``: Each Soft NIC instance is a virtual device.
29 * ``Device start``: The Soft NIC firmware script is executed every time the device
30 is started. The firmware script typically creates several internal objects,
31 such as: memory pools, SW queues, traffic manager, action profiles, pipelines,
34 * ``Device stop``: All the internal objects that were previously created by the
35 firmware script during device start are now destroyed.
37 * ``Device run``: Each Soft NIC device needs one or several CPU cores to run.
38 The firmware script maps each internal pipeline to a CPU core. Multiple
39 pipelines can be mapped to the same CPU core. In order for a given pipeline
40 assigned to CPU core X to run, the application needs to periodically call on
41 CPU core X the `rte_pmd_softnic_run()` function for the current Soft NIC
44 * ``Application run``: The application reads packets from the Soft NIC device RX
45 queues and writes packets to the Soft NIC device TX queues.
47 Supported Operating Systems
48 ---------------------------
50 Any Linux distribution fulfilling the conditions described in ``System Requirements``
51 section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK
57 The default PMD configuration available in the common_linuxapp configuration file:
59 CONFIG_RTE_LIBRTE_PMD_SOFTNIC=y
61 Once the DPDK is built, all the DPDK applications include support for the
64 Soft NIC PMD arguments
65 ----------------------
67 The user can specify below arguments in EAL ``--vdev`` options to create the
68 Soft NIC device instance:
70 --vdev "net_softnic0,firmware=firmware.cli,conn_port=8086"
72 #. ``firmware``: path to the firmware script used for Soft NIC configuration.
73 The example "firmware" script is provided at `drivers/net/softnic/`.
74 (Optional: No, Default = NA)
76 #. ``conn_port``: tcp connection port (non-zero value) used by remote client
77 (for examples- telnet, netcat, etc.) to connect and configure Soft NIC device in run-time.
78 (Optional: yes, Default value: 0, no connection with external client)
80 #. ``cpu_id``: numa node id. (Optional: yes, Default value: 0)
82 #. ``tm_n_queues``: number of traffic manager's scheduler queues. The traffic manager
83 is based on DPDK *librte_sched* library. (Optional: yes, Default value: 65,536 queues)
85 #. ``tm_qsize0``: size of scheduler queue 0 per traffic class of the pipes/subscribers.
86 (Optional: yes, Default: 64)
88 #. ``tm_qsize1``: size of scheduler queue 1 per traffic class of the pipes/subscribers.
89 (Optional: yes, Default: 64)
91 #. ``tm_qsize2``: size of scheduler queue 2 per traffic class of the pipes/subscribers.
92 (Optional: yes, Default: 64)
94 #. ``tm_qsize3``: size of scheduler queue 3 per traffic class of the pipes/subscribers.
95 (Optional: yes, Default: 64)
101 * Run testpmd application in Soft NIC forwarding mode with loopback feature
102 enabled on Soft NIC port:
104 .. code-block:: console
106 ./testpmd -c 0x3 --vdev 'net_softnic0,firmware=<script path>/firmware.cli,cpu_id=0,conn_port=8086' -- -i
107 --forward-mode=softnic --portmask=0x2
109 .. code-block:: console
112 Interactive-mode selected
113 Set softnic packet forwarding mode
115 Configuring Port 0 (socket 0)
116 Port 0: 90:E2:BA:37:9D:DC
117 Configuring Port 1 (socket 0)
119 ; SPDX-License-Identifier: BSD-3-Clause
120 ; Copyright(c) 2018 Intel Corporation
122 link LINK dev 0000:02:00.0
124 pipeline RX period 10 offset_port_id 0
125 pipeline RX port in bsz 32 link LINK rxq 0
126 pipeline RX port out bsz 32 swq RXQ0
127 pipeline RX table match stub
128 pipeline RX port in 0 table 0
130 pipeline TX period 10 offset_port_id 0
131 pipeline TX port in bsz 32 swq TXQ0
132 pipeline TX port out bsz 32 link LINK txq 0
133 pipeline TX table match stub
134 pipeline TX port in 0 table 0
136 thread 1 pipeline RX enable
137 thread 1 pipeline TX enable
138 Port 1: 00:00:00:00:00:00
139 Checking link statuses...
145 .. code-block:: console
148 softnic packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP over anonymous pages disabled
149 Logical Core 1 (socket 0) forwards packets on 1 streams:
150 RX P=2/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:02
152 softnic packet forwarding packets/burst=32
153 nb forwarding cores=1 - nb forwarding ports=1
154 port 0: RX queue number: 1 Tx queue number: 1
155 Rx offloads=0x1000 Tx offloads=0x0
157 RX desc=512 - RX free threshold=32
158 RX threshold registers: pthresh=8 hthresh=8 wthresh=0
161 TX desc=512 - TX free threshold=32
162 TX threshold registers: pthresh=32 hthresh=0 wthresh=0
163 TX offloads=0x0 - TX RS bit threshold=32
164 port 1: RX queue number: 1 Tx queue number: 1
165 Rx offloads=0x0 Tx offloads=0x0
167 RX desc=0 - RX free threshold=0
168 RX threshold registers: pthresh=0 hthresh=0 wthresh=0
171 TX desc=0 - TX free threshold=0
172 TX threshold registers: pthresh=0 hthresh=0 wthresh=0
173 TX offloads=0x0 - TX RS bit threshold=0
175 * Start remote client (e.g. telnet) to communicate with the softnic device:
177 .. code-block:: console
179 $ telnet 127.0.0.1 8086
181 Connected to 127.0.0.1.
182 Escape character is '^]'.
188 * Add/update Soft NIC pipeline table match-action entries from telnet client:
190 .. code-block:: console
192 softnic> pipeline RX table 0 rule add match default action fwd port 0
193 softnic> pipeline TX table 0 rule add match default action fwd port 0
198 The Soft NIC firmware, for example- `softnic/firmware.cli`, consists of following CLI commands
199 for creating and managing software based NIC pipelines. For more details, please refer to CLI
200 command description provided in `softnic/rte_eth_softnic_cli.c`.
202 * Physical port for packets send/receive:
204 .. code-block:: console
206 link LINK dev 0000:02:00.0
210 .. code-block:: console
212 pipeline RX period 10 offset_port_id 0 (Soft NIC rx-path pipeline)
213 pipeline TX period 10 offset_port_id 0 (Soft NIC tx-path pipeline)
215 * Pipeline input/output port create
217 .. code-block:: console
219 pipeline RX port in bsz 32 link LINK rxq 0 (Soft NIC rx pipeline input port)
220 pipeline RX port out bsz 32 swq RXQ0 (Soft NIC rx pipeline output port)
221 pipeline TX port in bsz 32 swq TXQ0 (Soft NIC tx pipeline input port)
222 pipeline TX port out bsz 32 link LINK txq 0 (Soft NIC tx pipeline output port)
224 * Pipeline table create
226 .. code-block:: console
228 pipeline RX table match stub (Soft NIC rx pipeline match-action table)
229 pipeline TX table match stub (Soft NIC tx pipeline match-action table)
231 * Pipeline input port connection with table
233 .. code-block:: console
235 pipeline RX port in 0 table 0 (Soft NIC rx pipeline input port 0 connection with table 0)
236 pipeline TX port in 0 table 0 (Soft NIC tx pipeline input port 0 connection with table 0)
238 * Pipeline table match-action rules add
240 .. code-block:: console
242 pipeline RX table 0 rule add match default action fwd port 0 (Soft NIC rx pipeline table 0 rule)
243 pipeline TX table 0 rule add match default action fwd port 0 (Soft NIC tx pipeline table 0 rule)
245 * Enable pipeline on CPU thread
247 .. code-block:: console
249 thread 1 pipeline RX enable (Soft NIC rx pipeline enable on cpu thread id 1)
250 thread 1 pipeline TX enable (Soft NIC tx pipeline enable on cpu thread id 1)