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