Lines Matching refs:the

16 three requirements that the PSCI 1.0 specification introduced :
18 -  Removing the framework assumption about the structure of the MPIDR, and
19    its relation to the power topology enables support for deeper and more
22 -  Reworking the power state coordination implementation in the framework
23    to support the more detailed PSCI 1.0 requirements and reduce platform
26 -  Enable the use of the extended power\_state parameter and the larger StateID
29 The PSCI 1.0 implementation introduces new frameworks to fulfill the above
30 requirements. These framework changes mean that the platform porting API must
31 also be modified. This document is a guide to assist migration of the existing
32 platform ports to the new platform API.
34 This document describes the new platform API and compares it with the
35 deprecated API. It also describes the compatibility layer that enables the
36 existing platform ports to work with the PSCI 1.0 implementation. The
42 This section describes changes to the platform APIs.
47 This removes the assumption in the PSCI implementation that MPIDR
60 and are meant to replace the existing ``platform_get_core_pos()`` API.
61 The description of these APIs can be found in the `Porting Guide`_.
62 These are used by the power domain topology framework such that:
64 #. The generic PSCI code does not generate MPIDRs or use them to query the
65    platform about the number of power domains at a particular power level. The
66    ``plat_get_power_domain_tree_desc()`` provides a description of the power
67    domain tree on the SoC through a pointer to the byte array containing the
72    the power domain tree. These core indices are unique for a core and it is a
75    a dynamic mapping, choosing to skip the unavailable/unused cores to compact
76    the core indices.
78 In addition, the platforms must define the macros ``PLAT_NUM_PWR_DOMAINS`` and
79 ``PLAT_MAX_PWR_LVL`` which replace the macros ``PLAT_NUM_AFFS`` and
80 ``PLATFORM_MAX_AFFLVL`` respectively. On platforms where the affinity instances
81 correspond to power domains, the values of new macros remain the same as the
84 More details on the power domain topology description and its platform
90 The state-ID field in the power-state parameter of a CPU\_SUSPEND call can be
91 used to describe the composite power states specific to a platform. The existing
92 PSCI state coordination had the limitation that it operates on a run/off
93 granularity of power states and it did not interpret the state-ID field. This
94 was acceptable as the specification requirement in PSCI 0.2 and the framework's
96 count of the number of cores that have requested the cluster to remain powered.
98 In the PSCI 1.0 specification, this approach is non optimal. If composite
99 power states are used, the PSCI implementation cannot make global
100 decisions about state coordination required because it does not understand the
103 The PSCI 1.0 implementation now defines a generic representation of the
113 Each entry in the array contains the local power state the power domain at
114 that power level could enter. The meaning of the local power state value is
116 implementation constraints the values only so that it can classify the state
117 as RUN, RETENTION or OFF as required by the specification:
124 The platform is required to define the macros ``PLAT_MAX_RET_STATE`` and
125 ``PLAT_MAX_OFF_STATE`` to the framework. The requirement for these macros can
126 be found in the `Porting Guide <porting-guide.rst>`__.
128 The PSCI 1.0 implementation adds support to involve the platform in state
129 coordination. This enables the platform to decide the final target state.
130 During a request to place a power domain in a low power state, the platform
132 each core within it through the ``plat_get_target_pwr_state()`` API. This API
135 this API is provided in the platform layer which returns the minimum of the
136 requested local states back to the PSCI state coordination. More details
137 of ``plat_get_target_pwr_state()`` API can be found in the
140 The PSCI Generic implementation expects platform ports to populate the handlers
141 for the ``plat_psci_ops`` structure which is declared as :
174 The description of these handlers can be found in the `Porting Guide <porting-guide.rst#user-conten…
175 The previous ``plat_pm_ops`` structure is deprecated. Compared with the previous
176 handlers, the major differences are:
180 The PSCI 1.0 implementation depends on the ``validate_power_state`` handler to
181 convert the power-state parameter (possibly encoding a composite power state)
182 passed in a PSCI ``CPU_SUSPEND`` to the ``psci_power_state`` format. This handler
186 and ``pwr_domain_suspend``, are passed the target local state for each affected
189 are passed the local states of the affected power domains before wakeup. The
195 Whereas the power management handlers in ``plat_pm_ops`` used to be invoked
196 for each affinity level till the target affinity level, the new handlers
197 are only invoked once. The ``target_state`` encodes the target low power
198 state or the low power state woken up from for each affected power domain.
202 Although the previous ``suspend`` handlers could be used for power down as well
203 as retention at different affinity levels, the new handlers make this support
205 retention at various power domain levels subject to the conditions mentioned
208 Unlike the previous ``standby`` handler, the ``cpu_standby()`` handler is only used
212 The below diagram shows the sequence of a PSCI SUSPEND call and the interaction
213 with the platform layer depicting the exchange of data between PSCI Generic
214 layer and the platform layer.
218 Refer `plat/arm/board/fvp/fvp\_pm.c`_ for the implementation details of
219 these handlers for the FVP. The commit `38dce70f51fb83b27958ba3e2ad15f5635cb1061`_
220 demonstrates the migration of ARM reference platforms to the new platform API.
225 In addition to the framework changes, unification of warm reset entry points on
226 wakeup from low power modes has led to a change in the platform API. In the
227 earlier implementation, the warm reset entry used to be programmed into the
228 mailboxes by the 'ON' and 'SUSPEND' power management hooks. In the PSCI 1.0
230 out by querying affinity info state whether to execute the 'suspend\_finisher\`
233 As a result, the warm reset entry point must be programmed only once. The
234 ``plat_setup_psci_ops()`` API takes the secure entry point as an
235 additional parameter to enable the platforms to configure their mailbox. The
237 the warm reset entry point as a parameter.
240 invoked to perform actions specific to the caller core which makes the argument
241 redundant. Therefore the platform APIs ``plat_get_my_entrypoint()``,
244 operations on the current caller core instead of ``platform_get_entrypoint()``,
250 To ease the migration of the platform ports to the new porting interface,
252 between the old platform API and the new API. The build flag
254 layer or not. A platform port which has migrated to the new API can disable
255 this flag within the platform specific makefile.
257 The compatibility layer works on the assumption that the onus of
259 is with the platform. The generic PSCI implementation only takes into
260 account whether the suspend request is power down or not. This corresponds
261 with the behavior of the PSCI implementation before the introduction of
262 new frameworks. Also, it assumes that the affinity levels of the platform
263 correspond directly to the power domain levels.
265 The compatibility layer dynamically constructs the new topology
266 description array by querying the platform using ``plat_get_aff_count()``
268 ``platform_get_core_pos()`` is used as the core index for the cores. The
269 higher level (non-core) power domain nodes must know the cores contained
270 within its domain. It does so by storing the core index of first core
273 power domain must be consecutive. We expect that this is the case for most
279 implemented for the compatibility layer. This allows the existing
280 platform ports to work with the new PSCI frameworks without significant
286 This section documents the deprecated platform porting API.
291 The mandatory macros to be defined by the platform port in ``platform_def.h``
295    Defines the total number of nodes in the affinity hierarchy at all affinity
296    levels used by the platform.
300    Defines the maximum affinity level that the power management operations
302    that hardware will implement fewer affinity levels. This macro allows the
303    PSCI implementation to consider only those affinity levels in the system
304    that the platform implements. For example, the Base AEM FVP implements two
305    clusters with a configurable number of cores. It reports the maximum
306    affinity level as 1, resulting in PSCI power control up to the cluster
309 The following functions must be implemented by the platform port to enable
310 the reset vector code to perform the required tasks.
320 This function is called with the ``SCTLR.M`` and ``SCTLR.C`` bits disabled. The core
321 is identified by its ``MPIDR``, which is passed as the argument. The function is
323 specific means. If it is a warm reset, it returns the entrypoint into the
324 BL31 image that the core must jump to. If it is a cold reset, this function
328 to handle the condition where the core has been warm reset but there is no
331 This function does not follow the Procedure Call Standard used by the
332 Application Binary Interface for the ARM 64-bit architecture. The caller should
344 This function identifies a core by its ``MPIDR``, which is passed as the argument,
345 to determine whether this core is the primary core or a secondary core. A return
346 value of zero indicates that the core is not the primary core, while a non-zero
347 return value indicates that the core is the primary core.
360 A platform may need to convert the ``MPIDR`` of a core to an absolute number, which
363 to perform this conversion, using the assumption that each cluster contains a
381 This function sets the current stack pointer to the normal memory stack that
382 has been allocated for the core specified by MPIDR. For BL images that only
383 require a stack for the primary core the parameter is ignored. The size of
384 the stack allocated to each core is specified by the platform defined constant
387 Common implementations of this function for the UP and MP BL images are
399 This function returns the base address of the normal memory stack that
400 has been allocated for the core specificed by MPIDR. For BL images that only
401 require a stack for the primary core the parameter is ignored. The size of
402 the stack allocated to each core is specified by the platform defined constant
405 Common implementations of this function for the UP and MP BL images are
413 the ARM Trusted Firmware.
423 This function may execute with the MMU and data caches enabled if the platform
424 port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
425 called by the primary core.
427 This function is called by the PSCI initialization code to detect the system
428 topology. Its purpose is to return the number of affinity instances implemented
429 at a given ``affinity level`` (specified by the first argument) and a given
430 ``MPIDR`` (specified by the second argument). For example, on a dual-cluster
431 system where first cluster implements two cores and the second cluster
433 to the first cluster (``0x0``) and affinity level 0, would return 2. A call
434 to this function with an ``MPIDR`` corresponding to the second cluster (``0x100``)
445 This function may execute with the MMU and data caches enabled if the platform
446 port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
447 called by the primary core.
449 This function is called by the PSCI initialization code. Its purpose is to
450 return the state of an affinity instance. The affinity instance is determined by
451 the affinity ID at a given ``affinity level`` (specified by the first argument)
452 and an ``MPIDR`` (specified by the second argument). The state can be one of
456 another core implemented directly on the interconnect with the cluster. The
457 ``MPIDR``\ s of the cluster would range from ``0x0-0x3``. The ``MPIDR`` of the single
459 is missing but needs to be accounted for to reach this single core in the
470 This function may execute with the MMU and data caches enabled if the platform
471 port does the necessary initializations in ``bl31_plat_arch_setup()``. It is only
472 called by the primary core.
476 the passed pointer with a pointer to the private ``plat_pm_ops`` structure of
480 is expected to implement these handlers if the corresponding PSCI operation
481 is to be supported and these handlers are expected to succeed if the return
487 Perform the platform-specific setup to enter the standby state indicated by the
488 passed argument. The generic code expects the handler to succeed.
493 Perform the platform specific setup to power on an affinity instance, specified
494 by the ``MPIDR`` (first argument) and ``affinity level`` (third argument). The
495 ``state`` (fourth argument) contains the current state of that affinity instance
497 example, while powering on a core, the cluster that contains this core might
498 already be in the ON state. The platform decides what actions must be taken to
499 transition from the current state to the target state (indicated by the power
500 management operation). The generic code expects the platform to return
506 Perform the platform specific setup to power off an affinity instance of the
507 calling core. It is called by the PSCI ``CPU_OFF`` API implementation.
510 a similar meaning as described in the ``affinst_on()`` operation. They
511 identify the affinity instance on which the call is made and its
512 current state. This gives the platform port an indication of the
513 state transition it must make to perform the requested action. For example, if
514 the calling core is the last powered on core in the cluster, after powering down
515 affinity level 0 (the core), the platform port should power down affinity
516 level 1 (the cluster) as well. The generic code expects the handler to succeed.
521 Perform the platform specific setup to power off an affinity instance of the
522 calling core. It is called by the PSCI ``CPU_SUSPEND`` API and ``SYSTEM_SUSPEND``
526 similar meaning as described in the ``affinst_on()`` operation. They are used to
527 identify the affinity instance on which the call is made and its current state.
528 This gives the platform port an indication of the state transition it must
529 make to perform the requested action. For example, if the calling core is the
530 last powered on core in the cluster, after powering down affinity level 0
531 (the core), the platform port should power down affinity level 1 (the cluster)
535 is that in the former case, the affinity instance is expected to re-initialize
536 its state when it is next powered on (see ``affinst_on_finish()``). In the latter
537 case, the affinity instance is expected to save enough state so that it can
539 ``affinst_suspend_finish()``).The generic code expects the handler to succeed.
544 This function is called by the PSCI implementation after the calling core is
546 It performs the platform-specific setup required to initialize enough state for
547 this core to enter the Normal world and also provide secure runtime firmware
551 similar meaning as described in the previous operations. The generic code
552 expects the handler to succeed.
557 This function is called by the PSCI implementation after the calling core is
559 event, for example a timer interrupt that was programmed by the core during the
560 ``CPU_SUSPEND`` call or ``SYSTEM_SUSPEND`` call. It performs the platform-specific
561 setup required to restore the saved state for this core to resume execution
562 in the Normal world and also provide secure runtime firmware services.
565 similar meaning as described in the previous operations. The generic code
566 expects the platform to succeed.
571 This function is called by the PSCI implementation during the ``CPU_SUSPEND``
572 call to validate the ``power_state`` parameter of the PSCI API. If the
573 ``power_state`` is known to be invalid, the platform must return
574 PSCI\_E\_INVALID\_PARAMS as an error, which is propagated back to the Normal
580 This function is called by the PSCI implementation during the ``CPU_SUSPEND``,
581 ``SYSTEM_SUSPEND`` and ``CPU_ON`` calls to validate the Non-secure ``entry_point``
582 parameter passed by the Normal world. If the ``entry_point`` is known to be
583 invalid, the platform must return PSCI\_E\_INVALID\_PARAMS as an error, which is
584 propagated back to the Normal world PSCI client.
589 This function is called by the PSCI implementation during the ``SYSTEM_SUSPEND``
590 call to return the ``power_state`` parameter. This allows the platform to encode
591 the appropriate State-ID field within the ``power_state`` parameter which can be
593 ``power_state`` parameter should be in the same format as specified by the
594 PSCI specification for the CPU\_SUSPEND API.