| 1 | |
| 2 |
|
| 3 | ========================
|
| 4 | Devlink Shared Instances
|
| 5 | ========================
|
| 6 |
|
| 7 | Overview
|
| 8 | ========
|
| 9 |
|
| 10 | Shared devlink instances allow multiple physical functions (PFs) on the same
|
| 11 | chip to share a devlink instance for chip-wide operations.
|
| 12 |
|
| 13 | Multiple PFs may reside on the same physical chip, running a single firmware.
|
| 14 | Some of the resources and configurations may be shared among these PFs. The
|
| 15 | shared devlink instance provides an object to pin configuration knobs on.
|
| 16 |
|
| 17 | There are two possible usage models:
|
| 18 |
|
| 19 | 1. The shared devlink instance is used alongside individual PF devlink
|
| 20 | instances, providing chip-wide configuration in addition to per-PF
|
| 21 | configuration.
|
| 22 | 2. The shared devlink instance is the only devlink instance, without
|
| 23 | per-PF instances.
|
| 24 |
|
| 25 | It is up to the driver to decide which usage model to use.
|
| 26 |
|
| 27 | The shared devlink instance is not backed by any struct *device*.
|
| 28 |
|
| 29 | Implementation
|
| 30 | ==============
|
| 31 |
|
| 32 | Architecture
|
| 33 | ------------
|
| 34 |
|
| 35 | The 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 |
|
| 40 | API Functions
|
| 41 | -------------
|
| 42 |
|
| 43 | The 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 |
|
| 49 | Initialization Flow
|
| 50 | -------------------
|
| 51 |
|
| 52 | 1. **PF calls shared devlink init** during driver probe
|
| 53 | 2. **Chip identification** using driver-specific method to determine device identity
|
| 54 | 3. **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 |
|
| 62 | 4. **Set nested devlink instance** for the PF devlink instance using
|
| 63 | ``devl_nested_devlink_set()`` before registering the PF devlink instance
|
| 64 |
|
| 65 | Cleanup Flow
|
| 66 | ------------
|
| 67 |
|
| 68 | 1. **Cleanup** when PF is removed
|
| 69 | 2. **Call** ``devlink_shd_put()`` to release reference (decrements reference count)
|
| 70 | 3. **Shared instance is automatically destroyed** when the last PF removes (reference count reaches zero)
|
| 71 |
|
| 72 | Chip Identification
|
| 73 | -------------------
|
| 74 |
|
| 75 | PFs belonging to the same chip are identified using a driver-specific method.
|
| 76 | The driver is free to choose any identifier that is suitable for determining
|
| 77 | whether 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 |
|
| 83 | Locking
|
| 84 | -------
|
| 85 |
|
| 86 | A global mutex (``shd_mutex``) protects the shared instances list during registration/deregistration.
|
| 87 |
|
| 88 | Similarly to other nested devlink instance relationships, devlink lock of
|
| 89 | the shared instance should be always taken after the devlink lock of PF.
|
| 90 |
|
| 91 | Reference Counting
|
| 92 | ------------------
|
| 93 |
|
| 94 | Each shared devlink instance maintains a reference count (``refcount_t refcount``).
|
| 95 | The reference count is incremented when ``devlink_shd_get()`` is called and decremented
|
| 96 | when ``devlink_shd_put()`` is called. When the reference count reaches zero, the shared
|
| 97 | instance is automatically destroyed.
|