1.. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) 2 3.. _napi: 4 5==== 6NAPI 7==== 8 9NAPI is the event handling mechanism used by the Linux networking stack. 10The name NAPI no longer stands for anything in particular [#]_. 11 12In basic operation the device notifies the host about new events 13via an interrupt. 14The host then schedules a NAPI instance to process the events. 15The device may also be polled for events via NAPI without receiving 16interrupts first (:ref:`busy polling<poll>`). 17 18NAPI processing usually happens in the software interrupt context, 19but there is an option to use :ref:`separate kernel threads<threaded>` 20for NAPI processing. 21 22All in all NAPI abstracts away from the drivers the context and configuration 23of event (packet Rx and Tx) processing. 24 25Driver API 26========== 27 28The two most important elements of NAPI are the struct napi_struct 29and the associated poll method. struct napi_struct holds the state 30of the NAPI instance while the method is the driver-specific event 31handler. The method will typically free Tx packets that have been 32transmitted and process newly received packets. 33 34.. _drv_ctrl: 35 36Control API 37----------- 38 39netif_napi_add() and netif_napi_del() add/remove a NAPI instance 40from the system. The instances are attached to the netdevice passed 41as argument (and will be deleted automatically when netdevice is 42unregistered). Instances are added in a disabled state. 43 44napi_enable() and napi_disable() manage the disabled state. 45A disabled NAPI can't be scheduled and its poll method is guaranteed 46to not be invoked. napi_disable() waits for ownership of the NAPI 47instance to be released. 48 49The control APIs are not idempotent. Control API calls are safe against 50concurrent use of datapath APIs but an incorrect sequence of control API 51calls may result in crashes, deadlocks, or race conditions. For example, 52calling napi_disable() multiple times in a row will deadlock. 53 54Datapath API 55------------ 56 57napi_schedule() is the basic method of scheduling a NAPI poll. 58Drivers should call this function in their interrupt handler 59(see :ref:`drv_sched` for more info). A successful call to napi_schedule() 60will take ownership of the NAPI instance. 61 62Later, after NAPI is scheduled, the driver's poll method will be 63called to process the events/packets. The method takes a ``budget`` 64argument - drivers can process completions for any number of Tx 65packets but should only process up to ``budget`` number of 66Rx packets. Rx processing is usually much more expensive. 67 68In other words for Rx processing the ``budget`` argument limits how many 69packets driver can process in a single poll. Rx specific APIs like page 70pool or XDP cannot be used at all when ``budget`` is 0. 71skb Tx processing should happen regardless of the ``budget``, but if 72the argument is 0 driver cannot call any XDP (or page pool) APIs. 73 74.. warning:: 75 76 The ``budget`` argument may be 0 if core tries to only process 77 skb Tx completions and no Rx or XDP packets. 78 79The poll method returns the amount of work done. If the driver still 80has outstanding work to do (e.g. ``budget`` was exhausted) 81the poll method should return exactly ``budget``. In that case, 82the NAPI instance will be serviced/polled again (without the 83need to be scheduled). 84 85If event processing has been completed (all outstanding packets 86processed) the poll method should call napi_complete_done() 87before returning. napi_complete_done() releases the ownership 88of the instance. 89 90.. warning:: 91 92 The case of finishing all events and using exactly ``budget`` 93 must be handled carefully. There is no way to report this 94 (rare) condition to the stack, so the driver must either 95 not call napi_complete_done() and wait to be called again, 96 or return ``budget - 1``. 97 98 If the ``budget`` is 0 napi_complete_done() should never be called. 99 100Call sequence 101------------- 102 103Drivers should not make assumptions about the exact sequencing 104of calls. The poll method may be called without the driver scheduling 105the instance (unless the instance is disabled). Similarly, 106it's not guaranteed that the poll method will be called, even 107if napi_schedule() succeeded (e.g. if the instance gets disabled). 108 109As mentioned in the :ref:`drv_ctrl` section - napi_disable() and subsequent 110calls to the poll method only wait for the ownership of the instance 111to be released, not for the poll method to exit. This means that 112drivers should avoid accessing any data structures after calling 113napi_complete_done(). 114 115.. _drv_sched: 116 117Scheduling and IRQ masking 118-------------------------- 119 120Drivers should keep the interrupts masked after scheduling 121the NAPI instance - until NAPI polling finishes any further 122interrupts are unnecessary. 123 124Drivers which have to mask the interrupts explicitly (as opposed 125to IRQ being auto-masked by the device) should use the napi_schedule_prep() 126and __napi_schedule() calls: 127 128.. code-block:: c 129 130 if (napi_schedule_prep(&v->napi)) { 131 mydrv_mask_rxtx_irq(v->idx); 132 /* schedule after masking to avoid races */ 133 __napi_schedule(&v->napi); 134 } 135 136IRQ should only be unmasked after a successful call to napi_complete_done(): 137 138.. code-block:: c 139 140 if (budget && napi_complete_done(&v->napi, work_done)) { 141 mydrv_unmask_rxtx_irq(v->idx); 142 return min(work_done, budget - 1); 143 } 144 145napi_schedule_irqoff() is a variant of napi_schedule() which takes advantage 146of guarantees given by being invoked in IRQ context (no need to 147mask interrupts). Note that PREEMPT_RT forces all interrupts 148to be threaded so the interrupt may need to be marked ``IRQF_NO_THREAD`` 149to avoid issues on real-time kernel configurations. 150 151Instance to queue mapping 152------------------------- 153 154Modern devices have multiple NAPI instances (struct napi_struct) per 155interface. There is no strong requirement on how the instances are 156mapped to queues and interrupts. NAPI is primarily a polling/processing 157abstraction without specific user-facing semantics. That said, most networking 158devices end up using NAPI in fairly similar ways. 159 160NAPI instances most often correspond 1:1:1 to interrupts and queue pairs 161(queue pair is a set of a single Rx and single Tx queue). 162 163In less common cases a NAPI instance may be used for multiple queues 164or Rx and Tx queues can be serviced by separate NAPI instances on a single 165core. Regardless of the queue assignment, however, there is usually still 166a 1:1 mapping between NAPI instances and interrupts. 167 168It's worth noting that the ethtool API uses a "channel" terminology where 169each channel can be either ``rx``, ``tx`` or ``combined``. It's not clear 170what constitutes a channel; the recommended interpretation is to understand 171a channel as an IRQ/NAPI which services queues of a given type. For example, 172a configuration of 1 ``rx``, 1 ``tx`` and 1 ``combined`` channel is expected 173to utilize 3 interrupts, 2 Rx and 2 Tx queues. 174 175User API 176======== 177 178User interactions with NAPI depend on NAPI instance ID. The instance IDs 179are only visible to the user thru the ``SO_INCOMING_NAPI_ID`` socket option. 180It's not currently possible to query IDs used by a given device. 181 182Software IRQ coalescing 183----------------------- 184 185NAPI does not perform any explicit event coalescing by default. 186In most scenarios batching happens due to IRQ coalescing which is done 187by the device. There are cases where software coalescing is helpful. 188 189NAPI can be configured to arm a repoll timer instead of unmasking 190the hardware interrupts as soon as all packets are processed. 191The ``gro_flush_timeout`` sysfs configuration of the netdevice 192is reused to control the delay of the timer, while 193``napi_defer_hard_irqs`` controls the number of consecutive empty polls 194before NAPI gives up and goes back to using hardware IRQs. 195 196.. _poll: 197 198Busy polling 199------------ 200 201Busy polling allows a user process to check for incoming packets before 202the device interrupt fires. As is the case with any busy polling it trades 203off CPU cycles for lower latency (production uses of NAPI busy polling 204are not well known). 205 206Busy polling is enabled by either setting ``SO_BUSY_POLL`` on 207selected sockets or using the global ``net.core.busy_poll`` and 208``net.core.busy_read`` sysctls. An io_uring API for NAPI busy polling 209also exists. 210 211IRQ mitigation 212--------------- 213 214While busy polling is supposed to be used by low latency applications, 215a similar mechanism can be used for IRQ mitigation. 216 217Very high request-per-second applications (especially routing/forwarding 218applications and especially applications using AF_XDP sockets) may not 219want to be interrupted until they finish processing a request or a batch 220of packets. 221 222Such applications can pledge to the kernel that they will perform a busy 223polling operation periodically, and the driver should keep the device IRQs 224permanently masked. This mode is enabled by using the ``SO_PREFER_BUSY_POLL`` 225socket option. To avoid system misbehavior the pledge is revoked 226if ``gro_flush_timeout`` passes without any busy poll call. 227 228The NAPI budget for busy polling is lower than the default (which makes 229sense given the low latency intention of normal busy polling). This is 230not the case with IRQ mitigation, however, so the budget can be adjusted 231with the ``SO_BUSY_POLL_BUDGET`` socket option. 232 233.. _threaded: 234 235Threaded NAPI 236------------- 237 238Threaded NAPI is an operating mode that uses dedicated kernel 239threads rather than software IRQ context for NAPI processing. 240The configuration is per netdevice and will affect all 241NAPI instances of that device. Each NAPI instance will spawn a separate 242thread (called ``napi/${ifc-name}-${napi-id}``). 243 244It is recommended to pin each kernel thread to a single CPU, the same 245CPU as the CPU which services the interrupt. Note that the mapping 246between IRQs and NAPI instances may not be trivial (and is driver 247dependent). The NAPI instance IDs will be assigned in the opposite 248order than the process IDs of the kernel threads. 249 250Threaded NAPI is controlled by writing 0/1 to the ``threaded`` file in 251netdev's sysfs directory. 252 253.. rubric:: Footnotes 254 255.. [#] NAPI was originally referred to as New API in 2.4 Linux. 256