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