rk3399_ARM-atf/docs/porting-guide.rst

152    Defines the total number of nodes in the power domain topology
153    tree at all the power domain levels used by the platform.
155    data structures to represent power domain topology.
159    Defines the maximum power domain level that the power management operations
160    should apply to. More often, but not always, the power domain level
162    to know the highest power domain level that it should consider for power
165    number of CPUs and it reports the maximum power domain level as 1.
169    Defines the local power state corresponding to the deepest power down
170    possible at every power domain level in the platform. The local power
173    value to initialize the local power states of the power domain nodes and
174    to specify the requested power state for a PSCI_CPU_OFF call.
178    Defines the local power state corresponding to the deepest retention state
179    possible at every power domain level in the platform. This macro should be
181    PSCI implementation to distinguish between retention and power down local
182    power states within PSCI_CPU_SUSPEND call.
186    Defines the maximum number of local power states per power domain level
188    most platforms just support a maximum of two local power states at each
189    power domain level (power-down and retention). If the platform needs to
190    account for more local power states, then it must redefine this macro.
542 ``PSCI_OS_INIT_MODE`` is enabled, and if the platform's maximum power domain
548    Defines the maximum power domain level that PSCI_CPU_SUSPEND should apply to.
1113 This function plays a crucial role in the power domain topology framework in
1128 be invoked by BL31 after the power domain topology is initialized and can
1130 represents the power domain topology and how this relates to the linear CPU
1352 present) during a cluster power down sequence. The default weak implementation
1353 doesn't do anything. Since this API is called during the power down sequence,
2281 -  Initialize the power controller device.
2284    power controller device.
2886 *power domain*. A *power domain* is a CPU or a logical group of CPUs which
2887 share some state on which power management operations can be performed as
2890 *power domains* are arranged in a hierarchical tree structure and each
2891 *power domain* can be identified in a system by the cpu index of any CPU that
2892 is part of that domain and a *power domain level*. A processing element (for
2893 example, a CPU) is at level 0. If the *power domain* node above a CPU is a
2896 example, the system). More details on the power domain topology and its
2900 power management operations required for the PSCI implementation to function
2903 power management operations on the power domains. For example, the target
2905 handler (if present) is called for the CPU power domain.
2907 The ``power-state`` parameter of a PSCI ``CPU_SUSPEND`` call can be used to
2908 describe composite power states specific to a platform. The PSCI implementation
2909 defines a generic representation of the power-state parameter, which is an
2910 array of local power states where each index corresponds to a power domain
2911 level. Each entry contains the local power state the power domain at that power
2913 convert the power-state parameter (possibly encoding a composite power state)
2927 accounting before entering a low power state. The ``pwr_domain_state`` field of
2930 index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
2945 accounting after exiting from a low power state. The ``pwr_domain_state`` field
2948 index 0 (CPU power level) in the ``pwr_domain_state`` array indicates a power down
2962 This is an optional interface that is is invoked after resuming from a low power
2963 state and provides the time spent resident in that low power state by the power
2964 domain at a particular power domain level. When a CPU wakes up from suspend,
2965 all its parent power domain levels are also woken up. The generic PSCI code
2966 invokes this function for each parent power domain that is resumed and it
2968 argument) describes the low power state that the power domain has resumed from.
2969 The current CPU is the first CPU in the power domain to resume from the low
2970 power state and the ``last_cpu_idx`` (third parameter) is the index of the last
2971 CPU in the power domain to suspend and may be needed to calculate the residency
2972 for that power domain.
2983 state coordination during a power management operation. The function is passed
2984 a pointer to an array of platform specific local power state ``states`` (second
2985 argument) which contains the requested power state for each CPU at a particular
2986 power domain level ``lvl`` (first argument) within the power domain. The function
2988 a coordinated target power state by the comparing all the requested power
2989 states. The target power state should not be deeper than any of the requested
2990 power states.
2994 of the power state i.e. for two power states X & Y, if X < Y
2995 then X represents a shallower power state than Y. As a result, the
2996 coordinated target local power state for a power domain will be the minimum
2997 of the requested local power state values.
3007 This function returns a pointer to the byte array containing the power domain
3011 statically or dynamically, to initialize the power domain topology tree. In case
3032 platform-specific psci power management actions by populating the passed
3051 the suspend state type specified in the ``power-state`` parameter should be
3052 STANDBY and the target power domain level specified should be the CPU. The
3053 handler should put the CPU into a low power retention state (usually by
3060 Perform the platform specific actions to power on a CPU, specified
3068 powering off the calling CPU and its higher parent power domain levels as
3071 The ``target_state`` encodes the platform coordinated target local power states
3072 for the CPU power domain and its parent power domain levels.
3074 For this handler, the local power state for the CPU power domain will be a
3075 power down state where as it could be either power down, retention or run state
3076 for the higher power domain levels depending on the result of state
3083 Perform the platform specific actions to prepare to power off the calling CPU
3084 and its higher parent power domain levels as indicated by the ``target_state``
3087 The ``target_state`` encodes the platform coordinated target local power states
3088 for the CPU power domain and its parent power domain levels. The handler
3089 needs to perform power management operation corresponding to the local state
3090 at each power level.
3092 For this handler, the local power state for the CPU power domain will be a
3093 power down state where as it could be either power down, retention or run state
3094 for the higher power domain levels depending on the result of state
3114 calls this function when suspending to a power down state, and it guarantees
3119 power down state and it is safe to perform some or all of the platform
3129 CPU and its higher parent power domain levels as indicated by the
3135 target local power states for the CPU power domain and its parent
3136 power domain levels. The handler needs to perform power management operation
3137 corresponding to the local state at each power level. The generic code
3140 The difference between turning a power domain off versus suspending it is that
3141 in the former case, the power domain is expected to re-initialize its state
3143 case, the power domain is expected to save enough state so that it can resume
3147 When suspending a core, the platform can also choose to power off the GICv3
3176 operation and it encodes the platform coordinated target local power states for
3177 the CPU power domain and its parent power domain levels.
3198 The ``target_state`` (first argument) is the prior state of the power domains
3199 immediately before the CPU was turned on. It indicates which power domains
3201 low power states. The generic code expects the handler to succeed.
3255 populate it in ``req_state`` (second argument) array as power domain level
3273 call to get the ``req_state`` parameter from platform which encodes the power
3286 supports more than two local power states at each power domain level, that is
3288 local power states.
3294 (second argument) parameter of the PSCI API corresponding to a target power
3295 domain. The target power domain is identified by using both ``MPIDR`` (first
3296 argument) and the power domain level encoded in ``power_state``. The power domain
3301 targeted power domain. If the ``power_state`` is invalid for the targeted power
3307 power state encoding for ``power_state`` parameter of PSCI_STAT_COUNT/RESIDENCY
3314 the power state of a node (identified by the first parameter, the ``MPIDR``) in
3315 the power domain topology (identified by the second parameter, ``power_level``),
3316 as retrieved from a power controller or equivalent component on the platform.
3366 Secure payload power management callback
3369 During PSCI power management operations, the EL3 Runtime Software may
3375 Typical bookkeeping during PSCI power management calls include save/restore
3378 appropriately during CPU power down/power up. Any secure interrupt targeted
3380 to power down of the current CPU. During power up, these interrupt can be
3408    The ``svc_suspend`` callback is called during power down bu either
3412    (first parameter) denotes the highest power domain level being powered down
3783 these functions should be able to handle being called with power domains off and
3786 (and their power off counterparts).