doc/guides/sample_app_ug/ip_frag.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 IP Fragmentation Sample Application
  32 ===================================
  33
  34 The IPv4 Fragmentation application is a simple example of packet processing
  35 using the Intel® Data Plane Development Kit (Intel® DPDK).
  36 The application does L3 forwarding with IPv4 and IPv6 packet fragmentation.
  37
  38 Overview
  39 --------
  40
  41 The application demonstrates the use of zero-copy buffers for packet fragmentation.
  42 The initialization and run-time paths are very similar to those of the L2 forwarding application
  43 (see Chapter 9 "L2 Forwarding Simple Application (in Real and Virtualised Environments)" for more information).
  44 This guide highlights the differences between the two applications.
  45
  46 There are three key differences from the L2 Forwarding sample application:
  47
  48 *   The first difference is that the IP Fragmentation sample application makes use of indirect buffers.
  49
  50 *   The second difference is that the forwarding decision is taken
  51     based on information read from the input packet's IP header.
  52
  53 *   The third difference is that the application differentiates between
  54     IP and non-IP traffic by means of offload flags.
  55
  56 The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number,
  57 associated with that IP address.
  58 Any unmatched packets are forwarded to the originating port.
  59
  60 By default, input frame sizes up to 9.5 KB are supported.
  61 Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
  62
  63 Building the Application
  64 ------------------------
  65
  66 To build the application:
  67
  68 #.  Go to the sample application directory:
  69
  70     .. code-block:: console
  71
  72         export RTE_SDK=/path/to/rte_sdk
  73         cd ${RTE_SDK}/examples/ip_fragmentation
  74
  75 #.  Set the target (a default target is used if not specified). For example:
  76
  77     .. code-block:: console
  78
  79         export RTE_TARGET=x86_64-native-linuxapp-gcc
  80
  81 See the *Intel® DPDK Getting Started Guide* for possible RTE_TARGET values.
  82
  83 #.  Build the application:
  84
  85     .. code-block:: console
  86
  87         make
  88
  89 Running the Application
  90 -----------------------
  91
  92 The LPM object is created and loaded with the pre-configured entries read from
  93 global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
  94 For each input packet, the packet forwarding decision
  95 (that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
  96 If the IP packet size is greater than default output MTU,
  97 then the input packet is fragmented and several fragments are sent via the output interface.
  98
  99 Application usage:
 100
 101 .. code-block:: console
 102
 103     ./build/ip_fragmentation [EAL options] -- -p PORTMASK [-q NQ]
 104
 105 where:
 106
 107 *   -p PORTMASK is a hexadecimal bitmask of ports to configure
 108
 109 *   -q NQ is the number of queue (=ports) per lcore (the default is 1)
 110
 111 To run the example in linuxapp environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
 112
 113 .. code-block:: console
 114
 115     ./build/ip_fragmentation -c 0x14 -n 3 -- -p 5
 116     EAL: coremask set to 14
 117     EAL: Detected lcore 0 on socket 0
 118     EAL: Detected lcore 1 on socket 1
 119     EAL: Detected lcore 2 on socket 0
 120     EAL: Detected lcore 3 on socket 1
 121     EAL: Detected lcore 4 on socket 0
 122     ...
 123
 124     Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1
 125     done: Link Up - speed 10000 Mbps - full-duplex
 126     Skipping disabled port 1
 127     Initializing port 2 on lcore 4... Address:00:1B:21:5C:FF:54, rxq=0 txq=2,0 txq=4,1
 128     done: Link Up - speed 10000 Mbps - full-duplex
 129     Skipping disabled port 3IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
 130     IP_FRAG: Socket 0: adding route 100.20.0.0/16 (port 1)
 131     ...
 132     IP_FRAG: Socket 0: adding route 0101:0101:0101:0101:0101:0101:0101:0101/48 (port 0)
 133     IP_FRAG: Socket 0: adding route 0201:0101:0101:0101:0101:0101:0101:0101/48 (port 1)
 134     ...
 135     IP_FRAG: entering main loop on lcore 4
 136     IP_FRAG: -- lcoreid=4 portid=2
 137     IP_FRAG: entering main loop on lcore 2
 138     IP_FRAG: -- lcoreid=2 portid=0
 139
 140 To run the example in linuxapp environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
 141
 142 .. code-block:: console
 143
 144     ./build/ip_fragmentation -c 0x10 -n 3 -- -p 5 -q 2
 145
 146 To test the application, flows should be set up in the flow generator that match the values in the
 147 l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
 148
 149 The default l3fwd_ipv4_route_array table is:
 150
 151 .. code-block:: c
 152
 153     struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
 154         {IPv4(100, 10, 0, 0), 16, 0},
 155         {IPv4(100, 20, 0, 0), 16, 1},
 156         {IPv4(100, 30, 0, 0), 16, 2},
 157         {IPv4(100, 40, 0, 0), 16, 3},
 158         {IPv4(100, 50, 0, 0), 16, 4},
 159         {IPv4(100, 60, 0, 0), 16, 5},
 160         {IPv4(100, 70, 0, 0), 16, 6},
 161         {IPv4(100, 80, 0, 0), 16, 7},
 162     };
 163
 164 The default l3fwd_ipv6_route_array table is:
 165
 166 .. code-block:: c
 167
 168     struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
 169         {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
 170         {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
 171         {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
 172         {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
 173         {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
 174         {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
 175         {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
 176         {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
 177     };
 178
 179 For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
 180 seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
 181 six of those packets will have length 1500 bytes and one packet will have length 318 bytes.
 182 IP Fragmentation sample application provides basic NUMA support
 183 in that all the memory structures are allocated on all sockets that have active lcores on them.
 184
 185
 186 Refer to the *Intel® DPDK Getting Started Guide* for general information on running applications
 187 and the Environment Abstraction Layer (EAL) options.