==============Device Drivers============== See the kerneldoc for the struct device_driver. Allocation~~~~~~~~~~ Device drivers are statically allocated structures. Though there maybe multiple devices in a system that a driver supports, structdevice_driver represents the driver as a whole (not a particulardevice instance). Initialization~~~~~~~~~~~~~~ The driver must initialize at least the name and bus fields. It shouldalso initialize the devclass field (when it arrives), so it may obtainthe proper linkage internally. It should also initialize as many ofthe callbacks as possible, though each is optional. Declaration~~~~~~~~~~~ As stated above, struct device_driver objects are staticallyallocated. Below is an example declaration of the eepro100driver. This declaration is hypothetical only; it relies on the driverbeing converted completely to the new model::   static struct device_driver eepro100_driver = {         .name		= "eepro100",         .bus		= &pci_bus_type,          .probe		= eepro100_probe,         .remove		= eepro100_remove,         .suspend		= eepro100_suspend,         .resume		= eepro100_resume,  }; Most drivers will not be able to be converted completely to the newmodel because the bus they belong to has a bus-specific structure withbus-specific fields that cannot be generalized. The most common example of this are device ID structures. A drivertypically defines an array of device IDs that it supports. The formatof these structures and the semantics for comparing device IDs arecompletely bus-specific. Defining them as bus-specific entities wouldsacrifice type-safety, so we keep bus-specific structures around. Bus-specific drivers should include a generic struct device_driver inthe definition of the bus-specific driver. Like this::   struct pci_driver {         const struct pci_device_id *id_table;         struct device_driver	  driver;  }; A definition that included bus-specific fields would look like(using the eepro100 driver again)::   static struct pci_driver eepro100_driver = {         .id_table       = eepro100_pci_tbl,         .driver	       = {		.name		= "eepro100",		.bus		= &pci_bus_type,		.probe		= eepro100_probe,		.remove		= eepro100_remove,		.suspend	= eepro100_suspend,		.resume		= eepro100_resume,         },  }; Some may find the syntax of embedded struct initialization awkward oreven a bit ugly. So far, it's the best way we've found to do what we want... Registration~~~~~~~~~~~~ ::   int driver_register(struct device_driver *drv); The driver registers the structure on startup. For drivers that haveno bus-specific fields (i.e. don't have a bus-specific driverstructure), they would use driver_register and pass a pointer to theirstruct device_driver object. Most drivers, however, will have a bus-specific structure and willneed to register with the bus using something like pci_driver_register. It is important that drivers register their driver structure as early aspossible. Registration with the core initializes several fields in thestruct device_driver object, including the reference count and thelock. These fields are assumed to be valid at all times and may beused by the device model core or the bus driver.  Transition Bus Drivers~~~~~~~~~~~~~~~~~~~~~~ By defining wrapper functions, the transition to the new model can bemade easier. Drivers can ignore the generic structure altogether andlet the bus wrapper fill in the fields. For the callbacks, the bus candefine generic callbacks that forward the call to the bus-specificcallbacks of the drivers. This solution is intended to be only temporary. In order to get classinformation in the driver, the drivers must be modified anyway. Sinceconverting drivers to the new model should reduce some infrastructuralcomplexity and code size, it is recommended that they are converted asclass information is added. Access~~~~~~ Once the object has been registered, it may access the common fields ofthe object, like the lock and the list of devices::   int driver_for_each_dev(struct device_driver *drv, void *data,			  int (*callback)(struct device *dev, void *data)); The devices field is a list of all the devices that have been bound tothe driver. The LDM core provides a helper function to operate on allthe devices a driver controls. This helper locks the driver on eachnode access, and does proper reference counting on each device as itaccesses it.  sysfs~~~~~ When a driver is registered, a sysfs directory is created in itsbus's directory. In this directory, the driver can export an interfaceto userspace to control operation of the driver on a global basis;e.g. toggling debugging output in the driver. A future feature of this directory will be a 'devices' directory. Thisdirectory will contain symlinks to the directories of devices itsupports.   Callbacks~~~~~~~~~ :: 	int	(*probe)	(struct device *dev); The probe() entry is called in task context, with the bus's rwsem lockedand the driver partially bound to the device.  Drivers commonly usecontainer_of() to convert "dev" to a bus-specific type, both in probe()and other routines.  That type often provides device resource data, suchas pci_dev.resource[] or platform_device.resources, which is used inaddition to dev->platform_data to initialize the driver. This callback holds the driver-specific logic to bind the driver to agiven device.  That includes verifying that the device is present, thatit's a version the driver can handle, that driver data structures canbe allocated and initialized, and that any hardware can be initialized.Drivers often store a pointer to their state with dev_set_drvdata().When the driver has successfully bound itself to that device, then probe()returns zero and the driver model code will finish its part of bindingthe driver to that device. A driver's probe() may return a negative errno value to indicate thatthe driver did not bind to this device, in which case it should havereleased all resources it allocated. Optionally, probe() may return -EPROBE_DEFER if the driver depends onresources that are not yet available (e.g., supplied by a driver thathasn't initialized yet).  The driver core will put the device onto thedeferred probe list and will try to call it again later. If a drivermust defer, it should return -EPROBE_DEFER as early as possible toreduce the amount of time spent on setup work that will need to beunwound and reexecuted at a later time. .. warning::      -EPROBE_DEFER must not be returned if probe() has already created      child devices, even if those child devices are removed again      in a cleanup path. If -EPROBE_DEFER is returned after a child      device has been registered, it may result in an infinite loop of      .probe() calls to the same driver. :: 	void	(*sync_state)	(struct device *dev); sync_state is called only once for a device. It's called when all the consumerdevices of the device have successfully probed. The list of consumers of thedevice is obtained by looking at the device links connecting that device to itsconsumer devices. The first attempt to call sync_state() is made during late_initcall_sync() togive firmware and drivers time to link devices to each other. During the firstattempt at calling sync_state(), if all the consumers of the device at thatpoint in time have already probed successfully, sync_state() is called rightaway. If there are no consumers of the device during the first attempt, thattoo is considered as "all consumers of the device have probed" and sync_state()is called right away. If during the first attempt at calling sync_state() for a device, there arestill consumers that haven't probed successfully, the sync_state() call ispostponed and reattempted in the future only when one or more consumers of thedevice probe successfully. If during the reattempt, the driver core finds thatthere are one or more consumers of the device that haven't probed yet, thensync_state() call is postponed again. A typical use case for sync_state() is to have the kernel cleanly take overmanagement of devices from the bootloader. For example, if a device is left onand at a particular hardware configuration by the bootloader, the device'sdriver might need to keep the device in the boot configuration until all theconsumers of the device have probed. Once all the consumers of the device haveprobed, the device's driver can synchronize the hardware state of the device tomatch the aggregated software state requested by all the consumers. Hence thename sync_state(). While obvious examples of resources that can benefit from sync_state() includeresources such as regulator, sync_state() can also be useful for complexresources like IOMMUs. For example, IOMMUs with multiple consumers (deviceswhose addresses are remapped by the IOMMU) might need to keep their mappingsfixed at (or additive to) the boot configuration until all its consumers haveprobed. While the typical use case for sync_state() is to have the kernel cleanly takeover management of devices from the bootloader, the usage of sync_state() isnot restricted to that. Use it whenever it makes sense to take an action afterall the consumers of a device have probed:: 	int 	(*remove)	(struct device *dev); remove is called to unbind a driver from a device. This may becalled if a device is physically removed from the system, if thedriver module is being unloaded, during a reboot sequence, orin other cases. It is up to the driver to determine if the device is present ornot. It should free any resources allocated specifically for thedevice; i.e. anything in the device's driver_data field. If the device is still present, it should quiesce the device and placeit into a supported low-power state. :: 	int	(*suspend)	(struct device *dev, pm_message_t state); suspend is called to put the device in a low power state. :: 	int	(*resume)	(struct device *dev); Resume is used to bring a device back from a low power state.  Attributes~~~~~~~~~~ ::   struct driver_attribute {          struct attribute        attr;          ssize_t (*show)(struct device_driver *driver, char *buf);          ssize_t (*store)(struct device_driver *, const char *buf, size_t count);  }; Device drivers can export attributes via their sysfs directories.Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_ROmacro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_ROmacros. Example:: 	DRIVER_ATTR_RW(debug); This is equivalent to declaring:: 	struct driver_attribute driver_attr_debug; This can then be used to add and remove the attribute from thedriver's directory using::   int driver_create_file(struct device_driver *, const struct driver_attribute *);  void driver_remove_file(struct device_driver *, const struct driver_attribute *);