9. Basic RTE Flow Filtering Sample Application

The Basic RTE flow filtering sample application is a simple example of a creating a RTE flow rule.

It is intended as a demonstration of the basic components RTE flow rules.

9.1. Compiling the Application

To compile the sample application see Compiling the Sample Applications.

9.2. Running the Application

To run the example in a linux environment:

./<build_dir>/examples/dpdk-flow_filtering -l 1 -n 1

Refer to DPDK Getting Started Guide for general information on running applications and the Environment Abstraction Layer (EAL) options.

9.3. Explanation

The example is built from 2 files, main.c which holds the example logic and flow_blocks.c that holds the implementation for building the flow rule.

The following sections provide an explanation of the main components of the code.

All DPDK library functions used in the sample code are prefixed with rte_ and are explained in detail in the DPDK API Documentation.

9.3.1. The Main Function

The main() function located in main.c file performs the initialization and runs the main loop function.

The first task is to initialize the Environment Abstraction Layer (EAL). The argc and argv arguments are provided to the rte_eal_init() function. The value returned is the number of parsed arguments:

ret = rte_eal_init(argc, argv);
if (ret < 0)
	rte_exit(EXIT_FAILURE, ":: invalid EAL arguments\n");

The main() also allocates a mempool to hold the mbufs (Message Buffers) used by the application:

mbuf_pool = rte_pktmbuf_pool_create("mbuf_pool", 4096, 128, 0,
				    RTE_MBUF_DEFAULT_BUF_SIZE,
				    rte_socket_id());

Mbufs are the packet buffer structure used by DPDK. They are explained in detail in the “Mbuf Library” section of the DPDK Programmer’s Guide.

The main() function also initializes all the ports using the user defined init_port() function which is explained in the next section:

init_port();

Once the initialization is complete, we set the flow rule using the following code:

flow = generate_ipv4_flow(port_id, selected_queue,
			SRC_IP, EMPTY_MASK,
			DEST_IP, FULL_MASK, &error);
/* >8 End of create flow and the flow rule. */
if (!flow) {
	printf("Flow can't be created %d message: %s\n",
		error.type,
		error.message ? error.message : "(no stated reason)");
	rte_exit(EXIT_FAILURE, "error in creating flow");
}

In the last part the application is ready to launch the main_loop() function. Which is explained below.

ret = main_loop();

9.3.2. The Port Initialization Function

The main functional part of the port initialization used in the flow filtering application is shown below:

static void
init_port(void)
{
	int ret;
	uint16_t i;
	/* Ethernet port configured with default settings. 8< */
	struct rte_eth_conf port_conf = {
		.rxmode = {
			.split_hdr_size = 0,
		},
		.txmode = {
			.offloads =
				DEV_TX_OFFLOAD_VLAN_INSERT |
				DEV_TX_OFFLOAD_IPV4_CKSUM  |
				DEV_TX_OFFLOAD_UDP_CKSUM   |
				DEV_TX_OFFLOAD_TCP_CKSUM   |
				DEV_TX_OFFLOAD_SCTP_CKSUM  |
				DEV_TX_OFFLOAD_TCP_TSO,
		},
	};
	struct rte_eth_txconf txq_conf;
	struct rte_eth_rxconf rxq_conf;
	struct rte_eth_dev_info dev_info;

	ret = rte_eth_dev_info_get(port_id, &dev_info);
	if (ret != 0)
		rte_exit(EXIT_FAILURE,
			"Error during getting device (port %u) info: %s\n",
			port_id, strerror(-ret));

	port_conf.txmode.offloads &= dev_info.tx_offload_capa;
	printf(":: initializing port: %d\n", port_id);
	ret = rte_eth_dev_configure(port_id,
				nr_queues, nr_queues, &port_conf);
	if (ret < 0) {
		rte_exit(EXIT_FAILURE,
			":: cannot configure device: err=%d, port=%u\n",
			ret, port_id);
	}

	rxq_conf = dev_info.default_rxconf;
	rxq_conf.offloads = port_conf.rxmode.offloads;
	/* >8 End of ethernet port configured with default settings. */

	/* Configuring number of RX and TX queues connected to single port. 8< */
	for (i = 0; i < nr_queues; i++) {
		ret = rte_eth_rx_queue_setup(port_id, i, 512,
				     rte_eth_dev_socket_id(port_id),
				     &rxq_conf,
				     mbuf_pool);
		if (ret < 0) {
			rte_exit(EXIT_FAILURE,
				":: Rx queue setup failed: err=%d, port=%u\n",
				ret, port_id);
		}
	}

	txq_conf = dev_info.default_txconf;
	txq_conf.offloads = port_conf.txmode.offloads;

	for (i = 0; i < nr_queues; i++) {
		ret = rte_eth_tx_queue_setup(port_id, i, 512,
				rte_eth_dev_socket_id(port_id),
				&txq_conf);
		if (ret < 0) {
			rte_exit(EXIT_FAILURE,
				":: Tx queue setup failed: err=%d, port=%u\n",
				ret, port_id);
		}
	}
	/* >8 End of Configuring RX and TX queues connected to single port. */

	/* Setting the RX port to promiscuous mode. 8< */
	ret = rte_eth_promiscuous_enable(port_id);
	if (ret != 0)
		rte_exit(EXIT_FAILURE,
			":: promiscuous mode enable failed: err=%s, port=%u\n",
			rte_strerror(-ret), port_id);
	/* >8 End of setting the RX port to promiscuous mode. */

	/* Starting the port. 8< */
	ret = rte_eth_dev_start(port_id);
	if (ret < 0) {
		rte_exit(EXIT_FAILURE,
			"rte_eth_dev_start:err=%d, port=%u\n",
			ret, port_id);
	}
	/* >8 End of starting the port. */

	assert_link_status();

	printf(":: initializing port: %d done\n", port_id);
}

The Ethernet port is configured with default settings using the rte_eth_dev_configure() function and the port_conf_default struct:

struct rte_eth_conf port_conf = {
	.rxmode = {
		.split_hdr_size = 0,
	},
	.txmode = {
		.offloads =
			DEV_TX_OFFLOAD_VLAN_INSERT |
			DEV_TX_OFFLOAD_IPV4_CKSUM  |
			DEV_TX_OFFLOAD_UDP_CKSUM   |
			DEV_TX_OFFLOAD_TCP_CKSUM   |
			DEV_TX_OFFLOAD_SCTP_CKSUM  |
			DEV_TX_OFFLOAD_TCP_TSO,
	},
};
struct rte_eth_txconf txq_conf;
struct rte_eth_rxconf rxq_conf;
struct rte_eth_dev_info dev_info;

ret = rte_eth_dev_info_get(port_id, &dev_info);
if (ret != 0)
	rte_exit(EXIT_FAILURE,
		"Error during getting device (port %u) info: %s\n",
		port_id, strerror(-ret));

port_conf.txmode.offloads &= dev_info.tx_offload_capa;
printf(":: initializing port: %d\n", port_id);
ret = rte_eth_dev_configure(port_id,
			nr_queues, nr_queues, &port_conf);
if (ret < 0) {
	rte_exit(EXIT_FAILURE,
		":: cannot configure device: err=%d, port=%u\n",
		ret, port_id);
}

rxq_conf = dev_info.default_rxconf;
rxq_conf.offloads = port_conf.rxmode.offloads;

For this example we are configuring number of rx and tx queues that are connected to a single port.

for (i = 0; i < nr_queues; i++) {
	ret = rte_eth_rx_queue_setup(port_id, i, 512,
			     rte_eth_dev_socket_id(port_id),
			     &rxq_conf,
			     mbuf_pool);
	if (ret < 0) {
		rte_exit(EXIT_FAILURE,
			":: Rx queue setup failed: err=%d, port=%u\n",
			ret, port_id);
	}
}

txq_conf = dev_info.default_txconf;
txq_conf.offloads = port_conf.txmode.offloads;

for (i = 0; i < nr_queues; i++) {
	ret = rte_eth_tx_queue_setup(port_id, i, 512,
			rte_eth_dev_socket_id(port_id),
			&txq_conf);
	if (ret < 0) {
		rte_exit(EXIT_FAILURE,
			":: Tx queue setup failed: err=%d, port=%u\n",
			ret, port_id);
	}
}

In the next step we create and apply the flow rule. which is to send packets with destination ip equals to 192.168.1.1 to queue number 1. The detail explanation of the generate_ipv4_flow() appears later in this document:

flow = generate_ipv4_flow(port_id, selected_queue,
			SRC_IP, EMPTY_MASK,
			DEST_IP, FULL_MASK, &error);

We are setting the RX port to promiscuous mode:

ret = rte_eth_promiscuous_enable(port_id);
if (ret != 0)
	rte_exit(EXIT_FAILURE,
		":: promiscuous mode enable failed: err=%s, port=%u\n",
		rte_strerror(-ret), port_id);

The last step is to start the port.

ret = rte_eth_dev_start(port_id);
if (ret < 0) {
	rte_exit(EXIT_FAILURE,
		"rte_eth_dev_start:err=%d, port=%u\n",
		ret, port_id);
}

9.3.3. The main_loop function

As we saw above the main() function calls an application function to handle the main loop. For the flow filtering application the main_loop function looks like the following:

static int
main_loop(void)
{
	struct rte_mbuf *mbufs[32];
	struct rte_ether_hdr *eth_hdr;
	struct rte_flow_error error;
	uint16_t nb_rx;
	uint16_t i;
	uint16_t j;
	int ret;

	/* Reading the packets from all queues. 8< */
	while (!force_quit) {
		for (i = 0; i < nr_queues; i++) {
			nb_rx = rte_eth_rx_burst(port_id,
						i, mbufs, 32);
			if (nb_rx) {
				for (j = 0; j < nb_rx; j++) {
					struct rte_mbuf *m = mbufs[j];

					eth_hdr = rte_pktmbuf_mtod(m,
							struct rte_ether_hdr *);
					print_ether_addr("src=",
							&eth_hdr->s_addr);
					print_ether_addr(" - dst=",
							&eth_hdr->d_addr);
					printf(" - queue=0x%x",
							(unsigned int)i);
					printf("\n");

					rte_pktmbuf_free(m);
				}
			}
		}
	}

The main work of the application is reading the packets from all queues and printing for each packet the destination queue:

	while (!force_quit) {
		for (i = 0; i < nr_queues; i++) {
			nb_rx = rte_eth_rx_burst(port_id,
						i, mbufs, 32);
			if (nb_rx) {
				for (j = 0; j < nb_rx; j++) {
					struct rte_mbuf *m = mbufs[j];

					eth_hdr = rte_pktmbuf_mtod(m,
							struct rte_ether_hdr *);
					print_ether_addr("src=",
							&eth_hdr->s_addr);
					print_ether_addr(" - dst=",
							&eth_hdr->d_addr);
					printf(" - queue=0x%x",
							(unsigned int)i);
					printf("\n");

					rte_pktmbuf_free(m);
				}
			}
		}
	}
	/* >8 End of reading the packets from all queues. */

	/* closing and releasing resources */
	rte_flow_flush(port_id, &error);
	ret = rte_eth_dev_stop(port_id);
	if (ret < 0)
		printf("Failed to stop port %u: %s",
		       port_id, rte_strerror(-ret));
	rte_eth_dev_close(port_id);
	return ret;
}

The forwarding loop can be interrupted and the application closed using Ctrl-C. Which results in closing the port and the device using rte_eth_dev_stop and rte_eth_dev_close

9.3.4. The generate_ipv4_flow function

The generate_ipv4_flow function is responsible for creating the flow rule. This function is located in the flow_blocks.c file.

struct rte_flow *
generate_ipv4_flow(uint16_t port_id, uint16_t rx_q,
		uint32_t src_ip, uint32_t src_mask,
		uint32_t dest_ip, uint32_t dest_mask,
		struct rte_flow_error *error)
{
	/* Declaring structs being used. 8< */
	struct rte_flow_attr attr;
	struct rte_flow_item pattern[MAX_PATTERN_NUM];
	struct rte_flow_action action[MAX_ACTION_NUM];
	struct rte_flow *flow = NULL;
	struct rte_flow_action_queue queue = { .index = rx_q };
	struct rte_flow_item_ipv4 ip_spec;
	struct rte_flow_item_ipv4 ip_mask;
	/* >8 End of declaring structs being used. */
	int res;

	memset(pattern, 0, sizeof(pattern));
	memset(action, 0, sizeof(action));

	/* Set the rule attribute, only ingress packets will be checked. 8< */
	memset(&attr, 0, sizeof(struct rte_flow_attr));
	attr.ingress = 1;
	/* >8 End of setting the rule attribute. */

	/*
	 * create the action sequence.
	 * one action only,  move packet to queue
	 */
	action[0].type = RTE_FLOW_ACTION_TYPE_QUEUE;
	action[0].conf = &queue;
	action[1].type = RTE_FLOW_ACTION_TYPE_END;

	/*
	 * set the first level of the pattern (ETH).
	 * since in this example we just want to get the
	 * ipv4 we set this level to allow all.
	 */

	/* IPv4 we set this level to allow all. 8< */
	pattern[0].type = RTE_FLOW_ITEM_TYPE_ETH;
	/* >8 End of setting the first level of the pattern. */

	/*
	 * setting the second level of the pattern (IP).
	 * in this example this is the level we care about
	 * so we set it according to the parameters.
	 */

	/* Setting the second level of the pattern. 8< */
	memset(&ip_spec, 0, sizeof(struct rte_flow_item_ipv4));
	memset(&ip_mask, 0, sizeof(struct rte_flow_item_ipv4));
	ip_spec.hdr.dst_addr = htonl(dest_ip);
	ip_mask.hdr.dst_addr = dest_mask;
	ip_spec.hdr.src_addr = htonl(src_ip);
	ip_mask.hdr.src_addr = src_mask;
	pattern[1].type = RTE_FLOW_ITEM_TYPE_IPV4;
	pattern[1].spec = &ip_spec;
	pattern[1].mask = &ip_mask;
	/* >8 End of setting the second level of the pattern. */

	/* The final level must be always type end. 8< */
	pattern[2].type = RTE_FLOW_ITEM_TYPE_END;
	/* >8 End of final level must be always type end. */

	/* Validate the rule and create it. 8< */
	res = rte_flow_validate(port_id, &attr, pattern, action, error);
	if (!res)
		flow = rte_flow_create(port_id, &attr, pattern, action, error);
	/* >8 End of validation the rule and create it. */

	return flow;
}

The first part of the function is declaring the structures that will be used.

struct rte_flow_attr attr;
struct rte_flow_item pattern[MAX_PATTERN_NUM];
struct rte_flow_action action[MAX_ACTION_NUM];
struct rte_flow *flow = NULL;
struct rte_flow_action_queue queue = { .index = rx_q };
struct rte_flow_item_ipv4 ip_spec;
struct rte_flow_item_ipv4 ip_mask;

The following part create the flow attributes, in our case ingress.

memset(&attr, 0, sizeof(struct rte_flow_attr));
attr.ingress = 1;

The third part defines the action to be taken when a packet matches the rule. In this case send the packet to queue.

struct rte_flow *
generate_ipv4_flow(uint16_t port_id, uint16_t rx_q,
		uint32_t src_ip, uint32_t src_mask,
		uint32_t dest_ip, uint32_t dest_mask,
		struct rte_flow_error *error)
{
	/* Declaring structs being used. 8< */
	struct rte_flow_attr attr;
	struct rte_flow_item pattern[MAX_PATTERN_NUM];
	struct rte_flow_action action[MAX_ACTION_NUM];
	struct rte_flow *flow = NULL;
	struct rte_flow_action_queue queue = { .index = rx_q };
	struct rte_flow_item_ipv4 ip_spec;
	struct rte_flow_item_ipv4 ip_mask;
	/* >8 End of declaring structs being used. */
	int res;

	memset(pattern, 0, sizeof(pattern));
	memset(action, 0, sizeof(action));

	/* Set the rule attribute, only ingress packets will be checked. 8< */
	memset(&attr, 0, sizeof(struct rte_flow_attr));
	attr.ingress = 1;

The fourth part is responsible for creating the pattern and is built from number of steps. In each step we build one level of the pattern starting with the lowest one.

Setting the first level of the pattern ETH:

pattern[0].type = RTE_FLOW_ITEM_TYPE_ETH;

Setting the second level of the pattern IP:

memset(&ip_spec, 0, sizeof(struct rte_flow_item_ipv4));
memset(&ip_mask, 0, sizeof(struct rte_flow_item_ipv4));
ip_spec.hdr.dst_addr = htonl(dest_ip);
ip_mask.hdr.dst_addr = dest_mask;
ip_spec.hdr.src_addr = htonl(src_ip);
ip_mask.hdr.src_addr = src_mask;
pattern[1].type = RTE_FLOW_ITEM_TYPE_IPV4;
pattern[1].spec = &ip_spec;
pattern[1].mask = &ip_mask;

Closing the pattern part.

pattern[2].type = RTE_FLOW_ITEM_TYPE_END;

The last part of the function is to validate the rule and create it.

res = rte_flow_validate(port_id, &attr, pattern, action, error);
if (!res)
	flow = rte_flow_create(port_id, &attr, pattern, action, error);