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