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