doc/guides/sample_app_ug/ipv4_multicast.rst

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