doc/guides/sample_app_ug/rxtx_callbacks.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015 Intel Corporation.
   3
   4 RX/TX Callbacks Sample Application
   5 ==================================
   6
   7 The RX/TX Callbacks sample application is a packet forwarding application that
   8 demonstrates the use of user defined callbacks on received and transmitted
   9 packets. The application performs a simple latency check, using callbacks, to
  10 determine the time packets spend within the application.
  11
  12 In the sample application a user defined callback is applied to all received
  13 packets to add a timestamp. A separate callback is applied to all packets
  14 prior to transmission to calculate the elapsed time, in CPU cycles.
  15
  16
  17 Compiling the Application
  18 -------------------------
  19
  20 To compile the sample application see :doc:`compiling`.
  21
  22 The application is located in the ``rxtx_callbacks`` sub-directory.
  23
  24 The callbacks feature requires that the ``CONFIG_RTE_ETHDEV_RXTX_CALLBACKS``
  25 setting is on in the ``config/common_`` config file that applies to the
  26 target. This is generally on by default:
  27
  28 .. code-block:: console
  29
  30     CONFIG_RTE_ETHDEV_RXTX_CALLBACKS=y
  31
  32 Running the Application
  33 -----------------------
  34
  35 To run the example in a ``linuxapp`` environment:
  36
  37 .. code-block:: console
  38
  39     ./build/rxtx_callbacks -l 1 -n 4
  40
  41 Refer to *DPDK Getting Started Guide* for general information on running
  42 applications and the Environment Abstraction Layer (EAL) options.
  43
  44
  45
  46 Explanation
  47 -----------
  48
  49 The ``rxtx_callbacks`` application is mainly a simple forwarding application
  50 based on the :doc:`skeleton`. See that section of the documentation for more
  51 details of the forwarding part of the application.
  52
  53 The sections below explain the additional RX/TX callback code.
  54
  55
  56 The Main Function
  57 ~~~~~~~~~~~~~~~~~
  58
  59 The ``main()`` function performs the application initialization and calls the
  60 execution threads for each lcore. This function is effectively identical to
  61 the ``main()`` function explained in :doc:`skeleton`.
  62
  63 The ``lcore_main()`` function is also identical.
  64
  65 The main difference is in the user defined ``port_init()`` function where the
  66 callbacks are added. This is explained in the next section:
  67
  68
  69 The Port Initialization  Function
  70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  71
  72 The main functional part of the port initialization is shown below with
  73 comments:
  74
  75 .. code-block:: c
  76
  77     static inline int
  78     port_init(uint16_t port, struct rte_mempool *mbuf_pool)
  79     {
  80         struct rte_eth_conf port_conf = port_conf_default;
  81         const uint16_t rx_rings = 1, tx_rings = 1;
  82         struct ether_addr addr;
  83         int retval;
  84         uint16_t q;
  85
  86         if (port >= rte_eth_dev_count())
  87             return -1;
  88
  89         /* Configure the Ethernet device. */
  90         retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf);
  91         if (retval != 0)
  92             return retval;
  93
  94         /* Allocate and set up 1 RX queue per Ethernet port. */
  95         for (q = 0; q < rx_rings; q++) {
  96             retval = rte_eth_rx_queue_setup(port, q, RX_RING_SIZE,
  97                     rte_eth_dev_socket_id(port), NULL, mbuf_pool);
  98             if (retval < 0)
  99                 return retval;
 100         }
 101
 102         /* Allocate and set up 1 TX queue per Ethernet port. */
 103         for (q = 0; q < tx_rings; q++) {
 104             retval = rte_eth_tx_queue_setup(port, q, TX_RING_SIZE,
 105                     rte_eth_dev_socket_id(port), NULL);
 106             if (retval < 0)
 107                 return retval;
 108         }
 109
 110         /* Start the Ethernet port. */
 111         retval = rte_eth_dev_start(port);
 112         if (retval < 0)
 113             return retval;
 114
 115         /* Enable RX in promiscuous mode for the Ethernet device. */
 116         rte_eth_promiscuous_enable(port);
 117
 118
 119         /* Add the callbacks for RX and TX.*/
 120         rte_eth_add_rx_callback(port, 0, add_timestamps, NULL);
 121         rte_eth_add_tx_callback(port, 0, calc_latency, NULL);
 122
 123         return 0;
 124     }
 125
 126
 127 The RX and TX callbacks are added to the ports/queues as function pointers:
 128
 129 .. code-block:: c
 130
 131         rte_eth_add_rx_callback(port, 0, add_timestamps, NULL);
 132         rte_eth_add_tx_callback(port, 0, calc_latency,   NULL);
 133
 134 More than one callback can be added and additional information can be passed
 135 to callback function pointers as a ``void*``. In the examples above ``NULL``
 136 is used.
 137
 138 The ``add_timestamps()`` and ``calc_latency()`` functions are explained below.
 139
 140
 141 The add_timestamps() Callback
 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 143
 144 The ``add_timestamps()`` callback is added to the RX port and is applied to
 145 all packets received:
 146
 147 .. code-block:: c
 148
 149     static uint16_t
 150     add_timestamps(uint16_t port __rte_unused, uint16_t qidx __rte_unused,
 151             struct rte_mbuf **pkts, uint16_t nb_pkts, void *_ __rte_unused)
 152     {
 153         unsigned i;
 154         uint64_t now = rte_rdtsc();
 155
 156         for (i = 0; i < nb_pkts; i++)
 157             pkts[i]->udata64 = now;
 158
 159         return nb_pkts;
 160     }
 161
 162 The DPDK function ``rte_rdtsc()`` is used to add a cycle count timestamp to
 163 each packet (see the *cycles* section of the *DPDK API Documentation* for
 164 details).
 165
 166
 167 The calc_latency() Callback
 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 169
 170 The ``calc_latency()`` callback is added to the TX port and is applied to all
 171 packets prior to transmission:
 172
 173 .. code-block:: c
 174
 175     static uint16_t
 176     calc_latency(uint16_t port __rte_unused, uint16_t qidx __rte_unused,
 177             struct rte_mbuf **pkts, uint16_t nb_pkts, void *_ __rte_unused)
 178     {
 179         uint64_t cycles = 0;
 180         uint64_t now = rte_rdtsc();
 181         unsigned i;
 182
 183         for (i = 0; i < nb_pkts; i++)
 184             cycles += now - pkts[i]->udata64;
 185
 186         latency_numbers.total_cycles += cycles;
 187         latency_numbers.total_pkts   += nb_pkts;
 188
 189         if (latency_numbers.total_pkts > (100 * 1000 * 1000ULL)) {
 190             printf("Latency = %"PRIu64" cycles\n",
 191                     latency_numbers.total_cycles / latency_numbers.total_pkts);
 192
 193             latency_numbers.total_cycles = latency_numbers.total_pkts = 0;
 194         }
 195
 196         return nb_pkts;
 197     }
 198
 199 The ``calc_latency()`` function accumulates the total number of packets and
 200 the total number of cycles used. Once more than 100 million packets have been
 201 transmitted the average cycle count per packet is printed out and the counters
 202 are reset.