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