Documentation/networking/napi.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/napi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/napi.rst
Extension
.rst
Size
20710 bytes
Lines
511
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct epoll_params {
      uint32_t busy_poll_usecs;
      uint16_t busy_poll_budget;
      uint8_t prefer_busy_poll;

      /* pad the struct to a multiple of 64bits */
      uint8_t __pad;
  };

IRQ mitigation
---------------

While busy polling is supposed to be used by low latency applications,
a similar mechanism can be used for IRQ mitigation.

Very high request-per-second applications (especially routing/forwarding
applications and especially applications using AF_XDP sockets) may not
want to be interrupted until they finish processing a request or a batch
of packets.

Such applications can pledge to the kernel that they will perform a busy
polling operation periodically, and the driver should keep the device IRQs
permanently masked. This mode is enabled by using the ``SO_PREFER_BUSY_POLL``
socket option. To avoid system misbehavior the pledge is revoked
if ``gro_flush_timeout`` passes without any busy poll call. For epoll-based
busy polling applications, the ``prefer_busy_poll`` field of ``struct
epoll_params`` can be set to 1 and the ``EPIOCSPARAMS`` ioctl can be issued to
enable this mode. See the above section for more details.

The NAPI budget for busy polling is lower than the default (which makes
sense given the low latency intention of normal busy polling). This is
not the case with IRQ mitigation, however, so the budget can be adjusted
with the ``SO_BUSY_POLL_BUDGET`` socket option. For epoll-based busy polling
applications, the ``busy_poll_budget`` field can be adjusted to the desired value
in ``struct epoll_params`` and set on a specific epoll context using the ``EPIOCSPARAMS``
ioctl. See the above section for more details.

It is important to note that choosing a large value for ``gro_flush_timeout``
will defer IRQs to allow for better batch processing, but will induce latency
when the system is not fully loaded. Choosing a small value for
``gro_flush_timeout`` can cause interference of the user application which is
attempting to busy poll by device IRQs and softirq processing. This value
should be chosen carefully with these tradeoffs in mind. epoll-based busy
polling applications may be able to mitigate how much user processing happens
by choosing an appropriate value for ``maxevents``.

Users may want to consider an alternate approach, IRQ suspension, to help deal
with these tradeoffs.

IRQ suspension
--------------

IRQ suspension is a mechanism wherein device IRQs are masked while epoll
triggers NAPI packet processing.

While application calls to epoll_wait successfully retrieve events, the kernel will
defer the IRQ suspension timer. If the kernel does not retrieve any events
while busy polling (for example, because network traffic levels subsided), IRQ
suspension is disabled and the IRQ mitigation strategies described above are
engaged.

This allows users to balance CPU consumption with network processing
efficiency.

To use this mechanism:

  1. The per-NAPI config parameter ``irq-suspend-timeout`` should be set to the
     maximum time (in nanoseconds) the application can have its IRQs
     suspended. This is done using netlink, as described above. This timeout
     serves as a safety mechanism to restart IRQ driver interrupt processing if

Annotation

Implementation Notes