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_linux 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 (traffic class 0) of the pipes/subscribers.
86 (Optional: yes, Default: 64)
88 #. ``tm_qsize1``: size of scheduler queue 1 (traffic class 1) of the pipes/subscribers.
89 (Optional: yes, Default: 64)
91 #. ``tm_qsize2``: size of scheduler queue 2 (traffic class 2) of the pipes/subscribers.
92 (Optional: yes, Default: 64)
94 #. ``tm_qsize3``: size of scheduler queue 3 (traffic class 3) of the pipes/subscribers.
95 (Optional: yes, Default: 64)
97 #. ``tm_qsize4``: size of scheduler queue 4 (traffic class 4) of the pipes/subscribers.
98 (Optional: yes, Default: 64)
100 #. ``tm_qsize5``: size of scheduler queue 5 (traffic class 5) of the pipes/subscribers.
101 (Optional: yes, Default: 64)
103 #. ``tm_qsize6``: size of scheduler queue 6 (traffic class 6) of the pipes/subscribers.
104 (Optional: yes, Default: 64)
106 #. ``tm_qsize7``: size of scheduler queue 7 (traffic class 7) of the pipes/subscribers.
107 (Optional: yes, Default: 64)
109 #. ``tm_qsize8``: size of scheduler queue 8 (traffic class 8) of the pipes/subscribers.
110 (Optional: yes, Default: 64)
112 #. ``tm_qsize9``: size of scheduler queue 9 (traffic class 9) of the pipes/subscribers.
113 (Optional: yes, Default: 64)
115 #. ``tm_qsize10``: size of scheduler queue 10 (traffic class 10) of the pipes/subscribers.
116 (Optional: yes, Default: 64)
118 #. ``tm_qsize11``: size of scheduler queue 11 (traffic class 11) of the pipes/subscribers.
119 (Optional: yes, Default: 64)
121 #. ``tm_qsize12``: size of scheduler queue 12 (traffic class 12) of the pipes/subscribers.
122 (Optional: yes, Default: 64)
128 * Run testpmd application with Soft NIC device with loopback feature
129 enabled on Soft NIC port:
131 .. code-block:: console
133 ./testpmd -c 0x7 -s 0x4 --vdev 'net_softnic0,firmware=<script path>/firmware.cli,cpu_id=0,conn_port=8086' -- -i
136 .. code-block:: console
139 Interactive-mode selected
140 Set softnic packet forwarding mode
142 Configuring Port 0 (socket 0)
143 Port 0: 90:E2:BA:37:9D:DC
144 Configuring Port 1 (socket 0)
146 ; SPDX-License-Identifier: BSD-3-Clause
147 ; Copyright(c) 2018 Intel Corporation
149 link LINK dev 0000:02:00.0
151 pipeline RX period 10 offset_port_id 0
152 pipeline RX port in bsz 32 link LINK rxq 0
153 pipeline RX port out bsz 32 swq RXQ0
154 pipeline RX table match stub
155 pipeline RX port in 0 table 0
157 pipeline TX period 10 offset_port_id 0
158 pipeline TX port in bsz 32 swq TXQ0
159 pipeline TX port out bsz 32 link LINK txq 0
160 pipeline TX table match stub
161 pipeline TX port in 0 table 0
163 thread 2 pipeline RX enable
164 thread 2 pipeline TX enable
165 Port 1: 00:00:00:00:00:00
166 Checking link statuses...
172 .. code-block:: console
175 softnic packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP over anonymous pages disabled
176 Logical Core 1 (socket 0) forwards packets on 1 streams:
177 RX P=2/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:02
179 softnic packet forwarding packets/burst=32
180 nb forwarding cores=1 - nb forwarding ports=1
181 port 0: RX queue number: 1 Tx queue number: 1
182 Rx offloads=0x1000 Tx offloads=0x0
184 RX desc=512 - RX free threshold=32
185 RX threshold registers: pthresh=8 hthresh=8 wthresh=0
188 TX desc=512 - TX free threshold=32
189 TX threshold registers: pthresh=32 hthresh=0 wthresh=0
190 TX offloads=0x0 - TX RS bit threshold=32
191 port 1: RX queue number: 1 Tx queue number: 1
192 Rx offloads=0x0 Tx offloads=0x0
194 RX desc=0 - RX free threshold=0
195 RX threshold registers: pthresh=0 hthresh=0 wthresh=0
198 TX desc=0 - TX free threshold=0
199 TX threshold registers: pthresh=0 hthresh=0 wthresh=0
200 TX offloads=0x0 - TX RS bit threshold=0
202 * Softnic device can be configured using remote client (e.g. telnet). However,
203 testpmd application doesn't support configuration through telnet :
205 .. code-block:: console
207 $ telnet 127.0.0.1 8086
209 Connected to 127.0.0.1.
210 Escape character is '^]'.
216 * Add/update Soft NIC pipeline table match-action entries from telnet client:
218 .. code-block:: console
220 softnic> pipeline RX table 0 rule add match default action fwd port 0
221 softnic> pipeline TX table 0 rule add match default action fwd port 0
226 The Soft NIC firmware, for example- `softnic/firmware.cli`, consists of following CLI commands
227 for creating and managing software based NIC pipelines. For more details, please refer to CLI
228 command description provided in `softnic/rte_eth_softnic_cli.c`.
230 * Physical port for packets send/receive:
232 .. code-block:: console
234 link LINK dev 0000:02:00.0
238 .. code-block:: console
240 pipeline RX period 10 offset_port_id 0 (Soft NIC rx-path pipeline)
241 pipeline TX period 10 offset_port_id 0 (Soft NIC tx-path pipeline)
243 * Pipeline input/output port create
245 .. code-block:: console
247 pipeline RX port in bsz 32 link LINK rxq 0 (Soft NIC rx pipeline input port)
248 pipeline RX port out bsz 32 swq RXQ0 (Soft NIC rx pipeline output port)
249 pipeline TX port in bsz 32 swq TXQ0 (Soft NIC tx pipeline input port)
250 pipeline TX port out bsz 32 link LINK txq 0 (Soft NIC tx pipeline output port)
252 * Pipeline table create
254 .. code-block:: console
256 pipeline RX table match stub (Soft NIC rx pipeline match-action table)
257 pipeline TX table match stub (Soft NIC tx pipeline match-action table)
259 * Pipeline input port connection with table
261 .. code-block:: console
263 pipeline RX port in 0 table 0 (Soft NIC rx pipeline input port 0 connection with table 0)
264 pipeline TX port in 0 table 0 (Soft NIC tx pipeline input port 0 connection with table 0)
266 * Pipeline table match-action rules add
268 .. code-block:: console
270 pipeline RX table 0 rule add match default action fwd port 0 (Soft NIC rx pipeline table 0 rule)
271 pipeline TX table 0 rule add match default action fwd port 0 (Soft NIC tx pipeline table 0 rule)
273 * Enable pipeline on CPU thread
275 .. code-block:: console
277 thread 2 pipeline RX enable (Soft NIC rx pipeline enable on cpu thread id 2)
278 thread 2 pipeline TX enable (Soft NIC tx pipeline enable on cpu thread id 2)
283 SoftNIC PMD implements ethdev traffic management APIs ``rte_tm.h`` that
284 allow building and committing traffic manager hierarchy, configuring hierarchy
285 nodes of the Quality of Service (QoS) scheduler supported by DPDK librte_sched
286 library. Furthermore, APIs for run-time update to the traffic manager hierarchy
287 are supported by PMD.
289 SoftNIC PMD also implements ethdev traffic metering and policing APIs
290 ``rte_mtr.h`` that enables metering and marking of the packets with the
291 appropriate color (green, yellow or red), according to the traffic metering
292 algorithm. For the meter output color, policer actions like
293 `keep the packet color same`, `change the packet color` or `drop the packet`
298 The SoftNIC does not support the meter object shared by several flows,
299 thus only supports creating meter object private to the flow. Once meter
300 object is successfully created, it can be linked to the specific flow by
301 specifying the ``meter`` flow action in the flow rule.
306 The SoftNIC PMD implements ethdev flow APIs ``rte_flow.h`` that allow validating
307 flow rules, adding flow rules to the SoftNIC pipeline as table rules, deleting
308 and querying the flow rules. The PMD provides new cli command for creating the
309 flow group and their mapping to the SoftNIC pipeline and table. This cli should
310 be configured as part of firmware file.
312 .. code-block:: console
314 flowapi map group <group_id> ingress | egress pipeline <pipeline_name> \
317 From the flow attributes of the flow, PMD uses the group id to get the mapped
318 pipeline and table. PMD supports number of flow actions such as
319 ``JMP, QUEUE, RSS, DROP, COUNT, METER, VXLAN`` etc.
323 The flow must have one terminating actions i.e.
324 ``JMP or RSS or QUEUE or DROP``. For the count and drop actions the
325 underlying PMD doesn't support the functionality yet. So it is not
328 The flow API can be tested with the help of testpmd application. The SoftNIC
329 firmware specifies CLI commands for port configuration, pipeline creation,
330 action profile creation and table creation. Once application gets initialized,
331 the flow rules can be added through the testpmd CLI.
332 The PMD will translate the flow rules to the SoftNIC pipeline tables rules.
336 Example demonstrates the flow queue action using the SoftNIC firmware and testpmd
339 * Prepare SoftNIC firmware
341 .. code-block:: console
343 link LINK0 dev 0000:83:00.0
344 link LINK1 dev 0000:81:00.0
345 pipeline RX period 10 offset_port_id 0
346 pipeline RX port in bsz 32 link LINK0 rxq 0
347 pipeline RX port in bsz 32 link LINK1 rxq 0
348 pipeline RX port out bsz 32 swq RXQ0
349 pipeline RX port out bsz 32 swq RXQ1
350 table action profile AP0 ipv4 offset 278 fwd
351 pipeline RX table match hash ext key 16 mask
352 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \
353 offset 278 buckets 16K size 65K action AP0
354 pipeline RX port in 0 table 0
355 pipeline RX port in 1 table 0
356 flowapi map group 0 ingress pipeline RX table 0
357 pipeline TX period 10 offset_port_id 0
358 pipeline TX port in bsz 32 swq TXQ0
359 pipeline TX port in bsz 32 swq TXQ1
360 pipeline TX port out bsz 32 link LINK0 txq 0
361 pipeline TX port out bsz 32 link LINK1 txq 0
362 pipeline TX table match hash ext key 16 mask
363 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \
364 offset 278 buckets 16K size 65K action AP0
365 pipeline TX port in 0 table 0
366 pipeline TX port in 1 table 0
367 pipeline TX table 0 rule add match hash ipv4_5tuple
368 1.10.11.12 2.20.21.22 100 200 6 action fwd port 0
369 pipeline TX table 0 rule add match hash ipv4_5tuple
370 1.10.11.13 2.20.21.23 100 200 6 action fwd port 1
371 thread 2 pipeline RX enable
372 thread 2 pipeline TX enable
376 .. code-block:: console
378 ./x86_64-native-linux-gcc/app/testpmd -c 0x7 -s 0x4 -n 4 \
379 --vdev 'net_softnic0, \
380 firmware=./drivers/net/softnic/ \
382 cpu_id=1,conn_port=8086' -- \
384 --txq=2, --disable-rss --portmask=0x4
386 * Configure flow rules on softnic:
388 .. code-block:: console
390 flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \
391 mask 255.255.255.255 dst mask 255.255.255.255 src spec
392 1.10.11.12 dst spec 2.20.21.22 proto spec 6 / tcp src mask 65535 \
393 dst mask 65535 src spec 100 dst spec 200 / end actions queue \
395 flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \
396 mask 255.255.255.255 dst mask 255.255.255.255 src spec 1.10.11.13 \
397 dst spec 2.20.21.23 proto spec 6 / tcp src mask 65535 dst mask \
398 65535 src spec 100 dst spec 200 / end actions queue index 1 / end