Linux-2.6.12-rc2
[linux-3.10.git] / Documentation / driver-model / driver.txt
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
19         int     (*suspend)      (struct device * dev, u32 state, u32 level);
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        = &ethernet_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       = &ethernet_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
198         int     (*suspend)      (struct device * dev, u32 state, u32 level);
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 *);