Commit e3941cd9 authored by Rafael J. Wysocki's avatar Rafael J. Wysocki Committed by Jonathan Corbet

PM / docs: Fix structure references in device.rst

There is a better way to represent structure references than it was
done in device.rst by commit 730c4c05 (PM / sleep / docs: Convert
PM notifiers document to reST), which is to use "struct name" as a
link caption (e.g. :c:type:`struct device <device>`).  That will
cause sphinx to generate a proper reference to the data type in
question (struct device in the example above) and "struct name"
will work as the link in the HTML output.

Fix device.rst by using that convention where applicable.

Fixes: 730c4c05 (PM / sleep / docs: Convert PM notifiers document to reST)
Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 62924fd7
.. |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 Device Power Management Basics
...@@ -95,17 +101,17 @@ Device Power Management Operations ...@@ -95,17 +101,17 @@ Device Power Management Operations
Device power management operations, at the subsystem level as well as at the 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 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`. |struct dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the
The roles of the methods included in it will be explained in what follows. For methods included in it will be explained in what follows. For now, it should be
now, it should be sufficient to remember that the last three methods are sufficient to remember that the last three methods are specific to runtime power
specific to runtime power management while the remaining ones are used during management while the remaining ones are used during system-wide power
system-wide power transitions. transitions.
There also is a deprecated "old" or "legacy" interface for power management There also is a deprecated "old" or "legacy" interface for power management
operations available at least for some subsystems. This approach does not use 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 |struct dev_pm_ops| objects and it is suitable only for implementing system
system sleep power management methods in a limited way. Therefore it is not sleep power management methods in a limited way. Therefore it is not described
described in this document, so please refer directly to the source code for more in this document, so please refer directly to the source code for more
information about it. information about it.
...@@ -113,14 +119,13 @@ Subsystem-Level Methods ...@@ -113,14 +119,13 @@ Subsystem-Level Methods
----------------------- -----------------------
The core methods to suspend and resume devices reside in The core methods to suspend and resume devices reside in
|struct| :c:type:`dev_pm_ops` pointed to by the :c:member:`ops` |struct dev_pm_ops| pointed to by the :c:member:`ops` member of
member of |struct| :c:type:`dev_pm_domain`, or by the :c:member:`pm` |struct dev_pm_domain|, or by the :c:member:`pm` member of |struct bus_type|,
member of |struct| :c:type:`bus_type`, |struct| :c:type:`device_type` and |struct device_type| and |struct class|. They are mostly of interest to the
|struct| :c:type:`class`. They are mostly of interest to the people writing people writing infrastructure for platforms and buses, like PCI or USB, or
infrastructure for platforms and buses, like PCI or USB, or device type and device type and device class drivers. They also are relevant to the writers of
device class drivers. They also are relevant to the writers of device drivers device drivers whose subsystems (PM domains, device types, device classes and
whose subsystems (PM domains, device types, device classes and bus types) don't bus types) don't provide all power management methods.
provide all power management methods.
Bus drivers implement these methods as appropriate for the hardware and the 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 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 ...@@ -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 driver) can physically support wakeup events. The
:c:func:`device_set_wakeup_capable()` routine affects this flag. 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 :c:member:`power.wakeup` field is a pointer to an object of type
|struct| :c:type:`wakeup_source` used for controlling whether or not |struct wakeup_source| used for controlling whether or not the device should use
the device should use its system wakeup mechanism and for notifying the its system wakeup mechanism and for notifying the PM core of system wakeup
PM core of system wakeup events signaled by the device. This object is only events signaled by the device. This object is only present for wakeup-capable
present for wakeup-capable devices (i.e. devices whose devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
:c:member:`can_wakeup` flags are set) and is created (or removed) by (or removed) by :c:func:`device_set_wakeup_capable()`.
:c:func:`device_set_wakeup_capable()`.
Whether or not a device is capable of issuing wakeup events is a hardware 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, 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 ...@@ -670,17 +674,17 @@ nested inside another power domain. The nested domain is referred to as the
sub-domain of the parent domain. sub-domain of the parent domain.
Support for power domains is provided through the :c:member:`pm_domain` field of 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 |struct device|. This field is a pointer to an object of type
type |struct| :c:type:`dev_pm_domain`, defined in :file:`include/linux/pm.h``, |struct dev_pm_domain|, defined in :file:`include/linux/pm.h``, providing a set
providing a set of power management callbacks analogous to the subsystem-level of power management callbacks analogous to the subsystem-level and device driver
and device driver callbacks that are executed for the given device during all callbacks that are executed for the given device during all power transitions,
power transitions, instead of the respective subsystem-level callbacks. instead of the respective subsystem-level callbacks. Specifically, if a
Specifically, if a device's :c:member:`pm_domain` pointer is not NULL, the device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
``->suspend()`` callback from the object pointed to by it will be executed from the object pointed to by it will be executed instead of its subsystem's
instead of its subsystem's (e.g. bus type's) ``->suspend()`` callback and (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
analogously for all of the remaining callbacks. In other words, power remaining callbacks. In other words, power management domain callbacks, if
management domain callbacks, if defined for the given device, always take defined for the given device, always take precedence over the callbacks provided
precedence over the callbacks provided by the device's subsystem (e.g. bus type). by the device's subsystem (e.g. bus type).
The support for device power management domains is only relevant to platforms The support for device power management domains is only relevant to platforms
needing to use the same device driver power management callbacks in many needing to use the same device driver power management callbacks in many
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment