1Arm SiP Services
2================
3
4This document enumerates and describes the Arm SiP (Silicon Provider) services.
5
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
16The Arm SiP implementation offers the following services:
17
18-  Execution State Switching service
19
20Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header
21file.
22
23+----------------------------+----------------------------+---------------------------------------+
24| ARM_SIP_SVC_VERSION_MAJOR  | ARM_SIP_SVC_VERSION_MINOR  | Changes                               |
25+============================+============================+=======================================+
26|                          1 |                          0 | Move DebugFS and PMF to the new vendor|
27|                            |                            | specific FID range. The old FID range |
28|                            |                            | for these services are deprecated     |
29+----------------------------+----------------------------+---------------------------------------+
30
31*Table 1: Showing different versions of arm-sip-service and changes done with each version*
32
33Execution State Switching service
34---------------------------------
35
36Execution State Switching service provides a mechanism for a non-secure lower
37Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to
38switch its execution state (a.k.a. Register Width), either from AArch64 to
39AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only
40available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build
41option ``ARCH`` is set to ``aarch64``).
42
43``ARM_SIP_SVC_EXE_STATE_SWITCH``
44~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
45
46::
47
48    Arguments:
49        uint32_t Function ID
50        uint32_t PC hi
51        uint32_t PC lo
52        uint32_t Cookie hi
53        uint32_t Cookie lo
54
55    Return:
56        uint32_t
57
58The function ID parameter must be ``0x82000020``. It uniquely identifies the
59Execution State Switching service being requested.
60
61The parameters *PC hi* and *PC lo* defines upper and lower words, respectively,
62of the entry point (physical address) at which execution should start, after
63Execution State has been switched. When calling from AArch64, *PC hi* must be 0.
64
65When execution starts at the supplied entry point after Execution State has been
66switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers
670 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0.
68
69This call can only be made on the primary CPU, before any secondaries were
70brought up with ``CPU_ON`` PSCI call. Otherwise, the call will always fail.
71
72The effect of switching execution state is as if the Exception Level were
73entered for the first time, following power on. This means CPU registers that
74have a defined reset value by the Architecture will assume that value. Other
75registers should not be expected to hold their values before the call was made.
76CPU endianness, however, is preserved from the previous execution state. Note
77that this switches the execution state of the calling CPU only. This is not a
78substitute for PSCI ``SYSTEM_RESET``.
79
80The service may return the following error codes:
81
82-  ``STATE_SW_E_PARAM``: If any of the parameters were deemed invalid for
83   a specific request.
84-  ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is
85   built for AArch32.
86
87If the call is successful, the caller wouldn't observe the SMC returning.
88Instead, execution starts at the supplied entry point, with the CPU registers 0
89and 1 populated with the supplied *Cookie hi* and *Cookie lo* values,
90respectively.
91
92--------------
93
94*Copyright (c) 2017-2024, Arm Limited and Contributors. All rights reserved.*
95
96.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest
97