blob: 82132169d47a837fc55ea9d53555abc29b2c7b5d [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2Device Drivers
3
4struct device_driver {
5 char * name;
6 struct bus_type * bus;
7
David Brownell4109aca2005-05-16 17:19:55 -07008 struct completion unloaded;
9 struct kobject kobj;
Linus Torvalds1da177e2005-04-16 15:20:36 -070010 list_t devices;
11
David Brownell4109aca2005-05-16 17:19:55 -070012 struct module *owner;
Linus Torvalds1da177e2005-04-16 15:20:36 -070013
14 int (*probe) (struct device * dev);
15 int (*remove) (struct device * dev);
16
Takashi Iwai1a222bca2005-10-28 16:45:34 +020017 int (*suspend) (struct device * dev, pm_message_t state);
18 int (*resume) (struct device * dev);
Linus Torvalds1da177e2005-04-16 15:20:36 -070019};
20
21
22
23Allocation
24~~~~~~~~~~
25
26Device drivers are statically allocated structures. Though there may
27be multiple devices in a system that a driver supports, struct
28device_driver represents the driver as a whole (not a particular
29device instance).
30
31Initialization
32~~~~~~~~~~~~~~
33
34The driver must initialize at least the name and bus fields. It should
35also initialize the devclass field (when it arrives), so it may obtain
36the proper linkage internally. It should also initialize as many of
37the callbacks as possible, though each is optional.
38
39Declaration
40~~~~~~~~~~~
41
42As stated above, struct device_driver objects are statically
43allocated. Below is an example declaration of the eepro100
44driver. This declaration is hypothetical only; it relies on the driver
45being converted completely to the new model.
46
47static struct device_driver eepro100_driver = {
48 .name = "eepro100",
49 .bus = &pci_bus_type,
Linus Torvalds1da177e2005-04-16 15:20:36 -070050
51 .probe = eepro100_probe,
52 .remove = eepro100_remove,
53 .suspend = eepro100_suspend,
54 .resume = eepro100_resume,
55};
56
57Most drivers will not be able to be converted completely to the new
58model because the bus they belong to has a bus-specific structure with
59bus-specific fields that cannot be generalized.
60
61The most common example of this are device ID structures. A driver
62typically defines an array of device IDs that it supports. The format
63of these structures and the semantics for comparing device IDs are
64completely bus-specific. Defining them as bus-specific entities would
65sacrifice type-safety, so we keep bus-specific structures around.
66
67Bus-specific drivers should include a generic struct device_driver in
68the definition of the bus-specific driver. Like this:
69
70struct pci_driver {
71 const struct pci_device_id *id_table;
72 struct device_driver driver;
73};
74
75A definition that included bus-specific fields would look like
76(using the eepro100 driver again):
77
78static struct pci_driver eepro100_driver = {
79 .id_table = eepro100_pci_tbl,
80 .driver = {
81 .name = "eepro100",
82 .bus = &pci_bus_type,
Linus Torvalds1da177e2005-04-16 15:20:36 -070083 .probe = eepro100_probe,
84 .remove = eepro100_remove,
85 .suspend = eepro100_suspend,
86 .resume = eepro100_resume,
87 },
88};
89
90Some may find the syntax of embedded struct initialization awkward or
91even a bit ugly. So far, it's the best way we've found to do what we want...
92
93Registration
94~~~~~~~~~~~~
95
96int driver_register(struct device_driver * drv);
97
98The driver registers the structure on startup. For drivers that have
99no bus-specific fields (i.e. don't have a bus-specific driver
100structure), they would use driver_register and pass a pointer to their
101struct device_driver object.
102
103Most drivers, however, will have a bus-specific structure and will
104need to register with the bus using something like pci_driver_register.
105
106It is important that drivers register their driver structure as early as
107possible. Registration with the core initializes several fields in the
108struct device_driver object, including the reference count and the
109lock. These fields are assumed to be valid at all times and may be
110used by the device model core or the bus driver.
111
112
113Transition Bus Drivers
114~~~~~~~~~~~~~~~~~~~~~~
115
116By defining wrapper functions, the transition to the new model can be
117made easier. Drivers can ignore the generic structure altogether and
118let the bus wrapper fill in the fields. For the callbacks, the bus can
119define generic callbacks that forward the call to the bus-specific
120callbacks of the drivers.
121
122This solution is intended to be only temporary. In order to get class
123information in the driver, the drivers must be modified anyway. Since
124converting drivers to the new model should reduce some infrastructural
125complexity and code size, it is recommended that they are converted as
126class information is added.
127
128Access
129~~~~~~
130
131Once the object has been registered, it may access the common fields of
132the object, like the lock and the list of devices.
133
134int driver_for_each_dev(struct device_driver * drv, void * data,
135 int (*callback)(struct device * dev, void * data));
136
137The devices field is a list of all the devices that have been bound to
138the driver. The LDM core provides a helper function to operate on all
139the devices a driver controls. This helper locks the driver on each
140node access, and does proper reference counting on each device as it
141accesses it.
142
143
144sysfs
145~~~~~
146
147When a driver is registered, a sysfs directory is created in its
148bus's directory. In this directory, the driver can export an interface
149to userspace to control operation of the driver on a global basis;
150e.g. toggling debugging output in the driver.
151
152A future feature of this directory will be a 'devices' directory. This
153directory will contain symlinks to the directories of devices it
154supports.
155
156
157
158Callbacks
159~~~~~~~~~
160
161 int (*probe) (struct device * dev);
162
David Brownell4109aca2005-05-16 17:19:55 -0700163The probe() entry is called in task context, with the bus's rwsem locked
164and the driver partially bound to the device. Drivers commonly use
165container_of() to convert "dev" to a bus-specific type, both in probe()
166and other routines. That type often provides device resource data, such
167as pci_dev.resource[] or platform_device.resources, which is used in
168addition to dev->platform_data to initialize the driver.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700169
David Brownell4109aca2005-05-16 17:19:55 -0700170This callback holds the driver-specific logic to bind the driver to a
171given device. That includes verifying that the device is present, that
172it's a version the driver can handle, that driver data structures can
173be allocated and initialized, and that any hardware can be initialized.
174Drivers often store a pointer to their state with dev_set_drvdata().
175When the driver has successfully bound itself to that device, then probe()
176returns zero and the driver model code will finish its part of binding
177the driver to that device.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700178
David Brownell4109aca2005-05-16 17:19:55 -0700179A driver's probe() may return a negative errno value to indicate that
180the driver did not bind to this device, in which case it should have
Matt LaPlanted6bc8ac2006-10-03 22:54:15 +0200181released all resources it allocated.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700182
183 int (*remove) (struct device * dev);
184
David Brownell4109aca2005-05-16 17:19:55 -0700185remove is called to unbind a driver from a device. This may be
Linus Torvalds1da177e2005-04-16 15:20:36 -0700186called if a device is physically removed from the system, if the
David Brownell4109aca2005-05-16 17:19:55 -0700187driver module is being unloaded, during a reboot sequence, or
188in other cases.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700189
190It is up to the driver to determine if the device is present or
191not. It should free any resources allocated specifically for the
192device; i.e. anything in the device's driver_data field.
193
194If the device is still present, it should quiesce the device and place
195it into a supported low-power state.
196
Takashi Iwai1a222bca2005-10-28 16:45:34 +0200197 int (*suspend) (struct device * dev, pm_message_t state);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700198
Russell King9480e302005-10-28 09:52:56 -0700199suspend is called to put the device in a low power state.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700200
Takashi Iwai1a222bca2005-10-28 16:45:34 +0200201 int (*resume) (struct device * dev);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700202
Russell King9480e302005-10-28 09:52:56 -0700203Resume is used to bring a device back from a low power state.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700204
205
206Attributes
207~~~~~~~~~~
208struct 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
214Device drivers can export attributes via their sysfs directories.
215Drivers can declare attributes using a DRIVER_ATTR macro that works
216identically to the DEVICE_ATTR macro.
217
218Example:
219
220DRIVER_ATTR(debug,0644,show_debug,store_debug);
221
222This is equivalent to declaring:
223
224struct driver_attribute driver_attr_debug;
225
226This can then be used to add and remove the attribute from the
227driver's directory using:
228
229int driver_create_file(struct device_driver *, struct driver_attribute *);
230void driver_remove_file(struct device_driver *, struct driver_attribute *);