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

[Jiri Pirko]

Tue, Feb 03, 2026 at 04:40:23AM +0100, kuba@xxxxxxxxxx wrote:
>On Wed, 28 Jan 2026 13:25:31 +0200 Tariq Toukan wrote:
>> From: Jiri Pirko <jiri@xxxxxxxxxx>
>> 
>> 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.

How exactly you can have a single devlink instance for multiple PFs of a
same device? I don't really understand how that could work, considering
dynamic binds/unbinds of the PFs within single host and/or multiple VMs
passing PFs to.


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

Okay. I originally wanted to use an id, similar to what we have in
the dpll. However I was forced by community to tie the instance to
bus/device. It is how it is, any idea how to relax this bond?



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

Hmm, any suggestion to make it cleaner?


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

Okay.


>
>> +   * 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

lock of PF devlink instance. I think that is what the text says, no?


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