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