1============== 2Device Drivers 3============== 4 5See the kerneldoc for the struct device_driver. 6 7Allocation 8~~~~~~~~~~ 9 10Device drivers are statically allocated structures. Though there may 11be multiple devices in a system that a driver supports, struct 12device_driver represents the driver as a whole (not a particular 13device instance). 14 15Initialization 16~~~~~~~~~~~~~~ 17 18The driver must initialize at least the name and bus fields. It should 19also initialize the devclass field (when it arrives), so it may obtain 20the proper linkage internally. It should also initialize as many of 21the callbacks as possible, though each is optional. 22 23Declaration 24~~~~~~~~~~~ 25 26As stated above, struct device_driver objects are statically 27allocated. Below is an example declaration of the eepro100 28driver. This declaration is hypothetical only; it relies on the driver 29being converted completely to the new model:: 30 31 static struct device_driver eepro100_driver = { 32 .name = "eepro100", 33 .bus = &pci_bus_type, 34 35 .probe = eepro100_probe, 36 .remove = eepro100_remove, 37 .suspend = eepro100_suspend, 38 .resume = eepro100_resume, 39 }; 40 41Most drivers will not be able to be converted completely to the new 42model because the bus they belong to has a bus-specific structure with 43bus-specific fields that cannot be generalized. 44 45The most common example of this are device ID structures. A driver 46typically defines an array of device IDs that it supports. The format 47of these structures and the semantics for comparing device IDs are 48completely bus-specific. Defining them as bus-specific entities would 49sacrifice type-safety, so we keep bus-specific structures around. 50 51Bus-specific drivers should include a generic struct device_driver in 52the definition of the bus-specific driver. Like this:: 53 54 struct pci_driver { 55 const struct pci_device_id *id_table; 56 struct device_driver driver; 57 }; 58 59A definition that included bus-specific fields would look like 60(using the eepro100 driver again):: 61 62 static struct pci_driver eepro100_driver = { 63 .id_table = eepro100_pci_tbl, 64 .driver = { 65 .name = "eepro100", 66 .bus = &pci_bus_type, 67 .probe = eepro100_probe, 68 .remove = eepro100_remove, 69 .suspend = eepro100_suspend, 70 .resume = eepro100_resume, 71 }, 72 }; 73 74Some may find the syntax of embedded struct initialization awkward or 75even a bit ugly. So far, it's the best way we've found to do what we want... 76 77Registration 78~~~~~~~~~~~~ 79 80:: 81 82 int driver_register(struct device_driver *drv); 83 84The driver registers the structure on startup. For drivers that have 85no bus-specific fields (i.e. don't have a bus-specific driver 86structure), they would use driver_register and pass a pointer to their 87struct device_driver object. 88 89Most drivers, however, will have a bus-specific structure and will 90need to register with the bus using something like pci_driver_register. 91 92It is important that drivers register their driver structure as early as 93possible. Registration with the core initializes several fields in the 94struct device_driver object, including the reference count and the 95lock. These fields are assumed to be valid at all times and may be 96used by the device model core or the bus driver. 97 98 99Transition Bus Drivers 100~~~~~~~~~~~~~~~~~~~~~~ 101 102By defining wrapper functions, the transition to the new model can be 103made easier. Drivers can ignore the generic structure altogether and 104let the bus wrapper fill in the fields. For the callbacks, the bus can 105define generic callbacks that forward the call to the bus-specific 106callbacks of the drivers. 107 108This solution is intended to be only temporary. In order to get class 109information in the driver, the drivers must be modified anyway. Since 110converting drivers to the new model should reduce some infrastructural 111complexity and code size, it is recommended that they are converted as 112class information is added. 113 114Access 115~~~~~~ 116 117Once the object has been registered, it may access the common fields of 118the object, like the lock and the list of devices:: 119 120 int driver_for_each_dev(struct device_driver *drv, void *data, 121 int (*callback)(struct device *dev, void *data)); 122 123The devices field is a list of all the devices that have been bound to 124the driver. The LDM core provides a helper function to operate on all 125the devices a driver controls. This helper locks the driver on each 126node access, and does proper reference counting on each device as it 127accesses it. 128 129 130sysfs 131~~~~~ 132 133When a driver is registered, a sysfs directory is created in its 134bus's directory. In this directory, the driver can export an interface 135to userspace to control operation of the driver on a global basis; 136e.g. toggling debugging output in the driver. 137 138A future feature of this directory will be a 'devices' directory. This 139directory will contain symlinks to the directories of devices it 140supports. 141 142 143 144Callbacks 145~~~~~~~~~ 146 147:: 148 149 int (*probe) (struct device *dev); 150 151The probe() entry is called in task context, with the bus's rwsem locked 152and the driver partially bound to the device. Drivers commonly use 153container_of() to convert "dev" to a bus-specific type, both in probe() 154and other routines. That type often provides device resource data, such 155as pci_dev.resource[] or platform_device.resources, which is used in 156addition to dev->platform_data to initialize the driver. 157 158This callback holds the driver-specific logic to bind the driver to a 159given device. That includes verifying that the device is present, that 160it's a version the driver can handle, that driver data structures can 161be allocated and initialized, and that any hardware can be initialized. 162Drivers often store a pointer to their state with dev_set_drvdata(). 163When the driver has successfully bound itself to that device, then probe() 164returns zero and the driver model code will finish its part of binding 165the driver to that device. 166 167A driver's probe() may return a negative errno value to indicate that 168the driver did not bind to this device, in which case it should have 169released all resources it allocated. 170 171Optionally, probe() may return -EPROBE_DEFER if the driver depends on 172resources that are not yet available (e.g., supplied by a driver that 173hasn't initialized yet). The driver core will put the device onto the 174deferred probe list and will try to call it again later. If a driver 175must defer, it should return -EPROBE_DEFER as early as possible to 176reduce the amount of time spent on setup work that will need to be 177unwound and reexecuted at a later time. 178 179.. warning:: 180 -EPROBE_DEFER must not be returned if probe() has already created 181 child devices, even if those child devices are removed again 182 in a cleanup path. If -EPROBE_DEFER is returned after a child 183 device has been registered, it may result in an infinite loop of 184 .probe() calls to the same driver. 185 186:: 187 188 void (*sync_state) (struct device *dev); 189 190sync_state is called only once for a device. It's called when all the consumer 191devices of the device have successfully probed. The list of consumers of the 192device is obtained by looking at the device links connecting that device to its 193consumer devices. 194 195The first attempt to call sync_state() is made during late_initcall_sync() to 196give firmware and drivers time to link devices to each other. During the first 197attempt at calling sync_state(), if all the consumers of the device at that 198point in time have already probed successfully, sync_state() is called right 199away. If there are no consumers of the device during the first attempt, that 200too is considered as "all consumers of the device have probed" and sync_state() 201is called right away. 202 203If during the first attempt at calling sync_state() for a device, there are 204still consumers that haven't probed successfully, the sync_state() call is 205postponed and reattempted in the future only when one or more consumers of the 206device probe successfully. If during the reattempt, the driver core finds that 207there are one or more consumers of the device that haven't probed yet, then 208sync_state() call is postponed again. 209 210A typical use case for sync_state() is to have the kernel cleanly take over 211management of devices from the bootloader. For example, if a device is left on 212and at a particular hardware configuration by the bootloader, the device's 213driver might need to keep the device in the boot configuration until all the 214consumers of the device have probed. Once all the consumers of the device have 215probed, the device's driver can synchronize the hardware state of the device to 216match the aggregated software state requested by all the consumers. Hence the 217name sync_state(). 218 219While obvious examples of resources that can benefit from sync_state() include 220resources such as regulator, sync_state() can also be useful for complex 221resources like IOMMUs. For example, IOMMUs with multiple consumers (devices 222whose addresses are remapped by the IOMMU) might need to keep their mappings 223fixed at (or additive to) the boot configuration until all its consumers have 224probed. 225 226While the typical use case for sync_state() is to have the kernel cleanly take 227over management of devices from the bootloader, the usage of sync_state() is 228not restricted to that. Use it whenever it makes sense to take an action after 229all the consumers of a device have probed:: 230 231 int (*remove) (struct device *dev); 232 233remove is called to unbind a driver from a device. This may be 234called if a device is physically removed from the system, if the 235driver module is being unloaded, during a reboot sequence, or 236in other cases. 237 238It is up to the driver to determine if the device is present or 239not. It should free any resources allocated specifically for the 240device; i.e. anything in the device's driver_data field. 241 242If the device is still present, it should quiesce the device and place 243it into a supported low-power state. 244 245:: 246 247 int (*suspend) (struct device *dev, pm_message_t state); 248 249suspend is called to put the device in a low power state. 250 251:: 252 253 int (*resume) (struct device *dev); 254 255Resume is used to bring a device back from a low power state. 256 257 258Attributes 259~~~~~~~~~~ 260 261:: 262 263 struct driver_attribute { 264 struct attribute attr; 265 ssize_t (*show)(struct device_driver *driver, char *buf); 266 ssize_t (*store)(struct device_driver *, const char *buf, size_t count); 267 }; 268 269Device drivers can export attributes via their sysfs directories. 270Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO 271macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO 272macros. 273 274Example:: 275 276 DRIVER_ATTR_RW(debug); 277 278This is equivalent to declaring:: 279 280 struct driver_attribute driver_attr_debug; 281 282This can then be used to add and remove the attribute from the 283driver's directory using:: 284 285 int driver_create_file(struct device_driver *, const struct driver_attribute *); 286 void driver_remove_file(struct device_driver *, const struct driver_attribute *); 287