doc/guides/prog_guide/packet_classif_access_ctrl.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2010-2015 Intel Corporation.
   3
   4 Packet Classification and Access Control
   5 ========================================
   6
   7 The DPDK provides an Access Control library that gives the ability
   8 to classify an input packet based on a set of classification rules.
   9
  10 The ACL library is used to perform an N-tuple search over a set of rules with multiple categories
  11 and find the best match (highest priority) for each category.
  12 The 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
  24 Overview
  25 --------
  26
  27 Rule definition
  28 ~~~~~~~~~~~~~~~
  29
  30 The current implementation allows the user for each AC context to specify its own rule (set of fields)
  31 over which packet classification will be performed.
  32 Though 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
  37 This 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
  39 To 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
  78 For 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
  90 The 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
 143 A 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
 150 Any IPv4 packets with protocol ID 17 (UDP), source address 192.168.1.[0-255], destination address 192.168.2.31,
 151 source port [0-65535] and destination port 1234 matches the above rule.
 152
 153 To 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_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;
 165
 166 The 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
 212 A 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
 219 Any 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
 222 In the following example the last element of the search key is 8-bit long.
 223 So it is a case where the 4 consecutive bytes of an input field are not fully occupied.
 224 The 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
 235 The 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
 280 A 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
 287 Any IPv4 packets with protocol ID 6 (TCP), source address 192.168.1.[0-255], destination address 192.168.2.31,
 288 ToS 1 matches the above rule.
 289
 290 When 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
 314 RT memory size limit
 315 ~~~~~~~~~~~~~~~~~~~~
 316
 317 Build phase (rte_acl_build()) creates for a given set of rules internal structure for further run-time traversal.
 318 With current implementation it is a set of multi-bit tries (with stride == 8).
 319 Depending on the rules set, that could consume significant amount of memory.
 320 In attempt to conserve some space ACL build process tries to split the given
 321 rule-set into several non-intersecting subsets and construct a separate trie
 322 for each of them.
 323 Depending on the rule-set, it might reduce RT memory requirements but might
 324 increase classification time.
 325 There is a possibility at build-time to specify maximum memory limit for internal RT structures for given AC context.
 326 It could be done via **max_size** field of the **rte_acl_config** structure.
 327 Setting 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
 332 Setting it to zero makes rte_acl_build() to use the default behavior:
 333 try to minimize size of the RT structures, but doesn't expose any hard limit on it.
 334
 335 That gives the user the ability to decisions about performance/space trade-off.
 336 For 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
 364 Classification methods
 365 ~~~~~~~~~~~~~~~~~~~~~~
 366
 367 After 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.
 368 There 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
 393 It is purely a runtime decision which method to choose, there is no build-time difference.
 394 All 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.
 395 At 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
 402 Application 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
 409 The following example demonstrates IPv4, 5-tuple classification for rules defined above
 410 with multiple categories in more detail.
 411
 412 Classify 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
 513 For a tuple with source IP address: 10.1.1.1 and destination IP address: 192.168.1.15,
 514 once 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
 522 then 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
 537 For a tuple with source IP address: 192.168.1.1 and destination IP address: 192.168.2.11,
 538 once 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
 546 the 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
 556 For a tuple with source IP address: 10.1.1.1 and destination IP address: 201.212.111.12,
 557 once 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
 564 the 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.