doc/guides/nics/softnic.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2018 Intel Corporation.
   3
   4 Soft NIC Poll Mode Driver
   5 =========================
   6
   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).
   9
  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.
  15
  16 The Soft NIC is configured through the standard DPDK ethdev API (ethdev, flow,
  17 QoS, security). The internal framework is not externally visible.
  18
  19 Key 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
  25 Flow
  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
  47 Supported Operating Systems
  48 ---------------------------
  49
  50 Any Linux distribution fulfilling the conditions described in ``System Requirements``
  51 section of :ref:`the DPDK documentation <linux_gsg>` or refer to *DPDK
  52 Release Notes*.
  53
  54 Build options
  55 -------------
  56
  57 The default PMD configuration available in the common_linux configuration file:
  58
  59 CONFIG_RTE_LIBRTE_PMD_SOFTNIC=y
  60
  61 Once the DPDK is built, all the DPDK applications include support for the
  62 Soft NIC PMD.
  63
  64 Soft NIC PMD arguments
  65 ----------------------
  66
  67 The user can specify below arguments in EAL ``--vdev`` options to create the
  68 Soft NIC device instance:
  69
  70         --vdev "net_softnic0,firmware=firmware.cli,conn_port=8086"
  71
  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)
  75
  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)
  79
  80 #.  ``cpu_id``: numa node id. (Optional: yes, Default value: 0)
  81
  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)
  84
  85 #.  ``tm_qsize0``: size of scheduler queue 0 (traffic class 0) of the pipes/subscribers.
  86     (Optional: yes, Default: 64)
  87
  88 #.  ``tm_qsize1``: size of scheduler queue 1 (traffic class 1) of the pipes/subscribers.
  89     (Optional: yes, Default: 64)
  90
  91 #.  ``tm_qsize2``: size of scheduler queue 2 (traffic class 2) of the pipes/subscribers.
  92     (Optional: yes, Default: 64)
  93
  94 #.  ``tm_qsize3``: size of scheduler queue 3 (traffic class 3) of the pipes/subscribers.
  95     (Optional: yes, Default: 64)
  96
  97 #.  ``tm_qsize4``: size of scheduler queue 4 (traffic class 4) of the pipes/subscribers.
  98     (Optional: yes, Default: 64)
  99
 100 #.  ``tm_qsize5``: size of scheduler queue 5 (traffic class 5) of the pipes/subscribers.
 101     (Optional: yes, Default: 64)
 102
 103 #.  ``tm_qsize6``: size of scheduler queue 6 (traffic class 6) of the pipes/subscribers.
 104     (Optional: yes, Default: 64)
 105
 106 #.  ``tm_qsize7``: size of scheduler queue 7 (traffic class 7) of the pipes/subscribers.
 107     (Optional: yes, Default: 64)
 108
 109 #.  ``tm_qsize8``: size of scheduler queue 8 (traffic class 8) of the pipes/subscribers.
 110     (Optional: yes, Default: 64)
 111
 112 #.  ``tm_qsize9``: size of scheduler queue 9 (traffic class 9) of the pipes/subscribers.
 113     (Optional: yes, Default: 64)
 114
 115 #.  ``tm_qsize10``: size of scheduler queue 10 (traffic class 10) of the pipes/subscribers.
 116     (Optional: yes, Default: 64)
 117
 118 #.  ``tm_qsize11``: size of scheduler queue 11 (traffic class 11) of the pipes/subscribers.
 119     (Optional: yes, Default: 64)
 120
 121 #.  ``tm_qsize12``: size of scheduler queue 12 (traffic class 12) of the pipes/subscribers.
 122     (Optional: yes, Default: 64)
 123
 124
 125 Soft NIC testing
 126 ----------------
 127
 128 * Run testpmd application with Soft NIC device with loopback feature
 129   enabled on Soft NIC port:
 130
 131     .. code-block:: console
 132
 133          ./testpmd -c 0x7 -s 0x4 --vdev 'net_softnic0,firmware=<script path>/firmware.cli,cpu_id=0,conn_port=8086' -- -i
 134               --portmask=0x2
 135
 136     .. code-block:: console
 137
 138         ...
 139         Interactive-mode selected
 140         Set softnic packet forwarding mode
 141         ...
 142         Configuring Port 0 (socket 0)
 143         Port 0: 90:E2:BA:37:9D:DC
 144         Configuring Port 1 (socket 0)
 145
 146         ; SPDX-License-Identifier: BSD-3-Clause
 147         ; Copyright(c) 2018 Intel Corporation
 148
 149         link LINK dev 0000:02:00.0
 150
 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
 156
 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
 162
 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...
 167         Done
 168         testpmd>
 169
 170 * Start forwarding
 171
 172     .. code-block:: console
 173
 174          testpmd> start
 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
 178
 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
 183          RX queue: 0
 184          RX desc=512 - RX free threshold=32
 185          RX threshold registers: pthresh=8 hthresh=8  wthresh=0
 186          RX Offloads=0x0
 187          TX queue: 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
 193          RX queue: 0
 194          RX desc=0 - RX free threshold=0
 195          RX threshold registers: pthresh=0 hthresh=0  wthresh=0
 196          RX Offloads=0x0
 197          TX queue: 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
 201
 202 * Softnic device can be configured using remote client (e.g. telnet). However,
 203   testpmd application doesn't support configuration through telnet :
 204
 205     .. code-block:: console
 206
 207         $ telnet 127.0.0.1 8086
 208         Trying 127.0.0.1...
 209         Connected to 127.0.0.1.
 210         Escape character is '^]'.
 211
 212         Welcome to Soft NIC!
 213
 214         softnic>
 215
 216 * Add/update Soft NIC pipeline table match-action entries from telnet client:
 217
 218     .. code-block:: console
 219
 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
 222
 223 Soft NIC Firmware
 224 -----------------
 225
 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`.
 229
 230 * Physical port for packets send/receive:
 231
 232     .. code-block:: console
 233
 234         link LINK dev 0000:02:00.0
 235
 236 * Pipeline create:
 237
 238     .. code-block:: console
 239
 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)
 242
 243 * Pipeline input/output port create
 244
 245     .. code-block:: console
 246
 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)
 251
 252 * Pipeline table create
 253
 254     .. code-block:: console
 255
 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)
 258
 259 * Pipeline input port connection with table
 260
 261     .. code-block:: console
 262
 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)
 265
 266 * Pipeline table match-action rules add
 267
 268     .. code-block:: console
 269
 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)
 272
 273 * Enable pipeline on CPU thread
 274
 275     .. code-block:: console
 276
 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)
 279
 280 QoS API Support:
 281 ----------------
 282
 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.
 288
 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`
 294 can be configured.
 295
 296 .. Note::
 297
 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.
 302
 303 Flow API support:
 304 -----------------
 305
 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.
 311
 312     .. code-block:: console
 313
 314         flowapi map group <group_id> ingress | egress pipeline <pipeline_name> \
 315             table <table_id>
 316
 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.
 320
 321 .. Note::
 322
 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
 326     recommended for use.
 327
 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.
 333
 334 Example:
 335 ~~~~~~~~
 336 Example demonstrates the flow queue action using the SoftNIC firmware and testpmd
 337 commands.
 338
 339 * Prepare SoftNIC firmware
 340
 341     .. code-block:: console
 342
 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
 373
 374 * Run testpmd:
 375
 376     .. code-block:: console
 377
 378         ./x86_64-native-linux-gcc/app/testpmd -c 0x7 -s 0x4 -n 4 \
 379                                     --vdev 'net_softnic0, \
 380                                     firmware=./drivers/net/softnic/ \
 381                                         firmware.cli, \
 382                                     cpu_id=1,conn_port=8086' -- \
 383                                     -i --rxq=2, \
 384                                     --txq=2, --disable-rss --portmask=0x4
 385
 386 * Configure flow rules on softnic:
 387
 388     .. code-block:: console
 389
 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 \
 394             index 0 / end
 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