1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2010-2014 Intel Corporation.
4 Link Status Interrupt Sample Application
5 ========================================
7 The Link Status Interrupt sample application is a simple example of packet processing using
8 the Data Plane Development Kit (DPDK) that
9 demonstrates how network link status changes for a network port can be captured and
10 used by a DPDK application.
15 The Link Status Interrupt sample application registers a user space callback for the link status interrupt of each port
16 and performs L2 forwarding for each packet that is received on an RX_PORT.
17 The following operations are performed:
19 * RX_PORT and TX_PORT are paired with available ports one-by-one according to the core mask
21 * The source MAC address is replaced by the TX_PORT MAC address
23 * The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
25 This application can be used to demonstrate the usage of link status interrupt and its user space callbacks
26 and the behavior of L2 forwarding each time the link status changes.
28 Compiling the Application
29 -------------------------
31 To compile the sample application see :doc:`compiling`.
33 The application is located in the ``link_status_interrupt`` sub-directory.
35 Running the Application
36 -----------------------
38 The application requires a number of command line options:
40 .. code-block:: console
42 ./build/link_status_interrupt [EAL options] -- -p PORTMASK [-q NQ][-T PERIOD]
46 * -p PORTMASK: A hexadecimal bitmask of the ports to configure
48 * -q NQ: A number of queues (=ports) per lcore (default is 1)
50 * -T PERIOD: statistics will be refreshed each PERIOD seconds (0 to disable, 10 default)
52 To run the application in a linuxapp environment with 4 lcores, 4 memory channels, 16 ports and 8 RX queues per lcore,
55 .. code-block:: console
57 $ ./build/link_status_interrupt -l 0-3 -n 4-- -q 8 -p ffff
59 Refer to the *DPDK Getting Started Guide* for general information on running applications
60 and the Environment Abstraction Layer (EAL) options.
65 The following sections provide some explanation of the code.
67 Command Line Arguments
68 ~~~~~~~~~~~~~~~~~~~~~~
70 The Link Status Interrupt sample application takes specific parameters,
71 in addition to Environment Abstraction Layer (EAL) arguments (see Section `Running the Application`_).
73 Command line parsing is done in the same way as it is done in the L2 Forwarding Sample Application.
74 See :ref:`l2_fwd_app_cmd_arguments` for more information.
76 Mbuf Pool Initialization
77 ~~~~~~~~~~~~~~~~~~~~~~~~
79 Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding Sample Application.
80 See :ref:`l2_fwd_app_mbuf_init` for more information.
85 The main part of the code in the main() function relates to the initialization of the driver.
86 To fully understand this code, it is recommended to study the chapters that related to the Poll Mode Driver in the
87 *DPDK Programmer's Guide and the DPDK API Reference*.
91 if (rte_pci_probe() < 0)
92 rte_exit(EXIT_FAILURE, "Cannot probe PCI\n");
95 * Each logical core is assigned a dedicated TX queue on each port.
98 RTE_ETH_FOREACH_DEV(portid) {
99 /* skip ports that are not enabled */
101 if ((lsi_enabled_port_mask & (1 << portid)) == 0)
104 /* save the destination port id */
106 if (nb_ports_in_mask % 2) {
107 lsi_dst_ports[portid] = portid_last;
108 lsi_dst_ports[portid_last] = portid;
111 portid_last = portid;
115 rte_eth_dev_info_get((uint8_t) portid, &dev_info);
120 * rte_pci_probe() parses the devices on the PCI bus and initializes recognized devices.
122 The next step is to configure the RX and TX queues.
123 For each port, there is only one RX queue (only one lcore is able to poll a given port).
124 The number of TX queues depends on the number of available lcores.
125 The rte_eth_dev_configure() function is used to configure the number of queues for a port:
129 ret = rte_eth_dev_configure((uint8_t) portid, 1, 1, &port_conf);
131 rte_exit(EXIT_FAILURE, "Cannot configure device: err=%d, port=%u\n", ret, portid);
133 The global configuration is stored in a static structure:
137 static const struct rte_eth_conf port_conf = {
140 .header_split = 0, /**< Header Split disabled */
141 .hw_ip_checksum = 0, /**< IP checksum offload disabled */
142 .hw_vlan_filter = 0, /**< VLAN filtering disabled */
143 .hw_strip_crc= 0, /**< CRC stripped by hardware */
147 .lsc = 1, /**< link status interrupt feature enabled */
151 Configuring lsc to 0 (the default) disables the generation of any link status change interrupts in kernel space
152 and no user space interrupt event is received.
153 The public interface rte_eth_link_get() accesses the NIC registers directly to update the link status.
154 Configuring lsc to non-zero enables the generation of link status change interrupts in kernel space
155 when a link status change is present and calls the user space callbacks registered by the application.
156 The public interface rte_eth_link_get() just reads the link status in a global structure
157 that would be updated in the interrupt host thread only.
159 Interrupt Callback Registration
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162 The application can register one or more callbacks to a specific port and interrupt event.
163 An example callback function that has been written as indicated below.
168 lsi_event_callback(uint16_t port_id, enum rte_eth_event_type type, void *param)
170 struct rte_eth_link link;
174 printf("\n\nIn registered callback...\n");
176 printf("Event type: %s\n", type == RTE_ETH_EVENT_INTR_LSC ? "LSC interrupt" : "unknown event");
178 rte_eth_link_get_nowait(port_id, &link);
180 if (link.link_status) {
181 printf("Port %d Link Up - speed %u Mbps - %s\n\n", port_id, (unsigned)link.link_speed,
182 (link.link_duplex == ETH_LINK_FULL_DUPLEX) ? ("full-duplex") : ("half-duplex"));
184 printf("Port %d Link Down\n\n", port_id);
187 This function is called when a link status interrupt is present for the right port.
188 The port_id indicates which port the interrupt applies to.
189 The type parameter identifies the interrupt event type,
190 which currently can be RTE_ETH_EVENT_INTR_LSC only, but other types can be added in the future.
191 The param parameter is the address of the parameter for the callback.
192 This function should be implemented with care since it will be called in the interrupt host thread,
193 which is different from the main thread of its caller.
195 The application registers the lsi_event_callback and a NULL parameter to the link status interrupt event on each port:
199 rte_eth_dev_callback_register((uint8_t)portid, RTE_ETH_EVENT_INTR_LSC, lsi_event_callback, NULL);
201 This registration can be done only after calling the rte_eth_dev_configure() function and before calling any other function.
202 If lsc is initialized with 0, the callback is never called since no interrupt event would ever be present.
204 RX Queue Initialization
205 ~~~~~~~~~~~~~~~~~~~~~~~
207 The application uses one lcore to poll one or several ports, depending on the -q option,
208 which specifies the number of queues per lcore.
210 For example, if the user specifies -q 4, the application is able to poll four ports with one lcore.
211 If there are 16 ports on the target (and if the portmask argument is -p ffff),
212 the application will need four lcores to poll all the ports.
216 ret = rte_eth_rx_queue_setup((uint8_t) portid, 0, nb_rxd, SOCKET0, &rx_conf, lsi_pktmbuf_pool);
218 rte_exit(EXIT_FAILURE, "rte_eth_rx_queue_setup: err=%d, port=%u\n", ret, portid);
220 The list of queues that must be polled for a given lcore is stored in a private structure called struct lcore_queue_conf.
224 struct lcore_queue_conf {
226 unsigned rx_port_list[MAX_RX_QUEUE_PER_LCORE]; unsigned tx_queue_id;
227 struct mbuf_table tx_mbufs[LSI_MAX_PORTS];
230 struct lcore_queue_conf lcore_queue_conf[RTE_MAX_LCORE];
232 The n_rx_port and rx_port_list[] fields are used in the main packet processing loop
233 (see `Receive, Process and Transmit Packets`_).
235 The global configuration for the RX queues is stored in a static structure:
239 static const struct rte_eth_rxconf rx_conf = {
241 .pthresh = RX_PTHRESH,
242 .hthresh = RX_HTHRESH,
243 .wthresh = RX_WTHRESH,
247 TX Queue Initialization
248 ~~~~~~~~~~~~~~~~~~~~~~~
250 Each lcore should be able to transmit on any port.
251 For every port, a single TX queue is initialized.
255 /* init one TX queue logical core on each port */
259 ret = rte_eth_tx_queue_setup(portid, 0, nb_txd, rte_eth_dev_socket_id(portid), &tx_conf);
261 rte_exit(EXIT_FAILURE, "rte_eth_tx_queue_setup: err=%d,port=%u\n", ret, (unsigned) portid);
263 The global configuration for TX queues is stored in a static structure:
267 static const struct rte_eth_txconf tx_conf = {
269 .pthresh = TX_PTHRESH,
270 .hthresh = TX_HTHRESH,
271 .wthresh = TX_WTHRESH,
273 .tx_free_thresh = RTE_TEST_TX_DESC_DEFAULT + 1, /* disable feature */
276 Receive, Process and Transmit Packets
277 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
279 In the lsi_main_loop() function, the main task is to read ingress packets from the RX queues.
280 This is done using the following code:
285 * Read packet from RX queues
288 for (i = 0; i < qconf->n_rx_port; i++) {
289 portid = qconf->rx_port_list[i];
290 nb_rx = rte_eth_rx_burst((uint8_t) portid, 0, pkts_burst, MAX_PKT_BURST);
291 port_statistics[portid].rx += nb_rx;
293 for (j = 0; j < nb_rx; j++) {
295 rte_prefetch0(rte_pktmbuf_mtod(m, void *));
296 lsi_simple_forward(m, portid);
300 Packets are read in a burst of size MAX_PKT_BURST.
301 The rte_eth_rx_burst() function writes the mbuf pointers in a local table and returns the number of available mbufs in the table.
303 Then, each mbuf in the table is processed by the lsi_simple_forward() function.
304 The processing is very simple: processes the TX port from the RX port and then replaces the source and destination MAC addresses.
308 In the following code, the two lines for calculating the output port require some explanation.
309 If portId is even, the first line does nothing (as portid & 1 will be 0), and the second line adds 1.
310 If portId is odd, the first line subtracts one and the second line does nothing.
311 Therefore, 0 goes to 1, and 1 to 0, 2 goes to 3 and 3 to 2, and so on.
316 lsi_simple_forward(struct rte_mbuf *m, unsigned portid)
318 struct ether_hdr *eth;
320 unsigned dst_port = lsi_dst_ports[portid];
322 eth = rte_pktmbuf_mtod(m, struct ether_hdr *);
324 /* 02:00:00:00:00:xx */
326 tmp = ð->d_addr.addr_bytes[0];
328 *((uint64_t *)tmp) = 0x000000000002 + (dst_port << 40);
331 ether_addr_copy(&lsi_ports_eth_addr[dst_port], ð->s_addr);
333 lsi_send_packet(m, dst_port);
336 Then, the packet is sent using the lsi_send_packet(m, dst_port) function.
337 For this test application, the processing is exactly the same for all packets arriving on the same RX port.
338 Therefore, it would have been possible to call the lsi_send_burst() function directly from the main loop
339 to send all the received packets on the same TX port using
340 the burst-oriented send function, which is more efficient.
342 However, in real-life applications (such as, L3 routing),
343 packet N is not necessarily forwarded on the same port as packet N-1.
344 The application is implemented to illustrate that so the same approach can be reused in a more complex application.
346 The lsi_send_packet() function stores the packet in a per-lcore and per-txport table.
347 If the table is full, the whole packets table is transmitted using the lsi_send_burst() function:
351 /* Send the packet on an output interface */
354 lsi_send_packet(struct rte_mbuf *m, uint16_t port)
356 unsigned lcore_id, len;
357 struct lcore_queue_conf *qconf;
359 lcore_id = rte_lcore_id();
360 qconf = &lcore_queue_conf[lcore_id];
361 len = qconf->tx_mbufs[port].len;
362 qconf->tx_mbufs[port].m_table[len] = m;
365 /* enough pkts to be sent */
367 if (unlikely(len == MAX_PKT_BURST)) {
368 lsi_send_burst(qconf, MAX_PKT_BURST, port);
371 qconf->tx_mbufs[port].len = len;
376 To ensure that no packets remain in the tables, each lcore does a draining of the TX queue in its main loop.
377 This technique introduces some latency when there are not many packets to send.
378 However, it improves performance:
382 cur_tsc = rte_rdtsc();
385 * TX burst queue drain
388 diff_tsc = cur_tsc - prev_tsc;
390 if (unlikely(diff_tsc > drain_tsc)) {
391 /* this could be optimized (use queueid instead of * portid), but it is not called so often */
393 for (portid = 0; portid < RTE_MAX_ETHPORTS; portid++) {
394 if (qconf->tx_mbufs[portid].len == 0)
397 lsi_send_burst(&lcore_queue_conf[lcore_id],
398 qconf->tx_mbufs[portid].len, (uint8_t) portid);
399 qconf->tx_mbufs[portid].len = 0;
402 /* if timer is enabled */
404 if (timer_period > 0) {
405 /* advance the timer */
407 timer_tsc += diff_tsc;
409 /* if timer has reached its timeout */
411 if (unlikely(timer_tsc >= (uint64_t) timer_period)) {
412 /* do this only on master core */
414 if (lcore_id == rte_get_master_lcore()) {
417 /* reset the timer */