diff options
| -rw-r--r-- | Documentation/driver-api/pm/devices.rst | 72 |
1 files changed, 38 insertions, 34 deletions
diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 0e8cf4efd7e7..bedd32388dac 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -1,4 +1,10 @@ -.. |struct| replace:: :c:type:`struct` +.. |struct dev_pm_ops| replace:: :c:type:`struct dev_pm_ops <dev_pm_ops>` +.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>` +.. |struct bus_type| replace:: :c:type:`struct bus_type <bus_type>` +.. |struct device_type| replace:: :c:type:`struct device_type <device_type>` +.. |struct class| replace:: :c:type:`struct class <class>` +.. |struct wakeup_source| replace:: :c:type:`struct wakeup_source <wakeup_source>` +.. |struct device| replace:: :c:type:`struct device <device>` ============================== Device Power Management Basics @@ -95,17 +101,17 @@ Device Power Management Operations Device power management operations, at the subsystem level as well as at the device driver level, are implemented by defining and populating objects of type -|struct| :c:type:`dev_pm_ops` defined in :file:`include/linux/pm.h`. -The roles of the methods included in it will be explained in what follows. For -now, it should be sufficient to remember that the last three methods are -specific to runtime power management while the remaining ones are used during -system-wide power transitions. +|struct dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the +methods included in it will be explained in what follows. For now, it should be +sufficient to remember that the last three methods are specific to runtime power +management while the remaining ones are used during system-wide power +transitions. There also is a deprecated "old" or "legacy" interface for power management operations available at least for some subsystems. This approach does not use -|struct| :c:type:`dev_pm_ops` objects and it is suitable only for implementing -system sleep power management methods in a limited way. Therefore it is not -described in this document, so please refer directly to the source code for more +|struct dev_pm_ops| objects and it is suitable only for implementing system +sleep power management methods in a limited way. Therefore it is not described +in this document, so please refer directly to the source code for more information about it. @@ -113,14 +119,13 @@ Subsystem-Level Methods ----------------------- The core methods to suspend and resume devices reside in -|struct| :c:type:`dev_pm_ops` pointed to by the :c:member:`ops` -member of |struct| :c:type:`dev_pm_domain`, or by the :c:member:`pm` -member of |struct| :c:type:`bus_type`, |struct| :c:type:`device_type` and -|struct| :c:type:`class`. They are mostly of interest to the people writing -infrastructure for platforms and buses, like PCI or USB, or device type and -device class drivers. They also are relevant to the writers of device drivers -whose subsystems (PM domains, device types, device classes and bus types) don't -provide all power management methods. +|struct dev_pm_ops| pointed to by the :c:member:`ops` member of +|struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|, +|struct device_type| and |struct class|. They are mostly of interest to the +people writing infrastructure for platforms and buses, like PCI or USB, or +device type and device class drivers. They also are relevant to the writers of +device drivers whose subsystems (PM domains, device types, device classes and +bus types) don't provide all power management methods. Bus drivers implement these methods as appropriate for the hardware and the drivers using it; PCI works differently from USB, and so on. Not many people @@ -145,12 +150,11 @@ The :c:member:`power.can_wakeup` flag just records whether the device (and its driver) can physically support wakeup events. The :c:func:`device_set_wakeup_capable()` routine affects this flag. The :c:member:`power.wakeup` field is a pointer to an object of type -|struct| :c:type:`wakeup_source` used for controlling whether or not -the device should use its system wakeup mechanism and for notifying the -PM core of system wakeup events signaled by the device. This object is only -present for wakeup-capable devices (i.e. devices whose -:c:member:`can_wakeup` flags are set) and is created (or removed) by -:c:func:`device_set_wakeup_capable()`. +|struct wakeup_source| used for controlling whether or not the device should use +its system wakeup mechanism and for notifying the PM core of system wakeup +events signaled by the device. This object is only present for wakeup-capable +devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created +(or removed) by :c:func:`device_set_wakeup_capable()`. Whether or not a device is capable of issuing wakeup events is a hardware matter, and the kernel is responsible for keeping track of it. By contrast, @@ -670,17 +674,17 @@ nested inside another power domain. The nested domain is referred to as the sub-domain of the parent domain. Support for power domains is provided through the :c:member:`pm_domain` field of -|struct| :c:type:`device`. This field is a pointer to an object of -type |struct| :c:type:`dev_pm_domain`, defined in :file:`include/linux/pm.h``, -providing a set of power management callbacks analogous to the subsystem-level -and device driver callbacks that are executed for the given device during all -power transitions, instead of the respective subsystem-level callbacks. -Specifically, if a device's :c:member:`pm_domain` pointer is not NULL, the -``->suspend()`` callback from the object pointed to by it will be executed -instead of its subsystem's (e.g. bus type's) ``->suspend()`` callback and -analogously for all of the remaining callbacks. In other words, power -management domain callbacks, if defined for the given device, always take -precedence over the callbacks provided by the device's subsystem (e.g. bus type). +|struct device|. This field is a pointer to an object of type +|struct dev_pm_domain|, defined in :file:`include/linux/pm.h``, providing a set +of power management callbacks analogous to the subsystem-level and device driver +callbacks that are executed for the given device during all power transitions, +instead of the respective subsystem-level callbacks. Specifically, if a +device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback +from the object pointed to by it will be executed instead of its subsystem's +(e.g. bus type's) ``->suspend()`` callback and analogously for all of the +remaining callbacks. In other words, power management domain callbacks, if +defined for the given device, always take precedence over the callbacks provided +by the device's subsystem (e.g. bus type). The support for device power management domains is only relevant to platforms needing to use the same device driver power management callbacks in many |