15630257fSFerruh Yigit.. SPDX-License-Identifier: BSD-3-Clause 25630257fSFerruh Yigit Copyright(c) 2015 Intel Corporation. 30d8d3df6SJohn McNamara 40d8d3df6SJohn McNamaraRX/TX Callbacks Sample Application 50d8d3df6SJohn McNamara================================== 60d8d3df6SJohn McNamara 7*8750576fSNandini PersadOverview 8*8750576fSNandini Persad-------- 9*8750576fSNandini Persad 100d8d3df6SJohn McNamaraThe RX/TX Callbacks sample application is a packet forwarding application that 110d8d3df6SJohn McNamarademonstrates the use of user defined callbacks on received and transmitted 120d8d3df6SJohn McNamarapackets. The application performs a simple latency check, using callbacks, to 13*8750576fSNandini Persaddetermine the time that packets spend within the application. 140d8d3df6SJohn McNamara 15*8750576fSNandini PersadIn the sample application, a user defined callback is applied to all received 160d8d3df6SJohn McNamarapackets to add a timestamp. A separate callback is applied to all packets 17*8750576fSNandini Persadprior to transmission to calculate the elapsed time in CPU cycles. 180d8d3df6SJohn McNamara 19cd1dadebSTom BarbetteIf hardware timestamping is supported by the NIC, the sample application will 20*8750576fSNandini Persadalso display the average latency. 21*8750576fSNandini PersadThe packet was timestamped in hardware 22cd1dadebSTom Barbetteon top of the latency since the packet was received and processed by the RX 23cd1dadebSTom Barbettecallback. 240d8d3df6SJohn McNamara 25*8750576fSNandini Persad 260d8d3df6SJohn McNamaraCompiling the Application 270d8d3df6SJohn McNamara------------------------- 280d8d3df6SJohn McNamara 29*8750576fSNandini PersadTo compile the sample application, see :doc:`compiling`. 300d8d3df6SJohn McNamara 317cacb056SHerakliusz LipiecThe application is located in the ``rxtx_callbacks`` sub-directory. 320d8d3df6SJohn McNamara 330d8d3df6SJohn McNamara 340d8d3df6SJohn McNamaraRunning the Application 350d8d3df6SJohn McNamara----------------------- 360d8d3df6SJohn McNamara 37218c4e68SBruce RichardsonTo run the example in a ``linux`` environment: 380d8d3df6SJohn McNamara 390d8d3df6SJohn McNamara.. code-block:: console 400d8d3df6SJohn McNamara 41e2a94f9aSCiara Power ./<build_dir>/examples/dpdk-rxtx_callbacks -l 1 -n 4 -- [-t] 42cd1dadebSTom Barbette 43cd1dadebSTom BarbetteUse -t to enable hardware timestamping. If not supported by the NIC, an error 44cd1dadebSTom Barbettewill be displayed. 450d8d3df6SJohn McNamara 460d8d3df6SJohn McNamaraRefer to *DPDK Getting Started Guide* for general information on running 470d8d3df6SJohn McNamaraapplications and the Environment Abstraction Layer (EAL) options. 480d8d3df6SJohn McNamara 490d8d3df6SJohn McNamara 500d8d3df6SJohn McNamara 510d8d3df6SJohn McNamaraExplanation 520d8d3df6SJohn McNamara----------- 530d8d3df6SJohn McNamara 540d8d3df6SJohn McNamaraThe ``rxtx_callbacks`` application is mainly a simple forwarding application 550d8d3df6SJohn McNamarabased on the :doc:`skeleton`. See that section of the documentation for more 560d8d3df6SJohn McNamaradetails of the forwarding part of the application. 570d8d3df6SJohn McNamara 580d8d3df6SJohn McNamaraThe sections below explain the additional RX/TX callback code. 590d8d3df6SJohn McNamara 600d8d3df6SJohn McNamara 610d8d3df6SJohn McNamaraThe Main Function 620d8d3df6SJohn McNamara~~~~~~~~~~~~~~~~~ 630d8d3df6SJohn McNamara 640d8d3df6SJohn McNamaraThe ``main()`` function performs the application initialization and calls the 650d8d3df6SJohn McNamaraexecution threads for each lcore. This function is effectively identical to 660d8d3df6SJohn McNamarathe ``main()`` function explained in :doc:`skeleton`. 670d8d3df6SJohn McNamara 680d8d3df6SJohn McNamaraThe ``lcore_main()`` function is also identical. 690d8d3df6SJohn McNamara 700d8d3df6SJohn McNamaraThe main difference is in the user defined ``port_init()`` function where the 710d8d3df6SJohn McNamaracallbacks are added. This is explained in the next section: 720d8d3df6SJohn McNamara 730d8d3df6SJohn McNamara 740d8d3df6SJohn McNamaraThe Port Initialization Function 75*8750576fSNandini Persad~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 760d8d3df6SJohn McNamara 770d8d3df6SJohn McNamaraThe main functional part of the port initialization is shown below with 780d8d3df6SJohn McNamaracomments: 790d8d3df6SJohn McNamara 809a212dc0SConor Fogarty.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 819a212dc0SConor Fogarty :language: c 829a212dc0SConor Fogarty :start-after: Port initialization. 8< 839a212dc0SConor Fogarty :end-before: >8 End of port initialization. 840d8d3df6SJohn McNamara 850d8d3df6SJohn McNamara 860d8d3df6SJohn McNamaraThe RX and TX callbacks are added to the ports/queues as function pointers: 870d8d3df6SJohn McNamara 889a212dc0SConor Fogarty.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 899a212dc0SConor Fogarty :language: c 909a212dc0SConor Fogarty :start-after: RX and TX callbacks are added to the ports. 8< 919a212dc0SConor Fogarty :end-before: >8 End of RX and TX callbacks. 929a212dc0SConor Fogarty :dedent: 1 930d8d3df6SJohn McNamara 940d8d3df6SJohn McNamaraMore than one callback can be added and additional information can be passed 950d8d3df6SJohn McNamarato callback function pointers as a ``void*``. In the examples above ``NULL`` 960d8d3df6SJohn McNamarais used. 970d8d3df6SJohn McNamara 980d8d3df6SJohn McNamaraThe ``add_timestamps()`` and ``calc_latency()`` functions are explained below. 990d8d3df6SJohn McNamara 1000d8d3df6SJohn McNamara 1010d8d3df6SJohn McNamaraThe add_timestamps() Callback 1020d8d3df6SJohn McNamara~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1030d8d3df6SJohn McNamara 1040d8d3df6SJohn McNamaraThe ``add_timestamps()`` callback is added to the RX port and is applied to 1050d8d3df6SJohn McNamaraall packets received: 1060d8d3df6SJohn McNamara 1079a212dc0SConor Fogarty.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 1089a212dc0SConor Fogarty :language: c 1099a212dc0SConor Fogarty :start-after: Callback added to the RX port and applied to packets. 8< 1109a212dc0SConor Fogarty :end-before: >8 End of callback addition and application. 1110d8d3df6SJohn McNamara 1120d8d3df6SJohn McNamaraThe DPDK function ``rte_rdtsc()`` is used to add a cycle count timestamp to 1130d8d3df6SJohn McNamaraeach packet (see the *cycles* section of the *DPDK API Documentation* for 1140d8d3df6SJohn McNamaradetails). 1150d8d3df6SJohn McNamara 1160d8d3df6SJohn McNamara 1170d8d3df6SJohn McNamaraThe calc_latency() Callback 1180d8d3df6SJohn McNamara~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1190d8d3df6SJohn McNamara 1200d8d3df6SJohn McNamaraThe ``calc_latency()`` callback is added to the TX port and is applied to all 1210d8d3df6SJohn McNamarapackets prior to transmission: 1220d8d3df6SJohn McNamara 1239a212dc0SConor Fogarty.. literalinclude:: ../../../examples/rxtx_callbacks/main.c 1249a212dc0SConor Fogarty :language: c 1259a212dc0SConor Fogarty :start-after: Callback is added to the TX port. 8< 1269a212dc0SConor Fogarty :end-before: >8 End of callback addition. 1270d8d3df6SJohn McNamara 1280d8d3df6SJohn McNamaraThe ``calc_latency()`` function accumulates the total number of packets and 1290d8d3df6SJohn McNamarathe total number of cycles used. Once more than 100 million packets have been 130*8750576fSNandini Persadtransmitted, the average cycle count per packet is printed out 131*8750576fSNandini Persadand the counters are reset. 132