1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2015 Intel Corporation. 3 4RX/TX Callbacks Sample Application 5================================== 6 7Overview 8-------- 9 10The RX/TX Callbacks sample application is a packet forwarding application that 11demonstrates the use of user defined callbacks on received and transmitted 12packets. The application performs a simple latency check, using callbacks, to 13determine the time that packets spend within the application. 14 15In the sample application, a user defined callback is applied to all received 16packets to add a timestamp. A separate callback is applied to all packets 17prior to transmission to calculate the elapsed time in CPU cycles. 18 19If hardware timestamping is supported by the NIC, the sample application will 20also display the average latency. 21The packet was timestamped in hardware 22on top of the latency since the packet was received and processed by the RX 23callback. 24 25 26Compiling the Application 27------------------------- 28 29To compile the sample application, see :doc:`compiling`. 30 31The application is located in the ``rxtx_callbacks`` sub-directory. 32 33 34Running the Application 35----------------------- 36 37To run the example in a ``linux`` environment: 38 39.. code-block:: console 40 41 ./<build_dir>/examples/dpdk-rxtx_callbacks -l 1 -n 4 -- [-t] 42 43Use -t to enable hardware timestamping. If not supported by the NIC, an error 44will be displayed. 45 46Refer to *DPDK Getting Started Guide* for general information on running 47applications and the Environment Abstraction Layer (EAL) options. 48 49 50 51Explanation 52----------- 53 54The ``rxtx_callbacks`` application is mainly a simple forwarding application 55based on the :doc:`skeleton`. See that section of the documentation for more 56details of the forwarding part of the application. 57 58The sections below explain the additional RX/TX callback code. 59 60 61The Main Function 62~~~~~~~~~~~~~~~~~ 63 64The ``main()`` function performs the application initialization and calls the 65execution threads for each lcore. This function is effectively identical to 66the ``main()`` function explained in :doc:`skeleton`. 67 68The ``lcore_main()`` function is also identical. 69 70The main difference is in the user defined ``port_init()`` function where the 71callbacks are added. This is explained in the next section: 72 73 74The Port Initialization Function 75~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 76 77The main functional part of the port initialization is shown below with 78comments: 79 80.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 81 :language: c 82 :start-after: Port initialization. 8< 83 :end-before: >8 End of port initialization. 84 85 86The RX and TX callbacks are added to the ports/queues as function pointers: 87 88.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 89 :language: c 90 :start-after: RX and TX callbacks are added to the ports. 8< 91 :end-before: >8 End of RX and TX callbacks. 92 :dedent: 1 93 94More than one callback can be added and additional information can be passed 95to callback function pointers as a ``void*``. In the examples above ``NULL`` 96is used. 97 98The ``add_timestamps()`` and ``calc_latency()`` functions are explained below. 99 100 101The add_timestamps() Callback 102~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 103 104The ``add_timestamps()`` callback is added to the RX port and is applied to 105all packets received: 106 107.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 108 :language: c 109 :start-after: Callback added to the RX port and applied to packets. 8< 110 :end-before: >8 End of callback addition and application. 111 112The DPDK function ``rte_rdtsc()`` is used to add a cycle count timestamp to 113each packet (see the *cycles* section of the *DPDK API Documentation* for 114details). 115 116 117The calc_latency() Callback 118~~~~~~~~~~~~~~~~~~~~~~~~~~~ 119 120The ``calc_latency()`` callback is added to the TX port and is applied to all 121packets prior to transmission: 122 123.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 124 :language: c 125 :start-after: Callback is added to the TX port. 8< 126 :end-before: >8 End of callback addition. 127 128The ``calc_latency()`` function accumulates the total number of packets and 129the total number of cycles used. Once more than 100 million packets have been 130transmitted, the average cycle count per packet is printed out 131and the counters are reset. 132