doc/guides/sample_app_ug/internet_proto_ip_pipeline.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 Internet Protocol (IP) Pipeline Sample Application
  32 ==================================================
  33
  34 The Internet Protocol (IP) Pipeline application illustrates the use of the DPDK Packet Framework tool suite.
  35 The DPDK pipeline methodology is used to implement functional blocks such as
  36 packet RX, packet TX, flow classification, firewall,
  37 routing, IP fragmentation, IP reassembly, etc
  38 which are then assigned to different CPU cores and connected together to create complex multi-core applications.
  39
  40 Overview
  41 --------
  42
  43 The pipelines for packet RX, packet TX, flow classification, firewall, routing, IP fragmentation, IP reassembly, management, etc
  44 are instantiated and different CPU cores and connected together through software queues.
  45 One of the CPU cores can be designated as the management core to run a Command Line Interface (CLI) to add entries to each table
  46 (e.g. flow table, firewall rule database, routing table, Address Resolution Protocol (ARP) table, and so on),
  47 bring NIC ports up or down, and so on.
  48
  49 Compiling the Application
  50 -------------------------
  51
  52 #.  Go to the examples directory:
  53
  54     .. code-block:: console
  55
  56         export RTE_SDK=/path/to/rte_sdk
  57         cd ${RTE_SDK}/examples/ip_pipeline
  58
  59 #.  Set the target (a default target is used if not specified):
  60
  61     .. code-block:: console
  62
  63         export RTE_TARGET=x86_64-native-linuxapp-gcc
  64
  65 #.  Build the application:
  66
  67     .. code-block:: console
  68
  69         make
  70
  71 Running the Sample Code
  72 -----------------------
  73
  74 The application execution command line is:
  75
  76 .. code-block:: console
  77
  78     ./ip_pipeline [EAL options] -- -p PORTMASK [-f CONFIG_FILE]
  79
  80 The number of ports in the PORTMASK can be either 2 or 4.
  81
  82 The config file assigns functionality to the CPU core by deciding the pipeline type to run on each CPU core
  83 (e.g. master, RX, flow classification, firewall, routing, IP fragmentation, IP reassembly, TX) and
  84 also allows creating complex topologies made up of CPU cores by interconnecting the CPU cores through SW queues.
  85
  86 Once the application is initialized, the CLI is available for populating the application tables,
  87 bringing NIC ports up or down, and so on.
  88
  89 The flow classification pipeline implements the flow table by using a large (multi-million entry) hash table with a 16-byte key size.
  90 The lookup key is the IPv4 5-tuple, which is extracted from the input packet by the packet RX pipeline and
  91 saved in the packet meta-data, has the following format:
  92
  93     [source IP address, destination IP address, L4 protocol, L4 protocol source port, L4 protocol destination port]
  94
  95 The firewall pipeline implements the rule database using an ACL table.
  96
  97 The routing pipeline implements an IP routing table by using an LPM IPv4 table and
  98 an ARP table by using a hash table with an 8-byte key size.
  99 The IP routing table lookup provides the output interface ID and the next hop IP address,
 100 which are stored in the packet meta-data, then used as the lookup key into the ARP table.
 101 The ARP table lookup provides the destination MAC address to be used for the output packet.
 102 The action for the default entry of both the IP routing table and the ARP table is packet drop.
 103
 104 The following CLI operations are available:
 105
 106 *   Enable/disable NIC ports (RX pipeline)
 107
 108 *   Add/delete/list flows (flow classification pipeline)
 109
 110 *   Add/delete/list firewall rules (firewall pipeline)
 111
 112 *   Add/delete/list routes (routing pipeline)
 113
 114 *   Add/delete/list ARP entries (routing pipeline)
 115
 116 In addition, there are two special commands:
 117
 118 *   flow add all:
 119     Populate the flow classification table with 16 million flows
 120     (by iterating through the last three bytes of the destination IP address).
 121     These flows are not displayed when using the flow print command.
 122     When this command is used, the following traffic profile must be used to have flow table lookup hits for all input packets.
 123     TCP/IPv4 packets with:
 124
 125     *   destination IP address = A.B.C.D with A fixed to 0 and B,C,D random
 126
 127     *   source IP address fixed to 0
 128
 129     *   source TCP port fixed to 0
 130
 131     *   destination TCP port fixed to 0
 132
 133 *   run cmd_file_path: Read CLI commands from an external file and run them one by one.
 134
 135 The full list of the available CLI commands can be displayed by pressing the TAB key while the application is running.