Get Started Using the Data Plane Development Kit (DPDK) Software Network Interface Card (Soft NIC)

Introduction

This article describes the features of the Data Plane Development Kit (DPDK) Software Network Interface Card (Soft NIC) poll mode driver (PMD). Soft NIC was introduced in DPDK 17.11 and evolved to provide support for various ethernet device (ethdev) APIs. For users of DPDK who would like to build customized NICs based on Soft NIC, the examples provided will help you get started.

Usages

Soft NIC is a DPDK poll mode driver developed to facilitate software fallback for ethdev APIs that are not supported in NIC hardware.

Initially, Soft NIC provided software fallback for traffic management APIs for Quality of Service (QoS) on the transmit (TX) side. Later it was extended to the receive (RX) side with policing, metering, and flow APIs. The Soft NIC mechanism is generic, so software fallback to any new ethdev API can be easily added.

Soft NIC enables you to build a pipeline in software with reconfiguration through “firmware” (a DPDK packet framework script) to achieve software fallback. The application provides the features to consider for software fallback using this firmware script. The Soft NIC PMD creates a soft port to serve as the virtual device (vdev) for a given hard port and drives the hard port, with Soft NIC acting as a software front end to the hard NICs. Applications will read and write to Soft NIC queues. Soft NIC can be created using Environment Abstraction Layer (EAL) command line options or vdev APIs. Features including flow, QoS, and security can be configured through the standard DPDK ethdev API. Soft NIC can run with any underlying hard NIC.

The Soft NIC leverages the DPDK Packet Framework libraries (librte_port, librte_table and librte_pipeline) to increase modularity, flexibility, and extensibility.

Key benefits

Usability

Soft NIC can be used to add features missing from hardware NICs. It enables consumption of advanced DPDK features without application redesign. For example, it is difficult for users to write a full application from scratch, whereas Soft NIC can do this easily by using the firmware to build the pipeline accordingly.

Performance

Soft NIC delivers a performance boost for a DPDK consumer application when used in its performance-sensitive path. Good performance can be achieved by using pre-packaged features (i.e., librte_ports and other libraries) for optimal RX and TX paths.

Soft NIC Connectivity with Hard NIC and Applications

Figure 1 shows how NIC RX and TX pipelines are built using Soft NIC and how they are used by the application.

Figure 1. NIC RX and TX Pipelines using Soft NIC

Soft NIC Creation and Configuration

To create and configure Soft NIC, call the DPDK ethdev API from your application’s primary thread.

Device creation

Each Soft NIC instance is a virtual device. An application creates the Soft NIC vdev using either the EAL command line option or the ethdev API. During this stage, the vdev is created and registered under the ethdev list.

Device queue configuration

The number of RX and TX queues can be defined and reconfigured using ethdev APIs. During this stage, the Soft NIC creates the rte_rings for each of the configured RX and TX queues.

Starting the device

The application must provide the features to be considered for software fallback in the firmware, using a firmware script that is executed every time the device is started. The firmware script typically creates several internal objects, including memory pools, software queues, a traffic manager, link objects, pipelines, action profiles, input ports, output ports, tables, and rules. This is followed by mapping the pipelines to CPU cores.

Stopping the device

Stopping the Soft NIC will destroy all the objects previously created by the firmware at startup time.

Running the device

Each Soft NIC device needs one or more CPU cores to run, and can use either service or non-service cores. Core selection can be specified through a Soft NIC device command line option. The firmware script maps each internal pipeline to a core. Multiple pipelines can be mapped to the same core. For a given pipeline to run on an assigned core, rte_pmd_softnic_run() has to be called the periodically.

Running the application

A Soft NIC acts as a software front end to hard NICs and drive the hard port. The application thread calls the ethdev API to read packets from or write packets to the Soft NIC queues. It is configured through the standard DPDK ethdev APIs ethdev, flow, QoS, and security. The internal framework is not externally visible.

Soft NIC threads, called data plane threads, use the Soft NIC run API to execute the pipelines assigned to the current thread.

Create the Soft NIC PMD

User applications can specify arguments in EAL ‘--vdev’ options to create the Soft NIC device instance. For example:

--vdev 'net_softnic0, firmware=firmware.cli, cpu_id=1, conn_port=8086'

firmware

Path to the firmware script used for Soft NIC configuration. The example firmware script is provided at ‘drivers/net/softnic/’.

Optional: No, Default = NA.

conn_port

The TCP connection port used by the remote client (ex: telnet, netcat, etc.) to connect and configure Soft NIC device in run-time.

Optional: yes, Default value: 0, no connection with external client

cpu_id

numa node id.

Optional: yes, Default value: 0

sc

Support running the Soft NIC device on service cores.

Optional: yes, Default value: 1

0: The current Soft NIC device is run explicitly by the application. The firmware creates one or more pipelines for this dev and maps them to CPU cores that should not be service cores. The app is required to call rte_pmd_softnic_run() to make this dev work.

1 (default): The current device is run on the service cores transparently to the app. The firmware creates one or more pipelines for this dev and maps them to CPU cores that should be service cores. Each of these service cores is required to call rte_pmd_softnic_run() in order to make this dev work with no app intervention.

More options are described in the Soft NIC Poll Mode Driver section of the DPDK Programmer's Guide.

Build options

The default PMD configuration is enabled in common_linuxapp i.e.

CONFIG_RTE_LIBRTE_PMD_SOFTNIC=y

Soft NIC Testing

Follow the steps below to use testpmd to test your Soft NIC.

1. Run the testpmd application in Soft NIC forwarding mode with the loopback feature enabled on Soft NIC port.

   ./testpmd -c 0x3 --vdev 'net_softnic0,firmware=<script path>/firmware.cli,cpu_id=0,conn_port=8086' -- -i --forward-mode=softnic --portmask=0x2

2. Start forwarding.

   testpmd> start

3. Start the remote client (e.g., telnet) to communicate with the Soft NIC device and to make additional configuration updates.

   $ telnet 127.0.0.1 8086
   Trying 127.0.0.1...
   Connected to 127.0.0.1.
   Escape character is '^]'.
   Welcome to Soft NIC!
   softnic>
   

4. Add or update the Soft NIC pipeline table match-action entries from the telnet client.
   For example:

   softnic> pipeline RX table 0 rule add match default action fwd port 0
   softnic> pipeline TX table 0 rule add match default action fwd port 0
   

Soft NIC Firmware

Soft NIC firmware – for example, `drivers/net/softnic/firmware.cli`, consists of the following command line interface (CLI) commands to create and managing software-based NIC pipelines. For more details, please refer to the CLI command description provided in `drivers/net/softnic/rte_eth_softnic_cli.c`.

Physical port for packet send/receive

link LINK dev 0000:02:00.0

Pipeline create

pipeline RX period 10 offset_port_id 0           (Soft NIC rx-path pipeline)
pipeline TX period 10 offset_port_id 0           (Soft NIC tx-path pipeline)

Pipeline input/output port create

pipeline RX port in bsz 32 link LINK rxq 0     (Soft NIC rx pipeline input port)
pipeline RX port out bsz 32 swq RXQ0           (Soft NIC rx pipeline output port)
pipeline TX port in bsz 32 swq TXQ0            (Soft NIC tx pipeline input port)
pipeline TX port out bsz 32 link LINK txq 0    (Soft NIC tx pipeline output port)

Pipeline table create

pipeline RX table match stub         (Soft NIC rx pipeline match-action table)
pipeline TX table match stub         (Soft NIC tx pipeline match-action table)

Pipeline input port connection, with table

pipeline RX port in 0 table 0     (Soft NIC rx pipeline input port 0 connection with table 0)
pipeline TX port in 0 table 0     (Soft NIC tx pipeline input port 0 connection with table 0)

Pipeline table match-action rules add

pipeline RX table 0 rule add match default action fwd port 0    (Soft NIC rx pipeline table 0 rule)
pipeline TX table 0 rule add match default action fwd port 0    (Soft NIC tx pipeline table 0 rule)

Enable pipeline on CPU thread

thread 1 pipeline RX enable        (Soft NIC rx pipeline enable on cpu thread id 1)
thread 1 pipeline TX enable        (Soft NIC tx pipeline enable on cpu thread id 1)

QoS API Support in Soft NIC

The Soft NIC PMD implements ethdev traffic management APIs in ‘rte_tm.h’, which allow building and committing the traffic manager hierarchy and configuring the hierarchy nodes of the Quality of Service (QoS) scheduler supported by the DPDK librte_sched library. In addition, APIs for the run-time update to the traffic manager hierarchy are supported by PMD.

The Soft NIC PMD also implements ethdev traffic metering and policing APIs in ‘rte_mtr.h’. These APIs enable metering and marking of packets with the appropriate color (green, yellow or red), according to the traffic metering algorithm. For the meter output color, policer actions including `keep the packet color same`, `change the packet color` or `drop the packet` can be configured.

Flow API Support in Soft NIC

The Soft NIC PMD implements the ethdev flow API ‘rte_flow.h’, which allows validating the flow rules, adding flow rules to the Soft NIC pipeline as table rules, and deleting and querying the flow rules. Actions such as JMP, QUEUE, RSS, DROP, COUNT, METER, and VXLAN are supported. The PMD provides new CLI command line options for creating the flow group and mapping it to the Soft NIC pipeline and table. This CLI should be configured as part of a firmware file.

flowapi map group <group_id> ingress | egress pipeline <pipeline_name> table <table_id>

Note: Here group id and ingress/egress value should be the same as the ones used in rte_flow rules to be added.

The flow API can be tested with the testpmd application. Once the application is initialized, the flow rules can be added through the testpmd CLI. The PMD will translate the flow rules to the Soft NIC pipeline table rules.

The example below demonstrates the flow queue action using the Soft NIC firmware and testpmd commands.

1. Prepare Soft NIC firmware

   link LINK0 dev 0000:02:00.0
   link LINK1 dev 0000:02:00.1
   pipeline RX period 10 offset_port_id 0
   pipeline RX port in bsz 32 link LINK0 rxq 0
   pipeline RX port in bsz 32 link LINK1 rxq 0
   pipeline RX port out bsz 32 swq RXQ0
   pipeline RX port out bsz 32 swq RXQ1
   table action profile AP0 ipv4 offset 278 fwd
   pipeline RX table match hash ext key 16 mask
                00FF0000FFFFFFFFFFFFFFFFFFFFFFFF
                offset 278 buckets 16K size 65K action AP0
   pipeline RX port in 0 table 0
   pipeline RX port in 1 table 0
   flowapi map group 0 ingress pipeline RX table 0
   pipeline TX period 10 offset_port_id 0
   pipeline TX port in bsz 32 swq TXQ0
   pipeline TX port in bsz 32 swq TXQ1
   pipeline TX port out bsz 32 link LINK0 txq 0
   pipeline TX port out bsz 32 link LINK1 txq 0
   pipeline TX table match hash ext key 16 mask
                00FF0000FFFFFFFFFFFFFFFFFFFFFFFF
                offset 278 buckets 16K size 65K action AP0
   pipeline TX port in 0 table 0
   pipeline TX port in 1 table 0
   pipeline TX table 0 rule add match hash ipv4_5tuple
                 1.10.11.12 2.20.21.22 100 200 6 action fwd port 0
    pipeline TX table 0 rule add match hash ipv4_5tuple
                 1.10.11.13 2.20.21.23 100 200 6 action fwd port 1
    thread 25 pipeline RX enable
    thread 25 pipeline TX enable

2. Run testpmd

   ./x86_64-native-linuxapp-gcc/app/testpmd -l 23-25  -n 4   --vdev 'net_softnic0, 
   firmware=./drivers/net/softnic/firmware.cli,  cpu_id=1,conn_port=8086' -- 
   -i --forward-mode=softnic --rxq=2,  --txq=2, --disable-rss --portmask=0x4

3. Configure flow rules on Soft NIC

   flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \
   mask 255.255.255.255 dst mask  255.255.255.255 src spec
   1.10.11.12 dst spec 2.20.21.22 proto spec 6 / tcp src mask 65535 \
   dst mask 65535 src spec 100 dst spec 200 / end actions queue \
   index 0 / end
   
   flow create 2 group 0 ingress pattern eth / ipv4 proto mask 255 src \
   mask 255.255.255.255 dst mask  255.255.255.255 src spec 1.10.11.13 \
   dst spec 2.20.21.23 proto spec 6 / tcp src mask 65535 dst mask \
   65535 src spec 100 dst spec 200 / end actions queue index 1 / end

Summary

In this article, you learned how to use Soft NIC to augment a hard NIC’s missing features and about various ethernet device APIs supported by Soft NIC. We covered:

• Soft NIC creation and configuration
• Configuration of Soft NIC firmware to build the RX and TX pipelines.
• Building and testing of Soft NIC.

Additional Information

• DPDK Programmer’s Guide: Soft NIC Poll Mode Driver
• DPDK Programmer’s Guide: Packet Framework
• DPDK Sample Applications Users Guide: Internet Protocol (IP) Pipeline Application
• YouTube*: DPDK Quality of Service APIs
• Presentation: Soft NIC: Build Your Own NIC in Software
• YouTube Soft NIC: Build Your Own NIC Pipeline in Software

For questions regarding usage, submit an email query.

About the Author

Reshma Pattan is a network software engineer at Intel Corporation. Her work primarily focuses on data plane library development for DPDK.