1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. 3 4Soft NIC Poll Mode Driver 5========================= 6 7The Soft NIC allows building custom NIC pipelines in software. The Soft NIC pipeline 8is DIY and reconfigurable through ``firmware`` (DPDK Packet Framework script). 9 10The Soft NIC leverages the DPDK Packet Framework libraries (librte_port, 11librte_table and librte_pipeline) to make it modular, flexible and extensible 12with new functionality. Please refer to DPDK Programmer's Guide, Chapter 13``Packet Framework`` and DPDK Sample Application User Guide, 14Chapter ``IP Pipeline Application`` for more details. 15 16The Soft NIC is configured through the standard DPDK ethdev API (ethdev, flow, 17QoS, security). The internal framework is not externally visible. 18 19Key benefits: 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. 24 25Flow 26---- 27* ``Device creation``: Each Soft NIC instance is a virtual device. 28 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, 32 etc. 33 34* ``Device stop``: All the internal objects that were previously created by the 35 firmware script during device start are now destroyed. 36 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 42 device. 43 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. 46 47Supported Operating Systems 48--------------------------- 49 50Any Linux distribution fulfilling the conditions described in ``System Requirements`` 51section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK 52Release Notes*. 53 54 55Runtime Configuration 56--------------------- 57 58The user can specify below arguments in EAL ``--vdev`` options to create the 59Soft NIC device instance: 60 61 --vdev "net_softnic0,firmware=firmware.cli,conn_port=8086" 62 63#. ``firmware``: path to the firmware script used for Soft NIC configuration. 64 The example "firmware" script is provided at `drivers/net/softnic/`. 65 (Optional: No, Default = NA) 66 67#. ``conn_port``: tcp connection port (non-zero value) used by remote client 68 (for examples- telnet, netcat, etc.) to connect and configure Soft NIC device in run-time. 69 (Optional: yes, Default value: 0, no connection with external client) 70 71#. ``cpu_id``: numa node id. (Optional: yes, Default value: 0) 72 73#. ``tm_n_queues``: number of traffic manager's scheduler queues. The traffic manager 74 is based on DPDK *librte_sched* library. (Optional: yes, Default value: 65,536 queues) 75 76#. ``tm_qsize0``: size of scheduler queue 0 (traffic class 0) of the pipes/subscribers. 77 (Optional: yes, Default: 64) 78 79#. ``tm_qsize1``: size of scheduler queue 1 (traffic class 1) of the pipes/subscribers. 80 (Optional: yes, Default: 64) 81 82#. ``tm_qsize2``: size of scheduler queue 2 (traffic class 2) of the pipes/subscribers. 83 (Optional: yes, Default: 64) 84 85#. ``tm_qsize3``: size of scheduler queue 3 (traffic class 3) of the pipes/subscribers. 86 (Optional: yes, Default: 64) 87 88#. ``tm_qsize4``: size of scheduler queue 4 (traffic class 4) of the pipes/subscribers. 89 (Optional: yes, Default: 64) 90 91#. ``tm_qsize5``: size of scheduler queue 5 (traffic class 5) of the pipes/subscribers. 92 (Optional: yes, Default: 64) 93 94#. ``tm_qsize6``: size of scheduler queue 6 (traffic class 6) of the pipes/subscribers. 95 (Optional: yes, Default: 64) 96 97#. ``tm_qsize7``: size of scheduler queue 7 (traffic class 7) of the pipes/subscribers. 98 (Optional: yes, Default: 64) 99 100#. ``tm_qsize8``: size of scheduler queue 8 (traffic class 8) of the pipes/subscribers. 101 (Optional: yes, Default: 64) 102 103#. ``tm_qsize9``: size of scheduler queue 9 (traffic class 9) of the pipes/subscribers. 104 (Optional: yes, Default: 64) 105 106#. ``tm_qsize10``: size of scheduler queue 10 (traffic class 10) of the pipes/subscribers. 107 (Optional: yes, Default: 64) 108 109#. ``tm_qsize11``: size of scheduler queue 11 (traffic class 11) of the pipes/subscribers. 110 (Optional: yes, Default: 64) 111 112#. ``tm_qsize12``: size of scheduler queue 12 (traffic class 12) of the pipes/subscribers. 113 (Optional: yes, Default: 64) 114 115 116Soft NIC testing 117---------------- 118 119* Run testpmd application with Soft NIC device with loopback feature 120 enabled on Soft NIC port: 121 122 .. code-block:: console 123 124 ./dpdk-testpmd -c 0x7 -s 0x4 --vdev 'net_softnic0,firmware=<script path>/firmware.cli,cpu_id=0,conn_port=8086' -- -i 125 --portmask=0x2 126 127 .. code-block:: console 128 129 ... 130 Interactive-mode selected 131 Set softnic packet forwarding mode 132 ... 133 Configuring Port 0 (socket 0) 134 Port 0: 90:E2:BA:37:9D:DC 135 Configuring Port 1 (socket 0) 136 137 ; SPDX-License-Identifier: BSD-3-Clause 138 ; Copyright(c) 2018 Intel Corporation 139 140 link LINK dev 0000:02:00.0 141 142 pipeline RX period 10 offset_port_id 0 143 pipeline RX port in bsz 32 link LINK rxq 0 144 pipeline RX port out bsz 32 swq RXQ0 145 pipeline RX table match stub 146 pipeline RX port in 0 table 0 147 148 pipeline TX period 10 offset_port_id 0 149 pipeline TX port in bsz 32 swq TXQ0 150 pipeline TX port out bsz 32 link LINK txq 0 151 pipeline TX table match stub 152 pipeline TX port in 0 table 0 153 154 thread 2 pipeline RX enable 155 thread 2 pipeline TX enable 156 Port 1: 00:00:00:00:00:00 157 Checking link statuses... 158 Done 159 testpmd> 160 161* Start forwarding 162 163 .. code-block:: console 164 165 testpmd> start 166 softnic packet forwarding - ports=1 - cores=1 - streams=1 - NUMA support enabled, MP over anonymous pages disabled 167 Logical Core 1 (socket 0) forwards packets on 1 streams: 168 RX P=2/Q=0 (socket 0) -> TX P=2/Q=0 (socket 0) peer=02:00:00:00:00:02 169 170 softnic packet forwarding packets/burst=32 171 nb forwarding cores=1 - nb forwarding ports=1 172 port 0: RX queue number: 1 Tx queue number: 1 173 Rx offloads=0x1000 Tx offloads=0x0 174 RX queue: 0 175 RX desc=512 - RX free threshold=32 176 RX threshold registers: pthresh=8 hthresh=8 wthresh=0 177 RX Offloads=0x0 178 TX queue: 0 179 TX desc=512 - TX free threshold=32 180 TX threshold registers: pthresh=32 hthresh=0 wthresh=0 181 TX offloads=0x0 - TX RS bit threshold=32 182 port 1: RX queue number: 1 Tx queue number: 1 183 Rx offloads=0x0 Tx offloads=0x0 184 RX queue: 0 185 RX desc=0 - RX free threshold=0 186 RX threshold registers: pthresh=0 hthresh=0 wthresh=0 187 RX Offloads=0x0 188 TX queue: 0 189 TX desc=0 - TX free threshold=0 190 TX threshold registers: pthresh=0 hthresh=0 wthresh=0 191 TX offloads=0x0 - TX RS bit threshold=0 192 193* Softnic device can be configured using remote client (e.g. telnet). However, 194 testpmd application doesn't support configuration through telnet : 195 196 .. code-block:: console 197 198 $ telnet 127.0.0.1 8086 199 Trying 127.0.0.1... 200 Connected to 127.0.0.1. 201 Escape character is '^]'. 202 203 Welcome to Soft NIC! 204 205 softnic> 206 207* Add/update Soft NIC pipeline table match-action entries from telnet client: 208 209 .. code-block:: console 210 211 softnic> pipeline RX table 0 rule add match default action fwd port 0 212 softnic> pipeline TX table 0 rule add match default action fwd port 0 213 214Soft NIC Firmware 215----------------- 216 217The Soft NIC firmware, for example- `softnic/firmware.cli`, consists of following CLI commands 218for creating and managing software based NIC pipelines. For more details, please refer to CLI 219command description provided in `softnic/rte_eth_softnic_cli.c`. 220 221* Physical port for packets send/receive: 222 223 .. code-block:: console 224 225 link LINK dev 0000:02:00.0 226 227* Pipeline create: 228 229 .. code-block:: console 230 231 pipeline RX period 10 offset_port_id 0 (Soft NIC rx-path pipeline) 232 pipeline TX period 10 offset_port_id 0 (Soft NIC tx-path pipeline) 233 234* Pipeline input/output port create 235 236 .. code-block:: console 237 238 pipeline RX port in bsz 32 link LINK rxq 0 (Soft NIC rx pipeline input port) 239 pipeline RX port out bsz 32 swq RXQ0 (Soft NIC rx pipeline output port) 240 pipeline TX port in bsz 32 swq TXQ0 (Soft NIC tx pipeline input port) 241 pipeline TX port out bsz 32 link LINK txq 0 (Soft NIC tx pipeline output port) 242 243* Pipeline table create 244 245 .. code-block:: console 246 247 pipeline RX table match stub (Soft NIC rx pipeline match-action table) 248 pipeline TX table match stub (Soft NIC tx pipeline match-action table) 249 250* Pipeline input port connection with table 251 252 .. code-block:: console 253 254 pipeline RX port in 0 table 0 (Soft NIC rx pipeline input port 0 connection with table 0) 255 pipeline TX port in 0 table 0 (Soft NIC tx pipeline input port 0 connection with table 0) 256 257* Pipeline table match-action rules add 258 259 .. code-block:: console 260 261 pipeline RX table 0 rule add match default action fwd port 0 (Soft NIC rx pipeline table 0 rule) 262 pipeline TX table 0 rule add match default action fwd port 0 (Soft NIC tx pipeline table 0 rule) 263 264* Enable pipeline on CPU thread 265 266 .. code-block:: console 267 268 thread 2 pipeline RX enable (Soft NIC rx pipeline enable on cpu thread id 2) 269 thread 2 pipeline TX enable (Soft NIC tx pipeline enable on cpu thread id 2) 270 271QoS API Support: 272---------------- 273 274SoftNIC PMD implements ethdev traffic management APIs ``rte_tm.h`` that 275allow building and committing traffic manager hierarchy, configuring hierarchy 276nodes of the Quality of Service (QoS) scheduler supported by DPDK librte_sched 277library. Furthermore, APIs for run-time update to the traffic manager hierarchy 278are supported by PMD. 279 280SoftNIC PMD also implements ethdev traffic metering and policing APIs 281``rte_mtr.h`` that enables metering and marking of the packets with the 282appropriate color (green, yellow or red), according to the traffic metering 283algorithm. For the meter output color, policer actions like 284`keep the packet color same`, `change the packet color` or `drop the packet` 285can be configured. 286 287.. Note:: 288 289 The SoftNIC does not support the meter object shared by several flows, 290 thus only supports creating meter object private to the flow. Once meter 291 object is successfully created, it can be linked to the specific flow by 292 specifying the ``meter`` flow action in the flow rule. 293 294Flow API support: 295----------------- 296 297The SoftNIC PMD implements ethdev flow APIs ``rte_flow.h`` that allow validating 298flow rules, adding flow rules to the SoftNIC pipeline as table rules, deleting 299and querying the flow rules. The PMD provides new cli command for creating the 300flow group and their mapping to the SoftNIC pipeline and table. This cli should 301be configured as part of firmware file. 302 303 .. code-block:: console 304 305 flowapi map group <group_id> ingress | egress pipeline <pipeline_name> \ 306 table <table_id> 307 308From the flow attributes of the flow, PMD uses the group id to get the mapped 309pipeline and table. PMD supports number of flow actions such as 310``JMP, QUEUE, RSS, DROP, COUNT, METER, VXLAN`` etc. 311 312.. Note:: 313 314 The flow must have one terminating actions i.e. 315 ``JMP or RSS or QUEUE or DROP``. For the count and drop actions the 316 underlying PMD doesn't support the functionality yet. So it is not 317 recommended for use. 318 319The flow API can be tested with the help of testpmd application. The SoftNIC 320firmware specifies CLI commands for port configuration, pipeline creation, 321action profile creation and table creation. Once application gets initialized, 322the flow rules can be added through the testpmd CLI. 323The PMD will translate the flow rules to the SoftNIC pipeline tables rules. 324 325Example: 326~~~~~~~~ 327Example demonstrates the flow queue action using the SoftNIC firmware and testpmd 328commands. 329 330* Prepare SoftNIC firmware 331 332 .. code-block:: console 333 334 link LINK0 dev 0000:83:00.0 335 link LINK1 dev 0000:81:00.0 336 pipeline RX period 10 offset_port_id 0 337 pipeline RX port in bsz 32 link LINK0 rxq 0 338 pipeline RX port in bsz 32 link LINK1 rxq 0 339 pipeline RX port out bsz 32 swq RXQ0 340 pipeline RX port out bsz 32 swq RXQ1 341 table action profile AP0 ipv4 offset 278 fwd 342 pipeline RX table match hash ext key 16 mask 343 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \ 344 offset 278 buckets 16K size 65K action AP0 345 pipeline RX port in 0 table 0 346 pipeline RX port in 1 table 0 347 flowapi map group 0 ingress pipeline RX table 0 348 pipeline TX period 10 offset_port_id 0 349 pipeline TX port in bsz 32 swq TXQ0 350 pipeline TX port in bsz 32 swq TXQ1 351 pipeline TX port out bsz 32 link LINK0 txq 0 352 pipeline TX port out bsz 32 link LINK1 txq 0 353 pipeline TX table match hash ext key 16 mask 354 00FF0000FFFFFFFFFFFFFFFFFFFFFFFF \ 355 offset 278 buckets 16K size 65K action AP0 356 pipeline TX port in 0 table 0 357 pipeline TX port in 1 table 0 358 pipeline TX table 0 rule add match hash ipv4_5tuple 359 1.10.11.12 2.20.21.22 100 200 6 action fwd port 0 360 pipeline TX table 0 rule add match hash ipv4_5tuple 361 1.10.11.13 2.20.21.23 100 200 6 action fwd port 1 362 thread 2 pipeline RX enable 363 thread 2 pipeline TX enable 364 365* Run testpmd: 366 367 .. code-block:: console 368 369 ./<build_dir>/app/dpdk-testpmd -c 0x7 -s 0x4 -n 4 \ 370 --vdev 'net_softnic0, \ 371 firmware=./drivers/net/softnic/ \ 372 firmware.cli, \ 373 cpu_id=1,conn_port=8086' -- \ 374 -i --rxq=2, \ 375 --txq=2, --disable-rss --portmask=0x4 376 377* Configure flow rules on softnic: 378 379 .. code-block:: console 380 381 flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \ 382 mask 255.255.255.255 dst mask 255.255.255.255 src spec 383 1.10.11.12 dst spec 2.20.21.22 proto spec 6 / tcp src mask 65535 \ 384 dst mask 65535 src spec 100 dst spec 200 / end actions queue \ 385 index 0 / end 386 flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \ 387 mask 255.255.255.255 dst mask 255.255.255.255 src spec 1.10.11.13 \ 388 dst spec 2.20.21.23 proto spec 6 / tcp src mask 65535 dst mask \ 389 65535 src spec 100 dst spec 200 / end actions queue index 1 / end 390