doc/guides/sample_app_ug/ip_frag.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2014 Intel Corporation.
   3
   4 IP Fragmentation Sample Application
   5 ===================================
   6
   7 The IPv4 Fragmentation application is a simple example of packet processing
   8 using the Data Plane Development Kit (DPDK).
   9 The application does L3 forwarding with IPv4 and IPv6 packet fragmentation.
  10
  11 Overview
  12 --------
  13
  14 The application demonstrates the use of zero-copy buffers for packet fragmentation.
  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
  18 There are three key differences from the L2 Forwarding sample application:
  19
  20 *   The first difference is that the IP Fragmentation sample application makes use of indirect buffers.
  21
  22 *   The second difference is that the forwarding decision is taken
  23     based on information read from the input packet's IP header.
  24
  25 *   The third difference is that the application differentiates between
  26     IP and non-IP traffic by means of offload flags.
  27
  28 The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number,
  29 associated with that IP address.
  30 Any unmatched packets are forwarded to the originating port.
  31
  32 By default, input frame sizes up to 9.5 KB are supported.
  33 Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
  34
  35 Compiling the Application
  36 -------------------------
  37
  38 To compile the sample application see :doc:`compiling`.
  39
  40 The application is located in the ``ip_fragmentation`` sub-directory.
  41
  42 Running the Application
  43 -----------------------
  44
  45 The LPM object is created and loaded with the pre-configured entries read from
  46 global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
  47 For each input packet, the packet forwarding decision
  48 (that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
  49 If the IP packet size is greater than default output MTU,
  50 then the input packet is fragmented and several fragments are sent via the output interface.
  51
  52 Application usage:
  53
  54 .. code-block:: console
  55
  56     ./<build_dir>/examples/dpdk-ip_fragmentation [EAL options] -- -p PORTMASK [-q NQ]
  57
  58 where:
  59
  60 *   -p PORTMASK is a hexadecimal bitmask of ports to configure
  61
  62 *   -q NQ is the number of queue (=ports) per lcore (the default is 1)
  63
  64 To run the example in linux environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
  65
  66 .. code-block:: console
  67
  68     ./<build_dir>/examples/dpdk-ip_fragmentation -l 2,4 -n 3 -- -p 5
  69     EAL: coremask set to 14
  70     EAL: Detected lcore 0 on socket 0
  71     EAL: Detected lcore 1 on socket 1
  72     EAL: Detected lcore 2 on socket 0
  73     EAL: Detected lcore 3 on socket 1
  74     EAL: Detected lcore 4 on socket 0
  75     ...
  76
  77     Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1
  78     done: Link Up - speed 10000 Mbps - full-duplex
  79     Skipping disabled port 1
  80     Initializing port 2 on lcore 4... Address:00:1B:21:5C:FF:54, rxq=0 txq=2,0 txq=4,1
  81     done: Link Up - speed 10000 Mbps - full-duplex
  82     Skipping disabled port 3IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
  83     IP_FRAG: Socket 0: adding route 100.20.0.0/16 (port 1)
  84     ...
  85     IP_FRAG: Socket 0: adding route 0101:0101:0101:0101:0101:0101:0101:0101/48 (port 0)
  86     IP_FRAG: Socket 0: adding route 0201:0101:0101:0101:0101:0101:0101:0101/48 (port 1)
  87     ...
  88     IP_FRAG: entering main loop on lcore 4
  89     IP_FRAG: -- lcoreid=4 portid=2
  90     IP_FRAG: entering main loop on lcore 2
  91     IP_FRAG: -- lcoreid=2 portid=0
  92
  93 To run the example in linux environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
  94
  95 .. code-block:: console
  96
  97     ./<build_dir>/examples/dpdk-ip_fragmentation -l 4 -n 3 -- -p 5 -q 2
  98
  99 To test the application, flows should be set up in the flow generator that match the values in the
 100 l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
 101
 102 The default l3fwd_ipv4_route_array table is:
 103
 104 .. code-block:: c
 105
 106     struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
 107         {RTE_IPV4(100, 10, 0, 0), 16, 0},
 108         {RTE_IPV4(100, 20, 0, 0), 16, 1},
 109         {RTE_IPV4(100, 30, 0, 0), 16, 2},
 110         {RTE_IPV4(100, 40, 0, 0), 16, 3},
 111         {RTE_IPV4(100, 50, 0, 0), 16, 4},
 112         {RTE_IPV4(100, 60, 0, 0), 16, 5},
 113         {RTE_IPV4(100, 70, 0, 0), 16, 6},
 114         {RTE_IPV4(100, 80, 0, 0), 16, 7},
 115     };
 116
 117 The default l3fwd_ipv6_route_array table is:
 118
 119 .. code-block:: c
 120
 121     struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
 122         {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
 123         {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
 124         {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
 125         {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
 126         {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
 127         {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
 128         {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
 129         {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
 130     };
 131
 132 For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
 133 seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
 134 six of those packets will have length 1500 bytes and one packet will have length 318 bytes.
 135 IP Fragmentation sample application provides basic NUMA support
 136 in that all the memory structures are allocated on all sockets that have active lcores on them.
 137
 138
 139 Refer to the *DPDK Getting Started Guide* for general information on running applications
 140 and the Environment Abstraction Layer (EAL) options.