2.9. EL3 Runtime Service Writer’s Guide
2.9.1. Introduction
This document describes how to add a runtime service to the EL3 Runtime Firmware component of Trusted Firmware-A (TF-A), BL31.
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 BL31 enables the independent implementation of services for each group, which are then compiled into the BL31 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 document 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.9.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 Yielding. Fast calls are uninterruptible whereas Yielding calls can be pre-empted. The majority of Owning Entities only have allocated ranges for Fast calls: Yielding 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 Secure Service calls
Fast 5 Standard Hypervisor Service Calls
Fast 6 Vendor Specific Hypervisor Service Calls
Fast 7 Vendor Specific EL3 Monitor Calls
Fast 8-47 Reserved for future use
Fast 48-49 Trusted Application calls
Fast 50-63 Trusted OS calls
Yielding 0- 1 Reserved for existing Armv7-A calls
Yielding 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.
2.9.3. Getting started
TF-A 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 lib/psci
directory.
Runtime service sources will need to include the runtime_svc.h
header file.
2.9.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 theOEN_*
values defined insmccc.h
_type
must be one ofSMC_TYPE_FAST
orSMC_TYPE_YIELD
_setup
is the initialization function with thert_svc_init
signature:typedef int32_t (*rt_svc_init)(void);
_smch
is the SMC handler function with thert_svc_handle
signature:typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid, u_register_t x1, u_register_t x2, u_register_t x3, u_register_t x4, void *cookie, void *handle, u_register_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:
The
_start
OEN is not greater than the_end
OENThe
_end
OEN does not exceed the maximum OEN value (63)The
_type
is one ofSMC_TYPE_FAST
orSMC_TYPE_YIELD
_setup
and_smch
routines have been specified
std_svc_setup.c
provides an example of registering a runtime service:
/* Register Standard Service Calls as runtime service */
DECLARE_RT_SVC(
std_svc,
OEN_STD_START,
OEN_STD_END,
SMC_TYPE_FAST,
std_svc_setup,
std_svc_smc_handler
);
2.9.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 <name of the 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.
2.9.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 uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid,
u_register_t x1, u_register_t x2,
u_register_t x3, u_register_t x4,
void *cookie,
void *handle,
u_register_t flags);
The handler is responsible for:
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);
Determining if the requested function is valid for the calling security state. SMC Calls can be made from Non-secure, Secure or Realm worlds and the framework will forward all calls to the service handler.
The
flags
parameter to this function indicates the caller security state in bits 0 and 5. Theis_caller_secure(flags)
,is_caller_non_secure(flags)
andis_caller_realm(flags)
helper functions can be used to determine whether the caller’s security state is Secure, Non-secure or Realm respectively.If invalid, the request should be completed with:
SMC_RET1(handle, SMC_UNK);
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.
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 appropriateCTX_GPREG_Xn
reference, e.g.uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6);
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.
TF-A expects owning entities to follow this recommendation.
Returning the result to the caller. Based on SMCCC spec, results are returned in W0-W7(X0-X7) registers for SMC32(SMC64) calls from AArch64 state. Results are returned in R0-R7 registers for SMC32 calls from AArch32 state. The framework provides a family of macros to set the multi-register return value and complete the handler:
AArch64 state: SMC_RET1(handle, x0); SMC_RET2(handle, x0, x1); SMC_RET3(handle, x0, x1, x2); SMC_RET4(handle, x0, x1, x2, x3); SMC_RET5(handle, x0, x1, x2, x3, x4); SMC_RET6(handle, x0, x1, x2, x3, x4, x5); SMC_RET7(handle, x0, x1, x2, x3, x4, x5, x6); SMC_RET8(handle, x0, x1, x2, x3, x4, x5, x6, x7); AArch32 state: SMC_RET1(handle, r0); SMC_RET2(handle, r0, r1); SMC_RET3(handle, r0, r1, r2); SMC_RET4(handle, r0, r1, r2, r3); SMC_RET5(handle, r0, r1, r2, r3, r4); SMC_RET6(handle, r0, r1, r2, r3, r4, r5); SMC_RET7(handle, r0, r1, r2, r3, r4, r5, r6); SMC_RET8(handle, r0, r1, r2, r3, r4, r5, r6, r7);
The cookie
parameter to the handler is reserved for future use and can be
ignored. The handle
is returned by the SMC handler - 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.
2.9.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. TF-A does not provide such a framework at present.
2.9.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 BL31 support for these services. Or a reference to the document that will provide this information….
2.9.9. Additional References:
Copyright (c) 2014-2024, Arm Limited and Contributors. All rights reserved.