doc/guides/sample_app_ug/flow_classify.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Intel Corporation.
   3
   4 Flow Classify Sample Application
   5 ================================
   6
   7 The Flow Classify sample application is based on the simple *skeleton* example
   8 of a forwarding application.
   9
  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.
  12
  13 Please refer to the
  14 :doc:`../prog_guide/flow_classify_lib`
  15 for more information.
  16
  17 Compiling the Application
  18 -------------------------
  19
  20 To compile the sample application see :doc:`compiling`.
  21
  22 The application is located in the ``flow_classify`` sub-directory.
  23
  24 Running the Application
  25 -----------------------
  26
  27 To run the example in a ``linux`` environment:
  28
  29 .. code-block:: console
  30
  31     cd ~/dpdk/examples/flow_classify
  32     ./build/flow_classify -c 4 -n 4 -- --rule_ipv4="../ipv4_rules_file.txt"
  33
  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
  37 Layer (EAL) options.
  38
  39
  40 Sample ipv4_rules_file.txt
  41 --------------------------
  42
  43 .. code-block:: console
  44
  45     #file format:
  46     #src_ip/masklen dst_ip/masklen src_port : mask dst_port : mask proto/mask priority
  47     #
  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
  53
  54 Explanation
  55 -----------
  56
  57 The following sections provide an explanation of the main components of the
  58 code.
  59
  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*.
  62
  63 ACL field definitions for the IPv4 5 tuple rule
  64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  65
  66 The following field definitions are used when creating the ACL table during
  67 initialisation of the ``Flow Classify`` application..
  68
  69 .. code-block:: c
  70
  71      enum {
  72          PROTO_FIELD_IPV4,
  73          SRC_FIELD_IPV4,
  74          DST_FIELD_IPV4,
  75          SRCP_FIELD_IPV4,
  76          DSTP_FIELD_IPV4,
  77          NUM_FIELDS_IPV4
  78     };
  79
  80     enum {
  81         PROTO_INPUT_IPV4,
  82         SRC_INPUT_IPV4,
  83         DST_INPUT_IPV4,
  84         SRCP_DESTP_INPUT_IPV4
  85     };
  86
  87     static struct rte_acl_field_def ipv4_defs[NUM_FIELDS_IPV4] = {
  88         /* first input field - always one byte long. */
  89         {
  90             .type = RTE_ACL_FIELD_TYPE_BITMASK,
  91             .size = sizeof(uint8_t),
  92             .field_index = PROTO_FIELD_IPV4,
  93             .input_index = PROTO_INPUT_IPV4,
  94             .offset = sizeof(struct rte_ether_hdr) +
  95                 offsetof(struct ipv4_hdr, next_proto_id),
  96         },
  97         /* next input field (IPv4 source address) - 4 consecutive bytes. */
  98         {
  99             /* rte_flow uses a bit mask for IPv4 addresses */
 100             .type = RTE_ACL_FIELD_TYPE_BITMASK,
 101             .size = sizeof(uint32_t),
 102             .field_index = SRC_FIELD_IPV4,
 103             .input_index = SRC_INPUT_IPV4,
 104             .offset = sizeof(struct rte_ether_hdr) +
 105                 offsetof(struct ipv4_hdr, src_addr),
 106         },
 107         /* next input field (IPv4 destination address) - 4 consecutive bytes. */
 108         {
 109             /* rte_flow uses a bit mask for IPv4 addresses */
 110             .type = RTE_ACL_FIELD_TYPE_BITMASK,
 111             .size = sizeof(uint32_t),
 112             .field_index = DST_FIELD_IPV4,
 113             .input_index = DST_INPUT_IPV4,
 114             .offset = sizeof(struct rte_ether_hdr) +
 115                 offsetof(struct ipv4_hdr, dst_addr),
 116         },
 117         /*
 118          * Next 2 fields (src & dst ports) form 4 consecutive bytes.
 119          * They share the same input index.
 120          */
 121         {
 122             /* rte_flow uses a bit mask for protocol ports */
 123             .type = RTE_ACL_FIELD_TYPE_BITMASK,
 124             .size = sizeof(uint16_t),
 125             .field_index = SRCP_FIELD_IPV4,
 126             .input_index = SRCP_DESTP_INPUT_IPV4,
 127             .offset = sizeof(struct rte_ether_hdr) +
 128                 sizeof(struct ipv4_hdr) +
 129                 offsetof(struct tcp_hdr, src_port),
 130         },
 131         {
 132              /* rte_flow uses a bit mask for protocol ports */
 133              .type = RTE_ACL_FIELD_TYPE_BITMASK,
 134              .size = sizeof(uint16_t),
 135              .field_index = DSTP_FIELD_IPV4,
 136              .input_index = SRCP_DESTP_INPUT_IPV4,
 137              .offset = sizeof(struct rte_ether_hdr) +
 138                  sizeof(struct ipv4_hdr) +
 139                  offsetof(struct tcp_hdr, dst_port),
 140         },
 141     };
 142
 143 The Main Function
 144 ~~~~~~~~~~~~~~~~~
 145
 146 The ``main()`` function performs the initialization and calls the execution
 147 threads for each lcore.
 148
 149 The first task is to initialize the Environment Abstraction Layer (EAL).
 150 The ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
 151 function. The value returned is the number of parsed arguments:
 152
 153 .. code-block:: c
 154
 155     int ret = rte_eal_init(argc, argv);
 156     if (ret < 0)
 157         rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
 158
 159 It then parses the flow_classify application arguments
 160
 161 .. code-block:: c
 162
 163     ret = parse_args(argc, argv);
 164     if (ret < 0)
 165         rte_exit(EXIT_FAILURE, "Invalid flow_classify parameters\n");
 166
 167 The ``main()`` function also allocates a mempool to hold the mbufs
 168 (Message Buffers) used by the application:
 169
 170 .. code-block:: c
 171
 172     mbuf_pool = rte_mempool_create("MBUF_POOL",
 173                                    NUM_MBUFS * nb_ports,
 174                                    MBUF_SIZE,
 175                                    MBUF_CACHE_SIZE,
 176                                    sizeof(struct rte_pktmbuf_pool_private),
 177                                    rte_pktmbuf_pool_init, NULL,
 178                                    rte_pktmbuf_init, NULL,
 179                                    rte_socket_id(),
 180                                    0);
 181
 182 mbufs are the packet buffer structure used by DPDK. They are explained in
 183 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
 184
 185 The ``main()`` function also initializes all the ports using the user defined
 186 ``port_init()`` function which is explained in the next section:
 187
 188 .. code-block:: c
 189
 190     RTE_ETH_FOREACH_DEV(portid) {
 191         if (port_init(portid, mbuf_pool) != 0) {
 192             rte_exit(EXIT_FAILURE,
 193                      "Cannot init port %" PRIu8 "\n", portid);
 194         }
 195     }
 196
 197 The ``main()`` function creates the ``flow classifier object`` and adds an ``ACL
 198 table`` to the flow classifier.
 199
 200 .. code-block:: c
 201
 202     struct flow_classifier {
 203         struct rte_flow_classifier *cls;
 204     };
 205
 206     struct flow_classifier_acl {
 207         struct flow_classifier cls;
 208     } __rte_cache_aligned;
 209
 210     /* Memory allocation */
 211     size = RTE_CACHE_LINE_ROUNDUP(sizeof(struct flow_classifier_acl));
 212     cls_app = rte_zmalloc(NULL, size, RTE_CACHE_LINE_SIZE);
 213     if (cls_app == NULL)
 214         rte_exit(EXIT_FAILURE, "Cannot allocate classifier memory\n");
 215
 216     cls_params.name = "flow_classifier";
 217     cls_params.socket_id = socket_id;
 218
 219     cls_app->cls = rte_flow_classifier_create(&cls_params);
 220     if (cls_app->cls == NULL) {
 221         rte_free(cls_app);
 222         rte_exit(EXIT_FAILURE, "Cannot create classifier\n");
 223     }
 224
 225     /* initialise ACL table params */
 226     table_acl_params.name = "table_acl_ipv4_5tuple";
 227     table_acl_params.n_rule_fields = RTE_DIM(ipv4_defs);
 228     table_acl_params.n_rules = FLOW_CLASSIFY_MAX_RULE_NUM;
 229     memcpy(table_acl_params.field_format, ipv4_defs, sizeof(ipv4_defs));
 230
 231     /* initialise table create params */
 232     cls_table_params.ops = &rte_table_acl_ops,
 233     cls_table_params.arg_create = &table_acl_params,
 234     cls_table_params.type = RTE_FLOW_CLASSIFY_TABLE_ACL_IP4_5TUPLE;
 235
 236     ret = rte_flow_classify_table_create(cls_app->cls, &cls_table_params);
 237     if (ret) {
 238         rte_flow_classifier_free(cls_app->cls);
 239         rte_free(cls);
 240         rte_exit(EXIT_FAILURE, "Failed to create classifier table\n");
 241     }
 242
 243 It then reads the ipv4_rules_file.txt file and initialises the parameters for
 244 the ``rte_flow_classify_table_entry_add`` API.
 245 This API adds a rule to the ACL table.
 246
 247 .. code-block:: c
 248
 249     if (add_rules(parm_config.rule_ipv4_name)) {
 250         rte_flow_classifier_free(cls_app->cls);
 251         rte_free(cls_app);
 252         rte_exit(EXIT_FAILURE, "Failed to add rules\n");
 253     }
 254
 255 Once the initialization is complete, the application is ready to launch a
 256 function on an lcore. In this example ``lcore_main()`` is called on a single
 257 lcore.
 258
 259 .. code-block:: c
 260
 261     lcore_main(cls_app);
 262
 263 The ``lcore_main()`` function is explained below.
 264
 265 The Port Initialization  Function
 266 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 267
 268 The main functional part of the port initialization used in the Basic
 269 Forwarding application is shown below:
 270
 271 .. code-block:: c
 272
 273     static inline int
 274     port_init(uint8_t port, struct rte_mempool *mbuf_pool)
 275     {
 276         struct rte_eth_conf port_conf = port_conf_default;
 277         const uint16_t rx_rings = 1, tx_rings = 1;
 278         struct rte_ether_addr addr;
 279         int retval;
 280         uint16_t q;
 281
 282         /* Configure the Ethernet device. */
 283         retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf);
 284         if (retval != 0)
 285             return retval;
 286
 287         /* Allocate and set up 1 RX queue per Ethernet port. */
 288         for (q = 0; q < rx_rings; q++) {
 289             retval = rte_eth_rx_queue_setup(port, q, RX_RING_SIZE,
 290                     rte_eth_dev_socket_id(port), NULL, mbuf_pool);
 291             if (retval < 0)
 292                 return retval;
 293         }
 294
 295         /* Allocate and set up 1 TX queue per Ethernet port. */
 296         for (q = 0; q < tx_rings; q++) {
 297             retval = rte_eth_tx_queue_setup(port, q, TX_RING_SIZE,
 298                     rte_eth_dev_socket_id(port), NULL);
 299             if (retval < 0)
 300                 return retval;
 301         }
 302
 303         /* Start the Ethernet port. */
 304         retval = rte_eth_dev_start(port);
 305         if (retval < 0)
 306             return retval;
 307
 308         /* Display the port MAC address. */
 309         rte_eth_macaddr_get(port, &addr);
 310         printf("Port %u MAC: %02" PRIx8 " %02" PRIx8 " %02" PRIx8
 311                " %02" PRIx8 " %02" PRIx8 " %02" PRIx8 "\n",
 312                port,
 313                addr.addr_bytes[0], addr.addr_bytes[1],
 314                addr.addr_bytes[2], addr.addr_bytes[3],
 315                addr.addr_bytes[4], addr.addr_bytes[5]);
 316
 317         /* Enable RX in promiscuous mode for the Ethernet device. */
 318         rte_eth_promiscuous_enable(port);
 319
 320         return 0;
 321     }
 322
 323 The Ethernet ports are configured with default settings using the
 324 ``rte_eth_dev_configure()`` function and the ``port_conf_default`` struct.
 325
 326 .. code-block:: c
 327
 328     static const struct rte_eth_conf port_conf_default = {
 329         .rxmode = { .max_rx_pkt_len = ETHER_MAX_LEN }
 330     };
 331
 332 For this example the ports are set up with 1 RX and 1 TX queue using the
 333 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
 334
 335 The Ethernet port is then started:
 336
 337 .. code-block:: c
 338
 339     retval  = rte_eth_dev_start(port);
 340
 341
 342 Finally the RX port is set in promiscuous mode:
 343
 344 .. code-block:: c
 345
 346     rte_eth_promiscuous_enable(port);
 347
 348 The Add Rules function
 349 ~~~~~~~~~~~~~~~~~~~~~~
 350
 351 The ``add_rules`` function reads the ``ipv4_rules_file.txt`` file and calls the
 352 ``add_classify_rule`` function which calls the
 353 ``rte_flow_classify_table_entry_add`` API.
 354
 355 .. code-block:: c
 356
 357     static int
 358     add_rules(const char *rule_path)
 359     {
 360         FILE *fh;
 361         char buff[LINE_MAX];
 362         unsigned int i = 0;
 363         unsigned int total_num = 0;
 364         struct rte_eth_ntuple_filter ntuple_filter;
 365
 366         fh = fopen(rule_path, "rb");
 367         if (fh == NULL)
 368             rte_exit(EXIT_FAILURE, "%s: Open %s failed\n", __func__,
 369                      rule_path);
 370
 371         fseek(fh, 0, SEEK_SET);
 372
 373         i = 0;
 374         while (fgets(buff, LINE_MAX, fh) != NULL) {
 375             i++;
 376
 377             if (is_bypass_line(buff))
 378                 continue;
 379
 380             if (total_num >= FLOW_CLASSIFY_MAX_RULE_NUM - 1) {
 381                 printf("\nINFO: classify rule capacity %d reached\n",
 382                        total_num);
 383                 break;
 384             }
 385
 386             if (parse_ipv4_5tuple_rule(buff, &ntuple_filter) != 0)
 387                 rte_exit(EXIT_FAILURE,
 388                          "%s Line %u: parse rules error\n",
 389                          rule_path, i);
 390
 391             if (add_classify_rule(&ntuple_filter) != 0)
 392                 rte_exit(EXIT_FAILURE, "add rule error\n");
 393
 394             total_num++;
 395         }
 396
 397         fclose(fh);
 398         return 0;
 399     }
 400
 401
 402 The Lcore Main function
 403 ~~~~~~~~~~~~~~~~~~~~~~~
 404
 405 As we saw above the ``main()`` function calls an application function on the
 406 available lcores.
 407 The ``lcore_main`` function calls the ``rte_flow_classifier_query`` API.
 408 For the Basic Forwarding application the ``lcore_main`` function looks like the
 409 following:
 410
 411 .. code-block:: c
 412
 413     /* flow classify data */
 414     static int num_classify_rules;
 415     static struct rte_flow_classify_rule *rules[MAX_NUM_CLASSIFY];
 416     static struct rte_flow_classify_ipv4_5tuple_stats ntuple_stats;
 417     static struct rte_flow_classify_stats classify_stats = {
 418             .stats = (void *)&ntuple_stats
 419     };
 420
 421     static __attribute__((noreturn)) void
 422     lcore_main(cls_app)
 423     {
 424         uint16_t port;
 425
 426         /*
 427          * Check that the port is on the same NUMA node as the polling thread
 428          * for best performance.
 429          */
 430         RTE_ETH_FOREACH_DEV(port)
 431             if (rte_eth_dev_socket_id(port) > 0 &&
 432                 rte_eth_dev_socket_id(port) != (int)rte_socket_id()) {
 433                 printf("\n\n");
 434                 printf("WARNING: port %u is on remote NUMA node\n",
 435                        port);
 436                 printf("to polling thread.\n");
 437                 printf("Performance will not be optimal.\n");
 438
 439                 printf("\nCore %u forwarding packets. \n",
 440                        rte_lcore_id());
 441                 printf("[Ctrl+C to quit]\n
 442             }
 443
 444         /* Run until the application is quit or killed. */
 445         for (;;) {
 446             /*
 447              * Receive packets on a port and forward them on the paired
 448              * port. The mapping is 0 -> 1, 1 -> 0, 2 -> 3, 3 -> 2, etc.
 449              */
 450             RTE_ETH_FOREACH_DEV(port) {
 451
 452                 /* Get burst of RX packets, from first port of pair. */
 453                 struct rte_mbuf *bufs[BURST_SIZE];
 454                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
 455                         bufs, BURST_SIZE);
 456
 457                 if (unlikely(nb_rx == 0))
 458                     continue;
 459
 460                 for (i = 0; i < MAX_NUM_CLASSIFY; i++) {
 461                     if (rules[i]) {
 462                         ret = rte_flow_classifier_query(
 463                             cls_app->cls,
 464                             bufs, nb_rx, rules[i],
 465                             &classify_stats);
 466                         if (ret)
 467                             printf(
 468                                 "rule [%d] query failed ret [%d]\n\n",
 469                                 i, ret);
 470                         else {
 471                             printf(
 472                                 "rule[%d] count=%"PRIu64"\n",
 473                                 i, ntuple_stats.counter1);
 474
 475                             printf("proto = %d\n",
 476                                 ntuple_stats.ipv4_5tuple.proto);
 477                         }
 478                      }
 479                  }
 480
 481                 /* Send burst of TX packets, to second port of pair. */
 482                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
 483                         bufs, nb_rx);
 484
 485                 /* Free any unsent packets. */
 486                 if (unlikely(nb_tx < nb_rx)) {
 487                     uint16_t buf;
 488                     for (buf = nb_tx; buf < nb_rx; buf++)
 489                         rte_pktmbuf_free(bufs[buf]);
 490                 }
 491             }
 492         }
 493     }
 494
 495 The main work of the application is done within the loop:
 496
 497 .. code-block:: c
 498
 499         for (;;) {
 500             RTE_ETH_FOREACH_DEV(port) {
 501
 502                 /* Get burst of RX packets, from first port of pair. */
 503                 struct rte_mbuf *bufs[BURST_SIZE];
 504                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
 505                         bufs, BURST_SIZE);
 506
 507                 if (unlikely(nb_rx == 0))
 508                     continue;
 509
 510                 /* Send burst of TX packets, to second port of pair. */
 511                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
 512                         bufs, nb_rx);
 513
 514                 /* Free any unsent packets. */
 515                 if (unlikely(nb_tx < nb_rx)) {
 516                     uint16_t buf;
 517                     for (buf = nb_tx; buf < nb_rx; buf++)
 518                         rte_pktmbuf_free(bufs[buf]);
 519                 }
 520             }
 521         }
 522
 523 Packets are received in bursts on the RX ports and transmitted in bursts on
 524 the TX ports. The ports are grouped in pairs with a simple mapping scheme
 525 using the an XOR on the port number::
 526
 527     0 -> 1
 528     1 -> 0
 529
 530     2 -> 3
 531     3 -> 2
 532
 533     etc.
 534
 535 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
 536 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
 537 must be freed explicitly using ``rte_pktmbuf_free()``.
 538
 539 The forwarding loop can be interrupted and the application closed using
 540 ``Ctrl-C``.