diff options
Diffstat (limited to 'Documentation/driver-api/pm')
| -rw-r--r-- | Documentation/driver-api/pm/cpuidle.rst | 65 | ||||
| -rw-r--r-- | Documentation/driver-api/pm/devices.rst | 34 |
2 files changed, 43 insertions, 56 deletions
diff --git a/Documentation/driver-api/pm/cpuidle.rst b/Documentation/driver-api/pm/cpuidle.rst index 3588bf078566..d477208604b8 100644 --- a/Documentation/driver-api/pm/cpuidle.rst +++ b/Documentation/driver-api/pm/cpuidle.rst @@ -1,11 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> -.. |struct cpuidle_governor| replace:: :c:type:`struct cpuidle_governor <cpuidle_governor>` -.. |struct cpuidle_device| replace:: :c:type:`struct cpuidle_device <cpuidle_device>` -.. |struct cpuidle_driver| replace:: :c:type:`struct cpuidle_driver <cpuidle_driver>` -.. |struct cpuidle_state| replace:: :c:type:`struct cpuidle_state <cpuidle_state>` - ======================== CPU Idle Time Management ======================== @@ -54,7 +49,7 @@ platform that the Linux kernel can run on. For this reason, data structures operated on by them cannot depend on any hardware architecture or platform design details as well. -The governor itself is represented by a |struct cpuidle_governor| object +The governor itself is represented by a struct cpuidle_governor object containing four callback pointers, :c:member:`enable`, :c:member:`disable`, :c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described below, and a name (string) used for identifying it. @@ -83,11 +78,11 @@ callbacks: int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); The role of this callback is to prepare the governor for handling the - (logical) CPU represented by the |struct cpuidle_device| object pointed - to by the ``dev`` argument. The |struct cpuidle_driver| object pointed + (logical) CPU represented by the struct cpuidle_device object pointed + to by the ``dev`` argument. The struct cpuidle_driver object pointed to by the ``drv`` argument represents the ``CPUIdle`` driver to be used with that CPU (among other things, it should contain the list of - |struct cpuidle_state| objects representing idle states that the + struct cpuidle_state objects representing idle states that the processor holding the given CPU can be asked to enter). It may fail, in which case it is expected to return a negative error @@ -102,7 +97,7 @@ callbacks: void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); Called to make the governor stop handling the (logical) CPU represented - by the |struct cpuidle_device| object pointed to by the ``dev`` + by the struct cpuidle_device object pointed to by the ``dev`` argument. It is expected to reverse any changes made by the ``->enable()`` @@ -116,12 +111,12 @@ callbacks: bool *stop_tick); Called to select an idle state for the processor holding the (logical) - CPU represented by the |struct cpuidle_device| object pointed to by the + CPU represented by the struct cpuidle_device object pointed to by the ``dev`` argument. The list of idle states to take into consideration is represented by the - :c:member:`states` array of |struct cpuidle_state| objects held by the - |struct cpuidle_driver| object pointed to by the ``drv`` argument (which + :c:member:`states` array of struct cpuidle_state objects held by the + struct cpuidle_driver object pointed to by the ``drv`` argument (which represents the ``CPUIdle`` driver to be used with the CPU at hand). The value returned by this callback is interpreted as an index into that array (unless it is a negative error code). @@ -136,7 +131,7 @@ callbacks: asking the processor to enter the idle state). This callback is mandatory (i.e. the :c:member:`select` callback pointer - in |struct cpuidle_governor| must not be ``NULL`` for the registration + in struct cpuidle_governor must not be ``NULL`` for the registration of the governor to succeed). :c:member:`reflect` @@ -167,21 +162,21 @@ CPU idle time management (``CPUIdle``) drivers provide an interface between the other parts of ``CPUIdle`` and the hardware. First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array -of |struct cpuidle_state| objects included in the |struct cpuidle_driver| object +of struct cpuidle_state objects included in the struct cpuidle_driver object representing it. Going forward this array will represent the list of available idle states that the processor hardware can be asked to enter shared by all of the logical CPUs handled by the given driver. The entries in the :c:member:`states` array are expected to be sorted by the -value of the :c:member:`target_residency` field in |struct cpuidle_state| in +value of the :c:member:`target_residency` field in struct cpuidle_state in the ascending order (that is, index 0 should correspond to the idle state with the minimum value of :c:member:`target_residency`). [Since the :c:member:`target_residency` value is expected to reflect the "depth" of the -idle state represented by the |struct cpuidle_state| object holding it, this +idle state represented by the struct cpuidle_state object holding it, this sorting order should be the same as the ascending sorting order by the idle state "depth".] -Three fields in |struct cpuidle_state| are used by the existing ``CPUIdle`` +Three fields in struct cpuidle_state are used by the existing ``CPUIdle`` governors for computations related to idle state selection: :c:member:`target_residency` @@ -203,7 +198,7 @@ governors for computations related to idle state selection: any idle state at all. [There are other flags used by the ``CPUIdle`` core in special situations.] -The :c:member:`enter` callback pointer in |struct cpuidle_state|, which must not +The :c:member:`enter` callback pointer in struct cpuidle_state, which must not be ``NULL``, points to the routine to execute in order to ask the processor to enter this particular idle state: @@ -212,14 +207,14 @@ enter this particular idle state: void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv, int index); -The first two arguments of it point to the |struct cpuidle_device| object +The first two arguments of it point to the struct cpuidle_device object representing the logical CPU running this callback and the -|struct cpuidle_driver| object representing the driver itself, respectively, -and the last one is an index of the |struct cpuidle_state| entry in the driver's +struct cpuidle_driver object representing the driver itself, respectively, +and the last one is an index of the struct cpuidle_state entry in the driver's :c:member:`states` array representing the idle state to ask the processor to enter. -The analogous ``->enter_s2idle()`` callback in |struct cpuidle_state| is used +The analogous ``->enter_s2idle()`` callback in struct cpuidle_state is used only for implementing the suspend-to-idle system-wide power management feature. The difference between in and ``->enter()`` is that it must not re-enable interrupts at any point (even temporarily) or attempt to change the states of @@ -227,48 +222,48 @@ clock event devices, which the ``->enter()`` callback may do sometimes. Once the :c:member:`states` array has been populated, the number of valid entries in it has to be stored in the :c:member:`state_count` field of the -|struct cpuidle_driver| object representing the driver. Moreover, if any +struct cpuidle_driver object representing the driver. Moreover, if any entries in the :c:member:`states` array represent "coupled" idle states (that is, idle states that can only be asked for if multiple related logical CPUs are -idle), the :c:member:`safe_state_index` field in |struct cpuidle_driver| needs +idle), the :c:member:`safe_state_index` field in struct cpuidle_driver needs to be the index of an idle state that is not "coupled" (that is, one that can be asked for if only one logical CPU is idle). In addition to that, if the given ``CPUIdle`` driver is only going to handle a subset of logical CPUs in the system, the :c:member:`cpumask` field in its -|struct cpuidle_driver| object must point to the set (mask) of CPUs that will be +struct cpuidle_driver object must point to the set (mask) of CPUs that will be handled by it. A ``CPUIdle`` driver can only be used after it has been registered. If there are no "coupled" idle state entries in the driver's :c:member:`states` array, -that can be accomplished by passing the driver's |struct cpuidle_driver| object +that can be accomplished by passing the driver's struct cpuidle_driver object to :c:func:`cpuidle_register_driver()`. Otherwise, :c:func:`cpuidle_register()` should be used for this purpose. -However, it also is necessary to register |struct cpuidle_device| objects for +However, it also is necessary to register struct cpuidle_device objects for all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the help of :c:func:`cpuidle_register_device()` after the driver has been registered and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`, does not do that automatically. For this reason, the drivers that use :c:func:`cpuidle_register_driver()` to register themselves must also take care -of registering the |struct cpuidle_device| objects as needed, so it is generally +of registering the struct cpuidle_device objects as needed, so it is generally recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver registration in all cases. -The registration of a |struct cpuidle_device| object causes the ``CPUIdle`` +The registration of a struct cpuidle_device object causes the ``CPUIdle`` ``sysfs`` interface to be created and the governor's ``->enable()`` callback to be invoked for the logical CPU represented by it, so it must take place after registering the driver that will handle the CPU in question. -``CPUIdle`` drivers and |struct cpuidle_device| objects can be unregistered +``CPUIdle`` drivers and struct cpuidle_device objects can be unregistered when they are not necessary any more which allows some resources associated with them to be released. Due to dependencies between them, all of the -|struct cpuidle_device| objects representing CPUs handled by the given +struct cpuidle_device objects representing CPUs handled by the given ``CPUIdle`` driver must be unregistered, with the help of :c:func:`cpuidle_unregister_device()`, before calling :c:func:`cpuidle_unregister_driver()` to unregister the driver. Alternatively, :c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver -along with all of the |struct cpuidle_device| objects representing CPUs handled +along with all of the struct cpuidle_device objects representing CPUs handled by it. ``CPUIdle`` drivers can respond to runtime system configuration changes that @@ -277,8 +272,8 @@ happen, for example, when the system's power source is switched from AC to battery or the other way around). Upon a notification of such a change, a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for -all of the |struct cpuidle_device| objects representing CPUs affected by that +all of the struct cpuidle_device objects representing CPUs affected by that change. Next, it can update its :c:member:`states` array in accordance with the new configuration of the system, call :c:func:`cpuidle_enable_device()` for -all of the relevant |struct cpuidle_device| objects and invoke +all of the relevant struct cpuidle_device objects and invoke :c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again. diff --git a/Documentation/driver-api/pm/devices.rst b/Documentation/driver-api/pm/devices.rst index 946ad0b94e31..d448cb57df86 100644 --- a/Documentation/driver-api/pm/devices.rst +++ b/Documentation/driver-api/pm/devices.rst @@ -1,14 +1,6 @@ .. SPDX-License-Identifier: GPL-2.0 .. include:: <isonum.txt> -.. |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>` - .. _driverapi_pm_devices: ============================== @@ -107,7 +99,7 @@ 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 dev_pm_ops| defined in :file:`include/linux/pm.h`. The roles of the +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 @@ -115,7 +107,7 @@ 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 dev_pm_ops| objects and it is suitable only for implementing system +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. @@ -125,9 +117,9 @@ Subsystem-Level Methods ----------------------- The core methods to suspend and resume devices reside in -|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 +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 @@ -156,7 +148,7 @@ 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 wakeup_source| used for controlling whether or not the device should use +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 @@ -225,7 +217,7 @@ system-wide transition to a sleep state even though its :c:member:`runtime_auto` flag is clear. For more information about the runtime power management framework, refer to -:file:`Documentation/power/runtime_pm.rst`. +Documentation/power/runtime_pm.rst. Calling Drivers to Enter and Leave System Sleep States @@ -418,7 +410,7 @@ On many platforms they will gate off one or more clock sources; sometimes they will also switch off power supplies or reduce voltages. [Drivers supporting runtime PM may already have performed some or all of these steps.] -If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be +If :c:func:`device_may_wakeup()` returns ``true``, the device should be prepared for generating hardware wakeup signals to trigger a system wakeup event when the system is in the sleep state. For example, :c:func:`enable_irq_wake()` might identify GPIO signals hooked up to a switch or other external hardware, @@ -663,7 +655,7 @@ been thawed. Generally speaking, the PM notifiers are suitable for performing actions that either require user space to be available, or at least won't interfere with user space. -For details refer to :doc:`notifiers`. +For details refer to Documentation/driver-api/pm/notifiers.rst. Device Low-Power (suspend) States @@ -713,8 +705,8 @@ 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 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 +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 @@ -734,7 +726,7 @@ it into account in any way. Devices may be defined as IRQ-safe which indicates to the PM core that their runtime PM callbacks may be invoked with disabled interrupts (see -:file:`Documentation/power/runtime_pm.rst` for more information). If an +Documentation/power/runtime_pm.rst for more information). If an IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be disallowed, unless the domain itself is defined as IRQ-safe. However, it makes sense to define a PM domain as IRQ-safe only if all the devices in it @@ -813,7 +805,7 @@ The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag -------------------------------------------- During system-wide resume from a sleep state it's easiest to put devices into -the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`. +the full-power state, as explained in Documentation/power/runtime_pm.rst. [Refer to that document for more information regarding this particular issue as well as for information on the device runtime power management framework in general.] However, it often is desirable to leave devices in suspend after |