[PATCH net-next v2] documentation: networking: Add NAPI config

[PATCH net-next v2] documentation: networking: Add NAPI config

[Joe Damato]

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>
---
 v2:
   - Reword the Persistent Napi config section using some suggestions
     from Jakub.

 Documentation/networking/napi.rst | 33 ++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/Documentation/networking/napi.rst
b/Documentation/networking/napi.rst
index f970a2be271a..d0e3953cae6a 100644
--- a/Documentation/networking/napi.rst
+++ b/Documentation/networking/napi.rst
@@ -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
 -----------------------

base-commit: ae9b3c0e79bcc154f80f6e862d3085de31bcb3ce
-- 
2.43.0

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Jakub Kicinski]

On Tue, 11 Feb 2025 20:06:03 +0000 Joe Damato wrote:
> 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.

LG!

Acked-by: Jakub Kicinski <kuba@kernel.org>

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2425 bytes --]

On Tue, Feb 11, 2025 at 08:06:03PM +0000, Joe Damato wrote:
> diff --git a/Documentation/networking/napi.rst
> b/Documentation/networking/napi.rst
> index f970a2be271a..d0e3953cae6a 100644
> --- a/Documentation/networking/napi.rst
> +++ b/Documentation/networking/napi.rst
> @@ -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
>  -----------------------
> 

Looks good, thanks!

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Paolo Abeni]

On 2/11/25 9:06 PM, Joe Damato wrote:
> 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>
> ---
>  v2:
>    - Reword the Persistent Napi config section using some suggestions
>      from Jakub.
> 
>  Documentation/networking/napi.rst | 33 ++++++++++++++++++++++++++++++-
>  1 file changed, 32 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/networking/napi.rst
> b/Documentation/networking/napi.rst
> index f970a2be271a..d0e3953cae6a 100644
> --- a/Documentation/networking/napi.rst
> +++ b/Documentation/networking/napi.rst
> @@ -171,12 +171,43 @@ a channel as an IRQ/NAPI which services queues
> of a given type. For example,

It looks like your client mangled the patch; the above lines are
corrupted (there should be no line split)

Please respin

/P

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Joe Damato]

On Thu, Feb 13, 2025 at 12:45:01PM +0100, Paolo Abeni wrote:
> On 2/11/25 9:06 PM, Joe Damato wrote:
> > 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>
> > ---
> >  v2:
> >    - Reword the Persistent Napi config section using some suggestions
> >      from Jakub.
> > 
> >  Documentation/networking/napi.rst | 33 ++++++++++++++++++++++++++++++-
> >  1 file changed, 32 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/networking/napi.rst
> > b/Documentation/networking/napi.rst
> > index f970a2be271a..d0e3953cae6a 100644
> > --- a/Documentation/networking/napi.rst
> > +++ b/Documentation/networking/napi.rst
> > @@ -171,12 +171,43 @@ a channel as an IRQ/NAPI which services queues
> > of a given type. For example,
> 
> It looks like your client mangled the patch; the above lines are
> corrupted (there should be no line split)
> 
> Please respin

I must be missing something: I don't see the line split when looking
at the original email and I just tried applying the patch directly
from my email and it applied just fine.

Are you sure its not something with your client?

See the message on lore:

https://lore.kernel.org/netdev/20250211151543.645d1c57@kernel.org/T/

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Jakub Kicinski]

On Thu, 13 Feb 2025 05:45:38 -0800 Joe Damato wrote:
> On Thu, Feb 13, 2025 at 12:45:01PM +0100, Paolo Abeni wrote:
> > On 2/11/25 9:06 PM, Joe Damato wrote:  
> > > +++ b/Documentation/networking/napi.rst
> > > @@ -171,12 +171,43 @@ a channel as an IRQ/NAPI which services queues
> > > of a given type. For example,  
> > 
> > It looks like your client mangled the patch; the above lines are
> > corrupted (there should be no line split)
> > 
> > Please respin  
> 
> I must be missing something: I don't see the line split when looking
> at the original email and I just tried applying the patch directly
> from my email and it applied just fine.
> 
> Are you sure its not something with your client?
> 
> See the message on lore:
> 
> https://lore.kernel.org/netdev/20250211151543.645d1c57@kernel.org/T/

It's also broken on lore.

The first diff block starting with the @@ line overflows and gets
broken into the next line. All lines within a diff block must start
with a space, + or -. The "of a given type. For example," line breaks
that.

Re: [PATCH net-next v2] documentation: networking: Add NAPI config

[Joe Damato]

On Thu, Feb 13, 2025 at 08:14:18AM -0800, Jakub Kicinski wrote:
> On Thu, 13 Feb 2025 05:45:38 -0800 Joe Damato wrote:
> > On Thu, Feb 13, 2025 at 12:45:01PM +0100, Paolo Abeni wrote:
> > > On 2/11/25 9:06 PM, Joe Damato wrote:  
> > > > +++ b/Documentation/networking/napi.rst
> > > > @@ -171,12 +171,43 @@ a channel as an IRQ/NAPI which services queues
> > > > of a given type. For example,  
> > > 
> > > It looks like your client mangled the patch; the above lines are
> > > corrupted (there should be no line split)
> > > 
> > > Please respin  
> > 
> > I must be missing something: I don't see the line split when looking
> > at the original email and I just tried applying the patch directly
> > from my email and it applied just fine.
> > 
> > Are you sure its not something with your client?
> > 
> > See the message on lore:
> > 
> > https://lore.kernel.org/netdev/20250211151543.645d1c57@kernel.org/T/
> 
> It's also broken on lore.
> 
> The first diff block starting with the @@ line overflows and gets
> broken into the next line. All lines within a diff block must start
> with a space, + or -. The "of a given type. For example," line breaks
> that.

I see; I think it's this oauth2 helper I've been trying to use with
my google cloud account. Arg.

I'll RESEND this and my XSK attribute thing, too, which for some
reason isn't on lore but is on other sites (like spinics).