renegade-project/linux-next
2
0
Fork 0
mirror of https://github.com/edk2-porting/linux-next.git synced 2024-12-25 13:43:55 +08:00
Code

Documentation/auxiliary_bus: Update Auxiliary device lifespan

Browse Source 
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>
This commit is contained in:
Ira Weiny 2021-12-01 20:43:01 -08:00 committed by Greg Kroah-Hartman
parent 0d058a206a
commit cb2ba75935
1 changed files with 21 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/driver-api/auxiliary_bus.rst
View File

@ -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
=================