diff options
| author | Ira Weiny <ira.weiny@intel.com> | 2021-12-01 20:43:01 -0800 |
|---|---|---|
| committer | Greg Kroah-Hartman <gregkh@linuxfoundation.org> | 2021-12-03 16:41:50 +0100 |
| commit | cb2ba75935558e65f2c4fe411a78c375b2c64cb4 (patch) | |
| tree | 47b29f6d5a70bf53ac735bef39ea98dffaaf90e2 /Documentation/driver-api | |
| parent | 0d058a206adadf0c38f891b19dbdcb2963a1cd20 (diff) | |
Documentation/auxiliary_bus: Update Auxiliary device lifespan
It was unclear when the auxiliary device objects were to be free'ed by
the parent (registering) driver.
Also there are some patterns like using devm_add_action_or_reset() which
are helpful to mention to those using the interface to ensure they don't
double free or miss freeing the auxiliary devices.
Signed-off-by: Ira Weiny <ira.weiny@intel.com>
Link: https://lore.kernel.org/r/20211202044305.4006853-4-ira.weiny@intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/auxiliary_bus.rst | 32 |
1 files changed, 21 insertions, 11 deletions
diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index b041a72dc322..3786e4664a1e 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -164,9 +164,15 @@ Auxiliary Device Memory Model and Lifespan ------------------------------------------ The registering driver is the entity that allocates memory for the -auxiliary_device and register it on the auxiliary bus. It is important to note +auxiliary_device and registers it on the auxiliary bus. It is important to note that, as opposed to the platform bus, the registering driver is wholly -responsible for the management for the memory used for the driver object. +responsible for the management of the memory used for the device object. + +To be clear the memory for the auxiliary_device is freed in the release() +callback defined by the registering driver. The registering driver should only +call auxiliary_device_delete() and then auxiliary_device_uninit() when it is +done with the device. The release() function is then automatically called if +and when other code releases their reference to the devices. A parent object, defined in the shared header file, contains the auxiliary_device. It also contains a pointer to the shared object(s), which @@ -177,18 +183,22 @@ from the pointer to the auxiliary_device, that is passed during the call to the auxiliary_driver's probe function, up to the parent object, and then have access to the shared object(s). -The memory for the auxiliary_device is freed only in its release() callback -flow as defined by its registering driver. - The memory for the shared object(s) must have a lifespan equal to, or greater -than, the lifespan of the memory for the auxiliary_device. The auxiliary_driver -should only consider that this shared object is valid as long as the -auxiliary_device is still registered on the auxiliary bus. It is up to the -registering driver to manage (e.g. free or keep available) the memory for the -shared object beyond the life of the auxiliary_device. +than, the lifespan of the memory for the auxiliary_device. The +auxiliary_driver should only consider that the shared object is valid as long +as the auxiliary_device is still registered on the auxiliary bus. It is up to +the registering driver to manage (e.g. free or keep available) the memory for +the shared object beyond the life of the auxiliary_device. The registering driver must unregister all auxiliary devices before its own -driver.remove() is completed. +driver.remove() is completed. An easy way to ensure this is to use the +devm_add_action_or_reset() call to register a function against the parent device +which unregisters the auxiliary device object(s). + +Finally, any operations which operate on the auxiliary devices must continue to +function (if only to return an error) after the registering driver unregisters +the auxiliary device. + Auxiliary Drivers ================= |