The sync_state() driver callback was added recently, but the documentation was missing. Adding it now.
Unified · Split
| @@ -169,6 +169,49 @@ A driver's probe() may return a negative errno value to indicate that · 168 unmodified lines | |||
| 169 | the driver did not bind to this device, in which case it should have | 169 | the driver did not bind to this device, in which case it should have |
| 170 | released all resources it allocated:: | 170 | released all resources it allocated:: |
| 171 | 171 | ||
| 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 | |||
| 172 | int (*remove) (struct device *dev); | 215 | int (*remove) (struct device *dev); |
| 173 | 216 | ||
| 174 | remove is called to unbind a driver from a device. This may be | 217 | remove is called to unbind a driver from a device. This may be |