Tue, Feb 03, 2026 at 04:40:23AM +0100, kuba@kernel.org wrote:

On Wed, 28 Jan 2026 13:25:31 +0200 Tariq Toukan wrote:

quoted

From: Jiri Pirko <redacted>

Document shared devlink instances for multiple PFs on the same chip.

quoted

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?

quoted

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

quoted

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

quoted

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

quoted

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

quoted

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

quoted

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

quoted

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