.. SPDX-License-Identifier: GPL-2.0 ========================Devlink Shared Instances======================== Overview======== Shared devlink instances allow multiple physical functions (PFs) on the samechip to share a devlink instance for chip-wide operations. 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. Theshared devlink instance provides an object to pin configuration knobs on. There are two possible usage models: 1. The shared devlink instance is used alongside individual PF devlink   instances, providing chip-wide configuration in addition to per-PF   configuration.2. The shared devlink instance is the only devlink instance, without   per-PF instances. It is up to the driver to decide which usage model to use. The shared devlink instance is not backed by any struct *device*. Implementation============== Architecture------------ The implementation uses: * **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 probe2. **Chip identification** using driver-specific method to determine device identity3. **Get or create shared instance** using ``devlink_shd_get()``:    * The function looks up existing instance by identifier   * If none exists, creates new instance:     - 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 removed2. **Call** ``devlink_shd_put()`` to release reference (decrements reference count)3. **Shared instance is automatically destroyed** when the last PF removes (reference count reaches zero) 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 determiningwhether 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 ofthe shared instance should be always taken after the devlink lock of 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 decrementedwhen ``devlink_shd_put()`` is called. When the reference count reaches zero, the sharedinstance is automatically destroyed.