€•ÃŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ2/translations/zh_CN/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ2/translations/zh_TW/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ2/translations/it_IT/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ2/translations/ja_JP/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ2/translations/ko_KR/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ2/translations/sp_SP/driver-api/driver-model/driver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒDevice Drivers”h]”hŒDevice Drivers”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒL/var/lib/git/docbuild/linux/Documentation/driver-api/driver-model/driver.rst”h KubhŒ paragraph”“”)”}”(hŒ/See the kerneldoc for the struct device_driver.”h]”hŒ/See the kerneldoc for the struct device_driver.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒ Allocation”h]”hŒ Allocation”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhÇhžhhŸh¶h Kubh¸)”}”(hŒÖDevice drivers are statically allocated structures. Though there may be multiple devices in a system that a driver supports, struct device_driver represents the driver as a whole (not a particular device instance).”h]”hŒÖDevice drivers are statically allocated structures. Though there may be multiple devices in a system that a driver supports, struct device_driver represents the driver as a whole (not a particular device instance).”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hhÇhžhubeh}”(h]”Œ allocation”ah ]”h"]”Œ allocation”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒInitialization”h]”hŒInitialization”…””}”(hhñhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hhîhžhhŸh¶h Kubh¸)”}”(hXThe driver must initialize at least the name and bus fields. It should also initialize the devclass field (when it arrives), so it may obtain the proper linkage internally. It should also initialize as many of the callbacks as possible, though each is optional.”h]”hXThe driver must initialize at least the name and bus fields. It should also initialize the devclass field (when it arrives), so it may obtain the proper linkage internally. It should also initialize as many of the callbacks as possible, though each is optional.”…””}”(hhÿhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khhîhžhubeh}”(h]”Œinitialization”ah ]”h"]”Œinitialization”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ Declaration”h]”hŒ Declaration”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjhžhhŸh¶h Kubh¸)”}”(hŒìAs stated above, struct device_driver objects are statically allocated. Below is an example declaration of the eepro100 driver. This declaration is hypothetical only; it relies on the driver being converted completely to the new model::”h]”hŒëAs stated above, struct device_driver objects are statically allocated. Below is an example declaration of the eepro100 driver. This declaration is hypothetical only; it relies on the driver being converted completely to the new model:”…””}”(hj&hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KhjhžhubhŒ literal_block”“”)”}”(hX:static struct device_driver eepro100_driver = { .name = "eepro100", .bus = &pci_bus_type, .probe = eepro100_probe, .remove = eepro100_remove, .suspend = eepro100_suspend, .resume = eepro100_resume, };”h]”hX:static struct device_driver eepro100_driver = { .name = "eepro100", .bus = &pci_bus_type, .probe = eepro100_probe, .remove = eepro100_remove, .suspend = eepro100_suspend, .resume = eepro100_resume, };”…””}”hj6sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1j4hŸh¶h Khjhžhubh¸)”}”(hŒºMost drivers will not be able to be converted completely to the new model because the bus they belong to has a bus-specific structure with bus-specific fields that cannot be generalized.”h]”hŒºMost drivers will not be able to be converted completely to the new model because the bus they belong to has a bus-specific structure with bus-specific fields that cannot be generalized.”…””}”(hjFhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K)hjhžhubh¸)”}”(hXSThe most common example of this are device ID structures. A driver typically defines an array of device IDs that it supports. The format of these structures and the semantics for comparing device IDs are completely bus-specific. Defining them as bus-specific entities would sacrifice type-safety, so we keep bus-specific structures around.”h]”hXSThe most common example of this are device ID structures. A driver typically defines an array of device IDs that it supports. The format of these structures and the semantics for comparing device IDs are completely bus-specific. Defining them as bus-specific entities would sacrifice type-safety, so we keep bus-specific structures around.”…””}”(hjThžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K-hjhžhubh¸)”}”(hŒ|Bus-specific drivers should include a generic struct device_driver in the definition of the bus-specific driver. Like this::”h]”hŒ{Bus-specific drivers should include a generic struct device_driver in the definition of the bus-specific driver. Like this:”…””}”(hjbhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K3hjhžhubj5)”}”(hŒkstruct pci_driver { const struct pci_device_id *id_table; struct device_driver driver; };”h]”hŒkstruct pci_driver { const struct pci_device_id *id_table; struct device_driver driver; };”…””}”hjpsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h K6hjhžhubh¸)”}”(hŒbA definition that included bus-specific fields would look like (using the eepro100 driver again)::”h]”hŒaA definition that included bus-specific fields would look like (using the eepro100 driver again):”…””}”(hj~hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K;hjhžhubj5)”}”(hX¤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, }, };”h]”hX¤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, }, };”…””}”hjŒsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h K>hjhžhubh¸)”}”(hŒ’Some may find the syntax of embedded struct initialization awkward or even a bit ugly. So far, it's the best way we've found to do what we want...”h]”hŒ–Some may find the syntax of embedded struct initialization awkward or even a bit ugly. So far, it’s the best way we’ve found to do what we want...”…””}”(hjšhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KJhjhžhubeh}”(h]”Œ declaration”ah ]”h"]”Œ declaration”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ Registration”h]”hŒ Registration”…””}”(hj³hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj°hžhhŸh¶h KNubj5)”}”(hŒ/int driver_register(struct device_driver *drv);”h]”hŒ/int driver_register(struct device_driver *drv);”…””}”hjÁsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h KRhj°hžhubh¸)”}”(hŒæThe driver registers the structure on startup. For drivers that have no bus-specific fields (i.e. don't have a bus-specific driver structure), they would use driver_register and pass a pointer to their struct device_driver object.”h]”hŒèThe driver registers the structure on startup. For drivers that have no bus-specific fields (i.e. don’t have a bus-specific driver structure), they would use driver_register and pass a pointer to their struct device_driver object.”…””}”(hjÏhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KThj°hžhubh¸)”}”(hŒŠMost drivers, however, will have a bus-specific structure and will need to register with the bus using something like pci_driver_register.”h]”hŒŠMost drivers, however, will have a bus-specific structure and will need to register with the bus using something like pci_driver_register.”…””}”(hjÝhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KYhj°hžhubh¸)”}”(hXFIt is important that drivers register their driver structure as early as possible. Registration with the core initializes several fields in the struct device_driver object, including the reference count and the lock. These fields are assumed to be valid at all times and may be used by the device model core or the bus driver.”h]”hXFIt is important that drivers register their driver structure as early as possible. Registration with the core initializes several fields in the struct device_driver object, including the reference count and the lock. These fields are assumed to be valid at all times and may be used by the device model core or the bus driver.”…””}”(hjëhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K\hj°hžhubeh}”(h]”Œ registration”ah ]”h"]”Œ registration”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KNubh¢)”}”(hhh]”(h§)”}”(hŒTransition Bus Drivers”h]”hŒTransition Bus Drivers”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjhžhhŸh¶h Kdubh¸)”}”(hX.By defining wrapper functions, the transition to the new model can be made easier. Drivers can ignore the generic structure altogether and let the bus wrapper fill in the fields. For the callbacks, the bus can define generic callbacks that forward the call to the bus-specific callbacks of the drivers.”h]”hX.By defining wrapper functions, the transition to the new model can be made easier. Drivers can ignore the generic structure altogether and let the bus wrapper fill in the fields. For the callbacks, the bus can define generic callbacks that forward the call to the bus-specific callbacks of the drivers.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kfhjhžhubh¸)”}”(hX5This solution is intended to be only temporary. In order to get class information in the driver, the drivers must be modified anyway. Since converting drivers to the new model should reduce some infrastructural complexity and code size, it is recommended that they are converted as class information is added.”h]”hX5This solution is intended to be only temporary. In order to get class information in the driver, the drivers must be modified anyway. Since converting drivers to the new model should reduce some infrastructural complexity and code size, it is recommended that they are converted as class information is added.”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Klhjhžhubeh}”(h]”Œtransition-bus-drivers”ah ]”h"]”Œtransition bus drivers”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kdubh¢)”}”(hhh]”(h§)”}”(hŒAccess”h]”hŒAccess”…””}”(hj9hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj6hžhhŸh¶h Ksubh¸)”}”(hŒ{Once the object has been registered, it may access the common fields of the object, like the lock and the list of devices::”h]”hŒzOnce the object has been registered, it may access the common fields of the object, like the lock and the list of devices:”…””}”(hjGhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kuhj6hžhubj5)”}”(hŒˆint driver_for_each_dev(struct device_driver *drv, void *data, int (*callback)(struct device *dev, void *data));”h]”hŒˆint driver_for_each_dev(struct device_driver *drv, void *data, int (*callback)(struct device *dev, void *data));”…””}”hjUsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Kxhj6hžhubh¸)”}”(hX"The devices field is a list of all the devices that have been bound to the driver. The LDM core provides a helper function to operate on all the devices a driver controls. This helper locks the driver on each node access, and does proper reference counting on each device as it accesses it.”h]”hX"The devices field is a list of all the devices that have been bound to the driver. The LDM core provides a helper function to operate on all the devices a driver controls. This helper locks the driver on each node access, and does proper reference counting on each device as it accesses it.”…””}”(hjchžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K{hj6hžhubeh}”(h]”Œaccess”ah ]”h"]”Œaccess”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Ksubh¢)”}”(hhh]”(h§)”}”(hŒsysfs”h]”hŒsysfs”…””}”(hj|hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjyhžhhŸh¶h Kƒubh¸)”}”(hŒøWhen a driver is registered, a sysfs directory is created in its bus's directory. In this directory, the driver can export an interface to userspace to control operation of the driver on a global basis; e.g. toggling debugging output in the driver.”h]”hŒúWhen a driver is registered, a sysfs directory is created in its bus’s directory. In this directory, the driver can export an interface to userspace to control operation of the driver on a global basis; e.g. toggling debugging output in the driver.”…””}”(hjŠhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K…hjyhžhubh¸)”}”(hŒ‘A future feature of this directory will be a 'devices' directory. This directory will contain symlinks to the directories of devices it supports.”h]”hŒ•A future feature of this directory will be a ‘devices’ directory. This directory will contain symlinks to the directories of devices it supports.”…””}”(hj˜hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KŠhjyhžhubeh}”(h]”Œsysfs”ah ]”h"]”Œsysfs”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kƒubh¢)”}”(hhh]”(h§)”}”(hŒ Callbacks”h]”hŒ Callbacks”…””}”(hj±hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj®hžhhŸh¶h K‘ubj5)”}”(hŒ-int (*probe) (struct device *dev);”h]”hŒ-int (*probe) (struct device *dev);”…””}”hj¿sbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h K•hj®hžhubh¸)”}”(hX›The probe() entry is called in task context, with the bus's rwsem locked and the driver partially bound to the device. Drivers commonly use container_of() to convert "dev" to a bus-specific type, both in probe() and other routines. That type often provides device resource data, such as pci_dev.resource[] or platform_device.resources, which is used in addition to dev->platform_data to initialize the driver.”h]”hX¡The probe() entry is called in task context, with the bus’s rwsem locked and the driver partially bound to the device. Drivers commonly use container_of() to convert “dev†to a bus-specific type, both in probe() and other routines. That type often provides device resource data, such as pci_dev.resource[] or platform_device.resources, which is used in addition to dev->platform_data to initialize the driver.”…””}”(hjÍhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K—hj®hžhubh¸)”}”(hX This callback holds the driver-specific logic to bind the driver to a given device. That includes verifying that the device is present, that it's a version the driver can handle, that driver data structures can be 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 binding the driver to that device.”h]”hXThis callback holds the driver-specific logic to bind the driver to a given device. That includes verifying that the device is present, that it’s a version the driver can handle, that driver data structures can be 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 binding the driver to that device.”…””}”(hjÛhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kžhj®hžhubh¸)”}”(hŒ¯A driver's probe() may return a negative errno value to indicate that the driver did not bind to this device, in which case it should have released all resources it allocated.”h]”hŒ±A driver’s probe() may return a negative errno value to indicate that the driver did not bind to this device, in which case it should have released all resources it allocated.”…””}”(hjéhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K§hj®hžhubh¸)”}”(hXÅOptionally, probe() may return -EPROBE_DEFER if the driver depends on resources that are not yet available (e.g., supplied by a driver that hasn't initialized yet). The driver core will put the device onto the deferred probe list and will try to call it again later. If a driver must defer, it should return -EPROBE_DEFER as early as possible to reduce the amount of time spent on setup work that will need to be unwound and reexecuted at a later time.”h]”hXÇOptionally, probe() may return -EPROBE_DEFER if the driver depends on resources that are not yet available (e.g., supplied by a driver that hasn’t initialized yet). The driver core will put the device onto the deferred probe list and will try to call it again later. If a driver must defer, it should return -EPROBE_DEFER as early as possible to reduce the amount of time spent on setup work that will need to be unwound and reexecuted at a later time.”…””}”(hj÷hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K«hj®hžhubhŒwarning”“”)”}”(hX -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.”h]”h¸)”}”(hX -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.”h]”hX -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.”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K´hjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhj®hžhhŸh¶h Nubj5)”}”(hŒ-void (*sync_state) (struct device *dev);”h]”hŒ-void (*sync_state) (struct device *dev);”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h K¼hj®hžhubh¸)”}”(hŒýsync_state is called only once for a device. It's called when all the consumer devices of the device have successfully probed. The list of consumers of the device is obtained by looking at the device links connecting that device to its consumer devices.”h]”hŒÿsync_state is called only once for a device. It’s called when all the consumer devices of the device have successfully probed. The list of consumers of the device is obtained by looking at the device links connecting that device to its consumer devices.”…””}”(hj-hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K¾hj®hžhubh¸)”}”(hXèThe first attempt to call sync_state() is made during late_initcall_sync() to give firmware and drivers time to link devices to each other. During the first attempt at calling sync_state(), if all the consumers of the device at that point in time have already probed successfully, sync_state() is called right away. If there are no consumers of the device during the first attempt, that too is considered as "all consumers of the device have probed" and sync_state() is called right away.”h]”hXìThe first attempt to call sync_state() is made during late_initcall_sync() to give firmware and drivers time to link devices to each other. During the first attempt at calling sync_state(), if all the consumers of the device at that point in time have already probed successfully, sync_state() is called right away. If there are no consumers of the device during the first attempt, that too is considered as “all consumers of the device have probed†and sync_state() is called right away.”…””}”(hj;hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÃhj®hžhubh¸)”}”(hX¦If during the first attempt at calling sync_state() for a device, there are still consumers that haven't probed successfully, the sync_state() call is postponed and reattempted in the future only when one or more consumers of the device probe successfully. If during the reattempt, the driver core finds that there are one or more consumers of the device that haven't probed yet, then sync_state() call is postponed again.”h]”hXªIf during the first attempt at calling sync_state() for a device, there are still consumers that haven’t probed successfully, the sync_state() call is postponed and reattempted in the future only when one or more consumers of the device probe successfully. If during the reattempt, the driver core finds that there are one or more consumers of the device that haven’t probed yet, then sync_state() call is postponed again.”…””}”(hjIhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KËhj®hžhubh¸)”}”(hX2A typical use case for sync_state() is to have the kernel cleanly take over management of devices from the bootloader. For example, if a device is left on and at a particular hardware configuration by the bootloader, the device's driver might need to keep the device in the boot configuration until all the consumers of the device have probed. Once all the consumers of the device have probed, the device's driver can synchronize the hardware state of the device to match the aggregated software state requested by all the consumers. Hence the name sync_state().”h]”hX6A typical use case for sync_state() is to have the kernel cleanly take over management of devices from the bootloader. For example, if a device is left on and at a particular hardware configuration by the bootloader, the device’s driver might need to keep the device in the boot configuration until all the consumers of the device have probed. Once all the consumers of the device have probed, the device’s driver can synchronize the hardware state of the device to match the aggregated software state requested by all the consumers. Hence the name sync_state().”…””}”(hjWhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÒhj®hžhubh¸)”}”(hX†While obvious examples of resources that can benefit from sync_state() include resources such as regulator, sync_state() can also be useful for complex resources like IOMMUs. For example, IOMMUs with multiple consumers (devices whose addresses are remapped by the IOMMU) might need to keep their mappings fixed at (or additive to) the boot configuration until all its consumers have probed.”h]”hX†While obvious examples of resources that can benefit from sync_state() include resources such as regulator, sync_state() can also be useful for complex resources like IOMMUs. For example, IOMMUs with multiple consumers (devices whose addresses are remapped by the IOMMU) might need to keep their mappings fixed at (or additive to) the boot configuration until all its consumers have probed.”…””}”(hjehžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KÛhj®hžhubh¸)”}”(hXWhile the typical use case for sync_state() is to have the kernel cleanly take over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after all the consumers of a device have probed::”h]”hXWhile the typical use case for sync_state() is to have the kernel cleanly take over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after all the consumers of a device have probed:”…””}”(hjshžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kâhj®hžhubj5)”}”(hŒ-int (*remove) (struct device *dev);”h]”hŒ-int (*remove) (struct device *dev);”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Kçhj®hžhubh¸)”}”(hŒÍremove is called to unbind a driver from a device. This may be called if a device is physically removed from the system, if the driver module is being unloaded, during a reboot sequence, or in other cases.”h]”hŒÍremove is called to unbind a driver from a device. This may be called if a device is physically removed from the system, if the driver module is being unloaded, during a reboot sequence, or in other cases.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kéhj®hžhubh¸)”}”(hŒ¹It is up to the driver to determine if the device is present or not. It should free any resources allocated specifically for the device; i.e. anything in the device's driver_data field.”h]”hŒ»It is up to the driver to determine if the device is present or not. It should free any resources allocated specifically for the device; i.e. anything in the device’s driver_data field.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kîhj®hžhubh¸)”}”(hŒkIf the device is still present, it should quiesce the device and place it into a supported low-power state.”h]”hŒkIf the device is still present, it should quiesce the device and place it into a supported low-power state.”…””}”(hj«hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kòhj®hžhubj5)”}”(hŒAint (*suspend) (struct device *dev, pm_message_t state);”h]”hŒAint (*suspend) (struct device *dev, pm_message_t state);”…””}”hj¹sbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h K÷hj®hžhubh¸)”}”(hŒ9suspend is called to put the device in a low power state.”h]”hŒ9suspend is called to put the device in a low power state.”…””}”(hjÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kùhj®hžhubj5)”}”(hŒ-int (*resume) (struct device *dev);”h]”hŒ-int (*resume) (struct device *dev);”…””}”hjÕsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Kýhj®hžhubh¸)”}”(hŒ=Resume is used to bring a device back from a low power state.”h]”hŒ=Resume is used to bring a device back from a low power state.”…””}”(hjãhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kÿhj®hžhubeh}”(h]”Œ callbacks”ah ]”h"]”Œ callbacks”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K‘ubh¢)”}”(hhh]”(h§)”}”(hŒ Attributes”h]”hŒ Attributes”…””}”(hjühžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjùhžhhŸh¶h Mubj5)”}”(hŒÕ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); };”h]”hŒÕ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); };”…””}”hj sbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Mhjùhžhubh¸)”}”(hŒØDevice drivers can export attributes via their sysfs directories. Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO macros.”h]”hŒØDevice drivers can export attributes via their sysfs directories. Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO macros.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h M hjùhžhubh¸)”}”(hŒ Example::”h]”hŒExample:”…””}”(hj&hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Mhjùhžhubj5)”}”(hŒDRIVER_ATTR_RW(debug);”h]”hŒDRIVER_ATTR_RW(debug);”…””}”hj4sbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Mhjùhžhubh¸)”}”(hŒ!This is equivalent to declaring::”h]”hŒ This is equivalent to declaring:”…””}”(hjBhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Mhjùhžhubj5)”}”(hŒ*struct driver_attribute driver_attr_debug;”h]”hŒ*struct driver_attribute driver_attr_debug;”…””}”hjPsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Mhjùhžhubh¸)”}”(hŒYThis can then be used to add and remove the attribute from the driver's directory using::”h]”hŒZThis can then be used to add and remove the attribute from the driver’s directory using:”…””}”(hj^hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Mhjùhžhubj5)”}”(hŒ¢int driver_create_file(struct device_driver *, const struct driver_attribute *); void driver_remove_file(struct device_driver *, const struct driver_attribute *);”h]”hŒ¢int driver_create_file(struct device_driver *, const struct driver_attribute *); void driver_remove_file(struct device_driver *, const struct driver_attribute *);”…””}”hjlsbah}”(h]”h ]”h"]”h$]”h&]”jDjEuh1j4hŸh¶h Mhjùhžhubeh}”(h]”Œ attributes”ah ]”h"]”Œ attributes”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Mubeh}”(h]”Œdevice-drivers”ah ]”h"]”Œdevice drivers”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j­Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j‡j„hëhèjjj­jªjþjûj3j0jvjsj«j¨jöjójj|uŒ nametypes”}”(j‡‰hë‰j‰j­‰jþ‰j3‰jv‰j«‰jö‰j‰uh}”(j„h£hèhÇjhîjªjjûj°j0jjsj6j¨jyjój®j|jùuŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nhžhub.