Re: [PATCH net-next V7 01/14] documentation: networking: add shared devlink documentation

[Jakub Kicinski <kuba@kernel.org>]

On Wed, 28 Jan 2026 13:25:31 +0200 Tariq Toukan wrote:
> From: Jiri Pirko <jiri@nvidia.com>
> 
> Document shared devlink instances for multiple PFs on the same chip.

> diff --git a/Documentation/networking/devlink/devlink-shared.rst b/Documentation/networking/devlink/devlink-shared.rst
> new file mode 100644
> index 000000000000..74655dc671bc
> --- /dev/null
> +++ b/Documentation/networking/devlink/devlink-shared.rst
> @@ -0,0 +1,95 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============================
> +Devlink Shared Instances
> +============================

Shouldn't the length of the ==== lines match the title length?

> +Overview
> +========
> +
> +Shared devlink instances allow multiple physical functions (PFs) on the same
> +chip to share an additional devlink instance for chip-wide operations. This
> +is implemented within individual drivers alongside the individual PF devlink
> +instances, not replacing them.
> +
> +Multiple PFs may reside on the same physical chip, running a single firmware.
> +Some of the resources and configurations may be shared among these PFs. The
> +shared devlink instance provides an object to pin configuration knobs on.
> +
> +The shared devlink instance is backed by a faux device and provides a common
> +interface for operations that affect the entire chip rather than individual PFs.
> +A faux device is used as a backing device for the 'entire chip' since there's no
> +additional real device instantiated by hardware besides the PF devices.

There needs to be a note here clearly stating the the use of "shared
devlink instace" is a hack for legacy drivers, and new drivers should
have a single devlink instance for the entire device. The fact that
single instance is always preferred, and *more correct* must be made
very clear to the reader. Ideally the single instance multiple function
implementation would leverage the infra added here for collecting the
functions, however.

> +Implementation
> +==============
> +
> +Architecture
> +------------
> +
> +The implementation uses:
> +
> +* **Faux device**: Virtual device backing the shared devlink instance

"backing"? It isn't backing anything, its just another hack because we
made the mistake of tying devlink instances to $bus/$device as an id.
Now we need a fake device to have an identifier.

> +* **Chip identification**: PFs are grouped by chip using a driver-specific identifier
> +* **Shared instance management**: Global list of shared instances with reference counting
> +
> +API Functions
> +-------------
> +
> +The following functions are provided for managing shared devlink instances:
> +
> +* ``devlink_shd_get()``: Get or create a shared devlink instance identified by a string ID
> +* ``devlink_shd_put()``: Release a reference on a shared devlink instance
> +* ``devlink_shd_get_priv()``: Get private data from shared devlink instance
> +
> +Initialization Flow
> +-------------------
> +
> +1. **PF calls shared devlink init** during driver probe
> +2. **Chip identification** using driver-specific method to determine device identity

This isn't very clear.

> +3. **Get or create shared instance** using ``devlink_shd_get()``:

Just "Call ``devlink_shd_get()`` with the identifier constructed in
step 2" (?) and then have the points below explain that it gets or
recreates

> +   * The function looks up existing instance by identifier
> +   * If none exists, creates new instance:
> +     - Creates faux device with chip identifier as name
> +     - Allocates and registers devlink instance
> +     - Adds to global shared instances list
> +     - Increments reference count
> +
> +4. **Set nested devlink instance** for the PF devlink instance using
> +   ``devl_nested_devlink_set()`` before registering the PF devlink instance
> +
> +Cleanup Flow
> +------------
> +
> +1. **Cleanup** when PF is removed

"``.remove()`` callback for a PCIe device is called"

> +2. **Call** ``devlink_shd_put()`` to release reference (decrements reference count)
> +3. **Shared instance is automatically destroyed** when the last PF removes (device list becomes empty)
> +
> +Chip Identification
> +-------------------
> +
> +PFs belonging to the same chip are identified using a driver-specific method.
> +The driver is free to choose any identifier that is suitable for determining
> +whether two PFs are part of the same device. Examples include:
> +
> +* **PCI VPD serial numbers**: Extract from PCI VPD
> +* **Device tree properties**: Read chip identifier from device tree
> +* **Other hardware-specific identifiers**: Any unique identifier that groups PFs by chip
> +
> +Locking
> +-------
> +
> +A global mutex (``shd_mutex``) protects the shared instances list during
> +registration/deregistration.
> +
> +Similarly to other nested devlink instance relationships, devlink lock of
> +the shared instance should be always taken after the devlink lock of PF.

of an instance, not a PF

> +
> +Reference Counting
> +------------------
> +
> +Each shared devlink instance maintains a reference count (``refcount_t refcount``).
> +The reference count is incremented when ``devlink_shd_get()`` is called and
> +decremented when ``devlink_shd_put()`` is called. When the reference count
> +reaches zero, the shared instance is automatically destroyed.

I think AI went too far with the text generation here, this is very
obvious from the previous sections.
-- 
pw-bot: cr