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