Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Device Drivers | |
3 | ||
4 | struct device_driver { | |
5 | char * name; | |
6 | struct bus_type * bus; | |
7 | ||
8 | rwlock_t lock; | |
9 | atomic_t refcount; | |
10 | ||
11 | list_t bus_list; | |
12 | list_t devices; | |
13 | ||
14 | struct driver_dir_entry dir; | |
15 | ||
16 | int (*probe) (struct device * dev); | |
17 | int (*remove) (struct device * dev); | |
18 | ||
438510f6 | 19 | int (*suspend) (struct device * dev, pm_message_t state, u32 level); |
1da177e4 LT |
20 | int (*resume) (struct device * dev, u32 level); |
21 | ||
22 | void (*release) (struct device_driver * drv); | |
23 | }; | |
24 | ||
25 | ||
26 | ||
27 | Allocation | |
28 | ~~~~~~~~~~ | |
29 | ||
30 | Device drivers are statically allocated structures. Though there may | |
31 | be multiple devices in a system that a driver supports, struct | |
32 | device_driver represents the driver as a whole (not a particular | |
33 | device instance). | |
34 | ||
35 | Initialization | |
36 | ~~~~~~~~~~~~~~ | |
37 | ||
38 | The driver must initialize at least the name and bus fields. It should | |
39 | also initialize the devclass field (when it arrives), so it may obtain | |
40 | the proper linkage internally. It should also initialize as many of | |
41 | the callbacks as possible, though each is optional. | |
42 | ||
43 | Declaration | |
44 | ~~~~~~~~~~~ | |
45 | ||
46 | As stated above, struct device_driver objects are statically | |
47 | allocated. Below is an example declaration of the eepro100 | |
48 | driver. This declaration is hypothetical only; it relies on the driver | |
49 | being converted completely to the new model. | |
50 | ||
51 | static struct device_driver eepro100_driver = { | |
52 | .name = "eepro100", | |
53 | .bus = &pci_bus_type, | |
54 | .devclass = ðernet_devclass, /* when it's implemented */ | |
55 | ||
56 | .probe = eepro100_probe, | |
57 | .remove = eepro100_remove, | |
58 | .suspend = eepro100_suspend, | |
59 | .resume = eepro100_resume, | |
60 | }; | |
61 | ||
62 | Most drivers will not be able to be converted completely to the new | |
63 | model because the bus they belong to has a bus-specific structure with | |
64 | bus-specific fields that cannot be generalized. | |
65 | ||
66 | The most common example of this are device ID structures. A driver | |
67 | typically defines an array of device IDs that it supports. The format | |
68 | of these structures and the semantics for comparing device IDs are | |
69 | completely bus-specific. Defining them as bus-specific entities would | |
70 | sacrifice type-safety, so we keep bus-specific structures around. | |
71 | ||
72 | Bus-specific drivers should include a generic struct device_driver in | |
73 | the definition of the bus-specific driver. Like this: | |
74 | ||
75 | struct pci_driver { | |
76 | const struct pci_device_id *id_table; | |
77 | struct device_driver driver; | |
78 | }; | |
79 | ||
80 | A definition that included bus-specific fields would look like | |
81 | (using the eepro100 driver again): | |
82 | ||
83 | static struct pci_driver eepro100_driver = { | |
84 | .id_table = eepro100_pci_tbl, | |
85 | .driver = { | |
86 | .name = "eepro100", | |
87 | .bus = &pci_bus_type, | |
88 | .devclass = ðernet_devclass, /* when it's implemented */ | |
89 | .probe = eepro100_probe, | |
90 | .remove = eepro100_remove, | |
91 | .suspend = eepro100_suspend, | |
92 | .resume = eepro100_resume, | |
93 | }, | |
94 | }; | |
95 | ||
96 | Some may find the syntax of embedded struct initialization awkward or | |
97 | even a bit ugly. So far, it's the best way we've found to do what we want... | |
98 | ||
99 | Registration | |
100 | ~~~~~~~~~~~~ | |
101 | ||
102 | int driver_register(struct device_driver * drv); | |
103 | ||
104 | The driver registers the structure on startup. For drivers that have | |
105 | no bus-specific fields (i.e. don't have a bus-specific driver | |
106 | structure), they would use driver_register and pass a pointer to their | |
107 | struct device_driver object. | |
108 | ||
109 | Most drivers, however, will have a bus-specific structure and will | |
110 | need to register with the bus using something like pci_driver_register. | |
111 | ||
112 | It is important that drivers register their driver structure as early as | |
113 | possible. Registration with the core initializes several fields in the | |
114 | struct device_driver object, including the reference count and the | |
115 | lock. These fields are assumed to be valid at all times and may be | |
116 | used by the device model core or the bus driver. | |
117 | ||
118 | ||
119 | Transition Bus Drivers | |
120 | ~~~~~~~~~~~~~~~~~~~~~~ | |
121 | ||
122 | By defining wrapper functions, the transition to the new model can be | |
123 | made easier. Drivers can ignore the generic structure altogether and | |
124 | let the bus wrapper fill in the fields. For the callbacks, the bus can | |
125 | define generic callbacks that forward the call to the bus-specific | |
126 | callbacks of the drivers. | |
127 | ||
128 | This solution is intended to be only temporary. In order to get class | |
129 | information in the driver, the drivers must be modified anyway. Since | |
130 | converting drivers to the new model should reduce some infrastructural | |
131 | complexity and code size, it is recommended that they are converted as | |
132 | class information is added. | |
133 | ||
134 | Access | |
135 | ~~~~~~ | |
136 | ||
137 | Once the object has been registered, it may access the common fields of | |
138 | the object, like the lock and the list of devices. | |
139 | ||
140 | int driver_for_each_dev(struct device_driver * drv, void * data, | |
141 | int (*callback)(struct device * dev, void * data)); | |
142 | ||
143 | The devices field is a list of all the devices that have been bound to | |
144 | the driver. The LDM core provides a helper function to operate on all | |
145 | the devices a driver controls. This helper locks the driver on each | |
146 | node access, and does proper reference counting on each device as it | |
147 | accesses it. | |
148 | ||
149 | ||
150 | sysfs | |
151 | ~~~~~ | |
152 | ||
153 | When a driver is registered, a sysfs directory is created in its | |
154 | bus's directory. In this directory, the driver can export an interface | |
155 | to userspace to control operation of the driver on a global basis; | |
156 | e.g. toggling debugging output in the driver. | |
157 | ||
158 | A future feature of this directory will be a 'devices' directory. This | |
159 | directory will contain symlinks to the directories of devices it | |
160 | supports. | |
161 | ||
162 | ||
163 | ||
164 | Callbacks | |
165 | ~~~~~~~~~ | |
166 | ||
167 | int (*probe) (struct device * dev); | |
168 | ||
169 | probe is called to verify the existence of a certain type of | |
170 | hardware. This is called during the driver binding process, after the | |
171 | bus has verified that the device ID of a device matches one of the | |
172 | device IDs supported by the driver. | |
173 | ||
174 | This callback only verifies that there actually is supported hardware | |
175 | present. It may allocate a driver-specific structure, but it should | |
176 | not do any initialization of the hardware itself. The device-specific | |
177 | structure may be stored in the device's driver_data field. | |
178 | ||
179 | int (*init) (struct device * dev); | |
180 | ||
181 | init is called during the binding stage. It is called after probe has | |
182 | successfully returned and the device has been registered with its | |
183 | class. It is responsible for initializing the hardware. | |
184 | ||
185 | int (*remove) (struct device * dev); | |
186 | ||
187 | remove is called to dissociate a driver with a device. This may be | |
188 | called if a device is physically removed from the system, if the | |
189 | driver module is being unloaded, or during a reboot sequence. | |
190 | ||
191 | It is up to the driver to determine if the device is present or | |
192 | not. It should free any resources allocated specifically for the | |
193 | device; i.e. anything in the device's driver_data field. | |
194 | ||
195 | If the device is still present, it should quiesce the device and place | |
196 | it into a supported low-power state. | |
197 | ||
438510f6 | 198 | int (*suspend) (struct device * dev, pm_message_t state, u32 level); |
1da177e4 LT |
199 | |
200 | suspend is called to put the device in a low power state. There are | |
201 | several stages to successfully suspending a device, which is denoted in | |
202 | the @level parameter. Breaking the suspend transition into several | |
203 | stages affords the platform flexibility in performing device power | |
204 | management based on the requirements of the system and the | |
205 | user-defined policy. | |
206 | ||
207 | SUSPEND_NOTIFY notifies the device that a suspend transition is about | |
208 | to happen. This happens on system power state transitions to verify | |
209 | that all devices can successfully suspend. | |
210 | ||
211 | A driver may choose to fail on this call, which should cause the | |
212 | entire suspend transition to fail. A driver should fail only if it | |
213 | knows that the device will not be able to be resumed properly when the | |
214 | system wakes up again. It could also fail if it somehow determines it | |
215 | is in the middle of an operation too important to stop. | |
216 | ||
217 | SUSPEND_DISABLE tells the device to stop I/O transactions. When it | |
218 | stops transactions, or what it should do with unfinished transactions | |
219 | is a policy of the driver. After this call, the driver should not | |
220 | accept any other I/O requests. | |
221 | ||
222 | SUSPEND_SAVE_STATE tells the device to save the context of the | |
223 | hardware. This includes any bus-specific hardware state and | |
224 | device-specific hardware state. A pointer to this saved state can be | |
225 | stored in the device's saved_state field. | |
226 | ||
227 | SUSPEND_POWER_DOWN tells the driver to place the device in the low | |
228 | power state requested. | |
229 | ||
230 | Whether suspend is called with a given level is a policy of the | |
231 | platform. Some levels may be omitted; drivers must not assume the | |
232 | reception of any level. However, all levels must be called in the | |
233 | order above; i.e. notification will always come before disabling; | |
234 | disabling the device will come before suspending the device. | |
235 | ||
236 | All calls are made with interrupts enabled, except for the | |
237 | SUSPEND_POWER_DOWN level. | |
238 | ||
239 | int (*resume) (struct device * dev, u32 level); | |
240 | ||
241 | Resume is used to bring a device back from a low power state. Like the | |
242 | suspend transition, it happens in several stages. | |
243 | ||
244 | RESUME_POWER_ON tells the driver to set the power state to the state | |
245 | before the suspend call (The device could have already been in a low | |
246 | power state before the suspend call to put in a lower power state). | |
247 | ||
248 | RESUME_RESTORE_STATE tells the driver to restore the state saved by | |
249 | the SUSPEND_SAVE_STATE suspend call. | |
250 | ||
251 | RESUME_ENABLE tells the driver to start accepting I/O transactions | |
252 | again. Depending on driver policy, the device may already have pending | |
253 | I/O requests. | |
254 | ||
255 | RESUME_POWER_ON is called with interrupts disabled. The other resume | |
256 | levels are called with interrupts enabled. | |
257 | ||
258 | As with the various suspend stages, the driver must not assume that | |
259 | any other resume calls have been or will be made. Each call should be | |
260 | self-contained and not dependent on any external state. | |
261 | ||
262 | ||
263 | Attributes | |
264 | ~~~~~~~~~~ | |
265 | struct driver_attribute { | |
266 | struct attribute attr; | |
267 | ssize_t (*show)(struct device_driver *, char * buf, size_t count, loff_t off); | |
268 | ssize_t (*store)(struct device_driver *, const char * buf, size_t count, loff_t off); | |
269 | }; | |
270 | ||
271 | Device drivers can export attributes via their sysfs directories. | |
272 | Drivers can declare attributes using a DRIVER_ATTR macro that works | |
273 | identically to the DEVICE_ATTR macro. | |
274 | ||
275 | Example: | |
276 | ||
277 | DRIVER_ATTR(debug,0644,show_debug,store_debug); | |
278 | ||
279 | This is equivalent to declaring: | |
280 | ||
281 | struct driver_attribute driver_attr_debug; | |
282 | ||
283 | This can then be used to add and remove the attribute from the | |
284 | driver's directory using: | |
285 | ||
286 | int driver_create_file(struct device_driver *, struct driver_attribute *); | |
287 | void driver_remove_file(struct device_driver *, struct driver_attribute *); |