1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2017 Intel Corporation.
4 Flow Classify Sample Application
5 ================================
7 The Flow Classify sample application is based on the simple *skeleton* example
8 of a forwarding application.
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.
14 :doc:`../prog_guide/flow_classify_lib`
17 Compiling the Application
18 -------------------------
20 To compile the sample application see :doc:`compiling`.
22 The application is located in the ``flow_classify`` sub-directory.
24 Running the Application
25 -----------------------
27 To run the example in a ``linux`` environment:
29 .. code-block:: console
31 ./<build_dir>/examples/dpdk-flow_classify -c 4 -n 4 -- /
32 --rule_ipv4="../ipv4_rules_file.txt"
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
40 Sample ipv4_rules_file.txt
41 --------------------------
43 .. code-block:: console
46 #src_ip/masklen dst_ip/masklen src_port : mask dst_port : mask proto/mask priority
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
57 The following sections provide an explanation of the main components of the
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*.
63 ACL field definitions for the IPv4 5 tuple rule
64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 The following field definitions are used when creating the ACL table during
67 initialisation of the ``Flow Classify`` application
69 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
71 :start-after: Creation of ACL table during initialization of application. 8<
72 :end-before: >8 End of creation of ACL table.
77 The ``main()`` function performs the initialization and calls the execution
78 threads for each lcore.
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:
84 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
86 :start-after: Initialize the Environment Abstraction Layer (EAL). 8<
87 :end-before: >8 End of initialization of EAL.
90 It then parses the flow_classify application arguments
92 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
94 :start-after: Parse application arguments (after the EAL ones). 8<
95 :end-before: >8 End of parse application arguments.
98 The ``main()`` function also allocates a mempool to hold the mbufs
99 (Message Buffers) used by the application:
101 .. literalinclude:: ../../../examples/flow_classify/flow_classify.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.
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*.
110 The ``main()`` function also initializes all the ports using the user defined
111 ``port_init()`` function which is explained in the next section:
113 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
115 :start-after: Initialize all ports. 8<
116 :end-before: >8 End of initialization of all ports.
119 The ``main()`` function creates the ``flow classifier object`` and adds an ``ACL
120 table`` to the flow classifier.
122 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
124 :start-after: Creation of flow classifier object. 8<
125 :end-before: >8 End of creation of flow classifier object.
127 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
129 :start-after: Memory allocation. 8<
130 :end-before: >8 End of initialization of table create params.
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.
137 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
139 :start-after: Read file of IPv4 tuple rules. 8<
140 :end-before: >8 End of reading file of IPv4 5 tuple rules.
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
151 The ``lcore_main()`` function is explained below.
153 The Port Initialization Function
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156 The main functional part of the port initialization used in the Basic
157 Forwarding application is shown below:
159 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
161 :start-after: Initializing port using global settings. 8<
162 :end-before: >8 End of initializing a given port.
164 The Ethernet ports are configured with default settings using the
165 ``rte_eth_dev_configure()`` function.
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.
170 The Ethernet port is then started:
172 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
174 :start-after: Start the Ethernet port. 8<
175 :end-before: >8 End of starting the Ethernet port.
179 Finally the RX port is set in promiscuous mode:
183 retval = rte_eth_promiscuous_enable(port);
185 The Add Rules function
186 ~~~~~~~~~~~~~~~~~~~~~~
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.
192 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
194 :start-after: Reads file and calls the add_classify_rule function. 8<
195 :end-before: >8 End of add_rules.
198 The Lcore Main function
199 ~~~~~~~~~~~~~~~~~~~~~~~
201 As we saw above the ``main()`` function calls an application function on the
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
207 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
209 :start-after: Flow classify data. 8<
210 :end-before: >8 End of flow classify data.
212 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
214 :start-after: Classifying the packets. 8<
215 :end-before: >8 End of lcore main.
217 The main work of the application is done within the loop:
219 .. literalinclude:: ../../../examples/flow_classify/flow_classify.c
221 :start-after: Run until the application is quit or killed. 8<
222 :end-before: >8 End of main loop.
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::
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()``.
241 The forwarding loop can be interrupted and the application closed using