blob: 9f0e26615156a069b22f36aabf1eb417e7756496 [file] [log] [blame]
Dan Handley610e7e12018-03-01 18:44:00 +00001Arm SiP Service
Douglas Raillardd7c21b72017-06-28 15:23:03 +01002===============
3
Dan Handley610e7e12018-03-01 18:44:00 +00004This document enumerates and describes the Arm SiP (Silicon Provider) services.
Douglas Raillardd7c21b72017-06-28 15:23:03 +01005
6SiP services are non-standard, platform-specific services offered by the silicon
7implementer or platform provider. They are accessed via. ``SMC`` ("SMC calls")
8instruction executed from Exception Levels below EL3. SMC calls for SiP
9services:
10
11- Follow `SMC Calling Convention`_;
12- Use SMC function IDs that fall in the SiP range, which are ``0xc2000000`` -
13 ``0xc200ffff`` for 64-bit calls, and ``0x82000000`` - ``0x8200ffff`` for 32-bit
14 calls.
15
Dan Handley610e7e12018-03-01 18:44:00 +000016The Arm SiP implementation offers the following services:
Douglas Raillardd7c21b72017-06-28 15:23:03 +010017
18- Performance Measurement Framework (PMF)
19- Execution State Switching service
20
Dan Handley610e7e12018-03-01 18:44:00 +000021Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header
Douglas Raillardd7c21b72017-06-28 15:23:03 +010022file.
23
24Performance Measurement Framework (PMF)
25---------------------------------------
26
27The `Performance Measurement Framework`_
Dan Handley610e7e12018-03-01 18:44:00 +000028allows callers to retrieve timestamps captured at various paths in TF-A
29execution. It's described in detail in `Firmware Design document`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010030
31Execution State Switching service
32---------------------------------
33
34Execution State Switching service provides a mechanism for a non-secure lower
35Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
36switch its execution state (a.k.a. Register Width), either from AArch64 to
37AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
Dan Handley610e7e12018-03-01 18:44:00 +000038available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build
39option ``ARCH`` is set to ``aarch64``).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010040
41``ARM_SIP_SVC_EXE_STATE_SWITCH``
42~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43
44::
45
46 Arguments:
47 uint32_t Function ID
48 uint32_t PC hi
49 uint32_t PC lo
50 uint32_t Cookie hi
51 uint32_t Cookie lo
52
53 Return:
54 uint32_t
55
56The function ID parameter must be ``0x82000020``. It uniquely identifies the
57Execution State Switching service being requested.
58
59The parameters *PC hi* and *PC lo* defines upper and lower words, respectively,
60of the entry point (physical address) at which execution should start, after
61Execution State has been switched. When calling from AArch64, *PC hi* must be 0.
62
63When execution starts at the supplied entry point after Execution State has been
64switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers
650 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0.
66
67This call can only be made on the primary CPU, before any secondaries were
68brought up with ``CPU_ON`` PSCI call. Otherwise, the call will always fail.
69
70The effect of switching execution state is as if the Exception Level were
71entered for the first time, following power on. This means CPU registers that
72have a defined reset value by the Architecture will assume that value. Other
73registers should not be expected to hold their values before the call was made.
74CPU endianness, however, is preserved from the previous execution state. Note
75that this switches the execution state of the calling CPU only. This is not a
76substitute for PSCI ``SYSTEM_RESET``.
77
78The service may return the following error codes:
79
80- ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
81 a specific request.
Dan Handley610e7e12018-03-01 18:44:00 +000082- ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is
83 built for AArch32.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010084
85If the call is successful, the caller wouldn't observe the SMC returning.
86Instead, execution starts at the supplied entry point, with the CPU registers 0
87and 1 populated with the supplied *Cookie hi* and *Cookie lo* values,
88respectively.
89
90--------------
91
Dan Handley610e7e12018-03-01 18:44:00 +000092*Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +010093
94.. _SMC Calling Convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
95.. _Performance Measurement Framework: ./firmware-design.rst#user-content-performance-measurement-framework
96.. _Firmware Design document: ./firmware-design.rst