Commit bf1b8e0a authored by Joe Damato's avatar Joe Damato Committed by Jakub Kicinski
Browse files

documentation: networking: Add NAPI config 



Document the existence of persistent per-NAPI configuration space and
the API that drivers can opt into.

Update stale documentation which suggested that NAPI IDs cannot be
queried from userspace.

Signed-off-by: default avatarJoe Damato <jdamato@fastly.com>
Acked-by: default avatarJakub Kicinski <kuba@kernel.org>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Link: https://patch.msgid.link/20250213191535.38792-1-jdamato@fastly.com


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 6041d8bf

Documentation/networking/napi.rst

+32 −1
Original line number Diff line number Diff line
@@ -171,12 +171,43 @@ a channel as an IRQ/NAPI which services queues of a given type. For example, 
a configuration of 1 ``rx``, 1 ``tx`` and 1 ``combined`` channel is expected

to utilize 3 interrupts, 2 Rx and 2 Tx queues.



Persistent NAPI config

----------------------



Drivers often allocate and free NAPI instances dynamically. This leads to loss

of NAPI-related user configuration each time NAPI instances are reallocated.

The netif_napi_add_config() API prevents this loss of configuration by

associating each NAPI instance with a persistent NAPI configuration based on

a driver defined index value, like a queue number.



Using this API allows for persistent NAPI IDs (among other settings), which can

be beneficial to userspace programs using ``SO_INCOMING_NAPI_ID``. See the

sections below for other NAPI configuration settings.



Drivers should try to use netif_napi_add_config() whenever possible.



User API

========



User interactions with NAPI depend on NAPI instance ID. The instance IDs

are only visible to the user thru the ``SO_INCOMING_NAPI_ID`` socket option.

It's not currently possible to query IDs used by a given device.



Users can query NAPI IDs for a device or device queue using netlink. This can

be done programmatically in a user application or by using a script included in

the kernel source tree: ``tools/net/ynl/pyynl/cli.py``.



For example, using the script to dump all of the queues for a device (which

will reveal each queue's NAPI ID):



.. code-block:: bash



   $ kernel-source/tools/net/ynl/pyynl/cli.py \

             --spec Documentation/netlink/specs/netdev.yaml \

             --dump queue-get \

             --json='{"ifindex": 2}'



See ``Documentation/netlink/specs/netdev.yaml`` for more details on

available operations and attributes.



Software IRQ coalescing

-----------------------