Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | Device Drivers | |
3 | ||
4 | struct device_driver { | |
5 | char * name; | |
6 | struct bus_type * bus; | |
7 | ||
4109aca0 DB |
8 | struct completion unloaded; |
9 | struct kobject kobj; | |
1da177e4 LT |
10 | list_t devices; |
11 | ||
4109aca0 | 12 | struct module *owner; |
1da177e4 LT |
13 | |
14 | int (*probe) (struct device * dev); | |
15 | int (*remove) (struct device * dev); | |
16 | ||
1a222bca TI |
17 | int (*suspend) (struct device * dev, pm_message_t state); |
18 | int (*resume) (struct device * dev); | |
1da177e4 LT |
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, | |
1da177e4 LT |
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, | |
1da177e4 LT |
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 | ||
4109aca0 DB |
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 reasources it allocated. | |
1da177e4 LT |
182 | |
183 | int (*remove) (struct device * dev); | |
184 | ||
4109aca0 | 185 | remove is called to unbind a driver from a device. This may be |
1da177e4 | 186 | called if a device is physically removed from the system, if the |
4109aca0 DB |
187 | driver module is being unloaded, during a reboot sequence, or |
188 | in other cases. | |
1da177e4 LT |
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 | ||
1a222bca | 197 | int (*suspend) (struct device * dev, pm_message_t state); |
1da177e4 | 198 | |
9480e307 | 199 | suspend is called to put the device in a low power state. |
1da177e4 | 200 | |
1a222bca | 201 | int (*resume) (struct device * dev); |
1da177e4 | 202 | |
9480e307 | 203 | Resume is used to bring a device back from a low power state. |
1da177e4 LT |
204 | |
205 | ||
206 | Attributes | |
207 | ~~~~~~~~~~ | |
208 | struct driver_attribute { | |
209 | struct attribute attr; | |
210 | ssize_t (*show)(struct device_driver *, char * buf, size_t count, loff_t off); | |
211 | ssize_t (*store)(struct device_driver *, const char * buf, size_t count, loff_t off); | |
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 *, struct driver_attribute *); | |
230 | void driver_remove_file(struct device_driver *, struct driver_attribute *); |