1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2015 Intel Corporation.
4 RX/TX Callbacks Sample Application
5 ==================================
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.
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.
17 Compiling the Application
18 -------------------------
20 To compile the sample application see :doc:`compiling`.
22 The application is located in the ``rxtx_callbacks`` sub-directory.
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:
28 .. code-block:: console
30 CONFIG_RTE_ETHDEV_RXTX_CALLBACKS=y
32 Running the Application
33 -----------------------
35 To run the example in a ``linuxapp`` environment:
37 .. code-block:: console
39 ./build/rxtx_callbacks -l 1 -n 4
41 Refer to *DPDK Getting Started Guide* for general information on running
42 applications and the Environment Abstraction Layer (EAL) options.
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.
53 The sections below explain the additional RX/TX callback code.
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`.
63 The ``lcore_main()`` function is also identical.
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:
69 The Port Initialization Function
70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72 The main functional part of the port initialization is shown below with
78 port_init(uint16_t port, struct rte_mempool *mbuf_pool)
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;
86 if (port >= rte_eth_dev_count())
89 /* Configure the Ethernet device. */
90 retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf);
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);
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);
110 /* Start the Ethernet port. */
111 retval = rte_eth_dev_start(port);
115 /* Enable RX in promiscuous mode for the Ethernet device. */
116 rte_eth_promiscuous_enable(port);
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);
127 The RX and TX callbacks are added to the ports/queues as function pointers:
131 rte_eth_add_rx_callback(port, 0, add_timestamps, NULL);
132 rte_eth_add_tx_callback(port, 0, calc_latency, NULL);
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``
138 The ``add_timestamps()`` and ``calc_latency()`` functions are explained below.
141 The add_timestamps() Callback
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
144 The ``add_timestamps()`` callback is added to the RX port and is applied to
145 all packets received:
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)
154 uint64_t now = rte_rdtsc();
156 for (i = 0; i < nb_pkts; i++)
157 pkts[i]->udata64 = now;
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
167 The calc_latency() Callback
168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
170 The ``calc_latency()`` callback is added to the TX port and is applied to all
171 packets prior to transmission:
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)
180 uint64_t now = rte_rdtsc();
183 for (i = 0; i < nb_pkts; i++)
184 cycles += now - pkts[i]->udata64;
186 latency_numbers.total_cycles += cycles;
187 latency_numbers.total_pkts += nb_pkts;
189 if (latency_numbers.total_pkts > (100 * 1000 * 1000ULL)) {
190 printf("Latency = %"PRIu64" cycles\n",
191 latency_numbers.total_cycles / latency_numbers.total_pkts);
193 latency_numbers.total_cycles = latency_numbers.total_pkts = 0;
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