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: Joe Damato <jdamato@fastly.com>
---
 Documentation/networking/napi.rst | 32 ++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/Documentation/networking/napi.rst b/Documentation/networking/napi.rst
index f970a2be271a..de146f63f09b 100644
--- a/Documentation/networking/napi.rst
+++ b/Documentation/networking/napi.rst
@@ -171,12 +171,42 @@ 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 can opt-in to using a persistent NAPI configuration space by calling
+netif_napi_add_config. This API maps a NAPI instance to a configuration
+structure using a driver defined index value, like a queue number. If the
+driver were to destroy and recreate NAPI instances (if a user requested a queue
+count change, for example), the new NAPI instances will inherit the configuration
+settings of the NAPI configuration structure they are mapped to.
+
+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.
+
 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
 -----------------------

base-commit: 7bca2b2d5fcc685b81eb32fe564689eca6a59a99
-- 
2.43.0

On Sat,  8 Feb 2025 01:28:21 +0000 Joe Damato wrote:
> +Persistent NAPI config
> +----------------------
> +
> +Drivers can opt-in to using a persistent NAPI configuration space by calling

Should we be more forceful? I think for new drivers the _add_config() 
API should always be preferred given the benefits.

> +netif_napi_add_config. This API maps a NAPI instance to a configuration
> +structure using a driver defined index value, like a queue number. If the
> +driver were to destroy and recreate NAPI instances (if a user requested a queue

"were" is correct here?

> +count change, for example), the new NAPI instances will inherit the configuration
> +settings of the NAPI configuration structure they are mapped to.

On February 10, 2025 6:16:35 PM PST, Jakub Kicinski <kuba@kernel.org> wrote:
>On Sat,  8 Feb 2025 01:28:21 +0000 Joe Damato wrote:
>> +Persistent NAPI config
>> +----------------------
>> +
>> +Drivers can opt-in to using a persistent NAPI configuration space by calling
>
>Should we be more forceful? I think for new drivers the _add_config() 
>API should always be preferred given the benefits.
>
>> +netif_napi_add_config. This API maps a NAPI instance to a configuration
>> +structure using a driver defined index value, like a queue number. If the
>> +driver were to destroy and recreate NAPI instances (if a user requested a queue
>
>"were" is correct here?

Yes, subjunctive mood.


>> +count change, for example), the new NAPI instances will inherit the configuration
>> +settings of the NAPI configuration structure they are mapped to.
>


~Randy

On Mon, Feb 10, 2025 at 06:16:35PM -0800, Jakub Kicinski wrote:
> On Sat,  8 Feb 2025 01:28:21 +0000 Joe Damato wrote:
> > +Persistent NAPI config
> > +----------------------
> > +
> > +Drivers can opt-in to using a persistent NAPI configuration space by calling
> 
> Should we be more forceful? I think for new drivers the _add_config() 
> API should always be preferred given the benefits.

How about: "Drivers should opt-in ..." instead? I have no strong
preference.

On Mon, 10 Feb 2025 18:50:47 -0800 Joe Damato wrote:
> On Mon, Feb 10, 2025 at 06:16:35PM -0800, Jakub Kicinski wrote:
> > On Sat,  8 Feb 2025 01:28:21 +0000 Joe Damato wrote:  
> > > +Persistent NAPI config
> > > +----------------------
> > > +
> > > +Drivers can opt-in to using a persistent NAPI configuration space by calling  
> > 
> > Should we be more forceful? I think for new drivers the _add_config() 
> > API should always be preferred given the benefits.  
> 
> How about: "Drivers should opt-in ..." instead? I have no strong
> preference.

A bit more editing may be beneficial, lead with the problem:

  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...

  Drivers should try to use netif_napi_add_config() whenever possible.

On Sat, Feb 08, 2025 at 01:28:21AM +0000, Joe Damato wrote:
> diff --git a/Documentation/networking/napi.rst b/Documentation/networking/napi.rst
> index f970a2be271a..de146f63f09b 100644
> --- a/Documentation/networking/napi.rst
> +++ b/Documentation/networking/napi.rst
> @@ -171,12 +171,42 @@ 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 can opt-in to using a persistent NAPI configuration space by calling
> +netif_napi_add_config. This API maps a NAPI instance to a configuration
> +structure using a driver defined index value, like a queue number. If the
> +driver were to destroy and recreate NAPI instances (if a user requested a queue
> +count change, for example), the new NAPI instances will inherit the configuration
> +settings of the NAPI configuration structure they are mapped to.
> +
> +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.
> +
>  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
>  -----------------------
> 

Looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara