API: Setting up Receive Side Scaling (RSS)

The SmartNIC can distribute traffic to multiple queues using the Napatech hashing algorithm based on flow information. Use this DPDK API example to configure RSS.

RSS action in a flow rule

The rte_flow_action_rss structure is used to specify the RSS action in a flow rule as shown in this example.

/* Create group 1 flow to forward IPv4 packets to 4 queues using RSS. */
struct rte_flow_attr attr = { .group = 1, .ingress = 1 };

struct rte_flow_item pattern[] = {
  [0] = { .type = RTE_FLOW_ITEM_TYPE_IPV4 },
  [1] = { .type = RTE_FLOW_ITEM_TYPE_UDP },
  [2] = { .type = RTE_FLOW_ITEM_TYPE_END }};

uint16_t queues[] = {0, 1, 2, 3};
struct rte_flow_action_rss rss = {
  .func = RTE_ETH_HASH_FUNCTION_DEFAULT,
  .level = 1,
  .types = RTE_ETH_RSS_UDP,
  .key_len = 0,
  .queue_num = 4,
  .key = NULL,
  .queue = &queues };
struct rte_flow_action action[] = {
  [0] = { .type = RTE_FLOW_ACTION_TYPE_RSS, .conf = rss },
  [1] = { .type = RTE_FLOW_ACTION_TYPE_END }};

struct rte_flow_error error;
struct rte_flow *flow = rte_flow_create(PORT_ID, &attr, pattern, action, &error);
if (!flow) {
  /* Error handling */
}

This example illustrates how to set up RSS using the rte_flow_action_rss structure. The fields in the rte_flow_action_rss structure is configured as follows:

The queues are set to {0, 1, 2, 3}. This is an array of queue IDs to which the RSS hash result should be mapped.
The RSS hash result to four different queues.
The RSS hash function is set to RTE_ETH_HASH_FUNCTION_DEFAULT which is the default NTH10 hash algorithm.
The RSS hash type is set to RTE_ETH_RSS_UDP which indicates the UDP header fields in the frame should be used to compute the hash value. The IP and UDP header fields are used to generate the hash value. For definitions of macros for header fields, see rte_ethdev.h.
Level: 1 requests RSS to be performed on the outermost encapsulation level.
key is set to NULL, and key_len is set to 0.

Frames must contain the required protocol fields in order to be valid for the given hash function. It is therefore a good practice to add a pattern item to match the protocol fields used in the hash function.

For more information on the rte_flow_action_rss structure, see rte_flow_action_rss Struct Reference.

Note: A flow rule with group 0 must be created before the flow rule in this API example is created. This step has been omitted in this example for brevity.

Setting RSS on all ports

By default, the 5-tuple hash mode on the outer layer is configured on all ports. It is possible to configure RSS on all ports using the DPDK API rte_eth_dev_rss_hash_update with the rte_eth_rss_conf structure as follows.

#include <rte_ethdev.h>
#include <stdio.h>

uint16_t port_id = 0;
struct rte_eth_rss_conf rss_conf;
memset(&rss_conf, 0, sizeof(rss_conf));
rss_conf.rss_key = NULL;
rss_conf.rss_key_len = 0;
// Destination IP address is used to generate hash values
rss_conf.rss_hf = RTE_ETH_RSS_LEVEL_OUTERMOST | RTE_ETH_RSS_L3_DST_ONLY | RTE_ETH_RSS_IP;

int ret = rte_eth_dev_rss_hash_update(port_id, &rss_conf);
if (ret < 0) {
    printf("Failed to update RSS hash function: %s\n", rte_strerror(ret));
    return ret;
}

rss_hf is a bit field that specifies the hash mode to be used. In this example, the destination IPv4 or IPv6 address of the outermost layer is used as a hash key. rss_key is to NULL, and rss_key_len is set to 0.