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 | 169 | the driver did not bind to this device, in which case it should have |
| 170 | 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 | 215 | int (*remove) (struct device *dev); |
| 173 | 216 | |
| 174 | 217 | remove is called to unbind a driver from a device. This may be |