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