2 Copyright(c) 2017 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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
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.
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.
31 Flow Classification Library
32 ===========================
34 DPDK provides a Flow Classification library that provides the ability
35 to classify an input packet by matching it against a set of Flow rules.
37 The initial implementation supports counting of IPv4 5-tuple packets which match
38 a particular Flow rule only.
44 The Flow Classification library uses the ``librte_table`` API for managing Flow
45 rules and matching packets against the Flow rules.
46 The library is table agnostic and can use the following tables:
47 ``Access Control List``, ``Hash`` and ``Longest Prefix Match(LPM)``.
48 The ``Access Control List`` table is used in the initial implementation.
51 :doc:`./packet_framework`
52 for more information.on ``librte_table``.
54 DPDK provides an Access Control List library that provides the ability to
55 classify an input packet based on a set of classification rules.
58 :doc:`./packet_classif_access_ctrl`
59 library for more information on ``librte_acl``.
61 There is also a Flow Classify sample application which demonstrates the use of
62 the Flow Classification Library API's.
65 :doc:`../sample_app_ug/flow_classify`
66 for more information on the ``flow_classify`` sample application.
71 The library has the following API's
76 * Flow classifier create
79 * Parameters for flow classifier creation
81 * Handle to flow classifier instance on success or NULL otherwise
83 struct rte_flow_classifier *
84 rte_flow_classifier_create(struct rte_flow_classifier_params *params);
87 * Flow classifier free
90 * Handle to flow classifier instance
92 * 0 on success, error code otherwise
95 rte_flow_classifier_free(struct rte_flow_classifier *cls);
98 * Flow classify table create
101 * Handle to flow classifier instance
103 * Parameters for flow_classify table creation
105 * 0 on success, error code otherwise
108 rte_flow_classify_table_create(struct rte_flow_classifier *cls,
109 struct rte_flow_classify_table_params *params);
112 * Validate the flow classify rule
115 * Handle to flow classifier instance
117 * Flow rule attributes
119 * Pattern specification (list terminated by the END pattern item).
121 * Associated actions (list terminated by the END pattern item).
123 * Perform verbose error reporting if not NULL. Structure
124 * initialised in case of error only.
126 * 0 on success, error code otherwise
129 rte_flow_classify_validate(struct rte_flow_classifier *cls,
130 const struct rte_flow_attr *attr,
131 const struct rte_flow_item pattern[],
132 const struct rte_flow_action actions[],
133 struct rte_flow_error *error);
136 * Add a flow classify rule to the flow_classifier table.
139 * Flow classifier handle
141 * Flow rule attributes
143 * Pattern specification (list terminated by the END pattern item).
145 * Associated actions (list terminated by the END pattern item).
146 * @param[out] key_found
147 * returns 1 if rule present already, 0 otherwise.
149 * Perform verbose error reporting if not NULL. Structure
150 * initialised in case of error only.
152 * A valid handle in case of success, NULL otherwise.
154 struct rte_flow_classify_rule *
155 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
156 const struct rte_flow_attr *attr,
157 const struct rte_flow_item pattern[],
158 const struct rte_flow_action actions[],
160 struct rte_flow_error *error);
163 * Delete a flow classify rule from the flow_classifier table.
166 * Flow classifier handle
170 * 0 on success, error code otherwise.
173 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
174 struct rte_flow_classify_rule *rule);
177 * Query flow classifier for given rule.
180 * Flow classifier handle
182 * Pointer to packets to process
184 * Number of packets to process
188 * Flow classify stats
191 * 0 on success, error code otherwise.
194 rte_flow_classifier_query(struct rte_flow_classifier *cls,
195 struct rte_mbuf **pkts,
196 const uint16_t nb_pkts,
197 struct rte_flow_classify_rule *rule,
198 struct rte_flow_classify_stats *stats);
203 The application creates the ``Classifier`` using the
204 ``rte_flow_classifier_create`` API.
205 The ``rte_flow_classify_params`` structure must be initialised by the
206 application before calling the API.
210 struct rte_flow_classifier_params {
211 /** flow classifier name */
214 /** CPU socket ID where memory for the flow classifier and its */
215 /** elements (tables) should be allocated */
219 The ``Classifier`` has the following internal structures:
223 struct rte_cls_table {
224 /* Input parameters */
225 struct rte_table_ops ops;
227 enum rte_flow_classify_table_type type;
229 /* Handle to the low-level table object */
233 #define RTE_FLOW_CLASSIFIER_MAX_NAME_SZ 256
235 struct rte_flow_classifier {
236 /* Input parameters */
237 char name[RTE_FLOW_CLASSIFIER_MAX_NAME_SZ];
242 struct rte_eth_ntuple_filter ntuple_filter;
244 /* classifier tables */
245 struct rte_cls_table tables[RTE_FLOW_CLASSIFY_TABLE_MAX];
250 struct rte_flow_classify_table_entry
251 *entries[RTE_PORT_IN_BURST_SIZE_MAX];
252 } __rte_cache_aligned;
254 Adding a table to the Classifier
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
257 The application adds a table to the ``Classifier`` using the
258 ``rte_flow_classify_table_create`` API.
259 The ``rte_flow_classify_table_params`` structure must be initialised by the
260 application before calling the API.
264 struct rte_flow_classify_table_params {
265 /** Table operations (specific to each table type) */
266 struct rte_table_ops *ops;
268 /** Opaque param to be passed to the table create operation */
271 /** Classifier table type */
272 enum rte_flow_classify_table_type type;
275 To create an ACL table the ``rte_table_acl_params`` structure must be
276 initialised and assigned to ``arg_create`` in the
277 ``rte_flow_classify_table_params`` structure.
281 struct rte_table_acl_params {
285 /** Maximum number of ACL rules in the table */
288 /** Number of fields in the ACL rule specification */
289 uint32_t n_rule_fields;
291 /** Format specification of the fields of the ACL rule */
292 struct rte_acl_field_def field_format[RTE_ACL_MAX_FIELDS];
295 The fields for the ACL rule must also be initialised by the application.
297 An ACL table can be added to the ``Classifier`` for each ACL rule, for example
298 another table could be added for the IPv6 5-tuple rule.
303 The library currently supports three IPv4 5-tuple flow patterns, for UDP, TCP
308 /* Pattern for IPv4 5-tuple UDP filter */
309 static enum rte_flow_item_type pattern_ntuple_1[] = {
310 RTE_FLOW_ITEM_TYPE_ETH,
311 RTE_FLOW_ITEM_TYPE_IPV4,
312 RTE_FLOW_ITEM_TYPE_UDP,
313 RTE_FLOW_ITEM_TYPE_END,
316 /* Pattern for IPv4 5-tuple TCP filter */
317 static enum rte_flow_item_type pattern_ntuple_2[] = {
318 RTE_FLOW_ITEM_TYPE_ETH,
319 RTE_FLOW_ITEM_TYPE_IPV4,
320 RTE_FLOW_ITEM_TYPE_TCP,
321 RTE_FLOW_ITEM_TYPE_END,
324 /* Pattern for IPv4 5-tuple SCTP filter */
325 static enum rte_flow_item_type pattern_ntuple_3[] = {
326 RTE_FLOW_ITEM_TYPE_ETH,
327 RTE_FLOW_ITEM_TYPE_IPV4,
328 RTE_FLOW_ITEM_TYPE_SCTP,
329 RTE_FLOW_ITEM_TYPE_END,
332 The API function ``rte_flow_classify_validate`` parses the
333 IPv4 5-tuple pattern, attributes and actions and returns the 5-tuple data in the
334 ``rte_eth_ntuple_filter`` structure.
339 rte_flow_classify_validate(struct rte_flow_classifier *cls,
340 const struct rte_flow_attr *attr,
341 const struct rte_flow_item pattern[],
342 const struct rte_flow_action actions[],
343 struct rte_flow_error *error)
348 The ``rte_flow_classify_table_entry_add`` API creates an
349 ``rte_flow_classify`` object which contains the flow_classify id and type, the
350 action, a union of add and delete keys and a union of rules.
351 It uses the ``rte_flow_classify_validate`` API function for parsing the
353 The 5-tuple ACL key data is obtained from the ``rte_eth_ntuple_filter``
354 structure populated by the ``classify_parse_ntuple_filter`` function which
355 parses the Flow rule.
360 struct rte_table_acl_rule_add_params key_add; /* add key */
361 struct rte_table_acl_rule_delete_params key_del; /* delete key */
364 struct classify_rules {
365 enum rte_flow_classify_rule_type type;
367 struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;
371 struct rte_flow_classify {
372 uint32_t id; /* unique ID of classify object */
373 enum rte_flow_classify_table_type tbl_type; /* rule table */
374 struct classify_rules rules; /* union of rules */
378 int key_found; /* rule key found in table */
379 struct rte_flow_classify_table_entry entry; /* rule meta data */
380 void *entry_ptr; /* handle to the table entry for rule meta data */
383 It then calls the ``table.ops.f_add`` API to add the rule to the ACL
389 The ``rte_flow_classify_table_entry_delete`` API calls the
390 ``table.ops.f_delete`` API to delete a rule from the ACL table.
395 The ``rte_flow_classifier_query`` API is used to find packets which match a
396 given flow Flow rule in the table.
397 This API calls the flow_classify_run internal function which calls the
398 ``table.ops.f_lookup`` API to see if any packets in a burst match any
399 of the Flow rules in the table.
400 The meta data for the highest priority rule matched for each packet is returned
401 in the entries array in the ``rte_flow_classify`` object.
402 The internal function ``action_apply`` implements the ``Count`` action which is
403 used to return data which matches a particular Flow rule.
405 The rte_flow_classifier_query API uses the following structures to return data
410 /** IPv4 5-tuple data */
411 struct rte_flow_classify_ipv4_5tuple {
412 uint32_t dst_ip; /**< Destination IP address in big endian. */
413 uint32_t dst_ip_mask; /**< Mask of destination IP address. */
414 uint32_t src_ip; /**< Source IP address in big endian. */
415 uint32_t src_ip_mask; /**< Mask of destination IP address. */
416 uint16_t dst_port; /**< Destination port in big endian. */
417 uint16_t dst_port_mask; /**< Mask of destination port. */
418 uint16_t src_port; /**< Source Port in big endian. */
419 uint16_t src_port_mask; /**< Mask of source port. */
420 uint8_t proto; /**< L4 protocol. */
421 uint8_t proto_mask; /**< Mask of L4 protocol. */
427 * For the count action, stats can be returned by the query API.
429 * Storage for stats is provided by the application.
433 struct rte_flow_classify_stats {
437 struct rte_flow_classify_5tuple_stats {
438 /** count of packets that match IPv4 5tuple pattern */
440 /** IPv4 5tuple data */
441 struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;