ip_frag.rst revision 97f17497
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
62Building the Application
63------------------------
64
65To build the application:
66
67#.  Go to the sample application directory:
68
69    .. code-block:: console
70
71        export RTE_SDK=/path/to/rte_sdk
72        cd ${RTE_SDK}/examples/ip_fragmentation
73
74#.  Set the target (a default target is used if not specified). For example:
75
76    .. code-block:: console
77
78        export RTE_TARGET=x86_64-native-linuxapp-gcc
79
80See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
81
82#.  Build the application:
83
84    .. code-block:: console
85
86        make
87
88Running the Application
89-----------------------
90
91The LPM object is created and loaded with the pre-configured entries read from
92global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
93For each input packet, the packet forwarding decision
94(that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
95If the IP packet size is greater than default output MTU,
96then the input packet is fragmented and several fragments are sent via the output interface.
97
98Application usage:
99
100.. code-block:: console
101
102    ./build/ip_fragmentation [EAL options] -- -p PORTMASK [-q NQ]
103
104where:
105
106*   -p PORTMASK is a hexadecimal bitmask of ports to configure
107
108*   -q NQ is the number of queue (=ports) per lcore (the default is 1)
109
110To run the example in linuxapp environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
111
112.. code-block:: console
113
114    ./build/ip_fragmentation -c 0x14 -n 3 -- -p 5
115    EAL: coremask set to 14
116    EAL: Detected lcore 0 on socket 0
117    EAL: Detected lcore 1 on socket 1
118    EAL: Detected lcore 2 on socket 0
119    EAL: Detected lcore 3 on socket 1
120    EAL: Detected lcore 4 on socket 0
121    ...
122
123    Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1
124    done: Link Up - speed 10000 Mbps - full-duplex
125    Skipping disabled port 1
126    Initializing port 2 on lcore 4... Address:00:1B:21:5C:FF:54, rxq=0 txq=2,0 txq=4,1
127    done: Link Up - speed 10000 Mbps - full-duplex
128    Skipping disabled port 3IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
129    IP_FRAG: Socket 0: adding route 100.20.0.0/16 (port 1)
130    ...
131    IP_FRAG: Socket 0: adding route 0101:0101:0101:0101:0101:0101:0101:0101/48 (port 0)
132    IP_FRAG: Socket 0: adding route 0201:0101:0101:0101:0101:0101:0101:0101/48 (port 1)
133    ...
134    IP_FRAG: entering main loop on lcore 4
135    IP_FRAG: -- lcoreid=4 portid=2
136    IP_FRAG: entering main loop on lcore 2
137    IP_FRAG: -- lcoreid=2 portid=0
138
139To run the example in linuxapp environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
140
141.. code-block:: console
142
143    ./build/ip_fragmentation -c 0x10 -n 3 -- -p 5 -q 2
144
145To test the application, flows should be set up in the flow generator that match the values in the
146l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
147
148The default l3fwd_ipv4_route_array table is:
149
150.. code-block:: c
151
152    struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
153        {IPv4(100, 10, 0, 0), 16, 0},
154        {IPv4(100, 20, 0, 0), 16, 1},
155        {IPv4(100, 30, 0, 0), 16, 2},
156        {IPv4(100, 40, 0, 0), 16, 3},
157        {IPv4(100, 50, 0, 0), 16, 4},
158        {IPv4(100, 60, 0, 0), 16, 5},
159        {IPv4(100, 70, 0, 0), 16, 6},
160        {IPv4(100, 80, 0, 0), 16, 7},
161    };
162
163The default l3fwd_ipv6_route_array table is:
164
165.. code-block:: c
166
167    struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
168        {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
169        {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
170        {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
171        {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
172        {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
173        {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
174        {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
175        {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
176    };
177
178For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
179seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
180six of those packets will have length 1500 bytes and one packet will have length 318 bytes.
181IP Fragmentation sample application provides basic NUMA support
182in that all the memory structures are allocated on all sockets that have active lcores on them.
183
184
185Refer to the *DPDK Getting Started Guide* for general information on running applications
186and the Environment Abstraction Layer (EAL) options.
187