Imported upstream release 16.04

* gbp import-orig ../dpdk-16.04.tar.xz

Change-Id: Iac2196db782ba322f6974d8a752acc34ce5024c3
Signed-off-by: C.J. Collier <cjcollier@linuxfoundation.org>

1 files changed, 186 insertions, 0 deletions

diff --git a/doc/guides/sample_app_ug/ip_frag.rst b/doc/guides/sample_app_ug/ip_frag.rst
new file mode 100644
index 00000000..0c8da194
--- /dev/null
+++ b/doc/guides/sample_app_ug/ip_frag.rst
@@ -0,0 +1,186 @@
+..  BSD LICENSE
+    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+    * Neither the name of Intel Corporation nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+IP Fragmentation Sample Application
+===================================
+
+The IPv4 Fragmentation application is a simple example of packet processing
+using the Data Plane Development Kit (DPDK).
+The application does L3 forwarding with IPv4 and IPv6 packet fragmentation.
+
+Overview
+--------
+
+The application demonstrates the use of zero-copy buffers for packet fragmentation.
+The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
+This guide highlights the differences between the two applications.
+
+There are three key differences from the L2 Forwarding sample application:
+
+*   The first difference is that the IP Fragmentation sample application makes use of indirect buffers.
+
+*   The second difference is that the forwarding decision is taken
+    based on information read from the input packet's IP header.
+
+*   The third difference is that the application differentiates between
+    IP and non-IP traffic by means of offload flags.
+
+The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number,
+associated with that IP address.
+Any unmatched packets are forwarded to the originating port.
+
+By default, input frame sizes up to 9.5 KB are supported.
+Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
+
+Building the Application
+------------------------
+
+To build the application:
+
+#.  Go to the sample application directory:
+
+    .. code-block:: console
+
+        export RTE_SDK=/path/to/rte_sdk
+        cd ${RTE_SDK}/examples/ip_fragmentation
+
+#.  Set the target (a default target is used if not specified). For example:
+
+    .. code-block:: console
+
+        export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+See the *DPDK Getting Started Guide* for possible RTE_TARGET values.
+
+#.  Build the application:
+
+    .. code-block:: console
+
+        make
+
+Running the Application
+-----------------------
+
+The LPM object is created and loaded with the pre-configured entries read from
+global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
+For each input packet, the packet forwarding decision
+(that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
+If the IP packet size is greater than default output MTU,
+then the input packet is fragmented and several fragments are sent via the output interface.
+
+Application usage:
+
+.. code-block:: console
+
+    ./build/ip_fragmentation [EAL options] -- -p PORTMASK [-q NQ]
+
+where:
+
+*   -p PORTMASK is a hexadecimal bitmask of ports to configure
+
+*   -q NQ is the number of queue (=ports) per lcore (the default is 1)
+
+To run the example in linuxapp environment with 2 lcores (2,4) over 2 ports(0,2) with 1 RX queue per lcore:
+
+.. code-block:: console
+
+    ./build/ip_fragmentation -c 0x14 -n 3 -- -p 5
+    EAL: coremask set to 14
+    EAL: Detected lcore 0 on socket 0
+    EAL: Detected lcore 1 on socket 1
+    EAL: Detected lcore 2 on socket 0
+    EAL: Detected lcore 3 on socket 1
+    EAL: Detected lcore 4 on socket 0
+    ...
+
+    Initializing port 0 on lcore 2... Address:00:1B:21:76:FA:2C, rxq=0 txq=2,0 txq=4,1
+    done: Link Up - speed 10000 Mbps - full-duplex
+    Skipping disabled port 1
+    Initializing port 2 on lcore 4... Address:00:1B:21:5C:FF:54, rxq=0 txq=2,0 txq=4,1
+    done: Link Up - speed 10000 Mbps - full-duplex
+    Skipping disabled port 3IP_FRAG: Socket 0: adding route 100.10.0.0/16 (port 0)
+    IP_FRAG: Socket 0: adding route 100.20.0.0/16 (port 1)
+    ...
+    IP_FRAG: Socket 0: adding route 0101:0101:0101:0101:0101:0101:0101:0101/48 (port 0)
+    IP_FRAG: Socket 0: adding route 0201:0101:0101:0101:0101:0101:0101:0101/48 (port 1)
+    ...
+    IP_FRAG: entering main loop on lcore 4
+    IP_FRAG: -- lcoreid=4 portid=2
+    IP_FRAG: entering main loop on lcore 2
+    IP_FRAG: -- lcoreid=2 portid=0
+
+To run the example in linuxapp environment with 1 lcore (4) over 2 ports(0,2) with 2 RX queues per lcore:
+
+.. code-block:: console
+
+    ./build/ip_fragmentation -c 0x10 -n 3 -- -p 5 -q 2
+
+To test the application, flows should be set up in the flow generator that match the values in the
+l3fwd_ipv4_route_array and/or l3fwd_ipv6_route_array table.
+
+The default l3fwd_ipv4_route_array table is:
+
+.. code-block:: c
+
+    struct l3fwd_ipv4_route l3fwd_ipv4_route_array[] = {
+        {IPv4(100, 10, 0, 0), 16, 0},
+        {IPv4(100, 20, 0, 0), 16, 1},
+        {IPv4(100, 30, 0, 0), 16, 2},
+        {IPv4(100, 40, 0, 0), 16, 3},
+        {IPv4(100, 50, 0, 0), 16, 4},
+        {IPv4(100, 60, 0, 0), 16, 5},
+        {IPv4(100, 70, 0, 0), 16, 6},
+        {IPv4(100, 80, 0, 0), 16, 7},
+    };
+
+The default l3fwd_ipv6_route_array table is:
+
+.. code-block:: c
+
+    struct l3fwd_ipv6_route l3fwd_ipv6_route_array[] = {
+        {{1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 0},
+        {{2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 1},
+        {{3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 2},
+        {{4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 3},
+        {{5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 4},
+        {{6, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 5},
+        {{7, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 6},
+        {{8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1}, 48, 7},
+    };
+
+For example, for the input IPv4 packet with destination address: 100.10.1.1 and packet length 9198 bytes,
+seven IPv4 packets will be sent out from port #0 to the destination address 100.10.1.1:
+six of those packets will have length 1500 bytes and one packet will have length 318 bytes.
+IP Fragmentation sample application provides basic NUMA support
+in that all the memory structures are allocated on all sockets that have active lcores on them.
+
+
+Refer to the *DPDK Getting Started Guide* for general information on running applications
+and the Environment Abstraction Layer (EAL) options.