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     ./<build_dir>/examples/dpdk-flow_classify -c 4 -n 4 -- /
  32     --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 rte_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 rte_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 rte_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 rte_ipv4_hdr) +
 129                 offsetof(struct rte_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 rte_ipv4_hdr) +
 139                  offsetof(struct rte_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(uint16_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         retval = rte_eth_macaddr_get(port, &addr);
 310         if (retval < 0)
 311             return retval;
 312         printf("Port %u MAC: %02" PRIx8 " %02" PRIx8 " %02" PRIx8
 313                " %02" PRIx8 " %02" PRIx8 " %02" PRIx8 "\n",
 314                port,
 315                addr.addr_bytes[0], addr.addr_bytes[1],
 316                addr.addr_bytes[2], addr.addr_bytes[3],
 317                addr.addr_bytes[4], addr.addr_bytes[5]);
 318
 319         /* Enable RX in promiscuous mode for the Ethernet device. */
 320         retval = rte_eth_promiscuous_enable(port);
 321         if (retval != 0)
 322                 return retval;
 323
 324         return 0;
 325     }
 326
 327 The Ethernet ports are configured with default settings using the
 328 ``rte_eth_dev_configure()`` function and the ``port_conf_default`` struct.
 329
 330 .. code-block:: c
 331
 332     static const struct rte_eth_conf port_conf_default = {
 333         .rxmode = { .max_rx_pkt_len = RTE_ETHER_MAX_LEN }
 334     };
 335
 336 For this example the ports are set up with 1 RX and 1 TX queue using the
 337 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
 338
 339 The Ethernet port is then started:
 340
 341 .. code-block:: c
 342
 343     retval  = rte_eth_dev_start(port);
 344
 345
 346 Finally the RX port is set in promiscuous mode:
 347
 348 .. code-block:: c
 349
 350     retval = rte_eth_promiscuous_enable(port);
 351
 352 The Add Rules function
 353 ~~~~~~~~~~~~~~~~~~~~~~
 354
 355 The ``add_rules`` function reads the ``ipv4_rules_file.txt`` file and calls the
 356 ``add_classify_rule`` function which calls the
 357 ``rte_flow_classify_table_entry_add`` API.
 358
 359 .. code-block:: c
 360
 361     static int
 362     add_rules(const char *rule_path)
 363     {
 364         FILE *fh;
 365         char buff[LINE_MAX];
 366         unsigned int i = 0;
 367         unsigned int total_num = 0;
 368         struct rte_eth_ntuple_filter ntuple_filter;
 369
 370         fh = fopen(rule_path, "rb");
 371         if (fh == NULL)
 372             rte_exit(EXIT_FAILURE, "%s: Open %s failed\n", __func__,
 373                      rule_path);
 374
 375         fseek(fh, 0, SEEK_SET);
 376
 377         i = 0;
 378         while (fgets(buff, LINE_MAX, fh) != NULL) {
 379             i++;
 380
 381             if (is_bypass_line(buff))
 382                 continue;
 383
 384             if (total_num >= FLOW_CLASSIFY_MAX_RULE_NUM - 1) {
 385                 printf("\nINFO: classify rule capacity %d reached\n",
 386                        total_num);
 387                 break;
 388             }
 389
 390             if (parse_ipv4_5tuple_rule(buff, &ntuple_filter) != 0)
 391                 rte_exit(EXIT_FAILURE,
 392                          "%s Line %u: parse rules error\n",
 393                          rule_path, i);
 394
 395             if (add_classify_rule(&ntuple_filter) != 0)
 396                 rte_exit(EXIT_FAILURE, "add rule error\n");
 397
 398             total_num++;
 399         }
 400
 401         fclose(fh);
 402         return 0;
 403     }
 404
 405
 406 The Lcore Main function
 407 ~~~~~~~~~~~~~~~~~~~~~~~
 408
 409 As we saw above the ``main()`` function calls an application function on the
 410 available lcores.
 411 The ``lcore_main`` function calls the ``rte_flow_classifier_query`` API.
 412 For the Basic Forwarding application the ``lcore_main`` function looks like the
 413 following:
 414
 415 .. code-block:: c
 416
 417     /* flow classify data */
 418     static int num_classify_rules;
 419     static struct rte_flow_classify_rule *rules[MAX_NUM_CLASSIFY];
 420     static struct rte_flow_classify_ipv4_5tuple_stats ntuple_stats;
 421     static struct rte_flow_classify_stats classify_stats = {
 422             .stats = (void *)&ntuple_stats
 423     };
 424
 425     static __rte_noreturn void
 426     lcore_main(cls_app)
 427     {
 428         uint16_t port;
 429
 430         /*
 431          * Check that the port is on the same NUMA node as the polling thread
 432          * for best performance.
 433          */
 434         RTE_ETH_FOREACH_DEV(port)
 435             if (rte_eth_dev_socket_id(port) > 0 &&
 436                 rte_eth_dev_socket_id(port) != (int)rte_socket_id()) {
 437                 printf("\n\n");
 438                 printf("WARNING: port %u is on remote NUMA node\n",
 439                        port);
 440                 printf("to polling thread.\n");
 441                 printf("Performance will not be optimal.\n");
 442
 443                 printf("\nCore %u forwarding packets. \n",
 444                        rte_lcore_id());
 445                 printf("[Ctrl+C to quit]\n
 446             }
 447
 448         /* Run until the application is quit or killed. */
 449         for (;;) {
 450             /*
 451              * Receive packets on a port and forward them on the paired
 452              * port. The mapping is 0 -> 1, 1 -> 0, 2 -> 3, 3 -> 2, etc.
 453              */
 454             RTE_ETH_FOREACH_DEV(port) {
 455
 456                 /* Get burst of RX packets, from first port of pair. */
 457                 struct rte_mbuf *bufs[BURST_SIZE];
 458                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
 459                         bufs, BURST_SIZE);
 460
 461                 if (unlikely(nb_rx == 0))
 462                     continue;
 463
 464                 for (i = 0; i < MAX_NUM_CLASSIFY; i++) {
 465                     if (rules[i]) {
 466                         ret = rte_flow_classifier_query(
 467                             cls_app->cls,
 468                             bufs, nb_rx, rules[i],
 469                             &classify_stats);
 470                         if (ret)
 471                             printf(
 472                                 "rule [%d] query failed ret [%d]\n\n",
 473                                 i, ret);
 474                         else {
 475                             printf(
 476                                 "rule[%d] count=%"PRIu64"\n",
 477                                 i, ntuple_stats.counter1);
 478
 479                             printf("proto = %d\n",
 480                                 ntuple_stats.ipv4_5tuple.proto);
 481                         }
 482                      }
 483                  }
 484
 485                 /* Send burst of TX packets, to second port of pair. */
 486                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
 487                         bufs, nb_rx);
 488
 489                 /* Free any unsent packets. */
 490                 if (unlikely(nb_tx < nb_rx)) {
 491                     uint16_t buf;
 492                     for (buf = nb_tx; buf < nb_rx; buf++)
 493                         rte_pktmbuf_free(bufs[buf]);
 494                 }
 495             }
 496         }
 497     }
 498
 499 The main work of the application is done within the loop:
 500
 501 .. code-block:: c
 502
 503         for (;;) {
 504             RTE_ETH_FOREACH_DEV(port) {
 505
 506                 /* Get burst of RX packets, from first port of pair. */
 507                 struct rte_mbuf *bufs[BURST_SIZE];
 508                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
 509                         bufs, BURST_SIZE);
 510
 511                 if (unlikely(nb_rx == 0))
 512                     continue;
 513
 514                 /* Send burst of TX packets, to second port of pair. */
 515                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
 516                         bufs, nb_rx);
 517
 518                 /* Free any unsent packets. */
 519                 if (unlikely(nb_tx < nb_rx)) {
 520                     uint16_t buf;
 521                     for (buf = nb_tx; buf < nb_rx; buf++)
 522                         rte_pktmbuf_free(bufs[buf]);
 523                 }
 524             }
 525         }
 526
 527 Packets are received in bursts on the RX ports and transmitted in bursts on
 528 the TX ports. The ports are grouped in pairs with a simple mapping scheme
 529 using the an XOR on the port number::
 530
 531     0 -> 1
 532     1 -> 0
 533
 534     2 -> 3
 535     3 -> 2
 536
 537     etc.
 538
 539 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
 540 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
 541 must be freed explicitly using ``rte_pktmbuf_free()``.
 542
 543 The forwarding loop can be interrupted and the application closed using
 544 ``Ctrl-C``.