doc/guides/sample_app_ug/flow_classify.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Flow Classify Sample Application
   5 ================================
   6
   7 The Flow Classify sample application is based on the simple *skeleton* example
   8 of a forwarding application.
   9
  10 It is intended as a demonstration of the basic components of a DPDK forwarding
  11 application which uses the Flow Classify library API's.
  12
  13 Please refer to the
  14 :doc:`../prog_guide/flow_classify_lib`
  15 for more information.
  16
  17 Compiling the Application
  18 -------------------------
  19
  20 To compile the sample application see :doc:`compiling`.
  21
  22 The application is located in the ``flow_classify`` sub-directory.
  23
  24 Running the Application
  25 -----------------------
  26
  27 To run the example in a ``linux`` environment:
  28
  29 .. code-block:: console
  30
  31     ./<build_dir>/examples/dpdk-flow_classify -c 4 -n 4 -- /
  32     --rule_ipv4="../ipv4_rules_file.txt"
  33
  34 Please refer to the *DPDK Getting Started Guide*, section
  35 :doc:`../linux_gsg/build_sample_apps`
  36 for general information on running applications and the Environment Abstraction
  37 Layer (EAL) options.
  38
  39
  40 Sample ipv4_rules_file.txt
  41 --------------------------
  42
  43 .. code-block:: console
  44
  45     #file format:
  46     #src_ip/masklen dst_ip/masklen src_port : mask dst_port : mask proto/mask priority
  47     #
  48     2.2.2.3/24 2.2.2.7/24 32 : 0xffff 33 : 0xffff 17/0xff 0
  49     9.9.9.3/24 9.9.9.7/24 32 : 0xffff 33 : 0xffff 17/0xff 1
  50     9.9.9.3/24 9.9.9.7/24 32 : 0xffff 33 : 0xffff 6/0xff 2
  51     9.9.8.3/24 9.9.8.7/24 32 : 0xffff 33 : 0xffff 6/0xff 3
  52     6.7.8.9/24 2.3.4.5/24 32 : 0x0000 33 : 0x0000 132/0xff 4
  53
  54 Explanation
  55 -----------
  56
  57 The following sections provide an explanation of the main components of the
  58 code.
  59
  60 All DPDK library functions used in the sample code are prefixed with ``rte_``
  61 and are explained in detail in the *DPDK API Documentation*.
  62
  63 ACL field definitions for the IPv4 5 tuple rule
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 The following field definitions are used when creating the ACL table during
  67 initialisation of the ``Flow Classify`` application
  68
  69 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
  70     :language: c
  71     :start-after: Creation of ACL table during initialization of application. 8<
  72     :end-before: >8 End of creation of ACL table.
  73
  74 The Main Function
  75 ~~~~~~~~~~~~~~~~~
  76
  77 The ``main()`` function performs the initialization and calls the execution
  78 threads for each lcore.
  79
  80 The first task is to initialize the Environment Abstraction Layer (EAL).
  81 The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
  82 function. The value returned is the number of parsed arguments:
  83
  84 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
  85     :language: c
  86     :start-after: Initialize the Environment Abstraction Layer (EAL). 8<
  87     :end-before: >8 End of initialization of EAL.
  88     :dedent: 1
  89
  90 It then parses the flow_classify application arguments
  91
  92 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
  93     :language: c
  94     :start-after: Parse application arguments (after the EAL ones). 8<
  95     :end-before: >8 End of parse application arguments.
  96     :dedent: 1
  97
  98 The ``main()`` function also allocates a mempool to hold the mbufs
  99 (Message Buffers) used by the application:
 100
 101 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 102     :language: c
 103     :start-after: Creates a new mempool in memory to hold the mbufs. 8<
 104     :end-before: >8 End of creation of new mempool in memory.
 105     :dedent: 1
 106
 107 mbufs are the packet buffer structure used by DPDK. They are explained in
 108 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
 109
 110 The ``main()`` function also initializes all the ports using the user defined
 111 ``port_init()`` function which is explained in the next section:
 112
 113 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 114     :language: c
 115     :start-after: Initialize all ports. 8<
 116     :end-before: >8 End of initialization of all ports.
 117     :dedent: 1
 118
 119 The ``main()`` function creates the ``flow classifier object`` and adds an ``ACL
 120 table`` to the flow classifier.
 121
 122 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 123     :language: c
 124     :start-after: Creation of flow classifier object. 8<
 125     :end-before: >8 End of creation of flow classifier object.
 126
 127 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 128     :language: c
 129     :start-after: Memory allocation. 8<
 130     :end-before: >8 End of initialization of table create params.
 131     :dedent: 1
 132
 133 It then reads the ipv4_rules_file.txt file and initialises the parameters for
 134 the ``rte_flow_classify_table_entry_add`` API.
 135 This API adds a rule to the ACL table.
 136
 137 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 138     :language: c
 139     :start-after: Read file of IPv4 tuple rules. 8<
 140     :end-before: >8 End of reading file of IPv4 5 tuple rules.
 141     :dedent: 1
 142
 143 Once the initialization is complete, the application is ready to launch a
 144 function on an lcore. In this example ``lcore_main()`` is called on a single
 145 lcore.
 146
 147 .. code-block:: c
 148
 149     lcore_main(cls_app);
 150
 151 The ``lcore_main()`` function is explained below.
 152
 153 The Port Initialization  Function
 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 The main functional part of the port initialization used in the Basic
 157 Forwarding application is shown below:
 158
 159 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 160     :language: c
 161     :start-after: Initializing port using global settings. 8<
 162     :end-before: >8 End of initializing a given port.
 163
 164 The Ethernet ports are configured with default settings using the
 165 ``rte_eth_dev_configure()`` function.
 166
 167 For this example the ports are set up with 1 RX and 1 TX queue using the
 168 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
 169
 170 The Ethernet port is then started:
 171
 172 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 173     :language: c
 174     :start-after: Start the Ethernet port. 8<
 175     :end-before: >8 End of starting the Ethernet port.
 176     :dedent: 1
 177
 178
 179 Finally the RX port is set in promiscuous mode:
 180
 181 .. code-block:: c
 182
 183     retval = rte_eth_promiscuous_enable(port);
 184
 185 The Add Rules function
 186 ~~~~~~~~~~~~~~~~~~~~~~
 187
 188 The ``add_rules`` function reads the ``ipv4_rules_file.txt`` file and calls the
 189 ``add_classify_rule`` function which calls the
 190 ``rte_flow_classify_table_entry_add`` API.
 191
 192 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 193     :language: c
 194     :start-after: Reads file and calls the add_classify_rule function. 8<
 195     :end-before: >8 End of add_rules.
 196
 197
 198 The Lcore Main function
 199 ~~~~~~~~~~~~~~~~~~~~~~~
 200
 201 As we saw above the ``main()`` function calls an application function on the
 202 available lcores.
 203 The ``lcore_main`` function calls the ``rte_flow_classifier_query`` API.
 204 For the Basic Forwarding application the ``lcore_main`` function looks like the
 205 following:
 206
 207 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 208     :language: c
 209     :start-after: Flow classify data. 8<
 210     :end-before: >8 End of flow classify data.
 211
 212 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 213     :language: c
 214     :start-after: Classifying the packets. 8<
 215     :end-before: >8 End of lcore main.
 216
 217 The main work of the application is done within the loop:
 218
 219 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
 220     :language: c
 221     :start-after: Run until the application is quit or killed. 8<
 222     :end-before: >8 End of main loop.
 223     :dedent: 1
 224
 225 Packets are received in bursts on the RX ports and transmitted in bursts on
 226 the TX ports. The ports are grouped in pairs with a simple mapping scheme
 227 using the an XOR on the port number::
 228
 229     0 -> 1
 230     1 -> 0
 231
 232     2 -> 3
 233     3 -> 2
 234
 235     etc.
 236
 237 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
 238 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
 239 must be freed explicitly using ``rte_pktmbuf_free()``.
 240
 241 The forwarding loop can be interrupted and the application closed using
 242 ``Ctrl-C``.