1.. SPDX-License-Identifier: GPL-2.0 2 3======================== 4Devlink Shared Instances 5======================== 6 7Overview 8======== 9 10Shared devlink instances allow multiple physical functions (PFs) on the same 11chip to share a devlink instance for chip-wide operations. 12 13Multiple PFs may reside on the same physical chip, running a single firmware. 14Some of the resources and configurations may be shared among these PFs. The 15shared devlink instance provides an object to pin configuration knobs on. 16 17There are two possible usage models: 18 191. The shared devlink instance is used alongside individual PF devlink 20 instances, providing chip-wide configuration in addition to per-PF 21 configuration. 222. The shared devlink instance is the only devlink instance, without 23 per-PF instances. 24 25It is up to the driver to decide which usage model to use. 26 27The shared devlink instance is not backed by any struct *device*. 28 29Implementation 30============== 31 32Architecture 33------------ 34 35The implementation uses: 36 37* **Chip identification**: PFs are grouped by chip using a driver-specific identifier 38* **Shared instance management**: Global list of shared instances with reference counting 39 40API Functions 41------------- 42 43The following functions are provided for managing shared devlink instances: 44 45* ``devlink_shd_get()``: Get or create a shared devlink instance identified by a string ID 46* ``devlink_shd_put()``: Release a reference on a shared devlink instance 47* ``devlink_shd_get_priv()``: Get private data from shared devlink instance 48 49Initialization Flow 50------------------- 51 521. **PF calls shared devlink init** during driver probe 532. **Chip identification** using driver-specific method to determine device identity 543. **Get or create shared instance** using ``devlink_shd_get()``: 55 56 * The function looks up existing instance by identifier 57 * If none exists, creates new instance: 58 - Allocates and registers devlink instance 59 - Adds to global shared instances list 60 - Increments reference count 61 624. **Set nested devlink instance** for the PF devlink instance using 63 ``devl_nested_devlink_set()`` before registering the PF devlink instance 64 65Cleanup Flow 66------------ 67 681. **Cleanup** when PF is removed 692. **Call** ``devlink_shd_put()`` to release reference (decrements reference count) 703. **Shared instance is automatically destroyed** when the last PF removes (reference count reaches zero) 71 72Chip Identification 73------------------- 74 75PFs belonging to the same chip are identified using a driver-specific method. 76The driver is free to choose any identifier that is suitable for determining 77whether two PFs are part of the same device. Examples include: 78 79* **PCI VPD serial numbers**: Extract from PCI VPD 80* **Device tree properties**: Read chip identifier from device tree 81* **Other hardware-specific identifiers**: Any unique identifier that groups PFs by chip 82 83Locking 84------- 85 86A global mutex (``shd_mutex``) protects the shared instances list during registration/deregistration. 87 88Similarly to other nested devlink instance relationships, devlink lock of 89the shared instance should be always taken after the devlink lock of PF. 90 91Reference Counting 92------------------ 93 94Each shared devlink instance maintains a reference count (``refcount_t refcount``). 95The reference count is incremented when ``devlink_shd_get()`` is called and decremented 96when ``devlink_shd_put()`` is called. When the reference count reaches zero, the shared 97instance is automatically destroyed. 98