blob: 37352659da64968ecab6dc46a754913a0a5ef5f4 [file] [log] [blame]
Dan Handley610e7e12018-03-01 18:44:00 +00001PSCI Library Integration guide for Armv8-A AArch32 systems
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002==========================================================
3
Douglas Raillardd7c21b72017-06-28 15:23:03 +01004This document describes the PSCI library interface with a focus on how to
Dan Handley610e7e12018-03-01 18:44:00 +00005integrate with a suitable Trusted OS for an Armv8-A AArch32 system. The PSCI
Douglas Raillardd7c21b72017-06-28 15:23:03 +01006Library implements the PSCI Standard as described in `PSCI spec`_ and is meant
7to be integrated with EL3 Runtime Software which invokes the PSCI Library
8interface appropriately. **EL3 Runtime Software** refers to software executing
9at the highest secure privileged mode, which is EL3 in AArch64 or Secure SVC/
10Monitor mode in AArch32, and provides runtime services to the non-secure world.
11The runtime service request is made via SMC (Secure Monitor Call) and the call
12must adhere to `SMCCC`_. In AArch32, EL3 Runtime Software may additionally
13include Trusted OS functionality. A minimal AArch32 Secure Payload, SP-MIN, is
Dan Handley610e7e12018-03-01 18:44:00 +000014provided in Trusted Firmware-A (TF-A) to illustrate the usage and integration
15of the PSCI library. The description of PSCI library interface and its
16integration with EL3 Runtime Software in this document is targeted towards
17AArch32 systems.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010018
19Generic call sequence for PSCI Library interface (AArch32)
20----------------------------------------------------------
21
22The generic call sequence of PSCI Library interfaces (see
Douglas Raillard30d7b362017-06-28 16:14:55 +010023`PSCI Library Interface`_) during cold boot in AArch32
Douglas Raillardd7c21b72017-06-28 15:23:03 +010024system is described below:
25
26#. After cold reset, the EL3 Runtime Software performs its cold boot
27 initialization including the PSCI library pre-requisites mentioned in
Douglas Raillard30d7b362017-06-28 16:14:55 +010028 `PSCI Library Interface`_, and also the necessary platform
Douglas Raillardd7c21b72017-06-28 15:23:03 +010029 setup.
30
31#. Call ``psci_setup()`` in Monitor mode.
32
33#. Optionally call ``psci_register_spd_pm_hook()`` to register callbacks to
34 do bookkeeping for the EL3 Runtime Software during power management.
35
36#. Call ``psci_prepare_next_non_secure_ctx()`` to initialize the non-secure CPU
37 context.
38
39#. Get the non-secure ``cpu_context_t`` for the current CPU by calling
40 ``cm_get_context()`` , then programming the registers in the non-secure
41 context and exiting to non-secure world. If the EL3 Runtime Software needs
42 additional configuration to be set for non-secure context, like routing
43 FIQs to the secure world, the values of the registers can be modified prior
Douglas Raillard30d7b362017-06-28 16:14:55 +010044 to programming. See `PSCI CPU context management`_ for more
Douglas Raillardd7c21b72017-06-28 15:23:03 +010045 details on CPU context management.
46
47The generic call sequence of PSCI library interfaces during warm boot in
48AArch32 systems is described below:
49
50#. After warm reset, the EL3 Runtime Software performs the necessary warm
51 boot initialization including the PSCI library pre-requisites mentioned in
Douglas Raillard30d7b362017-06-28 16:14:55 +010052 `PSCI Library Interface`_ (Note that the Data cache
Douglas Raillardd7c21b72017-06-28 15:23:03 +010053 **must not** be enabled).
54
55#. Call ``psci_warmboot_entrypoint()`` in Monitor mode. This interface
56 initializes/restores the non-secure CPU context as well.
57
58#. Do step 5 of the cold boot call sequence described above.
59
60The generic call sequence of PSCI library interfaces on receipt of a PSCI SMC
61on an AArch32 system is described below:
62
63#. On receipt of an SMC, save the register context as per `SMCCC`_.
64
65#. If the SMC function identifier corresponds to a SMC32 PSCI API, construct
66 the appropriate arguments and call the ``psci_smc_handler()`` interface.
67 The invocation may or may not return back to the caller depending on
68 whether the PSCI API resulted in power down of the CPU.
69
70#. If ``psci_smc_handler()`` returns, populate the return value in R0 (AArch32)/
71 X0 (AArch64) and restore other registers as per `SMCCC`_.
72
Douglas Raillard30d7b362017-06-28 16:14:55 +010073PSCI CPU context management
74---------------------------
Douglas Raillardd7c21b72017-06-28 15:23:03 +010075
76PSCI library is in charge of initializing/restoring the non-secure CPU system
77registers according to `PSCI specification`_ during cold/warm boot.
78This is referred to as ``PSCI CPU Context Management``. Registers that need to
79be preserved across CPU power down/power up cycles are maintained in
80``cpu_context_t`` data structure. The initialization of other non-secure CPU
81system registers which do not require coordination with the EL3 Runtime
82Software is done directly by the PSCI library (see ``cm_prepare_el3_exit()``).
83
84The EL3 Runtime Software is responsible for managing register context
85during switch between Normal and Secure worlds. The register context to be
86saved and restored depends on the mechanism used to trigger the world switch.
87For example, if the world switch was triggered by an SMC call, then the
88registers need to be saved and restored according to `SMCCC`_. In AArch64,
89due to the tight integration with BL31, both BL31 and PSCI library
90use the same ``cpu_context_t`` data structure for PSCI CPU context management
91and register context management during world switch. This cannot be assumed
92for AArch32 EL3 Runtime Software since most AArch32 Trusted OSes already implement
93a mechanism for register context management during world switch. Hence, when
94the PSCI library is integrated with a AArch32 EL3 Runtime Software, the
95``cpu_context_t`` is stripped down for just PSCI CPU context management.
96
97During cold/warm boot, after invoking appropriate PSCI library interfaces, it
98is expected that the EL3 Runtime Software will query the ``cpu_context_t`` and
99write appropriate values to the corresponding system registers. This mechanism
100resolves 2 additional problems for AArch32 EL3 Runtime Software:
101
102#. Values for certain system registers like SCR and SCTLR cannot be
103 unilaterally determined by PSCI library and need inputs from the EL3
104 Runtime Software. Using ``cpu_context_t`` as an intermediary data store
105 allows EL3 Runtime Software to modify the register values appropriately
106 before programming them.
107
108#. The PSCI library provides appropriate LR and SPSR values (entrypoint
109 information) for exit into non-secure world. Using ``cpu_context_t`` as an
110 intermediary data store allows the EL3 Runtime Software to store these
111 values safely until it is ready for exit to non-secure world.
112
113Currently the ``cpu_context_t`` data structure for AArch32 stores the following
114registers: R0 - R3, LR (R14), SCR, SPSR, SCTLR.
115
116The EL3 Runtime Software must implement accessors to get/set pointers
117to CPU context ``cpu_context_t`` data and these are described in
Douglas Raillard30d7b362017-06-28 16:14:55 +0100118`CPU Context management API`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100119
120PSCI Library Interface
121----------------------
122
123The PSCI library implements the `PSCI Specification`_. The interfaces
John Tsichritzis2bcd5322019-05-13 11:20:05 +0100124to this library are declared in ``psci_lib.h`` and are as listed below:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100125
126.. code:: c
127
128 u_register_t psci_smc_handler(uint32_t smc_fid, u_register_t x1,
129 u_register_t x2, u_register_t x3,
130 u_register_t x4, void *cookie,
131 void *handle, u_register_t flags);
132 int psci_setup(const psci_lib_args_t *lib_args);
133 void psci_warmboot_entrypoint(void);
134 void psci_register_spd_pm_hook(const spd_pm_ops_t *pm);
135 void psci_prepare_next_non_secure_ctx(entry_point_info_t *next_image_info);
136
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100137The CPU context data 'cpu_context_t' is programmed to the registers differently
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100138when PSCI is integrated with an AArch32 EL3 Runtime Software compared to
139when the PSCI is integrated with an AArch64 EL3 Runtime Software (BL31). For
140example, in the case of AArch64, there is no need to retrieve ``cpu_context_t``
141data and program the registers as it will done implicitly as part of
142``el3_exit``. The description below of the PSCI interfaces is targeted at
143integration with an AArch32 EL3 Runtime Software.
144
145The PSCI library is responsible for initializing/restoring the non-secure world
146to an appropriate state after boot and may choose to directly program the
147non-secure system registers. The PSCI generic code takes care not to directly
148modify any of the system registers affecting the secure world and instead
149returns the values to be programmed to these registers via ``cpu_context_t``.
150The EL3 Runtime Software is responsible for programming those registers and
151can use the proposed values provided in the ``cpu_context_t``, modifying the
152values if required.
153
154PSCI library needs the flexibility to access both secure and non-secure
155copies of banked registers. Hence it needs to be invoked in Monitor mode
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100156for AArch32 and in EL3 for AArch64. The NS bit in SCR (in AArch32) or SCR_EL3
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100157(in AArch64) must be set to 0. Additional requirements for the PSCI library
158interfaces are:
159
160- Instruction cache must be enabled
161- Both IRQ and FIQ must be masked for the current CPU
162- The page tables must be setup and the MMU enabled
163- The C runtime environment must be setup and stack initialized
164- The Data cache must be enabled prior to invoking any of the PSCI library
165 interfaces except for ``psci_warmboot_entrypoint()``. For
166 ``psci_warmboot_entrypoint()``, if the build option ``HW_ASSISTED_COHERENCY``
167 is enabled however, data caches are expected to be enabled.
168
169Further requirements for each interface can be found in the interface
170description.
171
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100172Interface : psci_setup()
173~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100174
175::
176
177 Argument : const psci_lib_args_t *lib_args
178 Return : void
179
180This function is to be called by the primary CPU during cold boot before
181any other interface to the PSCI library. It takes ``lib_args``, a const pointer
182to ``psci_lib_args_t``, as the argument. The ``psci_lib_args_t`` is a versioned
John Tsichritzis2bcd5322019-05-13 11:20:05 +0100183structure and is declared in ``psci_lib.h`` header as follows:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100184
185.. code:: c
186
187 typedef struct psci_lib_args {
188 /* The version information of PSCI Library Interface */
189 param_header_t h;
190 /* The warm boot entrypoint function */
191 mailbox_entrypoint_t mailbox_ep;
192 } psci_lib_args_t;
193
194The first field ``h``, of ``param_header_t`` type, provides the version
195information. The second field ``mailbox_ep`` is the warm boot entrypoint address
196and is used to configure the platform mailbox. Helper macros are provided in
John Tsichritzis2bcd5322019-05-13 11:20:05 +0100197``psci_lib.h`` to construct the ``lib_args`` argument statically or during
198runtime. Prior to calling the ``psci_setup()`` interface, the platform setup for
199cold boot must have completed. Major actions performed by this interface are:
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100200
201- Initializes architecture.
202- Initializes PSCI power domain and state coordination data structures.
203- Calls ``plat_setup_psci_ops()`` with warm boot entrypoint ``mailbox_ep`` as
204 argument.
205- Calls ``cm_set_context_by_index()`` (see
Douglas Raillard30d7b362017-06-28 16:14:55 +0100206 `CPU Context management API`_) for all the CPUs in the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100207 platform
208
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100209Interface : psci_prepare_next_non_secure_ctx()
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100211
212::
213
214 Argument : entry_point_info_t *next_image_info
215 Return : void
216
217After ``psci_setup()`` and prior to exit to the non-secure world, this function
218must be called by the EL3 Runtime Software to initialize the non-secure world
219context. The non-secure world entrypoint information ``next_image_info`` (first
220argument) will be used to determine the non-secure context. After this function
221returns, the EL3 Runtime Software must retrieve the ``cpu_context_t`` (using
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100222cm_get_context()) for the current CPU and program the registers prior to exit
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100223to the non-secure world.
224
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100225Interface : psci_register_spd_pm_hook()
226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100227
228::
229
230 Argument : const spd_pm_ops_t *
231 Return : void
232
Douglas Raillard30d7b362017-06-28 16:14:55 +0100233As explained in `Secure payload power management callback`_,
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100234the EL3 Runtime Software may want to perform some bookkeeping during power
235management operations. This function is used to register the ``spd_pm_ops_t``
236(first argument) callbacks with the PSCI library which will be called
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000237appropriately during power management. Calling this function is optional and
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100238need to be called by the primary CPU during the cold boot sequence after
239``psci_setup()`` has completed.
240
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100241Interface : psci_smc_handler()
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100243
244::
245
246 Argument : uint32_t smc_fid, u_register_t x1,
247 u_register_t x2, u_register_t x3,
248 u_register_t x4, void *cookie,
249 void *handle, u_register_t flags
250 Return : u_register_t
251
252This function is the top level handler for SMCs which fall within the
253PSCI service range specified in `SMCCC`_. The function ID ``smc_fid`` (first
254argument) determines the PSCI API to be called. The ``x1`` to ``x4`` (2nd to 5th
255arguments), are the values of the registers r1 - r4 (in AArch32) or x1 - x4
256(in AArch64) when the SMC is received. These are the arguments to PSCI API as
257described in `PSCI spec`_. The 'flags' (8th argument) is a bit field parameter
Antonio Nino Diaz3c817f42018-03-21 10:49:27 +0000258and is detailed in 'smccc.h' header. It includes whether the call is from the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100259secure or non-secure world. The ``cookie`` (6th argument) and the ``handle``
260(7th argument) are not used and are reserved for future use.
261
262The return value from this interface is the return value from the underlying
263PSCI API corresponding to ``smc_fid``. This function may not return back to the
264caller if PSCI API causes power down of the CPU. In this case, when the CPU
265wakes up, it will start execution from the warm reset address.
266
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100267Interface : psci_warmboot_entrypoint()
268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100269
270::
271
272 Argument : void
273 Return : void
274
275This function performs the warm boot initialization/restoration as mandated by
276`PSCI spec`_. For AArch32, on wakeup from power down the CPU resets to secure SVC
277mode and the EL3 Runtime Software must perform the prerequisite initializations
278mentioned at top of this section. This function must be called with Data cache
279disabled (unless build option ``HW_ASSISTED_COHERENCY`` is enabled) but with MMU
280initialized and enabled. The major actions performed by this function are:
281
282- Invalidates the stack and enables the data cache.
283- Initializes architecture and PSCI state coordination.
284- Restores/Initializes the peripheral drivers to the required state via
285 appropriate ``plat_psci_ops_t`` hooks
286- Restores the EL3 Runtime Software context via appropriate ``spd_pm_ops_t``
287 callbacks.
288- Restores/Initializes the non-secure context and populates the
289 ``cpu_context_t`` for the current CPU.
290
291Upon the return of this function, the EL3 Runtime Software must retrieve the
292non-secure ``cpu_context_t`` using ``cm_get_context()`` and program the registers
293prior to exit to the non-secure world.
294
295EL3 Runtime Software dependencies
296---------------------------------
297
298The PSCI Library includes supporting frameworks like context management,
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100299cpu operations (cpu_ops) and per-cpu data framework. Other helper library
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100300functions like bakery locks and spin locks are also included in the library.
301The dependencies which must be fulfilled by the EL3 Runtime Software
302for integration with PSCI library are described below.
303
304General dependencies
305~~~~~~~~~~~~~~~~~~~~
306
307The PSCI library being a Multiprocessor (MP) implementation, EL3 Runtime
308Software must provide an SMC handling framework capable of MP adhering to
309`SMCCC`_ specification.
310
311The EL3 Runtime Software must also export cache maintenance primitives
312and some helper utilities for assert, print and memory operations as listed
Dan Handley610e7e12018-03-01 18:44:00 +0000313below. The TF-A source tree provides implementations for all
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100314these functions but the EL3 Runtime Software may use its own implementation.
315
Antonio Nino Diazc0c8eb62018-08-15 17:02:28 +0100316**Functions : assert(), memcpy(), memset(), printf()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100317
318These must be implemented as described in ISO C Standard.
319
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100320**Function : flush_dcache_range()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100321
322::
323
324 Argument : uintptr_t addr, size_t size
325 Return : void
326
327This function cleans and invalidates (flushes) the data cache for memory
328at address ``addr`` (first argument) address and of size ``size`` (second argument).
329
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100330**Function : inv_dcache_range()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100331
332::
333
334 Argument : uintptr_t addr, size_t size
335 Return : void
336
337This function invalidates (flushes) the data cache for memory at address
338``addr`` (first argument) address and of size ``size`` (second argument).
339
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100340**Function : do_panic()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100341
342::
343
344 Argument : void
345 Return : void
346
347This function will be called by the PSCI library on encountering a critical
348failure that cannot be recovered from. This function **must not** return.
349
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100350CPU Context management API
351~~~~~~~~~~~~~~~~~~~~~~~~~~
352
353The CPU context management data memory is statically allocated by PSCI library
354in BSS section. The PSCI library requires the EL3 Runtime Software to implement
355APIs to store and retrieve pointers to this CPU context data. SP-MIN
356demonstrates how these APIs can be implemented but the EL3 Runtime Software can
357choose a more optimal implementation (like dedicating the secure TPIDRPRW
358system register (in AArch32) for storing these pointers).
359
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100360**Function : cm_set_context_by_index()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100361
362::
363
364 Argument : unsigned int cpu_idx, void *context, unsigned int security_state
365 Return : void
366
367This function is called during cold boot when the ``psci_setup()`` PSCI library
368interface is called.
369
370This function must store the pointer to the CPU context data, ``context`` (2nd
371argument), for the specified ``security_state`` (3rd argument) and CPU identified
372by ``cpu_idx`` (first argument). The ``security_state`` will always be non-secure
373when called by PSCI library and this argument is retained for compatibility
374with BL31. The ``cpu_idx`` will correspond to the index returned by the
375``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
376
377The actual method of storing the ``context`` pointers is implementation specific.
378For example, SP-MIN stores the pointers in the array ``sp_min_cpu_ctx_ptr``
379declared in ``sp_min_main.c``.
380
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100381**Function : cm_get_context()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100382
383::
384
385 Argument : uint32_t security_state
386 Return : void *
387
388This function must return the pointer to the ``cpu_context_t`` structure for
389the specified ``security_state`` (first argument) for the current CPU. The caller
390must ensure that ``cm_set_context_by_index`` is called first and the appropriate
391context pointers are stored prior to invoking this API. The ``security_state``
392will always be non-secure when called by PSCI library and this argument
393is retained for compatibility with BL31.
394
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100395**Function : cm_get_context_by_index()**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100396
397::
398
399 Argument : unsigned int cpu_idx, unsigned int security_state
400 Return : void *
401
402This function must return the pointer to the ``cpu_context_t`` structure for
403the specified ``security_state`` (second argument) for the CPU identified by
404``cpu_idx`` (first argument). The caller must ensure that
405``cm_set_context_by_index`` is called first and the appropriate context
406pointers are stored prior to invoking this API. The ``security_state`` will
407always be non-secure when called by PSCI library and this argument is
408retained for compatibility with BL31. The ``cpu_idx`` will correspond to the
409index returned by the ``plat_core_pos_by_mpidr()`` for ``mpidr`` of the CPU.
410
411Platform API
412~~~~~~~~~~~~
413
414The platform layer abstracts the platform-specific details from the generic
415PSCI library. The following platform APIs/macros must be defined by the EL3
416Runtime Software for integration with the PSCI library.
417
418The mandatory platform APIs are:
419
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100420- plat_my_core_pos
421- plat_core_pos_by_mpidr
422- plat_get_syscnt_freq2
423- plat_get_power_domain_tree_desc
424- plat_setup_psci_ops
425- plat_reset_handler
426- plat_panic_handler
427- plat_get_my_stack
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100428
429The mandatory platform macros are:
430
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100431- PLATFORM_CORE_COUNT
432- PLAT_MAX_PWR_LVL
433- PLAT_NUM_PWR_DOMAINS
434- CACHE_WRITEBACK_GRANULE
435- PLAT_MAX_OFF_STATE
436- PLAT_MAX_RET_STATE
437- PLAT_MAX_PWR_LVL_STATES (optional)
438- PLAT_PCPU_DATA_SIZE (optional)
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100439
Paul Beesleyf8640672019-04-12 14:19:42 +0100440The details of these APIs/macros can be found in the :ref:`Porting Guide`.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100441
442All platform specific operations for power management are done via
443``plat_psci_ops_t`` callbacks registered by the platform when
444``plat_setup_psci_ops()`` API is called. The description of each of
445the callbacks in ``plat_psci_ops_t`` can be found in PSCI section of the
Paul Beesleyf8640672019-04-12 14:19:42 +0100446:ref:`Porting Guide`. If any these callbacks are not registered, then the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100447PSCI API associated with that callback will not be supported by PSCI
448library.
449
450Secure payload power management callback
451~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452
453During PSCI power management operations, the EL3 Runtime Software may
454need to perform some bookkeeping, and PSCI library provides
455``spd_pm_ops_t`` callbacks for this purpose. These hooks must be
456populated and registered by using ``psci_register_spd_pm_hook()`` PSCI
457library interface.
458
459Typical bookkeeping during PSCI power management calls include save/restore
460of the EL3 Runtime Software context. Also if the EL3 Runtime Software makes
461use of secure interrupts, then these interrupts must also be managed
462appropriately during CPU power down/power up. Any secure interrupt targeted
463to the current CPU must be disabled or re-targeted to other running CPU prior
464to power down of the current CPU. During power up, these interrupt can be
465enabled/re-targeted back to the current CPU.
466
467.. code:: c
468
469 typedef struct spd_pm_ops {
470 void (*svc_on)(u_register_t target_cpu);
471 int32_t (*svc_off)(u_register_t __unused);
472 void (*svc_suspend)(u_register_t max_off_pwrlvl);
473 void (*svc_on_finish)(u_register_t __unused);
474 void (*svc_suspend_finish)(u_register_t max_off_pwrlvl);
475 int32_t (*svc_migrate)(u_register_t from_cpu, u_register_t to_cpu);
476 int32_t (*svc_migrate_info)(u_register_t *resident_cpu);
477 void (*svc_system_off)(void);
478 void (*svc_system_reset)(void);
479 } spd_pm_ops_t;
480
481A brief description of each callback is given below:
482
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100483- svc_on, svc_off, svc_on_finish
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100484
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100485 The ``svc_on``, ``svc_off`` callbacks are called during PSCI_CPU_ON,
486 PSCI_CPU_OFF APIs respectively. The ``svc_on_finish`` is called when the
487 target CPU of PSCI_CPU_ON API powers up and executes the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100488 ``psci_warmboot_entrypoint()`` PSCI library interface.
489
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100490- svc_suspend, svc_suspend_finish
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100491
492 The ``svc_suspend`` callback is called during power down bu either
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100493 PSCI_SUSPEND or PSCI_SYSTEM_SUSPEND APIs. The ``svc_suspend_finish`` is
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100494 called when the CPU wakes up from suspend and executes the
495 ``psci_warmboot_entrypoint()`` PSCI library interface. The ``max_off_pwrlvl``
496 (first parameter) denotes the highest power domain level being powered down
497 to or woken up from suspend.
498
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100499- svc_system_off, svc_system_reset
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100500
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100501 These callbacks are called during PSCI_SYSTEM_OFF and PSCI_SYSTEM_RESET
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100502 PSCI APIs respectively.
503
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100504- svc_migrate_info
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100505
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100506 This callback is called in response to PSCI_MIGRATE_INFO_TYPE or
507 PSCI_MIGRATE_INFO_UP_CPU APIs. The return value of this callback must
508 correspond to the return value of PSCI_MIGRATE_INFO_TYPE API as described
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100509 in `PSCI spec`_. If the secure payload is a Uniprocessor (UP)
510 implementation, then it must update the mpidr of the CPU it is resident in
511 via ``resident_cpu`` (first argument). The updates to ``resident_cpu`` is
512 ignored if the secure payload is a multiprocessor (MP) implementation.
513
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100514- svc_migrate
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100515
516 This callback is only relevant if the secure payload in EL3 Runtime
517 Software is a Uniprocessor (UP) implementation and supports migration from
518 the current CPU ``from_cpu`` (first argument) to another CPU ``to_cpu``
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100519 (second argument). This callback is called in response to PSCI_MIGRATE
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100520 API. This callback is never called if the secure payload is a
521 Multiprocessor (MP) implementation.
522
523CPU operations
524~~~~~~~~~~~~~~
525
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100526The CPU operations (cpu_ops) framework implement power down sequence specific
Paul Beesleyf8640672019-04-12 14:19:42 +0100527to the CPU and the details of which can be found at
528:ref:`firmware_design_cpu_ops_fwk`. The TF-A tree implements the ``cpu_ops``
529for various supported CPUs and the EL3 Runtime Software needs to include the
530required ``cpu_ops`` in its build. The start and end of the ``cpu_ops``
531descriptors must be exported by the EL3 Runtime Software via the
532``__CPU_OPS_START__`` and ``__CPU_OPS_END__`` linker symbols.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100533
534The ``cpu_ops`` descriptors also include reset sequences and may include errata
535workarounds for the CPU. The EL3 Runtime Software can choose to call this
536during cold/warm reset if it does not implement its own reset sequence/errata
537workarounds.
538
539--------------
540
laurenw-arm03e7e612020-04-16 10:02:17 -0500541*Copyright (c) 2016-2020, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100542
543.. _PSCI spec: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
laurenw-arm03e7e612020-04-16 10:02:17 -0500544.. _SMCCC: https://developer.arm.com/docs/den0028/latest
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100545.. _PSCI specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100546.. _PSCI Specification: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf