driver-api/driver-model/driver.rst

2 Device Drivers
10 Device drivers are statically allocated structures. Though there may
13 device instance).
42 model because the bus they belong to has a bus-specific structure with
43 bus-specific fields that cannot be generalized.
45 The most common example of this are device ID structures. A driver
46 typically defines an array of device IDs that it supports. The format
47 of these structures and the semantics for comparing device IDs are
48 completely bus-specific. Defining them as bus-specific entities would
49 sacrifice type-safety, so we keep bus-specific structures around.
51 Bus-specific drivers should include a generic struct device_driver in
52 the definition of the bus-specific driver. Like this::
59 A definition that included bus-specific fields would look like
85 no bus-specific fields (i.e. don't have a bus-specific driver
89 Most drivers, however, will have a bus-specific structure and will
96 used by the device model core or the bus driver.
105 define generic callbacks that forward the call to the bus-specific
121 			  int (*callback)(struct device *dev, void *data));
126 node access, and does proper reference counting on each device as it
149 	int	(*probe)	(struct device *dev);
152 and the driver partially bound to the device.  Drivers commonly use
153 container_of() to convert "dev" to a bus-specific type, both in probe()
154 and other routines.  That type often provides device resource data, such
156 addition to dev->platform_data to initialize the driver.
158 This callback holds the driver-specific logic to bind the driver to a
159 given device.  That includes verifying that the device is present, that
163 When the driver has successfully bound itself to that device, then probe()
165 the driver to that device.
168 the driver did not bind to this device, in which case it should have
171 Optionally, probe() may return -EPROBE_DEFER if the driver depends on
173 hasn't initialized yet).  The driver core will put the device onto the
175 must defer, it should return -EPROBE_DEFER as early as possible to
180       -EPROBE_DEFER must not be returned if probe() has already created
182       in a cleanup path. If -EPROBE_DEFER is returned after a child
183       device has been registered, it may result in an infinite loop of
188 	void	(*sync_state)	(struct device *dev);
190 sync_state is called only once for a device. It's called when all the consumer
191 devices of the device have successfully probed. The list of consumers of the
192 device is obtained by looking at the device links connecting that device to its
197 attempt at calling sync_state(), if all the consumers of the device at that
199 away. If there are no consumers of the device during the first attempt, that
200 too is considered as "all consumers of the device have probed" and sync_state()
203 If during the first attempt at calling sync_state() for a device, there are
206 device probe successfully. If during the reattempt, the driver core finds that
207 there are one or more consumers of the device that haven't probed yet, then
211 management of devices from the bootloader. For example, if a device is left on
212 and at a particular hardware configuration by the bootloader, the device's
213 driver might need to keep the device in the boot configuration until all the
214 consumers of the device have probed. Once all the consumers of the device have
215 probed, the device's driver can synchronize the hardware state of the device to
229 all the consumers of a device have probed::
231 	int 	(*remove)	(struct device *dev);
233 remove is called to unbind a driver from a device. This may be
234 called if a device is physically removed from the system, if the
238 It is up to the driver to determine if the device is present or
240 device; i.e. anything in the device's driver_data field.
242 If the device is still present, it should quiesce the device and place
243 it into a supported low-power state.
247 	int	(*suspend)	(struct device *dev, pm_message_t state);
249 suspend is called to put the device in a low power state.
253 	int	(*resume)	(struct device *dev);
255 Resume is used to bring a device back from a low power state.
269 Device drivers can export attributes via their sysfs directories.