History

docs: driver-model: Add documentation for sync_state

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

Saravana Kannan committed 7 years ago

Commit a3caeb81 parent 92df01e1 file · +43 −0Browse files

Showing the changes to Documentation/driver-api/driver-model (1 of 1 file). Show all

Unified · Split

Documentation/driver-api/driver-model/driver.rst+43−0
@@ -169,6 +169,49 @@ A driver's probe() may return a negative errno value to indicate that · 168 unmodified lines
169the driver did not bind to this device, in which case it should have169the driver did not bind to this device, in which case it should have
170released all resources it allocated::170released all resources it allocated::
171 171
172 void (*sync_state)(struct device *dev);
173
174sync_state is called only once for a device. It's called when all the consumer
175devices of the device have successfully probed. The list of consumers of the
176device is obtained by looking at the device links connecting that device to its
177consumer devices.
178
179The first attempt to call sync_state() is made during late_initcall_sync() to
180give firmware and drivers time to link devices to each other. During the first
181attempt at calling sync_state(), if all the consumers of the device at that
182point in time have already probed successfully, sync_state() is called right
183away. If there are no consumers of the device during the first attempt, that
184too is considered as "all consumers of the device have probed" and sync_state()
185is called right away.
186
187If during the first attempt at calling sync_state() for a device, there are
188still consumers that haven't probed successfully, the sync_state() call is
189postponed and reattempted in the future only when one or more consumers of the
190device probe successfully. If during the reattempt, the driver core finds that
191there are one or more consumers of the device that haven't probed yet, then
192sync_state() call is postponed again.
193
194A typical use case for sync_state() is to have the kernel cleanly take over
195management of devices from the bootloader. For example, if a device is left on
196and at a particular hardware configuration by the bootloader, the device's
197driver might need to keep the device in the boot configuration until all the
198consumers of the device have probed. Once all the consumers of the device have
199probed, the device's driver can synchronize the hardware state of the device to
200match the aggregated software state requested by all the consumers. Hence the
201name sync_state().
202
203While obvious examples of resources that can benefit from sync_state() include
204resources such as regulator, sync_state() can also be useful for complex
205resources like IOMMUs. For example, IOMMUs with multiple consumers (devices
206whose addresses are remapped by the IOMMU) might need to keep their mappings
207fixed at (or additive to) the boot configuration until all its consumers have
208probed.
209
210While the typical use case for sync_state() is to have the kernel cleanly take
211over management of devices from the bootloader, the usage of sync_state() is
212not restricted to that. Use it whenever it makes sense to take an action after
213all the consumers of a device have probed.
214
172 int (*remove) (struct device *dev);215 int (*remove) (struct device *dev);
173 216
174remove is called to unbind a driver from a device. This may be217remove is called to unbind a driver from a device. This may be

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t