doc/guides/sample_app_ug/flow_filtering.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2017 Mellanox Technologies, Ltd
   3
   4 Basic RTE Flow Filtering Sample Application
   5 ===========================================
   6
   7 The Basic RTE flow filtering sample application is a simple example of a
   8 creating a RTE flow rule.
   9
  10 It is intended as a demonstration of the basic components RTE flow rules.
  11
  12
  13 Compiling the Application
  14 -------------------------
  15
  16 To compile the sample application see :doc:`compiling`.
  17
  18
  19 Running the Application
  20 -----------------------
  21
  22 To run the example in a ``linux`` environment:
  23
  24 .. code-block:: console
  25
  26     ./<build_dir>/examples/dpdk-flow_filtering -l 1 -n 1
  27
  28 Refer to *DPDK Getting Started Guide* for general information on running
  29 applications and the Environment Abstraction Layer (EAL) options.
  30
  31
  32 Explanation
  33 -----------
  34
  35 The example is built from 2 files,
  36 ``main.c`` which holds the example logic and ``flow_blocks.c`` that holds the
  37 implementation for building the flow rule.
  38
  39 The following sections provide an explanation of the main components of the
  40 code.
  41
  42 All DPDK library functions used in the sample code are prefixed with ``rte_``
  43 and are explained in detail in the *DPDK API Documentation*.
  44
  45
  46 The Main Function
  47 ~~~~~~~~~~~~~~~~~
  48
  49 The ``main()`` function located in ``main.c`` file performs the initialization
  50 and runs the main loop function.
  51
  52 The first task is to initialize the Environment Abstraction Layer (EAL).  The
  53 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
  54 function. The value returned is the number of parsed arguments:
  55
  56 .. literalinclude:: ../../../examples/flow_filtering/main.c
  57     :language: c
  58     :start-after: Initialize EAL. 8<
  59     :end-before: >8 End of Initialization of EAL.
  60     :dedent: 1
  61
  62
  63 The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers)
  64 used by the application:
  65
  66 .. literalinclude:: ../../../examples/flow_filtering/main.c
  67     :language: c
  68     :start-after: Allocates a mempool to hold the mbufs. 8<
  69     :end-before: >8 End of allocating a mempool to hold the mbufs.
  70     :dedent: 1
  71
  72 Mbufs are the packet buffer structure used by DPDK. They are explained in
  73 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
  74
  75 The ``main()`` function also initializes all the ports using the user defined
  76 ``init_port()`` function which is explained in the next section:
  77
  78 .. literalinclude:: ../../../examples/flow_filtering/main.c
  79     :language: c
  80     :start-after: Initializes all the ports using the user defined init_port(). 8<
  81     :end-before: >8 End of Initializing the ports using user defined init_port().
  82     :dedent: 1
  83
  84 Once the initialization is complete, we set the flow rule using the
  85 following code:
  86
  87 .. literalinclude:: ../../../examples/flow_filtering/main.c
  88     :language: c
  89     :start-after: Create flow for send packet with. 8<
  90     :end-before: >8 End of creating flow for send packet with.
  91     :dedent: 1
  92
  93 In the last part the application is ready to launch the
  94 ``main_loop()`` function. Which is explained below.
  95
  96
  97 .. literalinclude:: ../../../examples/flow_filtering/main.c
  98     :language: c
  99     :start-after: Launching main_loop(). 8<
 100     :end-before: >8 End of launching main_loop().
 101     :dedent: 1
 102
 103 The Port Initialization  Function
 104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 105
 106 The main functional part of the port initialization used in the flow filtering
 107 application is shown below:
 108
 109 .. literalinclude:: ../../../examples/flow_filtering/main.c
 110     :language: c
 111     :start-after: Port initialization used in flow filtering. 8<
 112     :end-before: >8 End of Port initialization used in flow filtering.
 113
 114 The Ethernet port is configured with default settings using the
 115 ``rte_eth_dev_configure()`` function and the ``port_conf_default`` struct:
 116
 117 .. literalinclude:: ../../../examples/flow_filtering/main.c
 118     :language: c
 119     :start-after: Ethernet port configured with default settings. 8<
 120     :end-before: >8 End of ethernet port configured with default settings.
 121     :dedent: 1
 122
 123 For this example we are configuring number of rx and tx queues that are connected
 124 to a single port.
 125
 126 .. literalinclude:: ../../../examples/flow_filtering/main.c
 127     :language: c
 128     :start-after: Configuring number of RX and TX queues connected to single port. 8<
 129     :end-before: >8 End of Configuring RX and TX queues connected to single port.
 130     :dedent: 1
 131
 132 In the next step we create and apply the flow rule. which is to send packets
 133 with destination ip equals to 192.168.1.1 to queue number 1. The detail
 134 explanation of the ``generate_ipv4_flow()`` appears later in this document:
 135
 136 .. literalinclude:: ../../../examples/flow_filtering/main.c
 137     :language: c
 138     :start-after: Create flow for send packet with. 8<
 139     :end-before: >8 End of create flow and the flow rule.
 140     :dedent: 1
 141
 142 We are setting the RX port to promiscuous mode:
 143
 144 .. literalinclude:: ../../../examples/flow_filtering/main.c
 145     :language: c
 146     :start-after: Setting the RX port to promiscuous mode. 8<
 147     :end-before: >8 End of setting the RX port to promiscuous mode.
 148     :dedent: 1
 149
 150 The last step is to start the port.
 151
 152 .. literalinclude:: ../../../examples/flow_filtering/main.c
 153     :language: c
 154     :start-after: Starting the port. 8<
 155     :end-before: >8 End of starting the port.
 156     :dedent: 1
 157
 158
 159 The main_loop function
 160 ~~~~~~~~~~~~~~~~~~~~~~
 161
 162 As we saw above the ``main()`` function calls an application function to handle
 163 the main loop. For the flow filtering application the main_loop function
 164 looks like the following:
 165
 166 .. literalinclude:: ../../../examples/flow_filtering/main.c
 167     :language: c
 168     :start-after: Main_loop for flow filtering. 8<
 169     :end-before: >8 End of reading the packets from all queues.
 170
 171 The main work of the application is reading the packets from all
 172 queues and printing for each packet the destination queue:
 173
 174 .. literalinclude:: ../../../examples/flow_filtering/main.c
 175     :language: c
 176     :start-after: Reading the packets from all queues. 8<
 177     :end-before: >8 End of main_loop for flow filtering.
 178
 179
 180 The forwarding loop can be interrupted and the application closed using
 181 ``Ctrl-C``. Which results in closing the port and the device using
 182 ``rte_eth_dev_stop`` and ``rte_eth_dev_close``
 183
 184 The generate_ipv4_flow function
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186
 187 The generate_ipv4_flow function is responsible for creating the flow rule.
 188 This function is located in the ``flow_blocks.c`` file.
 189
 190 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 191     :language: c
 192     :start-after: Function responsible for creating the flow rule. 8<
 193     :end-before: >8 End of function responsible for creating the flow rule.
 194
 195 The first part of the function is declaring the structures that will be used.
 196
 197 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 198     :language: c
 199     :start-after: Declaring structs being used. 8<
 200     :end-before: >8 End of declaring structs being used.
 201     :dedent: 1
 202
 203 The following part create the flow attributes, in our case ingress.
 204
 205 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 206     :language: c
 207     :start-after: Set the rule attribute, only ingress packets will be checked. 8<
 208     :end-before: >8 End of setting the rule attribute.
 209     :dedent: 1
 210
 211 The third part defines the action to be taken when a packet matches
 212 the rule. In this case send the packet to queue.
 213
 214 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 215     :language: c
 216     :start-after: Function responsible for creating the flow rule. 8<
 217     :end-before: >8 End of setting the rule attribute.
 218
 219 The fourth part is responsible for creating the pattern and is built from
 220 number of steps. In each step we build one level of the pattern starting with
 221 the lowest one.
 222
 223 Setting the first level of the pattern ETH:
 224
 225 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 226     :language: c
 227     :start-after: IPv4 we set this level to allow all. 8<
 228     :end-before: >8 End of setting the first level of the pattern.
 229     :dedent: 1
 230
 231 Setting the second level of the pattern IP:
 232
 233 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 234     :language: c
 235     :start-after: Setting the second level of the pattern. 8<
 236     :end-before: >8 End of setting the second level of the pattern.
 237     :dedent: 1
 238
 239 Closing the pattern part.
 240
 241 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 242     :language: c
 243     :start-after: The final level must be always type end. 8<
 244     :end-before: >8 End of final level must be always type end.
 245     :dedent: 1
 246
 247 The last part of the function is to validate the rule and create it.
 248
 249 .. literalinclude:: ../../../examples/flow_filtering/flow_blocks.c
 250     :language: c
 251     :start-after: Validate the rule and create it. 8<
 252     :end-before: >8 End of validation the rule and create it.
 253     :dedent: 1