[PATCH 0/2] PM / docs: Fixes for PM and device links driver-api

[PATCH 0/2] PM / docs: Fixes for PM and device links driver-api

[Rafael J. Wysocki]

Hi Jon,

These two patches fix references to struct data types in two documents that
did those things more or less incorrectly.

Both of them fix existing commits, one in the mainline and one in your tree.

Thanks,
Rafael

[PATCH 1/2] PM / docs: Fix structure references in device.rst

[Rafael J. Wysocki]

From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

There is a better way to represent structure references than it was
done in device.rst by commit 730c4c053012 (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: 730c4c053012 (PM / sleep / docs: Convert PM notifiers document to reST)
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
---
 Documentation/driver-api/pm/devices.rst |   72 ++++++++++++++++----------------
 1 file changed, 38 insertions(+), 34 deletions(-)

Index: linux-pm/Documentation/driver-api/pm/devices.rst
===================================================================
--- linux-pm.orig/Documentation/driver-api/pm/devices.rst
+++ linux-pm/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 ju
 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
 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

[PATCH 2/2] docs / driver-api: Fix structure references in device_link.rst

[Rafael J. Wysocki]

From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

The format of the structure references in device_link.rst is
incorrect, because it doesn't cause proper references to the
struct data types to be generated (for struct dev_pm_domain in
particular).

Fix that by using the :c:type:`struct name <name>` convention
for encoding references to struct data types.

Fixes: aad800403a87 (Documentation/core-api/device_link: Add initial documentation)
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
---
 Documentation/driver-api/device_link.rst |   18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

Index: linux-pm/Documentation/driver-api/device_link.rst
===================================================================
--- linux-pm.orig/Documentation/driver-api/device_link.rst
+++ linux-pm/Documentation/driver-api/device_link.rst
@@ -1,3 +1,6 @@
+.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
+.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>`
+
 ============
 Device links
 ============
@@ -120,12 +123,11 @@ Examples
   is the same as if the MMU was the parent of the master device.
 
   The fact that both devices share the same power domain would normally
-  suggest usage of a :c:type:`struct dev_pm_domain` or :c:type:`struct
-  generic_pm_domain`, however these are not independent devices that
-  happen to share a power switch, but rather the MMU device serves the
-  busmaster device and is useless without it.  A device link creates a
-  synthetic hierarchical relationship between the devices and is thus
-  more apt.
+  suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
+  however these are not independent devices that happen to share a power
+  switch, but rather the MMU device serves the busmaster device and is
+  useless without it.  A device link creates a synthetic hierarchical
+  relationship between the devices and is thus more apt.
 
 * A Thunderbolt host controller comprises a number of PCIe hotplug ports
   and an NHI device to manage the PCIe switch.  On resume from system sleep,
@@ -157,7 +159,7 @@ Examples
 Alternatives
 ============
 
-* A :c:type:`struct dev_pm_domain` can be used to override the bus,
+* A |struct dev_pm_domain| can be used to override the bus,
   class or device type callbacks.  It is intended for devices sharing
   a single on/off switch, however it does not guarantee a specific
   suspend/resume ordering, this needs to be implemented separately.
@@ -166,7 +168,7 @@ Alternatives
   suspended.  Furthermore it cannot be used to enforce a specific shutdown
   ordering or a driver presence dependency.
 
-* A :c:type:`struct generic_pm_domain` is a lot more heavyweight than a
+* A |struct generic_pm_domain| is a lot more heavyweight than a
   device link and does not allow for shutdown ordering or driver presence
   dependencies.  It also cannot be used on ACPI systems.
 

Re: [PATCH 0/2] PM / docs: Fixes for PM and device links driver-api

[Jonathan Corbet]

On Mon, 20 Feb 2017 15:23:29 +0100
"Rafael J. Wysocki" <rjw@rjwysocki.net> wrote:

> These two patches fix references to struct data types in two documents that
> did those things more or less incorrectly.
> 
> Both of them fix existing commits, one in the mainline and one in your tree.

I've applied them both, and will sneak them into 4.11.

Thanks,

jon