summaryrefslogtreecommitdiff
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-06-07 10:53:36 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2020-06-07 10:53:36 -0700
commitf558b8364e19f9222e7976c64e9367f66bab02cc (patch)
treec50c0fc9a3ab8430c4aaa1170d1cc1e08448bd7b /Documentation/driver-api
parent80ef846e9909f22ccdc2a4a6d931266cecce8b2c (diff)
parent8c3e315d4296421cd26b3300ee0ac117f0877f20 (diff)
Merge tag 'driver-core-5.8-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core
Pull driver core updates from Greg KH: "Here is the set of driver core patches for 5.8-rc1. Not all that huge this release, just a number of small fixes and updates: - software node fixes - kobject now sends KOBJ_REMOVE when it is removed from sysfs, not when it is removed from memory (which could come much later) - device link additions and fixes based on testing on more devices - firmware core cleanups - other minor changes, full details in the shortlog All have been in linux-next for a while with no reported issues" * tag 'driver-core-5.8-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core: (23 commits) driver core: Update device link status correctly for SYNC_STATE_ONLY links firmware_loader: change enum fw_opt to u32 software node: implement software_node_unregister() kobject: send KOBJ_REMOVE uevent when the object is removed from sysfs driver core: Remove unnecessary is_fwnode_dev variable in device_add() drivers property: When no children in primary, try secondary driver core: platform: Fix spelling errors in platform.c driver core: Remove check in driver_deferred_probe_force_trigger() of: platform: Batch fwnode parsing when adding all top level devices driver core: fw_devlink: Add support for batching fwnode parsing driver core: Look for waiting consumers only for a fwnode's primary device driver core: Move code to the right part of the file Revert "Revert "driver core: Set fw_devlink to "permissive" behavior by default"" drivers: base: Fix NULL pointer exception in __platform_driver_probe() if a driver developer is foolish firmware_loader: move fw_fallback_config to a private kernel symbol namespace driver core: Add missing '\n' in log messages driver/base/soc: Use kobj_to_dev() API Add documentation on meaning of -EPROBE_DEFER driver core: platform: remove redundant assignment to variable ret debugfs: Use the correct style for SPDX License Identifier ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/driver-model/driver.rst32
1 files changed, 27 insertions, 5 deletions
diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index 63887b813005..7d5040f6a3d8 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -4,7 +4,6 @@ Device Drivers
See the kerneldoc for the struct device_driver.
-
Allocation
~~~~~~~~~~
@@ -167,9 +166,26 @@ the driver to that device.
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::
+released all resources it allocated.
+
+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.
+
+.. 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);
+ void (*sync_state) (struct device *dev);
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
@@ -212,6 +228,8 @@ 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::
+::
+
int (*remove) (struct device *dev);
remove is called to unbind a driver from a device. This may be
@@ -224,11 +242,15 @@ not. It should free any resources allocated specifically for the
device; i.e. anything in the device's driver_data field.
If the device is still present, it should quiesce the device and place
-it into a supported low-power state::
+it 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::
+suspend is called to put the device in a low power state.
+
+::
int (*resume) (struct device *dev);