1============== 2Device Drivers 3============== 4 5See the kerneldoc for the struct device_driver. 6 7 8Allocation 9~~~~~~~~~~ 10 11Device drivers are statically allocated structures. Though there may 12be multiple devices in a system that a driver supports, struct 13device_driver represents the driver as a whole (not a particular 14device instance). 15 16Initialization 17~~~~~~~~~~~~~~ 18 19The driver must initialize at least the name and bus fields. It should 20also initialize the devclass field (when it arrives), so it may obtain 21the proper linkage internally. It should also initialize as many of 22the callbacks as possible, though each is optional. 23 24Declaration 25~~~~~~~~~~~ 26 27As stated above, struct device_driver objects are statically 28allocated. Below is an example declaration of the eepro100 29driver. This declaration is hypothetical only; it relies on the driver 30being converted completely to the new model:: 31 32 static struct device_driver eepro100_driver = { 33 .name = "eepro100", 34 .bus = &pci_bus_type, 35 36 .probe = eepro100_probe, 37 .remove = eepro100_remove, 38 .suspend = eepro100_suspend, 39 .resume = eepro100_resume, 40 }; 41 42Most drivers will not be able to be converted completely to the new 43model because the bus they belong to has a bus-specific structure with 44bus-specific fields that cannot be generalized. 45 46The most common example of this are device ID structures. A driver 47typically defines an array of device IDs that it supports. The format 48of these structures and the semantics for comparing device IDs are 49completely bus-specific. Defining them as bus-specific entities would 50sacrifice type-safety, so we keep bus-specific structures around. 51 52Bus-specific drivers should include a generic struct device_driver in 53the definition of the bus-specific driver. Like this:: 54 55 struct pci_driver { 56 const struct pci_device_id *id_table; 57 struct device_driver driver; 58 }; 59 60A definition that included bus-specific fields would look like 61(using the eepro100 driver again):: 62 63 static struct pci_driver eepro100_driver = { 64 .id_table = eepro100_pci_tbl, 65 .driver = { 66 .name = "eepro100", 67 .bus = &pci_bus_type, 68 .probe = eepro100_probe, 69 .remove = eepro100_remove, 70 .suspend = eepro100_suspend, 71 .resume = eepro100_resume, 72 }, 73 }; 74 75Some may find the syntax of embedded struct initialization awkward or 76even a bit ugly. So far, it's the best way we've found to do what we want... 77 78Registration 79~~~~~~~~~~~~ 80 81:: 82 83 int driver_register(struct device_driver *drv); 84 85The driver registers the structure on startup. For drivers that have 86no bus-specific fields (i.e. don't have a bus-specific driver 87structure), they would use driver_register and pass a pointer to their 88struct device_driver object. 89 90Most drivers, however, will have a bus-specific structure and will 91need to register with the bus using something like pci_driver_register. 92 93It is important that drivers register their driver structure as early as 94possible. Registration with the core initializes several fields in the 95struct device_driver object, including the reference count and the 96lock. These fields are assumed to be valid at all times and may be 97used by the device model core or the bus driver. 98 99 100Transition Bus Drivers 101~~~~~~~~~~~~~~~~~~~~~~ 102 103By defining wrapper functions, the transition to the new model can be 104made easier. Drivers can ignore the generic structure altogether and 105let the bus wrapper fill in the fields. For the callbacks, the bus can 106define generic callbacks that forward the call to the bus-specific 107callbacks of the drivers. 108 109This solution is intended to be only temporary. In order to get class 110information in the driver, the drivers must be modified anyway. Since 111converting drivers to the new model should reduce some infrastructural 112complexity and code size, it is recommended that they are converted as 113class information is added. 114 115Access 116~~~~~~ 117 118Once the object has been registered, it may access the common fields of 119the object, like the lock and the list of devices:: 120 121 int driver_for_each_dev(struct device_driver *drv, void *data, 122 int (*callback)(struct device *dev, void *data)); 123 124The devices field is a list of all the devices that have been bound to 125the driver. The LDM core provides a helper function to operate on all 126the devices a driver controls. This helper locks the driver on each 127node access, and does proper reference counting on each device as it 128accesses it. 129 130 131sysfs 132~~~~~ 133 134When a driver is registered, a sysfs directory is created in its 135bus's directory. In this directory, the driver can export an interface 136to userspace to control operation of the driver on a global basis; 137e.g. toggling debugging output in the driver. 138 139A future feature of this directory will be a 'devices' directory. This 140directory will contain symlinks to the directories of devices it 141supports. 142 143 144 145Callbacks 146~~~~~~~~~ 147 148:: 149 150 int (*probe) (struct device *dev); 151 152The probe() entry is called in task context, with the bus's rwsem locked 153and the driver partially bound to the device. Drivers commonly use 154container_of() to convert "dev" to a bus-specific type, both in probe() 155and other routines. That type often provides device resource data, such 156as pci_dev.resource[] or platform_device.resources, which is used in 157addition to dev->platform_data to initialize the driver. 158 159This callback holds the driver-specific logic to bind the driver to a 160given device. That includes verifying that the device is present, that 161it's a version the driver can handle, that driver data structures can 162be allocated and initialized, and that any hardware can be initialized. 163Drivers often store a pointer to their state with dev_set_drvdata(). 164When the driver has successfully bound itself to that device, then probe() 165returns zero and the driver model code will finish its part of binding 166the driver to that device. 167 168A driver's probe() may return a negative errno value to indicate that 169the driver did not bind to this device, in which case it should have 170released all resources it allocated:: 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 215 int (*remove) (struct device *dev); 216 217remove is called to unbind a driver from a device. This may be 218called if a device is physically removed from the system, if the 219driver module is being unloaded, during a reboot sequence, or 220in other cases. 221 222It is up to the driver to determine if the device is present or 223not. It should free any resources allocated specifically for the 224device; i.e. anything in the device's driver_data field. 225 226If the device is still present, it should quiesce the device and place 227it into a supported low-power state:: 228 229 int (*suspend) (struct device *dev, pm_message_t state); 230 231suspend is called to put the device in a low power state:: 232 233 int (*resume) (struct device *dev); 234 235Resume is used to bring a device back from a low power state. 236 237 238Attributes 239~~~~~~~~~~ 240 241:: 242 243 struct driver_attribute { 244 struct attribute attr; 245 ssize_t (*show)(struct device_driver *driver, char *buf); 246 ssize_t (*store)(struct device_driver *, const char *buf, size_t count); 247 }; 248 249Device drivers can export attributes via their sysfs directories. 250Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO 251macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO 252macros. 253 254Example:: 255 256 DRIVER_ATTR_RW(debug); 257 258This is equivalent to declaring:: 259 260 struct driver_attribute driver_attr_debug; 261 262This can then be used to add and remove the attribute from the 263driver's directory using:: 264 265 int driver_create_file(struct device_driver *, const struct driver_attribute *); 266 void driver_remove_file(struct device_driver *, const struct driver_attribute *); 267