10. IPv4 Multicast Sample Application

The IPv4 Multicast application is a simple example of packet processing using the Data Plane Development Kit (DPDK). The application performs L3 multicasting.

10.1. Overview

The application demonstrates the use of zero-copy buffers for packet forwarding. The initialization and run-time paths are very similar to those of the L2 Forwarding Sample Application (in Real and Virtualized Environments). This guide highlights the differences between the two applications. There are two key differences from the L2 Forwarding sample application:

  • The IPv4 Multicast sample application makes use of indirect buffers.

  • The forwarding decision is taken based on information read from the input packet’s IPv4 header.

The lookup method is the Four-byte Key (FBK) hash-based method. The lookup table is composed of pairs of destination IPv4 addresses (the FBK) and a port mask associated with that IPv4 address. By default, the following IP addresses and their respective port masks are added:

		{RTE_IPV4(224,0,0,101), 0x1},
		{RTE_IPV4(224,0,0,102), 0x2},
		{RTE_IPV4(224,0,0,103), 0x3},
		{RTE_IPV4(224,0,0,104), 0x4},
		{RTE_IPV4(224,0,0,105), 0x5},
		{RTE_IPV4(224,0,0,106), 0x6},
		{RTE_IPV4(224,0,0,107), 0x7},
		{RTE_IPV4(224,0,0,108), 0x8},
		{RTE_IPV4(224,0,0,109), 0x9},
		{RTE_IPV4(224,0,0,110), 0xA},
		{RTE_IPV4(224,0,0,111), 0xB},
		{RTE_IPV4(224,0,0,112), 0xC},
		{RTE_IPV4(224,0,0,113), 0xD},
		{RTE_IPV4(224,0,0,114), 0xE},
		{RTE_IPV4(224,0,0,115), 0xF},

Note

The max port mask supported in the given hash table is 0xf, so only first four ports can be supported. If using non-consecutive ports, use the destination IPv4 address accordingly.

For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account, but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address) with the mask of ports to multicast packets.

Also, the application does not consider the Ethernet addresses; it looks only at the IPv4 destination address for any given packet.

10.2. Compiling the Application

To compile the sample application, see Compiling the Sample Applications.

The application is located in the ipv4_multicast sub-directory.

10.3. Running the Application

The application has a number of command line options:

./<build_dir>/examples/dpdk-ipv4_multicast [EAL options] -- -p PORTMASK [-q NQ]

where,

  • -p PORTMASK: Hexadecimal bitmask of ports to configure

  • -q NQ: determines the number of queues per lcore

Note

Unlike the basic L2/L3 Forwarding sample applications, NUMA support is not provided in the IPv4 Multicast sample application.

Typically, to run the IPv4 Multicast sample application, issue the following command (as root):

./<build_dir>/examples/dpdk-ipv4_multicast -l 0-3 -n 3 -- -p 0x3 -q 1

In this command:

  • The -l option enables cores 0, 1, 2 and 3

  • The -n option specifies 3 memory channels

  • The -p option enables ports 0 and 1

  • The -q option assigns 1 queue to each lcore

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

10.4. Explanation

The following sections provide some explanation of the code. As mentioned in the overview section, the initialization and run-time paths are very similar to those of the L2 Forwarding Sample Application (in Real and Virtualized Environments). The following sections describe aspects that are specific to the IPv4 Multicast sample application.

10.4.1. Memory Pool Initialization

The IPv4 Multicast sample application uses three memory pools. Two of the pools are for indirect buffers used for packet duplication purposes. Memory pools for indirect buffers are initialized differently from the memory pool for direct buffers:

packet_pool = rte_pktmbuf_pool_create("packet_pool", NB_PKT_MBUF, 32,
	0, PKT_MBUF_DATA_SIZE, rte_socket_id());

if (packet_pool == NULL)
	rte_exit(EXIT_FAILURE, "Cannot init packet mbuf pool\n");

header_pool = rte_pktmbuf_pool_create("header_pool", NB_HDR_MBUF, 32,
	0, HDR_MBUF_DATA_SIZE, rte_socket_id());

if (header_pool == NULL)
	rte_exit(EXIT_FAILURE, "Cannot init header mbuf pool\n");

clone_pool = rte_pktmbuf_pool_create("clone_pool", NB_CLONE_MBUF, 32,
	0, 0, rte_socket_id());

if (clone_pool == NULL)
	rte_exit(EXIT_FAILURE, "Cannot init clone mbuf pool\n");

The reason for this is that indirect buffers are not supposed to hold any packet data and therefore can be initialized with the lower amount of reserved memory for each buffer.

10.4.2. Hash Initialization

The hash object is created and loaded with the pre-configured entries read from a global array:

static int
init_mcast_hash(void)
{
	uint32_t i;

	mcast_hash_params.socket_id = rte_socket_id();
	mcast_hash = rte_fbk_hash_create(&mcast_hash_params);
	if (mcast_hash == NULL){
		return -1;
	}

	for (i = 0; i < RTE_DIM(mcast_group_table); i++) {
		if (rte_fbk_hash_add_key(mcast_hash,
			mcast_group_table[i].ip,
			mcast_group_table[i].port_mask) < 0) {
			return -1;
		}
	}

	return 0;
}

10.4.3. Forwarding

All forwarding is done inside the mcast_forward() function. Firstly, the Ethernet* header is removed from the packet and the IPv4 address is extracted from the IPv4 header:

iphdr = (struct rte_ipv4_hdr *)
	rte_pktmbuf_adj(m, (uint16_t)sizeof(struct rte_ether_hdr));
RTE_ASSERT(iphdr != NULL);

dest_addr = rte_be_to_cpu_32(iphdr->dst_addr);

Then, the packet is checked to see if it has a multicast destination address and if the routing table has any ports assigned to the destination address:

if (!RTE_IS_IPV4_MCAST(dest_addr) ||
    (hash = rte_fbk_hash_lookup(mcast_hash, dest_addr)) <= 0 ||
    (port_mask = hash & enabled_port_mask) == 0) {
	rte_pktmbuf_free(m);
	return;
}

Next, the number of ports in the destination portmask is calculated with the help of the bitcnt() function:

static inline uint32_t
bitcnt(uint32_t v)
{
	uint32_t n;

	for (n = 0; v != 0; v &= v - 1, n++)
		;

	return n;
}

This is done to determine which forwarding algorithm to use. This is explained in more detail in the next section.

Thereafter, a destination Ethernet address is constructed:

dst_eth_addr.as_int = ETHER_ADDR_FOR_IPV4_MCAST(dest_addr);

Since Ethernet addresses are also part of the multicast process, each outgoing packet carries the same destination Ethernet address. The destination Ethernet address is constructed from the lower 23 bits of the multicast group OR-ed with the Ethernet address 01:00:5e:00:00:00, as per RFC 1112:

#define	ETHER_ADDR_FOR_IPV4_MCAST(x)	\
	(rte_cpu_to_be_64(0x01005e000000ULL | ((x) & 0x7fffff)) >> 16)

Packets are then dispatched to the destination ports according to the portmask associated with a multicast group:

for (port = 0; use_clone != port_mask; port_mask >>= 1, port++) {

	/* Prepare output packet and send it out. */
	if ((port_mask & 1) != 0) {
		if (likely ((mc = mcast_out_pkt(m, use_clone)) != NULL))
			mcast_send_pkt(mc, &dst_eth_addr.as_addr,
					qconf, port);
		else if (use_clone == 0)
			rte_pktmbuf_free(m);
	}
}

The actual packet transmission is done in the mcast_send_pkt() function:

static inline void
mcast_send_pkt(struct rte_mbuf *pkt, struct rte_ether_addr *dest_addr,
		struct lcore_queue_conf *qconf, uint16_t port)
{
	struct rte_ether_hdr *ethdr;
	uint16_t len;

	/* Construct Ethernet header. */
	ethdr = (struct rte_ether_hdr *)
		rte_pktmbuf_prepend(pkt, (uint16_t)sizeof(*ethdr));
	RTE_ASSERT(ethdr != NULL);

	rte_ether_addr_copy(dest_addr, &ethdr->dst_addr);
	rte_ether_addr_copy(&ports_eth_addr[port], &ethdr->src_addr);
	ethdr->ether_type = rte_be_to_cpu_16(RTE_ETHER_TYPE_IPV4);

	/* Put new packet into the output queue */
	len = qconf->tx_mbufs[port].len;
	qconf->tx_mbufs[port].m_table[len] = pkt;
	qconf->tx_mbufs[port].len = ++len;

	/* Transmit packets */
	if (unlikely(MAX_PKT_BURST == len))
		send_burst(qconf, port);
}

10.4.4. Buffer Cloning

This is the most important part of the application since it demonstrates the use of zero-copy buffer cloning. There are two approaches for creating the outgoing packet. Although both are based on the data zero-copy idea, there are some differences in the details.

The first approach creates a clone of the input packet. For example, walk though all segments of the input packet and for each of segment, create a new buffer and attach that new buffer to the segment (refer to rte_pktmbuf_clone() in the mbuf library for more details). A new buffer is then allocated for the packet header and is prepended to the cloned buffer.

The second approach does not make a clone. It simply increments the reference counter for all input packet segments, allocates a new buffer for the packet header and prepends it to the input packet.

Basically, the first approach reuses only the input packet’s data, but creates its own copy of packet’s metadata. The second approach reuses both input packet’s data and metadata.

The advantage of the first approach is that each outgoing packet has its own copy of the metadata, so we can safely modify the data pointer of the input packet. That allows us to skip creation if the output packet is for the last destination port and, instead, modify the input packet’s header in place. For example, for N destination ports, we need to invoke mcast_out_pkt() (N-1) times.

The advantage of the second approach is that there is less work to be done for each outgoing packet. The “clone” operation is skipped completely. However, there is a price to pay. The input packet’s metadata must remain intact. For N destination ports, we need to invoke mcast_out_pkt() (N) times.

Therefore, for a small number of outgoing ports (and segments in the input packet), the first approach is faster. As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable.

Depending on the number of segments or the number of ports in the outgoing portmask, either the first (with cloning) or the second (without cloning) approach is taken:

use_clone = (port_num <= MCAST_CLONE_PORTS &&
    m->nb_segs <= MCAST_CLONE_SEGS);

It is the mcast_out_pkt() function that performs the packet duplication (either with or without actually cloning the buffers):

static inline struct rte_mbuf *
mcast_out_pkt(struct rte_mbuf *pkt, int use_clone)
{
	struct rte_mbuf *hdr;

	/* Create new mbuf for the header. */
	if (unlikely ((hdr = rte_pktmbuf_alloc(header_pool)) == NULL))
		return NULL;

	/* If requested, then make a new clone packet. */
	if (use_clone != 0 &&
	    unlikely ((pkt = rte_pktmbuf_clone(pkt, clone_pool)) == NULL)) {
		rte_pktmbuf_free(hdr);
		return NULL;
	}

	/* prepend new header */
	hdr->next = pkt;

	/* update header's fields */
	hdr->pkt_len = (uint16_t)(hdr->data_len + pkt->pkt_len);
	hdr->nb_segs = pkt->nb_segs + 1;

	__rte_mbuf_sanity_check(hdr, 1);
	return hdr;
}