openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: driver-model: Add documentation for sync_state 

The sync_state() driver callback was added recently, but the
documentation was missing.  Adding it now.

Signed-off-by: Saravana Kannan <saravanak@google.com>
Link: https://lore.kernel.org/r/20191011191521.179614-4-saravanak@google.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Saravana Kannan 2019-10-11 12:15:21 -07:00 committed by Greg Kroah-Hartman
parent 92df01e360
commit a3caeb8ffe
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
Documentation/driver-api/driver-model/driver.rst
View File

@ -169,6 +169,49 @@ A driver's probe() may return a negative errno value to indicate that
the driver did not bind to this device, in which case it should have
released all resources it allocated::
void (*sync_state)(struct device *dev);
sync_state is called only once for a device. It's called when all the consumer
devices of the device have successfully probed. The list of consumers of the
device is obtained by looking at the device links connecting that device to its
consumer devices.
The first attempt to call sync_state() is made during late_initcall_sync() to
give firmware and drivers time to link devices to each other. During the first
attempt at calling sync_state(), if all the consumers of the device at that
point in time have already probed successfully, sync_state() is called right
away. If there are no consumers of the device during the first attempt, that
too is considered as "all consumers of the device have probed" and sync_state()
is called right away.
If during the first attempt at calling sync_state() for a device, there are
still consumers that haven't probed successfully, the sync_state() call is
postponed and reattempted in the future only when one or more consumers of the
device probe successfully. If during the reattempt, the driver core finds that
there are one or more consumers of the device that haven't probed yet, then
sync_state() call is postponed again.
A typical use case for sync_state() is to have the kernel cleanly take over
management of devices from the bootloader. For example, if a device is left on
and at a particular hardware configuration by the bootloader, the device's
driver might need to keep the device in the boot configuration until all the
consumers of the device have probed. Once all the consumers of the device have
probed, the device's driver can synchronize the hardware state of the device to
match the aggregated software state requested by all the consumers. Hence the
name sync_state().
While obvious examples of resources that can benefit from sync_state() include
resources such as regulator, sync_state() can also be useful for complex
resources like IOMMUs. For example, IOMMUs with multiple consumers (devices
whose addresses are remapped by the IOMMU) might need to keep their mappings
fixed at (or additive to) the boot configuration until all its consumers have
probed.
While the typical use case for sync_state() is to have the kernel cleanly take
over management of devices from the bootloader, the usage of sync_state() is
not restricted to that. Use it whenever it makes sense to take an action after
all the consumers of a device have probed.
int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be