Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
1 2 Device Drivers 3 4 See the kerneldoc for the struct device_driver. 5 6 7 Allocation 8 ~~~~~~~~~~ 9 10 Device drivers are statically allocated structures. Though there may 11 be multiple devices in a system that a driver supports, struct 12 device_driver represents the driver as a whole (not a particular 13 device instance). 14 15 Initialization 16 ~~~~~~~~~~~~~~ 17 18 The driver must initialize at least the name and bus fields. It should 19 also initialize the devclass field (when it arrives), so it may obtain 20 the proper linkage internally. It should also initialize as many of 21 the callbacks as possible, though each is optional. 22 23 Declaration 24 ~~~~~~~~~~~ 25 26 As stated above, struct device_driver objects are statically 27 allocated. Below is an example declaration of the eepro100 28 driver. This declaration is hypothetical only; it relies on the driver 29 being 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 41 Most drivers will not be able to be converted completely to the new 42 model because the bus they belong to has a bus-specific structure with 43 bus-specific fields that cannot be generalized. 44 45 The most common example of this are device ID structures. A driver 46 typically defines an array of device IDs that it supports. The format 47 of these structures and the semantics for comparing device IDs are 48 completely bus-specific. Defining them as bus-specific entities would 49 sacrifice type-safety, so we keep bus-specific structures around. 50 51 Bus-specific drivers should include a generic struct device_driver in 52 the 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 59 A 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 74 Some may find the syntax of embedded struct initialization awkward or 75 even a bit ugly. So far, it's the best way we've found to do what we want... 76 77 Registration 78 ~~~~~~~~~~~~ 79 80 int driver_register(struct device_driver * drv); 81 82 The driver registers the structure on startup. For drivers that have 83 no bus-specific fields (i.e. don't have a bus-specific driver 84 structure), they would use driver_register and pass a pointer to their 85 struct device_driver object. 86 87 Most drivers, however, will have a bus-specific structure and will 88 need to register with the bus using something like pci_driver_register. 89 90 It is important that drivers register their driver structure as early as 91 possible. Registration with the core initializes several fields in the 92 struct device_driver object, including the reference count and the 93 lock. These fields are assumed to be valid at all times and may be 94 used by the device model core or the bus driver. 95 96 97 Transition Bus Drivers 98 ~~~~~~~~~~~~~~~~~~~~~~ 99 100 By defining wrapper functions, the transition to the new model can be 101 made easier. Drivers can ignore the generic structure altogether and 102 let the bus wrapper fill in the fields. For the callbacks, the bus can 103 define generic callbacks that forward the call to the bus-specific 104 callbacks of the drivers. 105 106 This solution is intended to be only temporary. In order to get class 107 information in the driver, the drivers must be modified anyway. Since 108 converting drivers to the new model should reduce some infrastructural 109 complexity and code size, it is recommended that they are converted as 110 class information is added. 111 112 Access 113 ~~~~~~ 114 115 Once the object has been registered, it may access the common fields of 116 the object, like the lock and the list of devices. 117 118 int driver_for_each_dev(struct device_driver * drv, void * data, 119 int (*callback)(struct device * dev, void * data)); 120 121 The devices field is a list of all the devices that have been bound to 122 the driver. The LDM core provides a helper function to operate on all 123 the devices a driver controls. This helper locks the driver on each 124 node access, and does proper reference counting on each device as it 125 accesses it. 126 127 128 sysfs 129 ~~~~~ 130 131 When a driver is registered, a sysfs directory is created in its 132 bus's directory. In this directory, the driver can export an interface 133 to userspace to control operation of the driver on a global basis; 134 e.g. toggling debugging output in the driver. 135 136 A future feature of this directory will be a 'devices' directory. This 137 directory will contain symlinks to the directories of devices it 138 supports. 139 140 141 142 Callbacks 143 ~~~~~~~~~ 144 145 int (*probe) (struct device * dev); 146 147 The probe() entry is called in task context, with the bus's rwsem locked 148 and the driver partially bound to the device. Drivers commonly use 149 container_of() to convert "dev" to a bus-specific type, both in probe() 150 and other routines. That type often provides device resource data, such 151 as pci_dev.resource[] or platform_device.resources, which is used in 152 addition to dev->platform_data to initialize the driver. 153 154 This callback holds the driver-specific logic to bind the driver to a 155 given device. That includes verifying that the device is present, that 156 it's a version the driver can handle, that driver data structures can 157 be allocated and initialized, and that any hardware can be initialized. 158 Drivers often store a pointer to their state with dev_set_drvdata(). 159 When the driver has successfully bound itself to that device, then probe() 160 returns zero and the driver model code will finish its part of binding 161 the driver to that device. 162 163 A driver's probe() may return a negative errno value to indicate that 164 the driver did not bind to this device, in which case it should have 165 released all resources it allocated. 166 167 int (*remove) (struct device * dev); 168 169 remove is called to unbind a driver from a device. This may be 170 called if a device is physically removed from the system, if the 171 driver module is being unloaded, during a reboot sequence, or 172 in other cases. 173 174 It is up to the driver to determine if the device is present or 175 not. It should free any resources allocated specifically for the 176 device; i.e. anything in the device's driver_data field. 177 178 If the device is still present, it should quiesce the device and place 179 it into a supported low-power state. 180 181 int (*suspend) (struct device * dev, pm_message_t state); 182 183 suspend is called to put the device in a low power state. 184 185 int (*resume) (struct device * dev); 186 187 Resume is used to bring a device back from a low power state. 188 189 190 Attributes 191 ~~~~~~~~~~ 192 struct driver_attribute { 193 struct attribute attr; 194 ssize_t (*show)(struct device_driver *driver, char *buf); 195 ssize_t (*store)(struct device_driver *, const char * buf, size_t count); 196 }; 197 198 Device drivers can export attributes via their sysfs directories. 199 Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO 200 macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO 201 macros. 202 203 Example: 204 205 DRIVER_ATTR_RW(debug); 206 207 This is equivalent to declaring: 208 209 struct driver_attribute driver_attr_debug; 210 211 This can then be used to add and remove the attribute from the 212 driver's directory using: 213 214 int driver_create_file(struct device_driver *, const struct driver_attribute *); 215 void driver_remove_file(struct device_driver *, const struct driver_attribute *);