diff --git a/docs/diagrams/rt-svc-descs-layout.png b/docs/diagrams/rt-svc-descs-layout.png new file mode 100644 index 0000000..1a9fa5b --- /dev/null +++ b/docs/diagrams/rt-svc-descs-layout.png Binary files differ diff --git a/docs/firmware-design.md b/docs/firmware-design.md index 89dd45f..4e7890e 100644 --- a/docs/firmware-design.md +++ b/docs/firmware-design.md @@ -4,11 +4,14 @@ 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 @@ 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 @@ * 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 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]. + 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-2 (Secure Payload) image initialization +3. EL3 runtime services framework +---------------------------------- -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. +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]. -### Normal world software execution +### Registration -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). +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. -3. Memory layout on FVP platforms +### 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. + +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): + +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. + +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. + + 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. + + +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 @@ ------------ 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 @@ 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 @@ 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 @@ 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 @@ 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 0000000..07394b0 --- /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)"