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