1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Link Status Interrupt Sample Application 5======================================== 6 7The Link Status Interrupt sample application is an example of packet processing using 8the Data Plane Development Kit (DPDK) that 9demonstrates how network link status changes for a network port can be captured and 10used by a DPDK application. 11 12Overview 13-------- 14 15The Link Status Interrupt sample application registers a user space callback for the link status interrupt of each port 16and performs L2 forwarding for each packet that is received on an RX_PORT. 17 18The following operations are performed: 19 20* RX_PORT and TX_PORT are paired with available ports one-by-one according to the core mask 21 22* The source MAC address is replaced by the TX_PORT MAC address 23 24* The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID 25 26This application can be used to demonstrate the usage of link status interrupt and its user space callbacks 27and the behavior of L2 forwarding each time the link status changes. 28 29Compiling the Application 30------------------------- 31 32To compile the sample application, see :doc:`compiling`. 33 34The application is located in the ``link_status_interrupt`` sub-directory. 35 36Running the Application 37----------------------- 38 39The application requires a number of command line options: 40 41.. code-block:: console 42 43 ./<build_dir>/examples/dpdk-link_status_interrupt [EAL options] -- -p PORTMASK [-q NQ][-T PERIOD] 44 45where, 46 47* -p PORTMASK: A hexadecimal bitmask of the ports to configure 48 49* -q NQ: Maximum number of queues per lcore (default is 1) 50 51* -T PERIOD: statistics will be refreshed each PERIOD seconds (0 to disable, 10 default) 52 53To run the application in a linux environment with 4 lcores, 4 memory channels, 16 ports and 8 RX queues per lcore, 54issue the command: 55 56.. code-block:: console 57 58 $ ./<build_dir>/examples/dpdk-link_status_interrupt -l 0-3 -n 4-- -q 8 -p ffff 59 60Refer to the *DPDK Getting Started Guide* for general information on running applications 61and the Environment Abstraction Layer (EAL) options. 62 63Explanation 64----------- 65 66The following sections provide some explanation of the code. 67 68Command Line Arguments 69~~~~~~~~~~~~~~~~~~~~~~ 70 71The Link Status Interrupt sample application takes specific parameters 72and Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_). 73 74Command line parsing is done in the same way as it is done in the L2 Forwarding Sample Application. 75See :ref:`l2_fwd_app_cmd_arguments` for more information. 76 77Mbuf Pool Initialization 78~~~~~~~~~~~~~~~~~~~~~~~~ 79 80Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding Sample Application. 81See :ref:`l2_fwd_app_mbuf_init` for more information. 82 83Driver Initialization 84~~~~~~~~~~~~~~~~~~~~~ 85 86The main part of the code in the main() function relates to the initialization of the driver. 87To fully understand this code, it is recommended to study the chapters that related to the Poll Mode Driver in the 88*DPDK Programmer's Guide and the DPDK API Reference*. 89 90.. literalinclude:: ../../../examples/link_status_interrupt/main.c 91 :language: c 92 :start-after: Each logical core is assigned a dedicated TX queue on each port. 8< 93 :end-before: >8 End of assigning logical core. 94 :dedent: 1 95 96The next step is to configure the RX and TX queues. 97For each port, there is only one RX queue (only one lcore is able to poll a given port). 98The number of TX queues depends on the number of available lcores. 99The rte_eth_dev_configure() function is used to configure the number of queues for a port: 100 101.. literalinclude:: ../../../examples/link_status_interrupt/main.c 102 :language: c 103 :start-after: Configure RX and TX queues. 8< 104 :end-before: >8 End of configure RX and TX queues. 105 :dedent: 2 106 107The global configuration is stored in a static structure: 108 109.. literalinclude:: ../../../examples/link_status_interrupt/main.c 110 :language: c 111 :start-after: Global configuration stored in a static structure. 8< 112 :end-before: >8 End of global configuration stored in a static structure. 113 114Configuring lsc to 0 (the default) disables the generation of any link status change interrupts in kernel space 115and no user space interrupt event is received. 116The public interface rte_eth_link_get() accesses the NIC registers directly to update the link status. 117Configuring lsc to non-zero enables the generation of link status change interrupts in kernel space 118when a link status change is present and calls the user space callbacks registered by the application. 119The public interface rte_eth_link_get() just reads the link status in a global structure 120that would be updated in the interrupt host thread only. 121 122Interrupt Callback Registration 123~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 124 125The application can register one or more callbacks to a specific port and interrupt event. 126An example callback function that has been written as indicated below. 127 128.. literalinclude:: ../../../examples/link_status_interrupt/main.c 129 :language: c 130 :start-after: lsi_event_callback 8< 131 :end-before: >8 End of registering one or more callbacks. 132 133This function is called when a link status interrupt is present for the right port. 134The port_id indicates which port the interrupt applies to. 135The type parameter identifies the interrupt event type, 136which currently can be RTE_ETH_EVENT_INTR_LSC only, but other types can be added in the future. 137The param parameter is the address of the parameter for the callback. 138This function should be implemented with care since it will be called in the interrupt host thread, 139which is different from the main thread of its caller. 140 141The application registers the lsi_event_callback and a NULL parameter to the link status interrupt event on each port: 142 143.. literalinclude:: ../../../examples/link_status_interrupt/main.c 144 :language: c 145 :start-after: RTE callback register. 8< 146 :end-before: >8 End of registering lsi interrupt callback. 147 :dedent: 2 148 149This registration can be done only after calling the rte_eth_dev_configure() function and before calling any other function. 150If lsc is initialized with 0, the callback is never called since no interrupt event would ever be present. 151 152RX Queue Initialization 153~~~~~~~~~~~~~~~~~~~~~~~ 154 155The application uses one lcore to poll one or several ports, depending on the -q option, 156which specifies the number of queues per lcore. 157 158For example, if the user specifies -q 4, the application is able to poll four ports with one lcore. 159If there are 16 ports on the target (and if the portmask argument is -p ffff), 160the application will need four lcores to poll all the ports. 161 162.. literalinclude:: ../../../examples/link_status_interrupt/main.c 163 :language: c 164 :start-after: RX queue initialization. 8< 165 :end-before: >8 End of RX queue initialization. 166 :dedent: 2 167 168The list of queues that must be polled for a given lcore is stored in a private structure called struct lcore_queue_conf. 169 170.. literalinclude:: ../../../examples/link_status_interrupt/main.c 171 :language: c 172 :start-after: List of queues must be polled for a give lcore. 8< 173 :end-before: >8 End of list of queues to be polled. 174 175The n_rx_port and rx_port_list[] fields are used in the main packet processing loop 176(see `Receive, Process and Transmit Packets`_). 177 178The global configuration for the RX queues is stored in a static structure: 179 180.. literalinclude:: ../../../examples/link_status_interrupt/main.c 181 :language: c 182 :start-after: List of queues must be polled for a give lcore. 8< 183 :end-before: >8 End of list of queues to be polled. 184 185TX Queue Initialization 186~~~~~~~~~~~~~~~~~~~~~~~ 187 188Each lcore should be able to transmit on any port. 189For every port, a single TX queue is initialized. 190 191.. literalinclude:: ../../../examples/link_status_interrupt/main.c 192 :language: c 193 :start-after: init one TX queue logical core on each port. 8< 194 :end-before: >8 End of init one TX queue. 195 :dedent: 2 196 197The global configuration for TX queues is stored in a static structure: 198 199.. code-block:: c 200 201 static const struct rte_eth_txconf tx_conf = { 202 .tx_thresh = { 203 .pthresh = TX_PTHRESH, 204 .hthresh = TX_HTHRESH, 205 .wthresh = TX_WTHRESH, 206 }, 207 .tx_free_thresh = TX_DESC_DEFAULT + 1, /* disable feature */ 208 }; 209 210Receive, Process and Transmit Packets 211~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 212 213In the lsi_main_loop() function, the main task is to read ingress packets from the RX queues. 214This is done using the following code: 215 216.. literalinclude:: ../../../examples/link_status_interrupt/main.c 217 :language: c 218 :start-after: Read packet from RX queues. 8< 219 :end-before: >8 End of reading packet from RX queues. 220 :dedent: 2 221 222Packets are read in a burst of size MAX_PKT_BURST. 223The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table. 224 225Then, each mbuf in the table is processed by the lsi_simple_forward() function. 226The processing is very simple: processes the TX port from the RX port and then replaces the source and destination MAC addresses. 227 228.. note:: 229 230 In the following code, the two lines for calculating the output port require some explanation. 231 If portId is even, the first line does nothing (as portid & 1 will be 0), and the second line adds 1. 232 If portId is odd, the first line subtracts one and the second line does nothing. 233 Therefore, 0 goes to 1, and 1 to 0, 2 goes to 3 and 3 to 2, and so on. 234 235.. literalinclude:: ../../../examples/link_status_interrupt/main.c 236 :language: c 237 :start-after: Replacing the source and destination MAC addresses. 8< 238 :end-before: >8 End of replacing the source and destination MAC addresses. 239 240Then, the packet is sent using the lsi_send_packet(m, dst_port) function. 241For this test application, the processing is exactly the same for all packets arriving on the same RX port. 242Therefore, it would have been possible to call the lsi_send_burst() function directly from the main loop 243to send all the received packets on the same TX port using 244the burst-oriented send function, which is more efficient. 245 246However, in real-life applications (such as, L3 routing), 247packet N is not necessarily forwarded on the same port as packet N-1. 248The application is implemented to illustrate that so the same approach can be reused in a more complex application. 249 250The lsi_send_packet() function stores the packet in a per-lcore and per-txport table. 251If the table is full, the whole packets table is transmitted using the lsi_send_burst() function: 252 253.. literalinclude:: ../../../examples/l2fwd-crypto/main.c 254 :language: c 255 :start-after: Enqueue packets for TX and prepare them to be sent. 8< 256 :end-before: >8 End of Enqueuing packets for TX. 257 258To ensure that no packets remain in the tables, each lcore does a draining of the TX queue in its main loop. 259This technique introduces some latency when there are not many packets to send. 260However, it improves performance: 261 262.. literalinclude:: ../../../examples/link_status_interrupt/main.c 263 :language: c 264 :start-after: Draining TX queue in its main loop. 8< 265 :end-before: >8 End of draining TX queue in its main loop. 266 :dedent: 2 267