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
  55 Soft NIC PMD arguments
  56 ----------------------
  57
  58 The user can specify below arguments in EAL ``--vdev`` options to create the
  59 Soft 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
 116 Soft 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
 214 Soft NIC Firmware
 215 -----------------
 216
 217 The Soft NIC firmware, for example- `softnic/firmware.cli`, consists of following CLI commands
 218 for creating and managing software based NIC pipelines. For more details, please refer to CLI
 219 command 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
 271 QoS API Support:
 272 ----------------
 273
 274 SoftNIC PMD implements ethdev traffic management APIs ``rte_tm.h`` that
 275 allow building and committing traffic manager hierarchy, configuring hierarchy
 276 nodes of the Quality of Service (QoS) scheduler supported by DPDK librte_sched
 277 library. Furthermore, APIs for run-time update to the traffic manager hierarchy
 278 are supported by PMD.
 279
 280 SoftNIC PMD also implements ethdev traffic metering and policing APIs
 281 ``rte_mtr.h`` that enables metering and marking of the packets with the
 282 appropriate color (green, yellow or red), according to the traffic metering
 283 algorithm. For the meter output color, policer actions like
 284 `keep the packet color same`, `change the packet color` or `drop the packet`
 285 can 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
 294 Flow API support:
 295 -----------------
 296
 297 The SoftNIC PMD implements ethdev flow APIs ``rte_flow.h`` that allow validating
 298 flow rules, adding flow rules to the SoftNIC pipeline as table rules, deleting
 299 and querying the flow rules. The PMD provides new cli command for creating the
 300 flow group and their mapping to the SoftNIC pipeline and table. This cli should
 301 be 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
 308 From the flow attributes of the flow, PMD uses the group id to get the mapped
 309 pipeline 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
 319 The flow API can be tested with the help of testpmd application. The SoftNIC
 320 firmware specifies CLI commands for port configuration, pipeline creation,
 321 action profile creation and table creation. Once application gets initialized,
 322 the flow rules can be added through the testpmd CLI.
 323 The PMD will translate the flow rules to the SoftNIC pipeline tables rules.
 324
 325 Example:
 326 ~~~~~~~~
 327 Example demonstrates the flow queue action using the SoftNIC firmware and testpmd
 328 commands.
 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