Documentation/networking/napi.rst

1 .. SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
14 The host then schedules a NAPI instance to process the events.
19 but there is an option to use :ref:`separate kernel threads<threaded>`
23 of event (packet Rx and Tx) processing.
30 of the NAPI instance while the method is the driver-specific event
31 handler. The method will typically free Tx packets that have been
37 -----------
40 from the system. The instances are attached to the netdevice passed
46 to not be invoked. napi_disable() waits for ownership of the NAPI
47 instance to be released.
50 concurrent use of datapath APIs but an incorrect sequence of control API
55 ------------
59 (see :ref:`drv_sched` for more info). A successful call to napi_schedule()
63 called to process the events/packets. The method takes a ``budget``
64 argument - drivers can process completions for any number of Tx
65 packets but should only process up to ``budget`` number of
71 skb Tx processing should happen regardless of the ``budget``, but if
76    The ``budget`` argument may be 0 if core tries to only process
77    skb Tx completions and no Rx or XDP packets.
80 has outstanding work to do (e.g. ``budget`` was exhausted)
83 need to be scheduled).
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``.
101 -------------
109 As mentioned in the :ref:`drv_ctrl` section - napi_disable() and subsequent
110 calls to the poll method only wait for the ownership of the instance
111 to be released, not for the poll method to exit. This means that
118 --------------------------
121 the NAPI instance - until NAPI polling finishes any further
124 Drivers which have to mask the interrupts explicitly (as opposed
125 to IRQ being auto-masked by the device) should use the napi_schedule_prep()
128 .. code-block:: c
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);
136 IRQ should only be unmasked after a successful call to napi_complete_done():
138 .. code-block:: c
140   if (budget && napi_complete_done(&v->napi, work_done)) {
141     mydrv_unmask_rxtx_irq(v->idx);
142     return min(work_done, budget - 1);
146 of guarantees given by being invoked in IRQ context (no need to
148 to be threaded so the interrupt may need to be marked ``IRQF_NO_THREAD``
149 to avoid issues on real-time kernel configurations.
151 Instance to queue mapping
152 -------------------------
156 mapped to queues and interrupts. NAPI is primarily a polling/processing
157 abstraction without specific user-facing semantics. That said, most networking
160 NAPI 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).
163 In less common cases a NAPI instance may be used for multiple queues
164 or Rx and Tx queues can be serviced by separate NAPI instances on a single
169 each channel can be either ``rx``, ``tx`` or ``combined``. It's not clear
170 what constitutes a channel; the recommended interpretation is to understand
171 a channel as an IRQ/NAPI which services queues of a given type. For example,
172 a configuration of 1 ``rx``, 1 ``tx`` and 1 ``combined`` channel is expected
173 to utilize 3 interrupts, 2 Rx and 2 Tx queues.
179 are only visible to the user thru the ``SO_INCOMING_NAPI_ID`` socket option.
180 It's not currently possible to query IDs used by a given device.
183 -----------------------
186 In most scenarios batching happens due to IRQ coalescing which is done
189 NAPI can be configured to arm a repoll timer instead of unmasking
192 is reused to control the delay of the timer, while
194 before NAPI gives up and goes back to using hardware IRQs.
199 ------------
201 Busy polling allows a user process to check for incoming packets before
212 ---------------
214 While busy polling is supposed to be used by low latency applications,
217 Very high request-per-second applications (especially routing/forwarding
219 want to be interrupted until they finish processing a request or a batch
222 Such applications can pledge to the kernel that they will perform a busy
225 socket option. To avoid system misbehavior the pledge is revoked
236 -------------
242 thread (called ``napi/${ifc-name}-${napi-id}``).
244 It is recommended to pin each kernel thread to a single CPU, the same
250 Threaded NAPI is controlled by writing 0/1 to the ``threaded`` file in
255 .. [#] NAPI was originally referred to as New API in 2.4 Linux.