1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2015 Intel Corporation. 3 4Packet Classification and Access Control (ACL) Library 5====================================================== 6 7The DPDK provides an Access Control library that gives the ability 8to classify an input packet based on a set of classification rules. 9 10The ACL library is used to perform an N-tuple search over a set of rules with multiple categories 11and find the best match (highest priority) for each category. 12The library API provides the following basic operations: 13 14* Create a new Access Control (AC) context. 15 16* Add rules into the context. 17 18* For all rules in the context, build the runtime structures necessary to perform packet classification. 19 20* Perform input packet classifications. 21 22* Destroy an AC context and its runtime structures and free the associated memory. 23 24Overview 25-------- 26 27Rule definition 28~~~~~~~~~~~~~~~ 29 30The current implementation allows the user for each AC context to specify its own rule (set of fields) 31over which packet classification will be performed. 32Though there are few restrictions on the rule fields layout: 33 34* First field in the rule definition has to be one byte long. 35* All subsequent fields has to be grouped into sets of 4 consecutive bytes. 36 37This is done mainly for performance reasons - search function processes the first input byte as part of the flow setup and then the inner loop of the search function is unrolled to process four input bytes at a time. 38 39To define each field inside an AC rule, the following structure is used: 40 41.. code-block:: c 42 43 struct rte_acl_field_def { 44 uint8_t type; /*< type - ACL_FIELD_TYPE. */ 45 uint8_t size; /*< size of field 1,2,4, or 8. */ 46 uint8_t field_index; /*< index of field inside the rule. */ 47 uint8_t input_index; /*< 0-N input index. */ 48 uint32_t offset; /*< offset to start of field. */ 49 }; 50 51* type 52 The field type is one of three choices: 53 54 * _MASK - for fields such as IP addresses that have a value and a mask defining the number of relevant bits. 55 56 * _RANGE - for fields such as ports that have a lower and upper value for the field. 57 58 * _BITMASK - for fields such as protocol identifiers that have a value and a bit mask. 59 60* size 61 The size parameter defines the length of the field in bytes. Allowable values are 1, 2, 4, or 8 bytes. 62 Note that due to the grouping of input bytes, 1 or 2 byte fields must be defined as consecutive fields 63 that make up 4 consecutive input bytes. 64 Also, it is best to define fields of 8 or more bytes as 4 byte fields so that 65 the build processes can eliminate fields that are all wild. 66 67* field_index 68 A zero-based value that represents the position of the field inside the rule; 0 to N-1 for N fields. 69 70* input_index 71 As mentioned above, all input fields, except the very first one, must be in groups of 4 consecutive bytes. 72 The input index specifies to which input group that field belongs to. 73 74* offset 75 The offset field defines the offset for the field. 76 This is the offset from the beginning of the buffer parameter for the search. 77 78For example, to define classification for the following IPv4 5-tuple structure: 79 80.. code-block:: c 81 82 struct ipv4_5tuple { 83 uint8_t proto; 84 uint32_t ip_src; 85 uint32_t ip_dst; 86 uint16_t port_src; 87 uint16_t port_dst; 88 }; 89 90The following array of field definitions can be used: 91 92.. code-block:: c 93 94 struct rte_acl_field_def ipv4_defs[5] = { 95 /* first input field - always one byte long. */ 96 { 97 .type = RTE_ACL_FIELD_TYPE_BITMASK, 98 .size = sizeof (uint8_t), 99 .field_index = 0, 100 .input_index = 0, 101 .offset = offsetof (struct ipv4_5tuple, proto), 102 }, 103 104 /* next input field (IPv4 source address) - 4 consecutive bytes. */ 105 { 106 .type = RTE_ACL_FIELD_TYPE_MASK, 107 .size = sizeof (uint32_t), 108 .field_index = 1, 109 .input_index = 1, 110 .offset = offsetof (struct ipv4_5tuple, ip_src), 111 }, 112 113 /* next input field (IPv4 destination address) - 4 consecutive bytes. */ 114 { 115 .type = RTE_ACL_FIELD_TYPE_MASK, 116 .size = sizeof (uint32_t), 117 .field_index = 2, 118 .input_index = 2, 119 .offset = offsetof (struct ipv4_5tuple, ip_dst), 120 }, 121 122 /* 123 * Next 2 fields (src & dst ports) form 4 consecutive bytes. 124 * They share the same input index. 125 */ 126 { 127 .type = RTE_ACL_FIELD_TYPE_RANGE, 128 .size = sizeof (uint16_t), 129 .field_index = 3, 130 .input_index = 3, 131 .offset = offsetof (struct ipv4_5tuple, port_src), 132 }, 133 134 { 135 .type = RTE_ACL_FIELD_TYPE_RANGE, 136 .size = sizeof (uint16_t), 137 .field_index = 4, 138 .input_index = 3, 139 .offset = offsetof (struct ipv4_5tuple, port_dst), 140 }, 141 }; 142 143A typical example of such an IPv4 5-tuple rule is a follows: 144 145:: 146 147 source addr/mask destination addr/mask source ports dest ports protocol/mask 148 192.168.1.0/24 192.168.2.31/32 0:65535 1234:1234 17/0xff 149 150Any IPv4 packets with protocol ID 17 (UDP), source address 192.168.1.[0-255], destination address 192.168.2.31, 151source port [0-65535] and destination port 1234 matches the above rule. 152 153To define classification for the IPv6 2-tuple: <protocol, IPv6 source address> over the following IPv6 header structure: 154 155.. code-block:: c 156 157 struct __rte_packed_begin rte_ipv6_hdr { 158 uint32_t vtc_flow; /* IP version, traffic class & flow label. */ 159 uint16_t payload_len; /* IP packet length - includes sizeof(ip_header). */ 160 uint8_t proto; /* Protocol, next header. */ 161 uint8_t hop_limits; /* Hop limits. */ 162 uint8_t src_addr[16]; /* IP address of source host. */ 163 uint8_t dst_addr[16]; /* IP address of destination host(s). */ 164 } __rte_packed_end; 165 166The following array of field definitions can be used: 167 168.. code-block:: c 169 170 struct rte_acl_field_def ipv6_2tuple_defs[5] = { 171 { 172 .type = RTE_ACL_FIELD_TYPE_BITMASK, 173 .size = sizeof (uint8_t), 174 .field_index = 0, 175 .input_index = 0, 176 .offset = offsetof (struct rte_ipv6_hdr, proto), 177 }, 178 179 { 180 .type = RTE_ACL_FIELD_TYPE_MASK, 181 .size = sizeof (uint32_t), 182 .field_index = 1, 183 .input_index = 1, 184 .offset = offsetof (struct rte_ipv6_hdr, src_addr[0]), 185 }, 186 187 { 188 .type = RTE_ACL_FIELD_TYPE_MASK, 189 .size = sizeof (uint32_t), 190 .field_index = 2, 191 .input_index = 2, 192 .offset = offsetof (struct rte_ipv6_hdr, src_addr[4]), 193 }, 194 195 { 196 .type = RTE_ACL_FIELD_TYPE_MASK, 197 .size = sizeof (uint32_t), 198 .field_index = 3, 199 .input_index = 3, 200 .offset = offsetof (struct rte_ipv6_hdr, src_addr[8]), 201 }, 202 203 { 204 .type = RTE_ACL_FIELD_TYPE_MASK, 205 .size = sizeof (uint32_t), 206 .field_index = 4, 207 .input_index = 4, 208 .offset = offsetof (struct rte_ipv6_hdr, src_addr[12]), 209 }, 210 }; 211 212A typical example of such an IPv6 2-tuple rule is a follows: 213 214:: 215 216 source addr/mask protocol/mask 217 2001:db8:1234:0000:0000:0000:0000:0000/48 6/0xff 218 219Any IPv6 packets with protocol ID 6 (TCP), and source address inside the range 220[2001:db8:1234:0000:0000:0000:0000:0000 - 2001:db8:1234:ffff:ffff:ffff:ffff:ffff] matches the above rule. 221 222In the following example the last element of the search key is 8-bit long. 223So it is a case where the 4 consecutive bytes of an input field are not fully occupied. 224The structure for the classification is: 225 226.. code-block:: c 227 228 struct acl_key { 229 uint8_t ip_proto; 230 uint32_t ip_src; 231 uint32_t ip_dst; 232 uint8_t tos; /*< This is partially using a 32-bit input element */ 233 }; 234 235The following array of field definitions can be used: 236 237.. code-block:: c 238 239 struct rte_acl_field_def ipv4_defs[4] = { 240 /* first input field - always one byte long. */ 241 { 242 .type = RTE_ACL_FIELD_TYPE_BITMASK, 243 .size = sizeof (uint8_t), 244 .field_index = 0, 245 .input_index = 0, 246 .offset = offsetof (struct acl_key, ip_proto), 247 }, 248 249 /* next input field (IPv4 source address) - 4 consecutive bytes. */ 250 { 251 .type = RTE_ACL_FIELD_TYPE_MASK, 252 .size = sizeof (uint32_t), 253 .field_index = 1, 254 .input_index = 1, 255 .offset = offsetof (struct acl_key, ip_src), 256 }, 257 258 /* next input field (IPv4 destination address) - 4 consecutive bytes. */ 259 { 260 .type = RTE_ACL_FIELD_TYPE_MASK, 261 .size = sizeof (uint32_t), 262 .field_index = 2, 263 .input_index = 2, 264 .offset = offsetof (struct acl_key, ip_dst), 265 }, 266 267 /* 268 * Next element of search key (Type of Service) is indeed 1 byte long. 269 * Anyway we need to allocate all the 4 consecutive bytes for it. 270 */ 271 { 272 .type = RTE_ACL_FIELD_TYPE_BITMASK, 273 .size = sizeof (uint32_t), /* All the 4 consecutive bytes are allocated */ 274 .field_index = 3, 275 .input_index = 3, 276 .offset = offsetof (struct acl_key, tos), 277 }, 278 }; 279 280A typical example of such an IPv4 4-tuple rule is as follows: 281 282:: 283 284 source addr/mask destination addr/mask tos/mask protocol/mask 285 192.168.1.0/24 192.168.2.31/32 1/0xff 6/0xff 286 287Any IPv4 packets with protocol ID 6 (TCP), source address 192.168.1.[0-255], destination address 192.168.2.31, 288ToS 1 matches the above rule. 289 290When creating a set of rules, for each rule, additional information must be supplied also: 291 292* **priority**: A weight to measure the priority of the rules (higher is better). 293 If the input tuple matches more than one rule, then the rule with the higher priority is returned. 294 Note that if the input tuple matches more than one rule and these rules have equal priority, 295 it is undefined which rule is returned as a match. 296 It is recommended to assign a unique priority for each rule. 297 298* **category_mask**: Each rule uses a bit mask value to select the relevant category(s) for the rule. 299 When a lookup is performed, the result for each category is returned. 300 This effectively provides a "parallel lookup" by enabling a single search to return multiple results if, 301 for example, there were four different sets of ACL rules, one for access control, one for routing, and so on. 302 Each set could be assigned its own category and by combining them into a single database, 303 one lookup returns a result for each of the four sets. 304 305* **userdata**: A user-defined value. 306 For each category, a successful match returns the userdata field of the highest priority matched rule. 307 When no rules match, returned value is zero. 308 309.. note:: 310 311 When adding new rules into an ACL context, all fields must be in host byte order (LSB). 312 When the search is performed for an input tuple, all fields in that tuple must be in network byte order (MSB). 313 314RT memory size limit 315~~~~~~~~~~~~~~~~~~~~ 316 317Build phase (rte_acl_build()) creates for a given set of rules internal structure for further run-time traversal. 318With current implementation it is a set of multi-bit tries (with stride == 8). 319Depending on the rules set, that could consume significant amount of memory. 320In attempt to conserve some space ACL build process tries to split the given 321rule-set into several non-intersecting subsets and construct a separate trie 322for each of them. 323Depending on the rule-set, it might reduce RT memory requirements but might 324increase classification time. 325There is a possibility at build-time to specify maximum memory limit for internal RT structures for given AC context. 326It could be done via **max_size** field of the **rte_acl_config** structure. 327Setting it to the value greater than zero, instructs rte_acl_build() to: 328 329* attempt to minimize number of tries in the RT table, but 330* make sure that size of RT table wouldn't exceed given value. 331 332Setting it to zero makes rte_acl_build() to use the default behavior: 333try to minimize size of the RT structures, but doesn't expose any hard limit on it. 334 335That gives the user the ability to decisions about performance/space trade-off. 336For example: 337 338.. code-block:: c 339 340 struct rte_acl_ctx * acx; 341 struct rte_acl_config cfg; 342 int ret; 343 344 /* 345 * assuming that acx points to already created and 346 * populated with rules AC context and cfg filled properly. 347 */ 348 349 /* try to build AC context, with RT structures less then 8MB. */ 350 cfg.max_size = 0x800000; 351 ret = rte_acl_build(acx, &cfg); 352 353 /* 354 * RT structures can't fit into 8MB for given context. 355 * Try to build without exposing any hard limit. 356 */ 357 if (ret == -ERANGE) { 358 cfg.max_size = 0; 359 ret = rte_acl_build(acx, &cfg); 360 } 361 362 363 364Classification methods 365~~~~~~~~~~~~~~~~~~~~~~ 366 367After rte_acl_build() over given AC context has finished successfully, it can be used to perform classification - search for a rule with highest priority over the input data. 368There are several implementations of classify algorithm: 369 370* **RTE_ACL_CLASSIFY_SCALAR**: generic implementation, doesn't require any specific HW support. 371 Requires max SIMD bitwidth to be at least 64. 372 373* **RTE_ACL_CLASSIFY_SSE**: vector implementation, can process up to 8 flows in parallel. Requires SSE 4.1 support. 374 Requires max SIMD bitwidth to be at least 128. 375 376* **RTE_ACL_CLASSIFY_AVX2**: vector implementation, can process up to 16 flows in parallel. Requires AVX2 support. 377 Requires max SIMD bitwidth to be at least 256. 378 379* **RTE_ACL_CLASSIFY_NEON**: vector implementation, can process up to 8 flows 380 in parallel. Requires NEON support. Requires max SIMD bitwidth to be at least 128. 381 382* **RTE_ACL_CLASSIFY_ALTIVEC**: vector implementation, can process up to 8 383 flows in parallel. Requires ALTIVEC support. Requires max SIMD bitwidth to be at least 128. 384 385* **RTE_ACL_CLASSIFY_AVX512X16**: vector implementation, can process up to 16 386 flows in parallel. Uses 256-bit width SIMD registers. 387 Requires AVX512 support. Requires max SIMD bitwidth to be at least 256. 388 389* **RTE_ACL_CLASSIFY_AVX512X32**: vector implementation, can process up to 32 390 flows in parallel. Uses 512-bit width SIMD registers. 391 Requires AVX512 support. Requires max SIMD bitwidth to be at least 512. 392 393It is purely a runtime decision which method to choose, there is no build-time difference. 394All implementations operates over the same internal RT structures and use similar principles. The main difference is that vector implementations can manually exploit IA SIMD instructions and process several input data flows in parallel. 395At startup ACL library determines the highest available classify method for the given platform and sets it as default one. Though the user has an ability to override the default classifier function for a given ACL context or perform particular search using non-default classify method. In that case it is user responsibility to make sure that given platform supports selected classify implementation. 396 397.. note:: 398 399 Runtime algorithm selection obeys EAL max SIMD bitwidth parameter. 400 For more details about expected behaviour please see :ref:`max_simd_bitwidth` 401 402Application Programming Interface (API) Usage 403--------------------------------------------- 404 405.. note:: 406 407 For more details about the Access Control API, please refer to the *DPDK API Reference*. 408 409The following example demonstrates IPv4, 5-tuple classification for rules defined above 410with multiple categories in more detail. 411 412Classify with Multiple Categories 413~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 414 415.. code-block:: c 416 417 struct rte_acl_ctx * acx; 418 struct rte_acl_config cfg; 419 int ret; 420 421 /* define a structure for the rule with up to 5 fields. */ 422 423 RTE_ACL_RULE_DEF(acl_ipv4_rule, RTE_DIM(ipv4_defs)); 424 425 /* AC context creation parameters. */ 426 427 struct rte_acl_param prm = { 428 .name = "ACL_example", 429 .socket_id = SOCKET_ID_ANY, 430 .rule_size = RTE_ACL_RULE_SZ(RTE_DIM(ipv4_defs)), 431 432 /* number of fields per rule. */ 433 434 .max_rule_num = 8, /* maximum number of rules in the AC context. */ 435 }; 436 437 struct acl_ipv4_rule acl_rules[] = { 438 439 /* matches all packets traveling to 192.168.0.0/16, applies for categories: 0,1 */ 440 { 441 .data = {.userdata = 1, .category_mask = 3, .priority = 1}, 442 443 /* destination IPv4 */ 444 .field[2] = {.value.u32 = RTE_IPV4(192,168,0,0),. mask_range.u32 = 16,}, 445 446 /* source port */ 447 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 448 449 /* destination port */ 450 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 451 }, 452 453 /* matches all packets traveling to 192.168.1.0/24, applies for categories: 0 */ 454 { 455 .data = {.userdata = 2, .category_mask = 1, .priority = 2}, 456 457 /* destination IPv4 */ 458 .field[2] = {.value.u32 = RTE_IPV4(192,168,1,0),. mask_range.u32 = 24,}, 459 460 /* source port */ 461 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 462 463 /* destination port */ 464 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 465 }, 466 467 /* matches all packets traveling from 10.1.1.1, applies for categories: 1 */ 468 { 469 .data = {.userdata = 3, .category_mask = 2, .priority = 3}, 470 471 /* source IPv4 */ 472 .field[1] = {.value.u32 = RTE_IPV4(10,1,1,1),. mask_range.u32 = 32,}, 473 474 /* source port */ 475 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 476 477 /* destination port */ 478 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 479 }, 480 481 }; 482 483 484 /* create an empty AC context */ 485 486 if ((acx = rte_acl_create(&prm)) == NULL) { 487 488 /* handle context create failure. */ 489 490 } 491 492 /* add rules to the context */ 493 494 ret = rte_acl_add_rules(acx, acl_rules, RTE_DIM(acl_rules)); 495 if (ret != 0) { 496 /* handle error at adding ACL rules. */ 497 } 498 499 /* prepare AC build config. */ 500 501 cfg.num_categories = 2; 502 cfg.num_fields = RTE_DIM(ipv4_defs); 503 504 memcpy(cfg.defs, ipv4_defs, sizeof (ipv4_defs)); 505 506 /* build the runtime structures for added rules, with 2 categories. */ 507 508 ret = rte_acl_build(acx, &cfg); 509 if (ret != 0) { 510 /* handle error at build runtime structures for ACL context. */ 511 } 512 513For a tuple with source IP address: 10.1.1.1 and destination IP address: 192.168.1.15, 514once the following lines are executed: 515 516.. code-block:: c 517 518 uint32_t results[4]; /* make classify for 4 categories. */ 519 520 rte_acl_classify(acx, data, results, 1, 4); 521 522then the results[] array contains: 523 524.. code-block:: c 525 526 results[4] = {2, 3, 0, 0}; 527 528* For category 0, both rules 1 and 2 match, but rule 2 has higher priority, 529 therefore results[0] contains the userdata for rule 2. 530 531* For category 1, both rules 1 and 3 match, but rule 3 has higher priority, 532 therefore results[1] contains the userdata for rule 3. 533 534* For categories 2 and 3, there are no matches, so results[2] and results[3] contain zero, 535 which indicates that no matches were found for those categories. 536 537For a tuple with source IP address: 192.168.1.1 and destination IP address: 192.168.2.11, 538once the following lines are executed: 539 540.. code-block:: c 541 542 uint32_t results[4]; /* make classify by 4 categories. */ 543 544 rte_acl_classify(acx, data, results, 1, 4); 545 546the results[] array contains: 547 548.. code-block:: c 549 550 results[4] = {1, 1, 0, 0}; 551 552* For categories 0 and 1, only rule 1 matches. 553 554* For categories 2 and 3, there are no matches. 555 556For a tuple with source IP address: 10.1.1.1 and destination IP address: 201.212.111.12, 557once the following lines are executed: 558 559.. code-block:: c 560 561 uint32_t results[4]; /* make classify by 4 categories. */ 562 rte_acl_classify(acx, data, results, 1, 4); 563 564the results[] array contains: 565 566.. code-block:: c 567 568 results[4] = {0, 3, 0, 0}; 569 570* For category 1, only rule 3 matches. 571 572* For categories 0, 2 and 3, there are no matches. 573