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