From 5e1e9200750d2fc5f969d28afa5e4ef75c4ffc94 Mon Sep 17 00:00:00 2001 From: Dan Handley Date: Tue, 25 Feb 2014 19:09:48 +0000 Subject: [PATCH] Add EL3 runtime services and SPD documentation 1. Add design information on EL3 runtime services and Secure-EL1 Payload Dispatchers (SPD) to firmware-design.md. 2. Create new EL3 runtime service writer's guide (rt-svc-writers-guide.md) to ease creation of new runtime services. Change-Id: I670aeb5fc246e25c6e599a15139aac886a0074fd --- docs/diagrams/rt-svc-descs-layout.png | Bin 0 -> 77894 bytes docs/firmware-design.md | 373 ++++++++++++++++++++++---- docs/rt-svc-writers-guide.md | 308 +++++++++++++++++++++ 3 files changed, 633 insertions(+), 48 deletions(-) create mode 100644 docs/diagrams/rt-svc-descs-layout.png create mode 100644 docs/rt-svc-writers-guide.md diff --git a/docs/diagrams/rt-svc-descs-layout.png b/docs/diagrams/rt-svc-descs-layout.png new file mode 100644 index 0000000000000000000000000000000000000000..1a9fa5b0dccfb6f1041dfbfe8dd3321403883973 GIT binary patch literal 77894 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ℑ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 N%ak9xO$(XAUiJ0_b=+KBM#s3dPO5D-j`pw zTvYi#{&H2-NVk3vbjJbH7jZCwg&|1IiFw>cvowP{mD1?2-VgonH|K7kEKBSvawcCO zJcA6pVY$lFB!6A-J8;iUaU`le&%L}66+H8JbmnMG8lq^p*EN{!w134&LxLW3@XJNo zJ7!FPLJyWI$V-GLVO=Oh&KnlyZSbdJzw3rql)*6U1){>QT>N6U4&nKrIyi~!`<$EY zr5ja)Fz}?)1mR=c;qA7#fp8nu7l1d0YkWW2%#w-#r-Dt9y>Qqe^6OGueLv#Jk>y8w z_`m3IbTAarJrk2XCke_K7+ z&&D;`I@j^OlU5;R!vId>QadvVJ684f9S5%{g+0;?XcW!Gt&BAA|HMjM+M2vN1~iT1 zA%Dfpl!`8`2XZynb{G5Hj<>f2%de0~ApG_@Du}mwC>@uQsY`R>1 zmf{e5KQ~^6%{+gKzE=mgl%Q{;=ytH1Ah{Q_nS}(>Pl6F^f%a zue;Z!pRc5Y@I=JT#4Qz3fqq_6i0|9^4Ua~#?AeXNzq{E}FtU^Pz-mRm@bbY$2heU! zm#k=oUyh)*4wkc?PRmL+I8dS>;kp*Rd_7Z_>q!q4aCwWSrW7+KjRpSJbI$;z>W|vz zbCq@F=T7^vF_lY$&mHDZ=ZZL95>GX3H`Zaz7L~t$I4wl>^hUlYBvr`7YvONE{fsRV z(N$8T=D{DuW4B}JV0PBD84^>ZEk!fc?kYcZbAKupVt&}@Q#=}K`NfiEWuCGF{7(!L zv?R~QuCXEp%F?i(;JsWjxIo;f=&N40xOz zW&jY(A>lVAyK_qK)mN^*MVnSzlqrR#3w_$>Y5#kZ1CCmIZ#XBu+IXD12S9sw%_f#~ zN*33&#>4n)?uVgfCasQw;V;ih?>}0-SK}rKjyz3Hu%BUnj|b{tu)$X0b^8JqXyW`h z_j~q-JY3{be7w5JAlmeE-uVD}(p69q6VK7hVk#Q4yqg9et12^ClGJ)DJ=kBIrPJsQ z8~tK!GnnY8a>^y`vI?EY*<+YKrh+5)NoSSrp4#l$KB8IYg920GGJ4&sDlhkb zQE9c7JUo@undwMG=_@nvu1I;{)V04#4Y-j@wVvmtOP)LTw;6vm?zoROPROPi?7-Vi z_xqb8kPHFYY&^Pr;J12DtONfZ7x+LpB2uke+BCrJ{-yhLc}j2RzLd9f7~Z@Mmv?e) zAq`7iL34`x=+XPHRvi+OTbw2aG|v5K)1PXkMt@xoM3j10k;h=9Q|peeyWYR_=J)KF z!w@rYAo#QA<8X{I4uFpyF-RZ10ACy}P!GiH+gMl5{?CB+|BMhf6*>m&t4*EY!v?OE z&jE*DdQF_k)n1|H#Wx37?H|7JBLSRw8kCvVY_#MGJF_w=M+kthEH_whM s@7~|vU*EZ&g@t9?l^MnmxdNXD`z=d1|K!kb;$Z*+Pgg&ebxsLQ0A2pPH2?qr literal 0 HcmV?d00001 diff --git a/docs/firmware-design.md b/docs/firmware-design.md index 89dd45f0..4e7890e8 100644 --- a/docs/firmware-design.md +++ b/docs/firmware-design.md @@ -4,11 +4,14 @@ ARM Trusted Firmware Design Contents : 1. Introduction -2. Cold Boot -3. Memory layout on FVP platforms -4. Firmware Image Package (FIP) -5. Code Structure -6. References +2. Cold boot +3. EL3 runtime services framework +4. Power State Coordination Interface +5. Secure-EL1 Payloads and Dispatchers +6. Memory layout on FVP platforms +7. Firmware Image Package (FIP) +8. Code Structure +9. References 1. Introduction @@ -29,7 +32,7 @@ instruction. The SMC instruction must be used as mandated by the [SMC Calling Convention PDD][SMCCC] [3]. -2. Cold Boot +2. Cold boot ------------- The cold boot path starts when the platform is physically turned on. One of @@ -334,59 +337,330 @@ memory address populated by BL2. * Runtime services initialization: - The only runtime service implemented by BL3-1 is PSCI. The complete PSCI API - is not yet implemented. The following functions are currently implemented: + The runtime service framework and its initialization is described in the + "EL3 runtime services framework" section below. - - `PSCI_VERSION` - - `CPU_OFF` - - `CPU_ON` - - `CPU_SUSPEND` - - `AFFINITY_INFO` + Details about the PSCI service are provided in the "Power State Coordination + Interface" section below. - The `CPU_ON`, `CPU_OFF` and `CPU_SUSPEND` functions implement the warm boot - path in ARM Trusted Firmware. `CPU_ON` and `CPU_OFF` have undergone testing - on all the supported FVPs. `CPU_SUSPEND` & `AFFINITY_INFO` have undergone - testing only on the AEM v8 Base FVP. Support for `AFFINITY_INFO` is still - experimental. Support for `CPU_SUSPEND` is stable for entry into power down - states. Standby states are currently not supported. `PSCI_VERSION` is - present but completely untested in this version of the software. +* BL3-2 (Secure-EL1 Payload) image initialization - Unsupported PSCI functions can be divided into ones that can return - execution to the caller and ones that cannot. The following functions - return with a error code as documented in the [Power State Coordination - Interface PDD] [PSCI]. + If a BL3-2 image is present then there must be a matching Secure-EL1 Payload + Dispatcher (SPD) service (see later for details). During initialization + that service must register a function to carry out initialization of BL3-2 + once the runtime services are fully initialized. BL3-1 invokes such a + registered function to initialize BL3-2 before running BL3-3. - - `MIGRATE` : -1 (NOT_SUPPORTED) - - `MIGRATE_INFO_TYPE` : 2 (Trusted OS is either not present or does not - require migration) - - `MIGRATE_INFO_UP_CPU` : 0 (Return value is UNDEFINED) + Details on BL3-2 initialization and the SPD's role are described in the + "Secure-EL1 Payloads and Dispatchers" section below. - The following unsupported functions do not return and signal an assertion - failure if invoked. +* BL3-3 (Non-trusted Firmware) execution - - `SYSTEM_OFF` - - `SYSTEM_RESET` + BL3-1 initializes the EL2 or EL1 processor context for normal-world cold + boot, ensuring that no secure state information finds its way into the + non-secure execution state. BL3-1 uses the entrypoint information provided + by BL2 to jump to the Non-trusted firmware image (BL3-3) at the highest + available Exception Level (EL2 if available, otherwise EL1). - BL3-1 returns the error code `-1` if an SMC is raised for any other runtime - service. This behavior is mandated by the [SMC calling convention PDD] - [SMCCC]. +3. EL3 runtime services framework +---------------------------------- + +Software executing in the non-secure state and in the secure state at exception +levels lower than EL3 will request runtime services using the Secure Monitor +Call (SMC) instruction. These requests will follow the convention described in +the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function +identifiers to each SMC request and describes how arguments are passed and +returned. + +The EL3 runtime services framework enables the development of services by +different providers that can be easily integrated into final product firmware. +The following sections describe the framework which facilitates the +registration, initialization and use of runtime services in EL3 Runtime +Firmware (BL3-1). + +The design of the runtime services depends heavily on the concepts and +definitions described in the [SMCCC], in particular SMC Function IDs, Owning +Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and SMC64 calling +conventions. Please refer to that document for more detailed explanation of +these terms. + +The following runtime services are expected to be implemented first. They have +not all been instantiated in the current implementation. + +1. Standard service calls + + This service is for management of the entire system. The Power State + Coordination Interface ([PSCI]) is the first set of standard service calls + defined by ARM (see PSCI section later). + + NOTE: Currently this service is called PSCI since there are no other + defined standard service calls. + +2. Secure-EL1 Payload Dispatcher service + + If a system runs a Trusted OS or other Secure-EL1 Payload (SP) then + it also requires a _Secure Monitor_ at EL3 to switch the EL1 processor + context between the normal world (EL1/EL2) and trusted world (Secure-EL1). + The Secure Monitor will make these world switches in response to SMCs. The + [SMCCC] provides for such SMCs with the Trusted OS Call and Trusted + Application Call OEN ranges. + + The interface between the EL3 Runtime Firmware and the Secure-EL1 Payload is + not defined by the [SMCCC] or any other standard. As a result, each + Secure-EL1 Payload requires a specific Secure Monitor that runs as a runtime + service - within ARM Trusted Firmware this service is referred to as the + Secure-EL1 Payload Dispatcher (SPD). + + ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and its + associated Dispatcher (TSPD). Details of SPD design and TSP/TSPD operation + are described in the "Secure-EL1 Payloads and Dispatchers" section below. + +3. CPU implementation service + + This service will provide an interface to CPU implementation specific + services for a given platform e.g. access to processor errata workarounds. + This service is currently unimplemented. + +Additional services for ARM Architecture, SiP and OEM calls can be implemented. +Each implemented service handles a range of SMC function identifiers as +described in the [SMCCC]. + + +### Registration + +A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying +the name of the service, the range of OENs covered, the type of service and +initialization and call handler functions. This macro instantiates a `const +struct rt_svc_desc` for the service with these details (see `runtime_svc.h`). +This structure is allocated in a special ELF section `rt_svc_descs`, enabling +the framework to find all service descriptors included into BL3-1. + +The specific service for a SMC Function is selected based on the OEN and call +type of the Function ID, and the framework uses that information in the service +descriptor to identify the handler for the SMC Call. + +The service descriptors do not include information to identify the precise set +of SMC function identifiers supported by this service implementation, the +security state from which such calls are valid nor the capability to support +64-bit and/or 32-bit callers (using SMC32 or SMC64). Responding appropriately +to these aspects of a SMC call is the responsibility of the service +implementation, the framework is focused on integration of services from +different providers and minimizing the time taken by the framework before the +service handler is invoked. + +Details of the parameters, requirements and behavior of the initialization and +call handling functions are provided in the following sections. + + +### Initialization + +`runtime_svc_init()` in `runtime_svc.c` initializes the runtime services +framework running on the primary CPU during cold boot as part of the BL3-1 +initialization. This happens prior to initializing a Trusted OS and running +Normal world boot firmware that might in turn use these services. +Initialization involves validating each of the declared runtime service +descriptors, calling the service initialization function and populating the +index used for runtime lookup of the service. + +The BL3-1 linker script collects all of the declared service descriptors into a +single array and defines symbols that allow the framework to locate and traverse +the array, and determine its size. + +The framework does basic validation of each descriptor to halt firmware +initialization if service declaration errors are detected. The framework does +not check descriptors for the following error conditions, and may behave in an +unpredictable manner under such scenarios: + +1. Overlapping OEN ranges +2. Multiple descriptors for the same range of OENs and `call_type` +3. Incorrect range of owning entity numbers for a given `call_type` + +Once validated, the service `init()` callback is invoked. This function carries +out any essential EL3 initialization before servicing requests. The `init()` +function is only invoked on the primary CPU during cold boot. If the service +uses per-CPU data this must either be initialized for all CPUs during this call, +or be done lazily when a CPU first issues an SMC call to that service. If +`init()` returns anything other than `0`, this is treated as an initialization +error and the service is ignored: this does not cause the firmware to halt. + +The OEN and call type fields present in the SMC Function ID cover a total of +128 distinct services, but in practice a single descriptor can cover a range of +OENs, e.g. SMCs to call a Trusted OS function. To optimize the lookup of a +service handler, the framework uses an array of 128 indices that map every +distinct OEN/call-type combination either to one of the declared services or to +indicate the service is not handled. This `rt_svc_descs_indices[]` array is +populated for all of the OENs covered by a service after the service `init()` +function has reported success. So a service that fails to initialize will never +have it's `handle()` function invoked. + +The following figure shows how the `rt_svc_descs_indices[]` index maps the SMC +Function ID call type and OEN onto a specific service handler in the +`rt_svc_descs[]` array. + +![Image 1](diagrams/rt-svc-descs-layout.png?raw=true) + + +### Handling an SMC + +When the EL3 runtime services framework receives a Secure Monitor Call, the SMC +Function ID is passed in W0 from the lower exception level (as per the +[SMCCC]). If the calling register width is AArch32, it is invalid to invoke an +SMC Function which indicates the SMC64 calling convention: such calls are +ignored and return the Unknown SMC Function Identifier result code `0xFFFFFFFF` +in R0/X0. + +Bit[31] (fast/standard call) and bits[29:24] (owning entity number) of the SMC +Function ID are combined to index into the `rt_svc_descs_indices[]` array. The +resulting value might indicate a service that has no handler, in this case the +framework will also report an Unknown SMC Function ID. Otherwise, the value is +used as a further index into the `rt_svc_descs[]` array to locate the required +service and handler. + +The service's `handle()` callback is provided with five of the SMC parameters +directly, the others are saved into memory for retrieval (if needed) by the +handler. The handler is also provided with an opaque `handle` for use with the +supporting library for parameter retrieval, setting return values and context +manipulation; and with `flags` indicating the security state of the caller. The +framework finally sets up the execution stack for the handler, and invokes the +services `handle()` function. + +On return from the handler the result registers are populated in X0-X3 before +restoring the stack and CPU state and returning from the original SMC. + + +4. Power State Coordination Interface +-------------------------------------- + +TODO: Provide design walkthrough of PSCI implementation. + +The complete PSCI API is not yet implemented. The following functions are +currently implemented: + +- `PSCI_VERSION` +- `CPU_OFF` +- `CPU_ON` +- `CPU_SUSPEND` +- `AFFINITY_INFO` + +The `CPU_ON`, `CPU_OFF` and `CPU_SUSPEND` functions implement the warm boot +path in ARM Trusted Firmware. `CPU_ON` and `CPU_OFF` have undergone testing +on all the supported FVPs. `CPU_SUSPEND` & `AFFINITY_INFO` have undergone +testing only on the AEM v8 Base FVP. Support for `AFFINITY_INFO` is still +experimental. Support for `CPU_SUSPEND` is stable for entry into power down +states. Standby states are currently not supported. `PSCI_VERSION` is +present but completely untested in this version of the software. + +Unsupported PSCI functions can be divided into ones that can return +execution to the caller and ones that cannot. The following functions +return with a error code as documented in the [Power State Coordination +Interface PDD] [PSCI]. + +- `MIGRATE` : -1 (NOT_SUPPORTED) +- `MIGRATE_INFO_TYPE` : 2 (Trusted OS is either not present or does not + require migration) +- `MIGRATE_INFO_UP_CPU` : 0 (Return value is UNDEFINED) + +The following unsupported functions do not return and signal an assertion +failure if invoked. + +- `SYSTEM_OFF` +- `SYSTEM_RESET` + + +5. Secure-EL1 Payloads and Dispatchers +--------------------------------------- + +On a production system that includes a Trusted OS running in Secure-EL1/EL0, +the Trusted OS is coupled with a companion runtime service in the BL3-1 +firmware. This service is responsible for the initialisation of the Trusted +OS and all communications with it. The Trusted OS is the BL3-2 stage of the +boot flow in ARM Trusted Firmware. The firmware will attempt to locate, load +and execute a BL3-2 image. + +ARM Trusted Firmware uses a more general term for the BL3-2 software that runs +at Secure-EL1 - the _Secure-EL1 Payload_ - as it is not always a Trusted OS. + +The ARM Trusted Firmware provides a Test Secure-EL1 Payload (TSP) and a Test +Secure-EL1 Payload Dispatcher (TSPD) service as an example of how a Trusted OS +is supported on a production system using the Runtime Services Framework. On +such a system, the Test BL3-2 image and service are replaced by the Trusted OS +and its dispatcher service. + +The TSP runs in Secure-EL1. It is designed to demonstrate synchronous +communication with the normal-world software running in EL1/EL2. Communication +is initiated by the normal-world software + +* either directly through a Fast SMC (as defined in the [SMCCC]) + +* or indirectly through a [PSCI] SMC. The [PSCI] implementation in turn + informs the TSPD about the requested power management operation. This allows + the TSP to prepare for or respond to the power state change + +The TSPD service is responsible for. + +* Initializing the TSP + +* Routing requests and responses between the secure and the non-secure + states during the two types of communications just described + +### Initializing a BL3-2 Image + +The Secure-EL1 Payload Dispatcher (SPD) service is responsible for initializing +the BL3-2 image. It needs access to the information passed by BL2 to BL3-1 to do +so. Hence BL3-1 implements: + +1. `bl31_plat_get_bl32_mem_layout()` to return the extents of memory + available for BL3-2's use as communicated by BL2. + +2. `bl31_get_next_image_info(uint32_t security_state)` to return a reference + to the `el_change_info` structure corresponding to the next image which will + be run in the specified security state. The SPD uses this api with the + secure security state as the parameter to get entry related information about + BL3-2. + +In the absence of a BL3-2 image, BL3-1 passes control to the normal world +bootloader image (BL3-3). When the BL3-2 image is present, it is typical +that the SPD wants control to be passed to BL3-2 first and then later to BL3-3. + +To do this the SPD has to register a BL3-2 initialization function during +initialization of the SPD service. The BL3-2 initialization function has this +prototype: + + int32_t init(meminfo *bl32_meminfo); + +and is registered using the `bl31_register_bl32_init()` function. -### BL3-2 (Secure Payload) image initialization +Trusted Firmware supports two approaches for the SPD to pass control to BL3-2 +before returning through EL3 and running the non-trusted firmware (BL3-3): -BL2 is responsible for loading a BL3-2 image in memory specified by the platform. -BL3-1 provides an api that uses the entrypoint and memory layout information for -the BL3-2 image provided by BL2 to initialise BL3-2 in S-EL1. +1. In the BL3-2 initialization function, set up a secure context (see below + for more details of CPU context support) for this CPU and use + `bl31_set_next_image_type()` to request that the exit from `bl31_main()` is + to the BL3-2 entrypoint in Secure-EL1. + When the BL3-2 has completed initialization at Secure-EL1, it returns to + BL3-1 by issuing an SMC, using a Function ID allocated to the SPD. On + receipt of this SMC, the SPD service handler should switch the CPU context + from trusted to normal world and use the `bl31_set_next_image_type()` and + `bl31_prepare_next_image_entry()` functions to set up the initial return to + the normal world firmware BL3-3. On return from the handler the framework + will exit to EL2 and run BL3-3. -### Normal world software execution +2. In the BL3-2 initialization function, use an SPD-defined mechanism to + invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL3-2 + entrypoint. + NOTE: The Test SPD service included with the Trusted Firmware provides one + implementation of such a mechanism. -BL3-1 uses the entrypoint information provided by BL2 to jump to the normal -world software image (BL3-3) at the highest available Exception Level (EL2 if -available, otherwise EL1). + On completion BL3-2 returns control to BL3-1 via a SMC, and on receipt the + SPD service handler invokes the synchronous call return mechanism to return + to the BL3-2 initialization function. On return from this function, + `bl31_main()` will set up the return to the normal world firmware BL3-3 and + continue the boot process in the normal world. -3. Memory layout on FVP platforms +6. Memory layout on FVP platforms ---------------------------------- On FVP platforms, we use the Trusted ROM and Trusted SRAM to store the trusted @@ -659,7 +933,7 @@ following view: ------------ 0x04000000 -4. Firmware Image Package (FIP) +7. Firmware Image Package (FIP) -------------------------------- Using a Firmware Image Package (FIP) allows for packing bootloader images (and @@ -739,7 +1013,7 @@ Currently the FVPs policy only allows for loading of known images. The platform policy can be modified to add additional images. -5. Code Structure +8. Code Structure ------------------ Trusted Firmware code is logically divided between the three boot loader @@ -754,11 +1028,13 @@ following categories (present as directories in the source code): other code. * **Stage specific.** Code specific to a boot stage. * **Drivers.** +* **Services.** EL3 runtime services, e.g. PSCI or SPD. Specific SPD services + reside in the `services/spd` directory (e.g. `services/spd/tspd`). Each boot loader stage uses code from one or more of the above mentioned categories. Based upon the above, the code layout looks like this: - Directory Used by BL1? Used by BL2? Used by BL3? + Directory Used by BL1? Used by BL2? Used by BL3-1? bl1 Yes No No bl2 No Yes No bl31 No No Yes @@ -767,6 +1043,7 @@ categories. Based upon the above, the code layout looks like this: drivers Yes No Yes common Yes Yes Yes lib Yes Yes Yes + services No No Yes All assembler files have the `.S` extension. The linker source files for each boot stage have the extension `.ld.S`. These are processed by GCC to create the @@ -776,7 +1053,7 @@ FDTs provide a description of the hardware platform and are used by the Linux kernel at boot time. These can be found in the `fdts` directory. -6. References +9. References -------------- 1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md new file mode 100644 index 00000000..07394b05 --- /dev/null +++ b/docs/rt-svc-writers-guide.md @@ -0,0 +1,308 @@ +EL3 Runtime Service Writers Guide for ARM Trusted Firmware +========================================================== + +Contents +-------- + +1. Introduction +2. Owning Entities, Call Types and Function IDs +3. Getting started +4. Registering a runtime service +5. Initializing a runtime service +6. Handling runtime service requests +7. Services that contain multiple sub-services +8. Secure-EL1 Payload Dispatcher service (SPD) + +- - - - - - - - - - - - - - - - - - + +1. Introduction +---------------- + +This document describes how to add a runtime service to the EL3 Runtime +Firmware component of ARM Trusted Firmware (BL3-1). + +Software executing in the normal world and in the trusted world at exception +levels lower than EL3 will request runtime services using the Secure Monitor +Call (SMC) instruction. These requests will follow the convention described in +the SMC Calling Convention PDD ([SMCCC]). The [SMCCC] assigns function +identifiers to each SMC request and describes how arguments are passed and +results are returned. + +SMC Functions are grouped together based on the implementor of the service, for +example a subset of the Function IDs are designated as "OEM Calls" (see [SMCCC] +for full details). The EL3 runtime services framework in BL3-1 enables the +independent implementation of services for each group, which are then compiled +into the BL3-1 image. This simplifies the integration of common software from +ARM to support [PSCI], Secure Monitor for a Trusted OS and SoC specific +software. The common runtime services framework ensures that SMC Functions are +dispatched to their respective service implementation - the [Firmware Design] +provides details of how this is achieved. + +The interface and operation of the runtime services depends heavily on the +concepts and definitions described in the [SMCCC], in particular SMC Function +IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and +SMC64 calling conventions. Please refer to that document for a full explanation +of these terms. + + +2. Owning Entities, Call Types and Function IDs +------------------------------------------------ + +The SMC Function Identifier includes a OEN field. These values and their +meaning are described in [SMCCC] and summarized in table 1 below. Some entities +are allocated a range of of OENs. The OEN must be interpreted in conjunction +with the SMC call type, which is either _Fast_ or _Standard_. Fast calls are +uninterruptible whereas Standard calls can be pre-empted. The majority of +Owning Entities only have allocated ranges for Fast calls: Standard calls are +reserved exclusively for Trusted OS providers or for interoperability with +legacy 32-bit software that predates the [SMCCC]. + + Type OEN Service + Fast 0 ARM Architecture calls + Fast 1 CPU Service calls + Fast 2 SiP Service calls + Fast 3 OEM Service calls + Fast 4 Standard Service calls + Fast 5-47 Reserved for future use + Fast 48-49 Trusted Application calls + Fast 50-63 Trusted OS calls + + Std 0- 1 Reserved for existing ARMv7 calls + Std 2-63 Trusted OS Standard Calls + +_Table 1: Service types and their corresponding Owning Entity Numbers_ + +Each individual entity can allocate the valid identifiers within the entity +range as they need - it is not necessary to coordinate with other entities of +the same type. For example, two SoC providers can use the same Function ID +within the SiP Service calls OEN range to mean different things - as these +calls should be specific to the SoC. The Standard Runtime Calls OEN is used for +services defined by ARM standards, such as [PSCI]. + +The SMC Function ID also indicates whether the call has followed the SMC32 +calling convention, where all parameters are 32-bit, or the SMC64 calling +convention, where the parameters are 64-bit. The framework identifies and +rejects invalid calls that use the SMC64 calling convention but that originate +from an AArch32 caller. + +The EL3 runtime services framework uses the call type and OEN to identify a +specific handler for each SMC call, but it is expected that an individual +handler will be responsible for all SMC Functions within a given service type. + + +3. Getting started +------------------- + +ARM Trusted Firmware has a [`services`] directory in the source tree under +which each owning entity can place the implementation of its runtime service. +The [PSCI] implementation is located here in the [`services/psci`] directory. + +Runtime service sources will need to include the [`runtime_svc.h`] header file. + + +4. Registering a runtime service +--------------------------------- + +A runtime service is registered using the `DECLARE_RT_SVC()` macro, specifying +the name of the service, the range of OENs covered, the type of service and +initialization and call handler functions. + + #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch) + +* `_name` is used to identify the data structure declared by this macro, and + is also used for diagnostic purposes + +* `_start` and `_end` values must be based on the `OEN_*` values defined in + [`runtime_svc.h`] + +* `_type` must be one of `SMC_TYPE_FAST` or `SMC_TYPE_STD` + +* `_setup` is the initialization function with the `rt_svc_init` signature: + + typedef int32_t (*rt_svc_init)(void); + +* `_smch` is the SMC handler function with the `rt_svc_handle` signature: + + typedef uint64_t (*rt_svc_handle)(uint32_t smc_fid, + uint64_t x1, uint64_t x2, + uint64_t x3, uint64_t x4, + void *reserved, + void *handle, + uint64_t flags); + +Details of the requirements and behavior of the two callbacks is provided in +the following sections. + +During initialization the services framework validates each declared service +to ensure that the following conditions are met: + +1. The `_start` OEN is not greater than the `_end` OEN +2. The `_end` OEN does not exceed the maximum OEN value (63) +3. The `_type` is one of `SMC_TYPE_FAST` or `SMC_TYPE_STD` +4. `_setup` and `_smch` routines have been specified + +[`psci_steup.c`] provides an example of registering a runtime service: + + /* Register PSCI as a run time service */ + DECLARE_RT_SVC( + psci, + OEN_STD_START, + OEN_STD_END, + SMC_TYPE_FAST, + psci_setup, + psci_smc_handler + ); + + +5. Initializing a runtime service +--------------------------------- + +Runtime services are initialized once, during cold boot, by the primary CPU +after platform and architectural initialization is complete. The framework +performs basic validation of the declared service before calling +the service initialization function (`_setup` in the declaration). This +function must carry out any essential EL3 initialization prior to receiving a +SMC Function call via the handler function. + +On success, the initialization function must return `0`. Any other return value +will cause the framework to issue a diagnostic: + + Error initializing runtime service + +and then ignore the service - the system will continue to boot but SMC calls +will not be passed to the service handler and instead return the _Unknown SMC +Function ID_ result `0xFFFFFFFF`. + +If the system must not be allowed to proceed without the service, the +initialization function must itself cause the firmware boot to be halted. + +If the service uses per-CPU data this must either be initialized for all CPUs +during this call, or be done lazily when a CPU first issues an SMC call to that +service. + + +6. Handling runtime service requests +------------------------------------- + +SMC calls for a service are forwarded by the framework to the service's SMC +handler function (`_smch` in the service declaration). This function must have +the following signature: + + typedef uint64_t (*rt_svc_handle)(uint32_t smc_fid, + uint64_t x1, uint64_t x2, + uint64_t x3, uint64_t x4, + void *reserved, + void *handle, + uint64_t flags); + +The handler is responsible for: + +1. Determining that `smc_fid` is a valid and supported SMC Function ID, + otherwise completing the request with the _Unknown SMC Function ID_: + + SMC_RET1(handle, SMC_UNK); + +2. Determining if the requested function is valid for the calling security + state. SMC Calls can be made from both the normal and trusted worlds and + the framework will forward all calls to the service handler. + + The `flags` parameter to this function indicates the caller security state + in bit[0], where a value of `1` indicates a non-secure caller. The + `is_caller_secure(flags)` and `is_caller_non_secure(flags)` can be used to + test this condition. + + If invalid, the request should be completed with: + + SMC_RET1(handle, SMC_UNK); + +3. Truncating parameters for calls made using the SMC32 calling convention. + Such calls can be determined by checking the CC field in bit[30] of the + `smc_fid` parameter, for example by using: + + if (GET_SMC_CC(smc_fid) == SMC_32) ... + + For such calls, the upper bits of the parameters x1-x4 and the saved + parameters X5-X7 are UNDEFINED and must be explicitly ignored by the + handler. This can be done by truncating the values to a suitable 32-bit + integer type before use, for example by ensuring that functions defined + to handle individual SMC Functions use appropriate 32-bit parameters. + +4. Providing the service requested by the SMC Function, utilizing the + immediate parameters x1-x4 and/or the additional saved parameters X5-X7. + The latter can be retrieved using the `SMC_GET_GP(handle, ref)` function, + supplying the appropriate `CTX_GPREG_Xn` reference, e.g. + + uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6); + +5. Implementing the standard SMC32 Functions that provide information about + the implementation of the service. These are the Call Count, Implementor + UID and Revision Details for each service documented in section 6 of the + [SMCCC]. + + The ARM Trusted Firmware expects owning entities to follow this + recommendation. + +5. Returning the result to the caller. The [SMCCC] allows for up to 256 bits + of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The + framework provides a family of macros to set the multi-register return + value and complete the handler: + + SMC_RET1(handle, x0); + SMC_RET2(handle, x0, x1); + SMC_RET3(handle, x0, x1, x2); + SMC_RET4(handle, x0, x1, x2, x3); + +The `reserved` parameter to the handler is reserved for future use and can be +ignored. The value returned by a SMC handler is also reserved for future use - +completion of the handler function must always be via one of the `SMC_RETn()` +macros. + +NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow +all of the above requirements yet. + + +7. Services that contain multiple sub-services +----------------------------------------------- + +It is possible that a single owning entity implements multiple sub-services. For +example, the Standard calls service handles `0x84000000`-`0x8400FFFF` and +`0xC4000000`-`0xC400FFFF` functions. Within that range, the [PSCI] service +handles the `0x84000000`-`0x8400001F` and `0xC4000000`-`0xC400001F` functions. +In that respect, [PSCI] is a 'sub-service' of the Standard calls service. In +future, there could be additional such sub-services in the Standard calls +service which perform independent functions. + +In this situation it may be valuable to introduce a second level framework to +enable independent implementation of sub-services. Such a framework might look +very similar to the current runtime services framework, but using a different +part of the SMC Function ID to identify the sub-service. Trusted Firmware does +not provide such a framework at present. + + +8. Secure-EL1 Payload Dispatcher service (SPD) +----------------------------------------------- + +Services that handle SMC Functions targeting a Trusted OS, Trusted Application, +or other Secure-EL1 Payload are special. These services need to manage the +Secure-EL1 context, provide the _Secure Monitor_ functionality of switching +between the normal and secure worlds, deliver SMC Calls through to Secure-EL1 +and generally manage the Secure-EL1 Payload through CPU power-state transitions. + +TODO: Provide details of the additional work required to implement a SPD and +the BL3-1 support for these services. Or a reference to the document that will +provide this information.... + + +- - - - - - - - - - - - - - - - - - - - - - - - - - + +_Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._ + + +[Firmware Design]: ./firmware-design.md + +[`services`]: ../services +[`services/psci`]: ../services/psci +[`psci_steup.c`]: ../services/psci/psci_setup.c +[`runtime_svc.h`]: ../include/runtime_svc.h +[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)" +[SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)" -- 2.30.2