Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 1 | Arm SiP Service |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 2 | =============== |
| 3 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 4 | This document enumerates and describes the Arm SiP (Silicon Provider) services. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 5 | |
| 6 | SiP services are non-standard, platform-specific services offered by the silicon |
Antonio Nino Diaz | 7330861 | 2019-02-28 13:35:21 +0000 | [diff] [blame] | 7 | implementer or platform provider. They are accessed via ``SMC`` ("SMC calls") |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 8 | instruction executed from Exception Levels below EL3. SMC calls for SiP |
| 9 | services: |
| 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 Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 16 | The Arm SiP implementation offers the following services: |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 17 | |
| 18 | - Performance Measurement Framework (PMF) |
| 19 | - Execution State Switching service |
| 20 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 21 | Source definitions for Arm SiP service are located in the ``arm_sip_svc.h`` header |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 22 | file. |
| 23 | |
| 24 | Performance Measurement Framework (PMF) |
| 25 | --------------------------------------- |
| 26 | |
| 27 | The `Performance Measurement Framework`_ |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 28 | allows callers to retrieve timestamps captured at various paths in TF-A |
| 29 | execution. It's described in detail in `Firmware Design document`_. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 30 | |
| 31 | Execution State Switching service |
| 32 | --------------------------------- |
| 33 | |
| 34 | Execution State Switching service provides a mechanism for a non-secure lower |
| 35 | Exception Level (either EL2, or NS EL1 if EL2 isn't implemented) to request to |
| 36 | switch its execution state (a.k.a. Register Width), either from AArch64 to |
| 37 | AArch32, or from AArch32 to AArch64, for the calling CPU. This service is only |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 38 | available when Trusted Firmware-A (TF-A) is built for AArch64 (i.e. when build |
| 39 | option ``ARCH`` is set to ``aarch64``). |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 40 | |
| 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 | |
| 56 | The function ID parameter must be ``0x82000020``. It uniquely identifies the |
| 57 | Execution State Switching service being requested. |
| 58 | |
| 59 | The parameters *PC hi* and *PC lo* defines upper and lower words, respectively, |
| 60 | of the entry point (physical address) at which execution should start, after |
| 61 | Execution State has been switched. When calling from AArch64, *PC hi* must be 0. |
| 62 | |
| 63 | When execution starts at the supplied entry point after Execution State has been |
| 64 | switched, the parameters *Cookie hi* and *Cookie lo* are passed in CPU registers |
| 65 | 0 and 1, respectively. When calling from AArch64, *Cookie hi* must be 0. |
| 66 | |
| 67 | This call can only be made on the primary CPU, before any secondaries were |
| 68 | brought up with ``CPU_ON`` PSCI call. Otherwise, the call will always fail. |
| 69 | |
| 70 | The effect of switching execution state is as if the Exception Level were |
| 71 | entered for the first time, following power on. This means CPU registers that |
| 72 | have a defined reset value by the Architecture will assume that value. Other |
| 73 | registers should not be expected to hold their values before the call was made. |
| 74 | CPU endianness, however, is preserved from the previous execution state. Note |
| 75 | that this switches the execution state of the calling CPU only. This is not a |
| 76 | substitute for PSCI ``SYSTEM_RESET``. |
| 77 | |
| 78 | The 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 Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 82 | - ``STATE_SW_E_DENIED``: If the call is not successful, or when TF-A is |
| 83 | built for AArch32. |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 84 | |
| 85 | If the call is successful, the caller wouldn't observe the SMC returning. |
| 86 | Instead, execution starts at the supplied entry point, with the CPU registers 0 |
| 87 | and 1 populated with the supplied *Cookie hi* and *Cookie lo* values, |
| 88 | respectively. |
| 89 | |
| 90 | -------------- |
| 91 | |
Dan Handley | 4def07d | 2018-03-01 18:44:00 +0000 | [diff] [blame] | 92 | *Copyright (c) 2017-2018, Arm Limited and Contributors. All rights reserved.* |
Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 93 | |
| 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 |