1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4IPv4 Multicast Sample Application 5================================= 6 7The IPv4 Multicast application is a simple example of packet processing 8using the Data Plane Development Kit (DPDK). 9The application performs L3 multicasting. 10 11Overview 12-------- 13 14The application demonstrates the use of zero-copy buffers for packet forwarding. 15The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`. 16This guide highlights the differences between the two applications. 17There are two key differences from the L2 Forwarding sample application: 18 19* The IPv4 Multicast sample application makes use of indirect buffers. 20 21* The forwarding decision is taken based on information read from the input packet's IPv4 header. 22 23The lookup method is the Four-byte Key (FBK) hash-based method. 24The lookup table is composed of pairs of destination IPv4 addresses (the FBK) 25and a port mask associated with that IPv4 address. 26By default, the following IP addresses and their respective port masks are added: 27 28.. literalinclude:: ../../../examples/ipv4_multicast/main.c 29 :language: c 30 :start-after: mcast_group_table 31 :end-before: }; 32 33.. note:: 34 35 The max port mask supported in the given hash table is 0xf, so only first 36 four ports can be supported. 37 If using non-consecutive ports, use the destination IPv4 address accordingly. 38 39For convenience and simplicity, this sample application does not take IANA-assigned multicast addresses into account, 40but instead equates the last four bytes of the multicast group (that is, the last four bytes of the destination IP address) 41with the mask of ports to multicast packets. 42 43Also, the application does not consider the Ethernet addresses; 44it looks only at the IPv4 destination address for any given packet. 45 46Compiling the Application 47------------------------- 48 49To compile the sample application, see :doc:`compiling`. 50 51The application is located in the ``ipv4_multicast`` sub-directory. 52 53Running the Application 54----------------------- 55 56The application has a number of command line options: 57 58.. code-block:: console 59 60 ./<build_dir>/examples/dpdk-ipv4_multicast [EAL options] -- -p PORTMASK [-q NQ] 61 62where, 63 64* -p PORTMASK: Hexadecimal bitmask of ports to configure 65 66* -q NQ: determines the number of queues per lcore 67 68.. note:: 69 70 Unlike the basic L2/L3 Forwarding sample applications, 71 NUMA support is not provided in the IPv4 Multicast sample application. 72 73Typically, to run the IPv4 Multicast sample application, issue the following command (as root): 74 75.. code-block:: console 76 77 ./<build_dir>/examples/dpdk-ipv4_multicast -l 0-3 -n 3 -- -p 0x3 -q 1 78 79In this command: 80 81* The -l option enables cores 0, 1, 2 and 3 82 83* The -n option specifies 3 memory channels 84 85* The -p option enables ports 0 and 1 86 87* The -q option assigns 1 queue to each lcore 88 89Refer to the *DPDK Getting Started Guide* for general information on running applications 90and the Environment Abstraction Layer (EAL) options. 91 92Explanation 93----------- 94 95The following sections provide some explanation of the code. 96As mentioned in the overview section, 97the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`. 98The following sections describe aspects that are specific to the IPv4 Multicast sample application. 99 100Memory Pool Initialization 101~~~~~~~~~~~~~~~~~~~~~~~~~~ 102 103The IPv4 Multicast sample application uses three memory pools. 104Two of the pools are for indirect buffers used for packet duplication purposes. 105Memory pools for indirect buffers are initialized differently from the memory pool for direct buffers: 106 107.. literalinclude:: ../../../examples/ipv4_multicast/main.c 108 :language: c 109 :start-after: Create the mbuf pools. 8< 110 :end-before: >8 End of create mbuf pools. 111 :dedent: 1 112 113The reason for this is that indirect buffers are not supposed to hold any packet data and 114therefore can be initialized with the lower amount of reserved memory for each buffer. 115 116Hash Initialization 117~~~~~~~~~~~~~~~~~~~ 118 119The hash object is created and loaded with the pre-configured entries read from a global array: 120 121.. literalinclude:: ../../../examples/ipv4_multicast/main.c 122 :language: c 123 :start-after: Hash object is created and loaded. 8< 124 :end-before: >8 End of hash object is created and loaded. 125 126Forwarding 127~~~~~~~~~~ 128 129All forwarding is done inside the ``mcast_forward()`` function. 130Firstly, the Ethernet* header is removed from the packet and the IPv4 address is extracted from the IPv4 header: 131 132.. literalinclude:: ../../../examples/ipv4_multicast/main.c 133 :language: c 134 :start-after: Remove the Ethernet header from the input packet. 8< 135 :end-before: >8 End of removing the Ethernet header from the input packet. 136 :dedent: 1 137 138Then, the packet is checked to see if it has a multicast destination address and 139if the routing table has any ports assigned to the destination address: 140 141.. literalinclude:: ../../../examples/ipv4_multicast/main.c 142 :language: c 143 :start-after: Check valid multicast address. 8< 144 :end-before: >8 End of valid multicast address check. 145 :dedent: 1 146 147Next, the number of ports in the destination portmask 148is calculated with the help of the ``bitcnt()`` function: 149 150.. literalinclude:: ../../../examples/ipv4_multicast/main.c 151 :language: c 152 :start-after: Get number of bits set. 8< 153 :end-before: >8 End of getting number of bits set. 154 155This is done to determine which forwarding algorithm to use. 156This is explained in more detail in the next section. 157 158Thereafter, a destination Ethernet address is constructed: 159 160.. literalinclude:: ../../../examples/ipv4_multicast/main.c 161 :language: c 162 :start-after: Construct destination ethernet address. 8< 163 :end-before: >8 End of constructing destination ethernet address. 164 :dedent: 1 165 166Since Ethernet addresses are also part of the multicast process, each outgoing packet carries the same destination Ethernet address. 167The destination Ethernet address is constructed from the lower 23 bits of the multicast group OR-ed 168with the Ethernet address 01:00:5e:00:00:00, as per RFC 1112: 169 170.. literalinclude:: ../../../examples/ipv4_multicast/main.c 171 :language: c 172 :start-after: Construct Ethernet multicast address from IPv4 multicast Address. 8< 173 :end-before: >8 End of Construction of multicast address from IPv4 multicast address. 174 175Packets are then dispatched to the destination ports according to the portmask associated with a multicast group: 176 177.. literalinclude:: ../../../examples/ipv4_multicast/main.c 178 :language: c 179 :start-after: Packets dispatched to destination ports. 8< 180 :end-before: >8 End of packets dispatched to destination ports. 181 :dedent: 1 182 183The actual packet transmission is done in the ``mcast_send_pkt()`` function: 184 185.. literalinclude:: ../../../examples/ipv4_multicast/main.c 186 :language: c 187 :start-after: Write new Ethernet header to outgoing packets. 8< 188 :end-before: >8 End of writing new Ethernet headers. 189 190Buffer Cloning 191~~~~~~~~~~~~~~ 192 193This is the most important part of the application 194since it demonstrates the use of zero-copy buffer cloning. 195There are two approaches for creating the outgoing packet. 196Although both are based on the data zero-copy idea, 197there are some differences in the details. 198 199The first approach creates a clone of the input packet. For example, 200walk though all segments of the input packet and for each of segment, 201create a new buffer and attach that new buffer to the segment 202(refer to ``rte_pktmbuf_clone()`` in the mbuf library for more details). 203A new buffer is then allocated for the packet header and is prepended to the cloned buffer. 204 205The second approach does not make a clone. 206It simply increments the reference counter for all input packet segments, 207allocates a new buffer for the packet header and prepends it to the input packet. 208 209Basically, the first approach reuses only the input packet's data, but creates its own copy of packet's metadata. 210The second approach reuses both input packet's data and metadata. 211 212The advantage of the first approach is that each outgoing packet has its own copy of the metadata, 213so we can safely modify the data pointer of the input packet. 214That allows us to skip creation if the output packet is for the last destination port 215and, instead, modify the input packet's header in place. 216For example, for N destination ports, we need to invoke ``mcast_out_pkt()`` (N-1) times. 217 218The advantage of the second approach is that there is less work to be done for each outgoing packet. 219The "clone" operation is skipped completely. 220However, there is a price to pay. 221The input packet's metadata must remain intact. For N destination ports, 222we need to invoke ``mcast_out_pkt()`` (N) times. 223 224Therefore, for a small number of outgoing ports (and segments in the input packet), 225the first approach is faster. 226As the number of outgoing ports (and/or input segments) grows, the second approach becomes more preferable. 227 228Depending on the number of segments or the number of ports in the outgoing portmask, 229either the first (with cloning) or the second (without cloning) approach is taken: 230 231.. literalinclude:: ../../../examples/ipv4_multicast/main.c 232 :language: c 233 :start-after: Should we use rte_pktmbuf_clone() or not. 8< 234 :end-before: >8 End of using rte_pktmbuf_clone(). 235 :dedent: 1 236 237It is the ``mcast_out_pkt()`` function that performs the packet duplication 238(either with or without actually cloning the buffers): 239 240.. literalinclude:: ../../../examples/ipv4_multicast/main.c 241 :language: c 242 :start-after: mcast_out_pkt 8< 243 :end-before: >8 End of mcast_out_kt. 244