^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) PCI Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) An overview of concepts and the Linux kernel's interfaces related to PCI power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) management. Based on previous work by Patrick Mochel <mochel@transmeta.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) (and others).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This document only covers the aspects of power management specific to PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) devices. For general description of the kernel's interfaces related to device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) power management refer to Documentation/driver-api/pm/devices.rst and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Documentation/power/runtime_pm.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) .. contents:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) 1. Hardware and Platform Support for PCI Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 2. PCI Subsystem and Device Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) 3. PCI Device Drivers and Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 4. Resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 1. Hardware and Platform Support for PCI Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) =========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) 1.1. Native and Platform-Based Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) -----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) In general, power management is a feature allowing one to save energy by putting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) devices into states in which they draw less power (low-power states) at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) price of reduced functionality or performance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Usually, a device is put into a low-power state when it is underutilized or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) completely inactive. However, when it is necessary to use the device once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) again, it has to be put back into the "fully functional" state (full-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) state). This may happen when there are some data for the device to handle or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) as a result of an external event requiring the device to be active, which may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) be signaled by the device itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) PCI devices may be put into low-power states in two ways, by using the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) capabilities introduced by the PCI Bus Power Management Interface Specification,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) or with the help of platform firmware, such as an ACPI BIOS. In the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) approach, that is referred to as the native PCI power management (native PCI PM)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) in what follows, the device power state is changed as a result of writing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) specific value into one of its standard configuration registers. The second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) approach requires the platform firmware to provide special methods that may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) used by the kernel to change the device's power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Devices supporting the native PCI PM usually can generate wakeup signals called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Power Management Events (PMEs) to let the kernel know about external events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) requiring the device to be active. After receiving a PME the kernel is supposed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) to put the device that sent it into the full-power state. However, the PCI Bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Power Management Interface Specification doesn't define any standard method of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) delivering the PME from the device to the CPU and the operating system kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) It is assumed that the platform firmware will perform this task and therefore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) even though a PCI device is set up to generate PMEs, it also may be necessary to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) prepare the platform firmware for notifying the CPU of the PMEs coming from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) device (e.g. by generating interrupts).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) In turn, if the methods provided by the platform firmware are used for changing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) the power state of a device, usually the platform also provides a method for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) preparing the device to generate wakeup signals. In that case, however, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) often also is necessary to prepare the device for generating PMEs using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) native PCI PM mechanism, because the method provided by the platform depends on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Thus in many situations both the native and the platform-based power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) mechanisms have to be used simultaneously to obtain the desired result.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) 1.2. Native PCI Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) The PCI Bus Power Management Interface Specification (PCI PM Spec) was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) standard interface for performing various operations related to power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) The implementation of the PCI PM Spec is optional for conventional PCI devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) but it is mandatory for PCI Express devices. If a device supports the PCI PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) Spec, it has an 8 byte power management capability field in its PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) configuration space. This field is used to describe and control the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) features related to the native PCI power management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) The PCI PM Spec defines 4 operating states for devices (D0-D3) and for buses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) (B0-B3). The higher the number, the less power is drawn by the device or bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) in that state. However, the higher the number, the longer the latency for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) the device or bus to return to the full-power state (D0 or B0, respectively).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) There are two variants of the D3 state defined by the specification. The first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) one is D3hot, referred to as the software accessible D3, because devices can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) programmed to go into it. The second one, D3cold, is the state that PCI devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) are in when the supply voltage (Vcc) is removed from them. It is not possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) to program a PCI device to go into D3cold, although there may be a programmable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) interface for putting the bus the device is on into a state in which Vcc is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) removed from all devices on the bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) PCI bus power management, however, is not supported by the Linux kernel at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) time of this writing and therefore it is not covered by this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) Note that every PCI device can be in the full-power state (D0) or in D3cold,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) regardless of whether or not it implements the PCI PM Spec. In addition to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) that, if the PCI PM Spec is implemented by the device, it must support D3hot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) as well as D0. The support for the D1 and D2 power states is optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) PCI devices supporting the PCI PM Spec can be programmed to go to any of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) supported low-power states (except for D3cold). While in D1-D3hot the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) standard configuration registers of the device must be accessible to software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) (i.e. the device is required to respond to PCI configuration accesses), although
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) its I/O and memory spaces are then disabled. This allows the device to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) programmatically put into D0. Thus the kernel can switch the device back and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) forth between D0 and the supported low-power states (except for D3cold) and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) possible power state transitions the device can undergo are the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) | Current State | New State |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) | D0 | D1, D2, D3 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) | D1 | D2, D3 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) | D2 | D3 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) | D1, D2, D3 | D0 |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) +----------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) The transition from D3cold to D0 occurs when the supply voltage is provided to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) the device (i.e. power is restored). In that case the device returns to D0 with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) a full power-on reset sequence and the power-on defaults are restored to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) device by hardware just as at initial power up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) PCI devices supporting the PCI PM Spec can be programmed to generate PMEs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) while in any power state (D0-D3), but they are not required to be capable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) of generating PMEs from all supported power states. In particular, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) capability of generating PMEs from D3cold is optional and depends on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) presence of additional voltage (3.3Vaux) allowing the device to remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) sufficiently active to generate a wakeup signal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) 1.3. ACPI Device Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ---------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) The platform firmware support for the power management of PCI devices is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) system-specific. However, if the system in question is compliant with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Advanced Configuration and Power Interface (ACPI) Specification, like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) majority of x86-based systems, it is supposed to implement device power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) management interfaces defined by the ACPI standard.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) For this purpose the ACPI BIOS provides special functions called "control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) methods" that may be executed by the kernel to perform specific tasks, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) putting a device into a low-power state. These control methods are encoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) using special byte-code language called the ACPI Machine Language (AML) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) stored in the machine's BIOS. The kernel loads them from the BIOS and executes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) them as needed using an AML interpreter that translates the AML byte code into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) computations and memory or I/O space accesses. This way, in theory, a BIOS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) writer can provide the kernel with a means to perform actions depending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) on the system design in a system-specific fashion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) ACPI control methods may be divided into global control methods, that are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) associated with any particular devices, and device control methods, that have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) to be defined separately for each device supposed to be handled with the help of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) the platform. This means, in particular, that ACPI device control methods can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) only be used to handle devices that the BIOS writer knew about in advance. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) ACPI methods used for device power management fall into that category.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) The ACPI specification assumes that devices can be in one of four power states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) labeled as D0, D1, D2, and D3 that roughly correspond to the native PCI PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) D0-D3 states (although the difference between D3hot and D3cold is not taken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) into account by ACPI). Moreover, for each power state of a device there is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) set of power resources that have to be enabled for the device to be put into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) that state. These power resources are controlled (i.e. enabled or disabled)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) with the help of their own control methods, _ON and _OFF, that have to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) defined individually for each of them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) To put a device into the ACPI power state Dx (where x is a number between 0 and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 3 inclusive) the kernel is supposed to (1) enable the power resources required
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) by the device in this state using their _ON control methods and (2) execute the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) _PSx control method defined for the device. In addition to that, if the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) is going to be put into a low-power state (D1-D3) and is supposed to generate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) wakeup signals from that state, the _DSW (or _PSW, replaced with _DSW by ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) 3.0) control method defined for it has to be executed before _PSx. Power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) resources that are not required by the device in the target power state and are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) not required any more by any other device should be disabled (by executing their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) _OFF control methods). If the current power state of the device is D3, it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) only be put into D0 this way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) However, quite often the power states of devices are changed during a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) system-wide transition into a sleep state or back into the working state. ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) defines four system sleep states, S1, S2, S3, and S4, and denotes the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) working state as S0. In general, the target system sleep (or working) state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) determines the highest power (lowest number) state the device can be put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) into and the kernel is supposed to obtain this information by executing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) device's _SxD control method (where x is a number between 0 and 4 inclusive).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) If the device is required to wake up the system from the target sleep state, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) lowest power (highest number) state it can be put into is also determined by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) target state of the system. The kernel is then supposed to use the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) _SxW control method to obtain the number of that state. It also is supposed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) use the device's _PRW control method to learn which power resources need to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) enabled for the device to be able to generate wakeup signals.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 1.4. Wakeup Signaling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) Wakeup signals generated by PCI devices, either as native PCI PMEs, or as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) a result of the execution of the _DSW (or _PSW) ACPI control method before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) putting the device into a low-power state, have to be caught and handled as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) appropriate. If they are sent while the system is in the working state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) (ACPI S0), they should be translated into interrupts so that the kernel can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) put the devices generating them into the full-power state and take care of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) events that triggered them. In turn, if they are sent while the system is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) sleeping, they should cause the system's core logic to trigger wakeup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) On ACPI-based systems wakeup signals sent by conventional PCI devices are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) converted into ACPI General-Purpose Events (GPEs) which are hardware signals
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) from the system core logic generated in response to various events that need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) be acted upon. Every GPE is associated with one or more sources of potentially
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) interesting events. In particular, a GPE may be associated with a PCI device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) capable of signaling wakeup. The information on the connections between GPEs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) and event sources is recorded in the system's ACPI BIOS from where it can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) read by the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) If a PCI device known to the system's ACPI BIOS signals wakeup, the GPE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) associated with it (if there is one) is triggered. The GPEs associated with PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) bridges may also be triggered in response to a wakeup signal from one of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) devices below the bridge (this also is the case for root bridges) and, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) example, native PCI PMEs from devices unknown to the system's ACPI BIOS may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) handled this way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) A GPE may be triggered when the system is sleeping (i.e. when it is in one of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) the ACPI S1-S4 states), in which case system wakeup is started by its core logic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) (the device that was the source of the signal causing the system wakeup to occur
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) may be identified later). The GPEs used in such situations are referred to as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) wakeup GPEs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) Usually, however, GPEs are also triggered when the system is in the working
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) state (ACPI S0) and in that case the system's core logic generates a System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) Control Interrupt (SCI) to notify the kernel of the event. Then, the SCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) handler identifies the GPE that caused the interrupt to be generated which,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) in turn, allows the kernel to identify the source of the event (that may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) a PCI device signaling wakeup). The GPEs used for notifying the kernel of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) events occurring while the system is in the working state are referred to as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) runtime GPEs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Unfortunately, there is no standard way of handling wakeup signals sent by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) conventional PCI devices on systems that are not ACPI-based, but there is one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) for PCI Express devices. Namely, the PCI Express Base Specification introduced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) a native mechanism for converting native PCI PMEs into interrupts generated by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) root ports. For conventional PCI devices native PMEs are out-of-band, so they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) are routed separately and they need not pass through bridges (in principle they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) may be routed directly to the system's core logic), but for PCI Express devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) they are in-band messages that have to pass through the PCI Express hierarchy,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) including the root port on the path from the device to the Root Complex. Thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) it was possible to introduce a mechanism by which a root port generates an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) interrupt whenever it receives a PME message from one of the devices below it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) The PCI Express Requester ID of the device that sent the PME message is then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) recorded in one of the root port's configuration registers from where it may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) read by the interrupt handler allowing the device to be identified. [PME
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) messages sent by PCI Express endpoints integrated with the Root Complex don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) pass through root ports, but instead they cause a Root Complex Event Collector
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) (if there is one) to generate interrupts.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) In principle the native PCI Express PME signaling may also be used on ACPI-based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) systems along with the GPEs, but to use it the kernel has to ask the system's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) ACPI BIOS to release control of root port configuration registers. The ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) BIOS, however, is not required to allow the kernel to control these registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) and if it doesn't do that, the kernel must not modify their contents. Of course
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) the native PCI Express PME signaling cannot be used by the kernel in that case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) 2. PCI Subsystem and Device Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 2.1. Device Power Management Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) The PCI Subsystem participates in the power management of PCI devices in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) number of ways. First of all, it provides an intermediate code layer between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) the device power management core (PM core) and PCI device drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) Specifically, the pm field of the PCI subsystem's struct bus_type object,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) pointers to several device power management callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) const struct dev_pm_ops pci_dev_pm_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) .prepare = pci_pm_prepare,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) .complete = pci_pm_complete,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) .suspend = pci_pm_suspend,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) .resume = pci_pm_resume,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) .freeze = pci_pm_freeze,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) .thaw = pci_pm_thaw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) .poweroff = pci_pm_poweroff,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) .restore = pci_pm_restore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) .suspend_noirq = pci_pm_suspend_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) .resume_noirq = pci_pm_resume_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) .freeze_noirq = pci_pm_freeze_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) .thaw_noirq = pci_pm_thaw_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) .poweroff_noirq = pci_pm_poweroff_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) .restore_noirq = pci_pm_restore_noirq,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) .runtime_suspend = pci_pm_runtime_suspend,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) .runtime_resume = pci_pm_runtime_resume,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) .runtime_idle = pci_pm_runtime_idle,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) These callbacks are executed by the PM core in various situations related to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) device power management and they, in turn, execute power management callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) provided by PCI device drivers. They also perform power management operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) involving some standard configuration registers of PCI devices that device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) drivers need not know or care about.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) The structure representing a PCI device, struct pci_dev, contains several fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) that these callbacks operate on::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) struct pci_dev {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) pci_power_t current_state; /* Current operating state. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) int pm_cap; /* PM capability offset in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) configuration space */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) unsigned int pme_support:5; /* Bitmask of states from which PME#
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) can be generated */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) unsigned int pme_interrupt:1;/* Is native PCIe PME signaling used? */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) unsigned int d1_support:1; /* Low power state D1 is supported */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) unsigned int d2_support:1; /* Low power state D2 is supported */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) unsigned int no_d1d2:1; /* D1 and D2 are forbidden */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) unsigned int wakeup_prepared:1; /* Device prepared for wake up */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) unsigned int d3hot_delay; /* D3hot->D0 transition time in ms */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) They also indirectly use some fields of the struct device that is embedded in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) struct pci_dev.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) 2.2. Device Initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) The PCI subsystem's first task related to device power management is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) prepare the device for power management and initialize the fields of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) pci_dev used for this purpose. This happens in two functions defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) drivers/pci/pci.c, pci_pm_init() and platform_pci_wakeup_init().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) The first of these functions checks if the device supports native PCI PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) and if that's the case the offset of its power management capability structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) in the configuration space is stored in the pm_cap field of the device's struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) pci_dev object. Next, the function checks which PCI low-power states are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) supported by the device and from which low-power states the device can generate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) native PCI PMEs. The power management fields of the device's struct pci_dev and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) the struct device embedded in it are updated accordingly and the generation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) PMEs by the device is disabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) The second function checks if the device can be prepared to signal wakeup with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) the help of the platform firmware, such as the ACPI BIOS. If that is the case,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) the function updates the wakeup fields in struct device embedded in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) device's struct pci_dev and uses the firmware-provided method to prevent the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) device from signaling wakeup.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) At this point the device is ready for power management. For driverless devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) however, this functionality is limited to a few basic operations carried out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) during system-wide transitions to a sleep state and back to the working state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) 2.3. Runtime Device Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) The PCI subsystem plays a vital role in the runtime power management of PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) devices. For this purpose it uses the general runtime power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) (runtime PM) framework described in Documentation/power/runtime_pm.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Namely, it provides subsystem-level callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) pci_pm_runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) pci_pm_runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) pci_pm_runtime_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) that are executed by the core runtime PM routines. It also implements the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) entire mechanics necessary for handling runtime wakeup signals from PCI devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) in low-power states, which at the time of this writing works for both the native
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) PCI Express PME signaling and the ACPI GPE-based wakeup signaling described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) Section 1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) First, a PCI device is put into a low-power state, or suspended, with the help
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) of pm_schedule_suspend() or pm_runtime_suspend() which for PCI devices call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) pci_pm_runtime_suspend() to do the actual job. For this to work, the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) driver has to provide a pm->runtime_suspend() callback (see below), which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) run by pci_pm_runtime_suspend() as the first action. If the driver's callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) returns successfully, the device's standard configuration registers are saved,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) the device is prepared to generate wakeup signals and, finally, it is put into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) the target low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) The low-power state to put the device into is the lowest-power (highest number)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) state from which it can signal wakeup. The exact method of signaling wakeup is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) system-dependent and is determined by the PCI subsystem on the basis of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) reported capabilities of the device and the platform firmware. To prepare the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) device for signaling wakeup and put it into the selected low-power state, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) PCI subsystem can use the platform firmware as well as the device's native PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) PM capabilities, if supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) It is expected that the device driver's pm->runtime_suspend() callback will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) not attempt to prepare the device for signaling wakeup or to put it into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) low-power state. The driver ought to leave these tasks to the PCI subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) that has all of the information necessary to perform them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) A suspended device is brought back into the "active" state, or resumed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) with the help of pm_request_resume() or pm_runtime_resume() which both call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) pci_pm_runtime_resume() for PCI devices. Again, this only works if the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) driver provides a pm->runtime_resume() callback (see below). However, before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) the driver's callback is executed, pci_pm_runtime_resume() brings the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) back into the full-power state, prevents it from signaling wakeup while in that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) state and restores its standard configuration registers. Thus the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) callback need not worry about the PCI-specific aspects of the device resume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) Note that generally pci_pm_runtime_resume() may be called in two different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) situations. First, it may be called at the request of the device's driver, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) example if there are some data for it to process. Second, it may be called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) as a result of a wakeup signal from the device itself (this sometimes is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) referred to as "remote wakeup"). Of course, for this purpose the wakeup signal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) is handled in one of the ways described in Section 1 and finally converted into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) a notification for the PCI subsystem after the source device has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) identified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) The pci_pm_runtime_idle() function, called for PCI devices by pm_runtime_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) and pm_request_idle(), executes the device driver's pm->runtime_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) callback, if defined, and if that callback doesn't return error code (or is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) present at all), suspends the device with the help of pm_runtime_suspend().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) Sometimes pci_pm_runtime_idle() is called automatically by the PM core (for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) example, it is called right after the device has just been resumed), in which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) cases it is expected to suspend the device if that makes sense. Usually,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) however, the PCI subsystem doesn't really know if the device really can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) suspended, so it lets the device's driver decide by running its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) pm->runtime_idle() callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) 2.4. System-Wide Power Transitions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) There are a few different types of system-wide power transitions, described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) Documentation/driver-api/pm/devices.rst. Each of them requires devices to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) handled in a specific way and the PM core executes subsystem-level power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) management callbacks for this purpose. They are executed in phases such that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) each phase involves executing the same subsystem-level callback for every device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) belonging to the given subsystem before the next phase begins. These phases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) always run after tasks have been frozen.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) 2.4.1. System Suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) ^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) When the system is going into a sleep state in which the contents of memory will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) prepare, suspend, suspend_noirq.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) The following PCI bus type's callbacks, respectively, are used in these phases::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) pci_pm_prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) pci_pm_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) pci_pm_suspend_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) The pci_pm_prepare() routine first puts the device into the "fully functional"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) state with the help of pm_runtime_resume(). Then, it executes the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) driver's pm->prepare() callback if defined (i.e. if the driver's struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) dev_pm_ops object is present and the prepare pointer in that object is valid).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) The pci_pm_suspend() routine first checks if the device's driver implements
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) legacy PCI suspend routines (see Section 3), in which case the driver's legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) suspend callback is executed, if present, and its result is returned. Next, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) the device's driver doesn't provide a struct dev_pm_ops object (containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) pointers to the driver's callbacks), pci_pm_default_suspend() is called, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) simply turns off the device's bus master capability and runs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) pcibios_disable_device() to disable it, unless the device is a bridge (PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) bridges are ignored by this routine). Next, the device driver's pm->suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) callback is executed, if defined, and its result is returned if it fails.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) Finally, pci_fixup_device() is called to apply hardware suspend quirks related
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) to the device if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) Note that the suspend phase is carried out asynchronously for PCI devices, so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) the pci_pm_suspend() callback may be executed in parallel for any pair of PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) devices that don't depend on each other in a known way (i.e. none of the paths
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) in the device tree from the root bridge to a leaf device contains both of them).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) The pci_pm_suspend_noirq() routine is executed after suspend_device_irqs() has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) been called, which means that the device driver's interrupt handler won't be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) invoked while this routine is running. It first checks if the device's driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) implements legacy PCI suspends routines (Section 3), in which case the legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) late suspend routine is called and its result is returned (the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) configuration registers of the device are saved if the driver's callback hasn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) done that). Second, if the device driver's struct dev_pm_ops object is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) present, the device's standard configuration registers are saved and the routine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) returns success. Otherwise the device driver's pm->suspend_noirq() callback is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) executed, if present, and its result is returned if it fails. Next, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) device's standard configuration registers haven't been saved yet (one of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) device driver's callbacks executed before might do that), pci_pm_suspend_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) saves them, prepares the device to signal wakeup (if necessary) and puts it into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) a low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) The low-power state to put the device into is the lowest-power (highest number)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) state from which it can signal wakeup while the system is in the target sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) state. Just like in the runtime PM case described above, the mechanism of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) signaling wakeup is system-dependent and determined by the PCI subsystem, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) is also responsible for preparing the device to signal wakeup from the system's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) target sleep state as appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) PCI device drivers (that don't implement legacy power management callbacks) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) generally not expected to prepare devices for signaling wakeup or to put them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) into low-power states. However, if one of the driver's suspend callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) (pm->suspend() or pm->suspend_noirq()) saves the device's standard configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) registers, pci_pm_suspend_noirq() will assume that the device has been prepared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) to signal wakeup and put into a low-power state by the driver (the driver is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) then assumed to have used the helper functions provided by the PCI subsystem for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) this purpose). PCI device drivers are not encouraged to do that, but in some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) rare cases doing that in the driver may be the optimum approach.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) 2.4.2. System Resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) ^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) When the system is undergoing a transition from a sleep state in which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) contents of memory have been preserved, such as one of the ACPI sleep states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) S1-S3, into the working state (ACPI S0), the phases are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) resume_noirq, resume, complete.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) The following PCI bus type's callbacks, respectively, are executed in these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) phases::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) pci_pm_resume_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) pci_pm_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) pci_pm_complete()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) The pci_pm_resume_noirq() routine first puts the device into the full-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) state, restores its standard configuration registers and applies early resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) hardware quirks related to the device, if necessary. This is done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) unconditionally, regardless of whether or not the device's driver implements
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) legacy PCI power management callbacks (this way all PCI devices are in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) full-power state and their standard configuration registers have been restored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) when their interrupt handlers are invoked for the first time during resume,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) which allows the kernel to avoid problems with the handling of shared interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) by drivers whose devices are still suspended). If legacy PCI power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) callbacks (see Section 3) are implemented by the device's driver, the legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) early resume callback is executed and its result is returned. Otherwise, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) device driver's pm->resume_noirq() callback is executed, if defined, and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) result is returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) The pci_pm_resume() routine first checks if the device's standard configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) registers have been restored and restores them if that's not the case (this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) only is necessary in the error path during a failing suspend). Next, resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) hardware quirks related to the device are applied, if necessary, and if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) device's driver implements legacy PCI power management callbacks (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) Section 3), the driver's legacy resume callback is executed and its result is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) returned. Otherwise, the device's wakeup signaling mechanisms are blocked and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) its driver's pm->resume() callback is executed, if defined (the callback's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) result is then returned).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) The resume phase is carried out asynchronously for PCI devices, like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) suspend phase described above, which means that if two PCI devices don't depend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) on each other in a known way, the pci_pm_resume() routine may be executed for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) the both of them in parallel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) The pci_pm_complete() routine only executes the device driver's pm->complete()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) callback, if defined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) 2.4.3. System Hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) ^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555) System hibernation is more complicated than system suspend, because it requires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) a system image to be created and written into a persistent storage medium. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) image is created atomically and all devices are quiesced, or frozen, before that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) happens.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) The freezing of devices is carried out after enough memory has been freed (at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) the time of this writing the image creation requires at least 50% of system RAM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) to be free) in the following three phases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) prepare, freeze, freeze_noirq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) that correspond to the PCI bus type's callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) pci_pm_prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) pci_pm_freeze()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) pci_pm_freeze_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) This means that the prepare phase is exactly the same as for system suspend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) The other two phases, however, are different.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) The pci_pm_freeze() routine is quite similar to pci_pm_suspend(), but it runs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) the device driver's pm->freeze() callback, if defined, instead of pm->suspend(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) and it doesn't apply the suspend-related hardware quirks. It is executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) asynchronously for different PCI devices that don't depend on each other in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) known way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) The pci_pm_freeze_noirq() routine, in turn, is similar to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) pci_pm_suspend_noirq(), but it calls the device driver's pm->freeze_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) routine instead of pm->suspend_noirq(). It also doesn't attempt to prepare the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) device for signaling wakeup and put it into a low-power state. Still, it saves
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) the device's standard configuration registers if they haven't been saved by one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) of the driver's callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) Once the image has been created, it has to be saved. However, at this point all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) devices are frozen and they cannot handle I/O, while their ability to handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) I/O is obviously necessary for the image saving. Thus they have to be brought
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) back to the fully functional state and this is done in the following phases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) thaw_noirq, thaw, complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) using the following PCI bus type's callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) pci_pm_thaw_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) pci_pm_thaw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) pci_pm_complete()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) The first of them, pci_pm_thaw_noirq(), is analogous to pci_pm_resume_noirq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) It puts the device into the full power state and restores its standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) configuration registers. It also executes the device driver's pm->thaw_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) callback, if defined, instead of pm->resume_noirq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) The pci_pm_thaw() routine is similar to pci_pm_resume(), but it runs the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) driver's pm->thaw() callback instead of pm->resume(). It is executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) asynchronously for different PCI devices that don't depend on each other in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) known way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) The complete phase is the same as for system resume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) After saving the image, devices need to be powered down before the system can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) enter the target sleep state (ACPI S4 for ACPI-based systems). This is done in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) three phases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) prepare, poweroff, poweroff_noirq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) where the prepare phase is exactly the same as for system suspend. The other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) two phases are analogous to the suspend and suspend_noirq phases, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) The PCI subsystem-level callbacks they correspond to::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) pci_pm_poweroff()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) pci_pm_poweroff_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) work in analogy with pci_pm_suspend() and pci_pm_poweroff_noirq(), respectively,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) although they don't attempt to save the device's standard configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) 2.4.4. System Restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) ^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) System restore requires a hibernation image to be loaded into memory and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) pre-hibernation memory contents to be restored before the pre-hibernation system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) activity can be resumed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) As described in Documentation/driver-api/pm/devices.rst, the hibernation image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) is loaded into memory by a fresh instance of the kernel, called the boot kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) which in turn is loaded and run by a boot loader in the usual way. After the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) boot kernel has loaded the image, it needs to replace its own code and data with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) the code and data of the "hibernated" kernel stored within the image, called the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) image kernel. For this purpose all devices are frozen just like before creating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) the image during hibernation, in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) prepare, freeze, freeze_noirq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) phases described above. However, the devices affected by these phases are only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) those having drivers in the boot kernel; other devices will still be in whatever
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) state the boot loader left them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) Should the restoration of the pre-hibernation memory contents fail, the boot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) kernel would go through the "thawing" procedure described above, using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) thaw_noirq, thaw, and complete phases (that will only affect the devices having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) drivers in the boot kernel), and then continue running normally.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) If the pre-hibernation memory contents are restored successfully, which is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) usual situation, control is passed to the image kernel, which then becomes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) responsible for bringing the system back to the working state. To achieve this,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) it must restore the devices' pre-hibernation functionality, which is done much
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) like waking up from the memory sleep state, although it involves different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) phases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) restore_noirq, restore, complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) The first two of these are analogous to the resume_noirq and resume phases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) described above, respectively, and correspond to the following PCI subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) callbacks::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) pci_pm_restore_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) pci_pm_restore()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) These callbacks work in analogy with pci_pm_resume_noirq() and pci_pm_resume(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) respectively, but they execute the device driver's pm->restore_noirq() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) pm->restore() callbacks, if available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) The complete phase is carried out in exactly the same way as during system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) resume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) 3. PCI Device Drivers and Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) 3.1. Power Management Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) PCI device drivers participate in power management by providing callbacks to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) executed by the PCI subsystem's power management routines described above and by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) controlling the runtime power management of their devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) At the time of this writing there are two ways to define power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) callbacks for a PCI device driver, the recommended one, based on using a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) the "legacy" one, in which the .suspend() and .resume() callbacks from struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) pci_driver are used. The legacy approach, however, doesn't allow one to define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) runtime power management callbacks and is not really suitable for any new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) drivers. Therefore it is not covered by this document (refer to the source code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) to learn more about it).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) It is recommended that all PCI device drivers define a struct dev_pm_ops object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) containing pointers to power management (PM) callbacks that will be executed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) the PCI subsystem's PM routines in various circumstances. A pointer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) driver's struct dev_pm_ops object has to be assigned to the driver.pm field in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) its struct pci_driver object. Once that has happened, the "legacy" PM callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) in struct pci_driver are ignored (even if they are not NULL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) The PM callbacks in struct dev_pm_ops are not mandatory and if they are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) defined (i.e. the respective fields of struct dev_pm_ops are unset) the PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) subsystem will handle the device in a simplified default manner. If they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) defined, though, they are expected to behave as described in the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) subsections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) 3.1.1. prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) ^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) The prepare() callback is executed during system suspend, during hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) (when a hibernation image is about to be created), during power-off after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719) saving a hibernation image and during system restore, when a hibernation image
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) has just been loaded into memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) This callback is only necessary if the driver's device has children that in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) general may be registered at any time. In that case the role of the prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) callback is to prevent new children of the device from being registered until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) one of the resume_noirq(), thaw_noirq(), or restore_noirq() callbacks is run.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) In addition to that the prepare() callback may carry out some operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) preparing the device to be suspended, although it should not allocate memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) (if additional memory is required to suspend the device, it has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) preallocated earlier, for example in a suspend/hibernate notifier as described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) in Documentation/driver-api/pm/notifiers.rst).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) 3.1.2. suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) ^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) The suspend() callback is only executed during system suspend, after prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) callbacks have been executed for all devices in the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) This callback is expected to quiesce the device and prepare it to be put into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) low-power state by the PCI subsystem. It is not required (in fact it even is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) not recommended) that a PCI driver's suspend() callback save the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) configuration registers of the device, prepare it for waking up the system, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) put it into a low-power state. All of these operations can very well be taken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) care of by the PCI subsystem, without the driver's participation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) However, in some rare case it is convenient to carry out these operations in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) a PCI driver. Then, pci_save_state(), pci_prepare_to_sleep(), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) pci_set_power_state() should be used to save the device's standard configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) registers, to prepare it for system wakeup (if necessary), and to put it into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) low-power state, respectively. Moreover, if the driver calls pci_save_state(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) the PCI subsystem will not execute either pci_prepare_to_sleep(), or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) pci_set_power_state() for its device, so the driver is then responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) handling the device as appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) While the suspend() callback is being executed, the driver's interrupt handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) can be invoked to handle an interrupt from the device, so all suspend-related
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) operations relying on the driver's ability to handle interrupts should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) carried out in this callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) 3.1.3. suspend_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) ^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) The suspend_noirq() callback is only executed during system suspend, after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) suspend() callbacks have been executed for all devices in the system and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) after device interrupts have been disabled by the PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) The difference between suspend_noirq() and suspend() is that the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) interrupt handler will not be invoked while suspend_noirq() is running. Thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) suspend_noirq() can carry out operations that would cause race conditions to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) arise if they were performed in suspend().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) 3.1.4. freeze()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) ^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) The freeze() callback is hibernation-specific and is executed in two situations,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) during hibernation, after prepare() callbacks have been executed for all devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) in preparation for the creation of a system image, and during restore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) after a system image has been loaded into memory from persistent storage and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) prepare() callbacks have been executed for all devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) The role of this callback is analogous to the role of the suspend() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) described above. In fact, they only need to be different in the rare cases when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) the driver takes the responsibility for putting the device into a low-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) In that cases the freeze() callback should not prepare the device system wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) or put it into a low-power state. Still, either it or freeze_noirq() should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) save the device's standard configuration registers using pci_save_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) 3.1.5. freeze_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) ^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) The freeze_noirq() callback is hibernation-specific. It is executed during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) hibernation, after prepare() and freeze() callbacks have been executed for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) devices in preparation for the creation of a system image, and during restore,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) after a system image has been loaded into memory and after prepare() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) freeze() callbacks have been executed for all devices. It is always executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) after device interrupts have been disabled by the PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) The role of this callback is analogous to the role of the suspend_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) callback described above and it very rarely is necessary to define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) freeze_noirq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) The difference between freeze_noirq() and freeze() is analogous to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) difference between suspend_noirq() and suspend().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) 3.1.6. poweroff()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) ^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) The poweroff() callback is hibernation-specific. It is executed when the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) is about to be powered off after saving a hibernation image to a persistent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) storage. prepare() callbacks are executed for all devices before poweroff() is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) The role of this callback is analogous to the role of the suspend() and freeze()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) callbacks described above, although it does not need to save the contents of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) the device's registers. In particular, if the driver wants to put the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) into a low-power state itself instead of allowing the PCI subsystem to do that,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) the poweroff() callback should use pci_prepare_to_sleep() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) pci_set_power_state() to prepare the device for system wakeup and to put it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) into a low-power state, respectively, but it need not save the device's standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) configuration registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) 3.1.7. poweroff_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) ^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) The poweroff_noirq() callback is hibernation-specific. It is executed after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) poweroff() callbacks have been executed for all devices in the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) The role of this callback is analogous to the role of the suspend_noirq() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) freeze_noirq() callbacks described above, but it does not need to save the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) contents of the device's registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) The difference between poweroff_noirq() and poweroff() is analogous to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) difference between suspend_noirq() and suspend().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) 3.1.8. resume_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) ^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) The resume_noirq() callback is only executed during system resume, after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) PM core has enabled the non-boot CPUs. The driver's interrupt handler will not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) be invoked while resume_noirq() is running, so this callback can carry out
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) operations that might race with the interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) Since the PCI subsystem unconditionally puts all devices into the full power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) state in the resume_noirq phase of system resume and restores their standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) configuration registers, resume_noirq() is usually not necessary. In general
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) it should only be used for performing operations that would lead to race
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) conditions if carried out by resume().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) 3.1.9. resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) ^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) The resume() callback is only executed during system resume, after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) resume_noirq() callbacks have been executed for all devices in the system and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) device interrupts have been enabled by the PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) This callback is responsible for restoring the pre-suspend configuration of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) device and bringing it back to the fully functional state. The device should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) able to process I/O in a usual way after resume() has returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) 3.1.10. thaw_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) ^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) The thaw_noirq() callback is hibernation-specific. It is executed after a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) system image has been created and the non-boot CPUs have been enabled by the PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) core, in the thaw_noirq phase of hibernation. It also may be executed if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) loading of a hibernation image fails during system restore (it is then executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) after enabling the non-boot CPUs). The driver's interrupt handler will not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) invoked while thaw_noirq() is running.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) The role of this callback is analogous to the role of resume_noirq(). The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) difference between these two callbacks is that thaw_noirq() is executed after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) freeze() and freeze_noirq(), so in general it does not need to modify the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) contents of the device's registers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) 3.1.11. thaw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) ^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) The thaw() callback is hibernation-specific. It is executed after thaw_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) callbacks have been executed for all devices in the system and after device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) interrupts have been enabled by the PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) This callback is responsible for restoring the pre-freeze configuration of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) the device, so that it will work in a usual way after thaw() has returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) 3.1.12. restore_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) ^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) The restore_noirq() callback is hibernation-specific. It is executed in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) restore_noirq phase of hibernation, when the boot kernel has passed control to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) the image kernel and the non-boot CPUs have been enabled by the image kernel's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) This callback is analogous to resume_noirq() with the exception that it cannot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) make any assumption on the previous state of the device, even if the BIOS (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) generally the platform firmware) is known to preserve that state over a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) suspend-resume cycle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) For the vast majority of PCI device drivers there is no difference between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) resume_noirq() and restore_noirq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) 3.1.13. restore()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904) ^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) The restore() callback is hibernation-specific. It is executed after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) restore_noirq() callbacks have been executed for all devices in the system and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) after the PM core has enabled device drivers' interrupt handlers to be invoked.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) This callback is analogous to resume(), just like restore_noirq() is analogous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) to resume_noirq(). Consequently, the difference between restore_noirq() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) restore() is analogous to the difference between resume_noirq() and resume().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) For the vast majority of PCI device drivers there is no difference between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) resume() and restore().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) 3.1.14. complete()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) ^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) The complete() callback is executed in the following situations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) - during system resume, after resume() callbacks have been executed for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924) - during hibernation, before saving the system image, after thaw() callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) have been executed for all devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) - during system restore, when the system is going back to its pre-hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) state, after restore() callbacks have been executed for all devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) It also may be executed if the loading of a hibernation image into memory fails
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) (in that case it is run after thaw() callbacks have been executed for all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) devices that have drivers in the boot kernel).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) This callback is entirely optional, although it may be necessary if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934) prepare() callback performs operations that need to be reversed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) 3.1.15. runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) ^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) The runtime_suspend() callback is specific to device runtime power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) (runtime PM). It is executed by the PM core's runtime PM framework when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) device is about to be suspended (i.e. quiesced and put into a low-power state)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) at run time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) This callback is responsible for freezing the device and preparing it to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) put into a low-power state, but it must allow the PCI subsystem to perform all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) of the PCI-specific actions necessary for suspending the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) 3.1.16. runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) ^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) The runtime_resume() callback is specific to device runtime PM. It is executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) by the PM core's runtime PM framework when the device is about to be resumed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) (i.e. put into the full-power state and programmed to process I/O normally) at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954) run time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) This callback is responsible for restoring the normal functionality of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) device after it has been put into the full-power state by the PCI subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958) The device is expected to be able to process I/O in the usual way after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) runtime_resume() has returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) 3.1.17. runtime_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) ^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) The runtime_idle() callback is specific to device runtime PM. It is executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) by the PM core's runtime PM framework whenever it may be desirable to suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) the device according to the PM core's information. In particular, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967) automatically executed right after runtime_resume() has returned in case the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) resume of the device has happened as a result of a spurious event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) This callback is optional, but if it is not implemented or if it returns 0, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971) PCI subsystem will call pm_runtime_suspend() for the device, which in turn will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972) cause the driver's runtime_suspend() callback to be executed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) 3.1.18. Pointing Multiple Callback Pointers to One Routine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977) Although in principle each of the callbacks described in the previous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) subsections can be defined as a separate function, it often is convenient to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) point two or more members of struct dev_pm_ops to the same routine. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) a few convenience macros that can be used for this purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982) The SIMPLE_DEV_PM_OPS macro declares a struct dev_pm_ops object with one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) suspend routine pointed to by the .suspend(), .freeze(), and .poweroff()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) members and one resume routine pointed to by the .resume(), .thaw(), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985) .restore() members. The other function pointers in this struct dev_pm_ops are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) unset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) The UNIVERSAL_DEV_PM_OPS macro is similar to SIMPLE_DEV_PM_OPS, but it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) additionally sets the .runtime_resume() pointer to the same value as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990) .resume() (and .thaw(), and .restore()) and the .runtime_suspend() pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) the same value as .suspend() (and .freeze() and .poweroff()).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) The SET_SYSTEM_SLEEP_PM_OPS can be used inside of a declaration of struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994) dev_pm_ops to indicate that one suspend routine is to be pointed to by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) .suspend(), .freeze(), and .poweroff() members and one resume routine is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) be pointed to by the .resume(), .thaw(), and .restore() members.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) 3.1.19. Driver Flags for Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001) The PM core allows device drivers to set flags that influence the handling of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) power management for the devices by the core itself and by middle layer code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003) including the PCI bus type. The flags should be set once at the driver probe
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) time with the help of the dev_pm_set_driver_flags() function and they should not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005) be updated directly afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) The DPM_FLAG_NO_DIRECT_COMPLETE flag prevents the PM core from using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) direct-complete mechanism allowing device suspend/resume callbacks to be skipped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) if the device is in runtime suspend when the system suspend starts. That also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) affects all of the ancestors of the device, so this flag should only be used if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011) absolutely necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013) The DPM_FLAG_SMART_PREPARE flag causes the PCI bus type to return a positive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) value from pci_pm_prepare() only if the ->prepare callback provided by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015) driver of the device returns a positive value. That allows the driver to opt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) out from using the direct-complete mechanism dynamically (whereas setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) DPM_FLAG_NO_DIRECT_COMPLETE means permanent opt-out).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) The DPM_FLAG_SMART_SUSPEND flag tells the PCI bus type that from the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020) perspective the device can be safely left in runtime suspend during system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) suspend. That causes pci_pm_suspend(), pci_pm_freeze() and pci_pm_poweroff()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022) to avoid resuming the device from runtime suspend unless there are PCI-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) reasons for doing that. Also, it causes pci_pm_suspend_late/noirq() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024) pci_pm_poweroff_late/noirq() to return early if the device remains in runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) suspend during the "late" phase of the system-wide transition under way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) Moreover, if the device is in runtime suspend in pci_pm_resume_noirq() or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) pci_pm_restore_noirq(), its runtime PM status will be changed to "active" (as it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) is going to be put into D0 going forward).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030) Setting the DPM_FLAG_MAY_SKIP_RESUME flag means that the driver allows its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) "noirq" and "early" resume callbacks to be skipped if the device can be left
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) in suspend after a system-wide transition into the working state. This flag is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033) taken into consideration by the PM core along with the power.may_skip_resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) status bit of the device which is set by pci_pm_suspend_noirq() in certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) situations. If the PM core determines that the driver's "noirq" and "early"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) resume callbacks should be skipped, the dev_pm_skip_resume() helper function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037) will return "true" and that will cause pci_pm_resume_noirq() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) pci_pm_resume_early() to return upfront without touching the device and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) executing the driver callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041) 3.2. Device Runtime Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) In addition to providing device power management callbacks PCI device drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) are responsible for controlling the runtime power management (runtime PM) of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) their devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) The PCI device runtime PM is optional, but it is recommended that PCI device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049) drivers implement it at least in the cases where there is a reliable way of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050) verifying that the device is not used (like when the network cable is detached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051) from an Ethernet adapter or there are no devices attached to a USB controller).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053) To support the PCI runtime PM the driver first needs to implement the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) runtime_suspend() and runtime_resume() callbacks. It also may need to implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055) the runtime_idle() callback to prevent the device from being suspended again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056) every time right after the runtime_resume() callback has returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057) (alternatively, the runtime_suspend() callback will have to check if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) device should really be suspended and return -EAGAIN if that is not the case).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060) The runtime PM of PCI devices is enabled by default by the PCI core. PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) device drivers do not need to enable it and should not attempt to do so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062) However, it is blocked by pci_pm_init() that runs the pm_runtime_forbid()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063) helper function. In addition to that, the runtime PM usage counter of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064) each PCI device is incremented by local_pci_probe() before executing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) probe callback provided by the device's driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) If a PCI driver implements the runtime PM callbacks and intends to use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068) runtime PM framework provided by the PM core and the PCI subsystem, it needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069) to decrement the device's runtime PM usage counter in its probe callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) function. If it doesn't do that, the counter will always be different from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) zero for the device and it will never be runtime-suspended. The simplest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072) way to do that is by calling pm_runtime_put_noidle(), but if the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073) wants to schedule an autosuspend right away, for example, it may call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) pm_runtime_put_autosuspend() instead for this purpose. Generally, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) just needs to call a function that decrements the devices usage counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076) from its probe routine to make runtime PM work for the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) It is important to remember that the driver's runtime_suspend() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079) may be executed right after the usage counter has been decremented, because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) user space may already have caused the pm_runtime_allow() helper function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081) unblocking the runtime PM of the device to run via sysfs, so the driver must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082) be prepared to cope with that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084) The driver itself should not call pm_runtime_allow(), though. Instead, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) should let user space or some platform-specific code do that (user space can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086) do it via sysfs as stated above), but it must be prepared to handle the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087) runtime PM of the device correctly as soon as pm_runtime_allow() is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088) (which may happen at any time, even before the driver is loaded).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090) When the driver's remove callback runs, it has to balance the decrementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091) of the device's runtime PM usage counter at the probe time. For this reason,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092) if it has decremented the counter in its probe callback, it must run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) pm_runtime_get_noresume() in its remove callback. [Since the core carries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094) out a runtime resume of the device and bumps up the device's usage counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095) before running the driver's remove callback, the runtime PM of the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) is effectively disabled for the duration of the remove execution and all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) runtime PM helper functions incrementing the device's usage counter are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098) then effectively equivalent to pm_runtime_get_noresume().]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) The runtime PM framework works by processing requests to suspend or resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101) devices, or to check if they are idle (in which cases it is reasonable to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) subsequently request that they be suspended). These requests are represented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103) by work items put into the power management workqueue, pm_wq. Although there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104) are a few situations in which power management requests are automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105) queued by the PM core (for example, after processing a request to resume a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) device the PM core automatically queues a request to check if the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) idle), device drivers are generally responsible for queuing power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108) requests for their devices. For this purpose they should use the runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) helper functions provided by the PM core, discussed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110) Documentation/power/runtime_pm.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112) Devices can also be suspended and resumed synchronously, without placing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113) request into pm_wq. In the majority of cases this also is done by their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114) drivers that use helper functions provided by the PM core for this purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116) For more information on the runtime PM of devices refer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117) Documentation/power/runtime_pm.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120) 4. Resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123) PCI Local Bus Specification, Rev. 3.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125) PCI Bus Power Management Interface Specification, Rev. 1.2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129) PCI Express Base Specification, Rev. 2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) Documentation/driver-api/pm/devices.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133) Documentation/power/runtime_pm.rst
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags