| Message ID | 20250208012822.34327-1-jdamato@fastly.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next] documentation: networking: Add NAPI config | expand |
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>
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.
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 -----------------------
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(-) base-commit: 7bca2b2d5fcc685b81eb32fe564689eca6a59a99