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_linuxapp 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 per traffic class of the pipes/subscribers.
  86     (Optional: yes, Default: 64)
  87
  88 #.  ``tm_qsize1``: size of scheduler queue 1 per traffic class of the pipes/subscribers.
  89     (Optional: yes, Default: 64)
  90
  91 #.  ``tm_qsize2``: size of scheduler queue 2 per traffic class of the pipes/subscribers.
  92     (Optional: yes, Default: 64)
  93
  94 #.  ``tm_qsize3``: size of scheduler queue 3 per traffic class of the pipes/subscribers.
  95     (Optional: yes, Default: 64)
  96
  97
  98 Soft NIC testing
  99 ----------------
 100
 101 * Run testpmd application in Soft NIC forwarding mode with loopback feature
 102   enabled on Soft NIC port:
 103
 104     .. code-block:: console
 105
 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
 108
 109     .. code-block:: console
 110
 111         ...
 112         Interactive-mode selected
 113         Set softnic packet forwarding mode
 114         ...
 115         Configuring Port 0 (socket 0)
 116         Port 0: 90:E2:BA:37:9D:DC
 117         Configuring Port 1 (socket 0)
 118
 119         ; SPDX-License-Identifier: BSD-3-Clause
 120         ; Copyright(c) 2018 Intel Corporation
 121
 122         link LINK dev 0000:02:00.0
 123
 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
 129
 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
 135
 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...
 140         Done
 141         testpmd>
 142
 143 * Start forwarding
 144
 145     .. code-block:: console
 146
 147          testpmd> start
 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
 151
 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
 156          RX queue: 0
 157          RX desc=512 - RX free threshold=32
 158          RX threshold registers: pthresh=8 hthresh=8  wthresh=0
 159          RX Offloads=0x0
 160          TX queue: 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
 166          RX queue: 0
 167          RX desc=0 - RX free threshold=0
 168          RX threshold registers: pthresh=0 hthresh=0  wthresh=0
 169          RX Offloads=0x0
 170          TX queue: 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
 174
 175 * Start remote client (e.g. telnet) to communicate with the softnic device:
 176
 177     .. code-block:: console
 178
 179         $ telnet 127.0.0.1 8086
 180         Trying 127.0.0.1...
 181         Connected to 127.0.0.1.
 182         Escape character is '^]'.
 183
 184         Welcome to Soft NIC!
 185
 186         softnic>
 187
 188 * Add/update Soft NIC pipeline table match-action entries from telnet client:
 189
 190     .. code-block:: console
 191
 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
 194
 195 Soft NIC Firmware
 196 -----------------
 197
 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`.
 201
 202 * Physical port for packets send/receive:
 203
 204     .. code-block:: console
 205
 206         link LINK dev 0000:02:00.0
 207
 208 * Pipeline create:
 209
 210     .. code-block:: console
 211
 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)
 214
 215 * Pipeline input/output port create
 216
 217     .. code-block:: console
 218
 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)
 223
 224 * Pipeline table create
 225
 226     .. code-block:: console
 227
 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)
 230
 231 * Pipeline input port connection with table
 232
 233     .. code-block:: console
 234
 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)
 237
 238 * Pipeline table match-action rules add
 239
 240     .. code-block:: console
 241
 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)
 244
 245 * Enable pipeline on CPU thread
 246
 247     .. code-block:: console
 248
 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)