^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Device Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) See the kerneldoc for the struct device_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Allocation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Device drivers are statically allocated structures. Though there may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) be multiple devices in a system that a driver supports, struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) device_driver represents the driver as a whole (not a particular
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) device instance).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) The driver must initialize at least the name and bus fields. It should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) also initialize the devclass field (when it arrives), so it may obtain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) the proper linkage internally. It should also initialize as many of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) the callbacks as possible, though each is optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Declaration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) As stated above, struct device_driver objects are statically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) allocated. Below is an example declaration of the eepro100
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) driver. This declaration is hypothetical only; it relies on the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) being converted completely to the new model::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) static struct device_driver eepro100_driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) .name = "eepro100",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) .bus = &pci_bus_type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) .probe = eepro100_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) .remove = eepro100_remove,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) .suspend = eepro100_suspend,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) .resume = eepro100_resume,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Most drivers will not be able to be converted completely to the new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) model because the bus they belong to has a bus-specific structure with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) bus-specific fields that cannot be generalized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The most common example of this are device ID structures. A driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) typically defines an array of device IDs that it supports. The format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) of these structures and the semantics for comparing device IDs are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) completely bus-specific. Defining them as bus-specific entities would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) sacrifice type-safety, so we keep bus-specific structures around.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Bus-specific drivers should include a generic struct device_driver in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) the definition of the bus-specific driver. Like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) struct pci_driver {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) const struct pci_device_id *id_table;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) struct device_driver driver;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) A definition that included bus-specific fields would look like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) (using the eepro100 driver again)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) static struct pci_driver eepro100_driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) .id_table = eepro100_pci_tbl,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) .driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) .name = "eepro100",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) .bus = &pci_bus_type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) .probe = eepro100_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) .remove = eepro100_remove,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) .suspend = eepro100_suspend,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) .resume = eepro100_resume,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Some may find the syntax of embedded struct initialization awkward or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) even a bit ugly. So far, it's the best way we've found to do what we want...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Registration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) int driver_register(struct device_driver *drv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) The driver registers the structure on startup. For drivers that have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) no bus-specific fields (i.e. don't have a bus-specific driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) structure), they would use driver_register and pass a pointer to their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) struct device_driver object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Most drivers, however, will have a bus-specific structure and will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) need to register with the bus using something like pci_driver_register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) It is important that drivers register their driver structure as early as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) possible. Registration with the core initializes several fields in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) struct device_driver object, including the reference count and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) lock. These fields are assumed to be valid at all times and may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) used by the device model core or the bus driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Transition Bus Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) By defining wrapper functions, the transition to the new model can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) made easier. Drivers can ignore the generic structure altogether and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) let the bus wrapper fill in the fields. For the callbacks, the bus can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) define generic callbacks that forward the call to the bus-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) callbacks of the drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) This solution is intended to be only temporary. In order to get class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) information in the driver, the drivers must be modified anyway. Since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) converting drivers to the new model should reduce some infrastructural
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) complexity and code size, it is recommended that they are converted as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) class information is added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Access
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) ~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Once the object has been registered, it may access the common fields of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) the object, like the lock and the list of devices::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) int driver_for_each_dev(struct device_driver *drv, void *data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) int (*callback)(struct device *dev, void *data));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) The devices field is a list of all the devices that have been bound to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) the driver. The LDM core provides a helper function to operate on all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) the devices a driver controls. This helper locks the driver on each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) node access, and does proper reference counting on each device as it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) accesses it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) ~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) When a driver is registered, a sysfs directory is created in its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) bus's directory. In this directory, the driver can export an interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) to userspace to control operation of the driver on a global basis;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) e.g. toggling debugging output in the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) A future feature of this directory will be a 'devices' directory. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) directory will contain symlinks to the directories of devices it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) supports.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) int (*probe) (struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) The probe() entry is called in task context, with the bus's rwsem locked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) and the driver partially bound to the device. Drivers commonly use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) container_of() to convert "dev" to a bus-specific type, both in probe()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) and other routines. That type often provides device resource data, such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) as pci_dev.resource[] or platform_device.resources, which is used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) addition to dev->platform_data to initialize the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) This callback holds the driver-specific logic to bind the driver to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) given device. That includes verifying that the device is present, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) it's a version the driver can handle, that driver data structures can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) be allocated and initialized, and that any hardware can be initialized.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Drivers often store a pointer to their state with dev_set_drvdata().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) When the driver has successfully bound itself to that device, then probe()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) returns zero and the driver model code will finish its part of binding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) the driver to that device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) A driver's probe() may return a negative errno value to indicate that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) the driver did not bind to this device, in which case it should have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) released all resources it allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) Optionally, probe() may return -EPROBE_DEFER if the driver depends on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) resources that are not yet available (e.g., supplied by a driver that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) hasn't initialized yet). The driver core will put the device onto the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) deferred probe list and will try to call it again later. If a driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) must defer, it should return -EPROBE_DEFER as early as possible to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) reduce the amount of time spent on setup work that will need to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) unwound and reexecuted at a later time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) -EPROBE_DEFER must not be returned if probe() has already created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) child devices, even if those child devices are removed again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) in a cleanup path. If -EPROBE_DEFER is returned after a child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) device has been registered, it may result in an infinite loop of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) .probe() calls to the same driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) void (*sync_state) (struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) sync_state is called only once for a device. It's called when all the consumer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) devices of the device have successfully probed. The list of consumers of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) device is obtained by looking at the device links connecting that device to its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) consumer devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The first attempt to call sync_state() is made during late_initcall_sync() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) give firmware and drivers time to link devices to each other. During the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) attempt at calling sync_state(), if all the consumers of the device at that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) point in time have already probed successfully, sync_state() is called right
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) away. If there are no consumers of the device during the first attempt, that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) too is considered as "all consumers of the device have probed" and sync_state()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) is called right away.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) If during the first attempt at calling sync_state() for a device, there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) still consumers that haven't probed successfully, the sync_state() call is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) postponed and reattempted in the future only when one or more consumers of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) device probe successfully. If during the reattempt, the driver core finds that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) there are one or more consumers of the device that haven't probed yet, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) sync_state() call is postponed again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) A typical use case for sync_state() is to have the kernel cleanly take over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) management of devices from the bootloader. For example, if a device is left on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) and at a particular hardware configuration by the bootloader, the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) driver might need to keep the device in the boot configuration until all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) consumers of the device have probed. Once all the consumers of the device have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) probed, the device's driver can synchronize the hardware state of the device to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) match the aggregated software state requested by all the consumers. Hence the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) name sync_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) While obvious examples of resources that can benefit from sync_state() include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) resources such as regulator, sync_state() can also be useful for complex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) resources like IOMMUs. For example, IOMMUs with multiple consumers (devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) whose addresses are remapped by the IOMMU) might need to keep their mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) fixed at (or additive to) the boot configuration until all its consumers have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) probed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) While the typical use case for sync_state() is to have the kernel cleanly take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) over management of devices from the bootloader, the usage of sync_state() is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) not restricted to that. Use it whenever it makes sense to take an action after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) all the consumers of a device have probed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) int (*remove) (struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) remove is called to unbind a driver from a device. This may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) called if a device is physically removed from the system, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) driver module is being unloaded, during a reboot sequence, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) in other cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) It is up to the driver to determine if the device is present or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) not. It should free any resources allocated specifically for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) device; i.e. anything in the device's driver_data field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) If the device is still present, it should quiesce the device and place
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) it into a supported low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) int (*suspend) (struct device *dev, pm_message_t state);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) suspend is called to put the device in a low power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) int (*resume) (struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) Resume is used to bring a device back from a low power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) Attributes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) ~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) struct driver_attribute {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) struct attribute attr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) ssize_t (*show)(struct device_driver *driver, char *buf);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) Device drivers can export attributes via their sysfs directories.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) macros.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) DRIVER_ATTR_RW(debug);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) This is equivalent to declaring::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) struct driver_attribute driver_attr_debug;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) This can then be used to add and remove the attribute from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) driver's directory using::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) int driver_create_file(struct device_driver *, const struct driver_attribute *);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) void driver_remove_file(struct device_driver *, const struct driver_attribute *);
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags