1EL3 Runtime Service Writers Guide for ARM Trusted Firmware 2========================================================== 3 4 5.. section-numbering:: 6 :suffix: . 7 8.. contents:: 9 10-------------- 11 12Introduction 13------------ 14 15This document describes how to add a runtime service to the EL3 Runtime 16Firmware component of ARM Trusted Firmware (BL31). 17 18Software executing in the normal world and in the trusted world at exception 19levels lower than EL3 will request runtime services using the Secure Monitor 20Call (SMC) instruction. These requests will follow the convention described in 21the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function 22identifiers to each SMC request and describes how arguments are passed and 23results are returned. 24 25SMC Functions are grouped together based on the implementor of the service, for 26example a subset of the Function IDs are designated as "OEM Calls" (see `SMCCC`_ 27for full details). The EL3 runtime services framework in BL31 enables the 28independent implementation of services for each group, which are then compiled 29into the BL31 image. This simplifies the integration of common software from 30ARM to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific 31software. The common runtime services framework ensures that SMC Functions are 32dispatched to their respective service implementation - the `Firmware Design`_ 33provides details of how this is achieved. 34 35The interface and operation of the runtime services depends heavily on the 36concepts and definitions described in the `SMCCC`_, in particular SMC Function 37IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and 38SMC64 calling conventions. Please refer to that document for a full explanation 39of these terms. 40 41Owning Entities, Call Types and Function IDs 42-------------------------------------------- 43 44The SMC Function Identifier includes a OEN field. These values and their 45meaning are described in `SMCCC`_ and summarized in table 1 below. Some entities 46are allocated a range of of OENs. The OEN must be interpreted in conjunction 47with the SMC call type, which is either *Fast* or *Yielding*. Fast calls are 48uninterruptible whereas Yielding calls can be pre-empted. The majority of 49Owning Entities only have allocated ranges for Fast calls: Yielding calls are 50reserved exclusively for Trusted OS providers or for interoperability with 51legacy 32-bit software that predates the `SMCCC`_. 52 53:: 54 55 Type OEN Service 56 Fast 0 ARM Architecture calls 57 Fast 1 CPU Service calls 58 Fast 2 SiP Service calls 59 Fast 3 OEM Service calls 60 Fast 4 Standard Service calls 61 Fast 5-47 Reserved for future use 62 Fast 48-49 Trusted Application calls 63 Fast 50-63 Trusted OS calls 64 65 Yielding 0- 1 Reserved for existing ARMv7 calls 66 Yielding 2-63 Trusted OS Standard Calls 67 68*Table 1: Service types and their corresponding Owning Entity Numbers* 69 70Each individual entity can allocate the valid identifiers within the entity 71range as they need - it is not necessary to coordinate with other entities of 72the same type. For example, two SoC providers can use the same Function ID 73within the SiP Service calls OEN range to mean different things - as these 74calls should be specific to the SoC. The Standard Runtime Calls OEN is used for 75services defined by ARM standards, such as `PSCI`_. 76 77The SMC Function ID also indicates whether the call has followed the SMC32 78calling convention, where all parameters are 32-bit, or the SMC64 calling 79convention, where the parameters are 64-bit. The framework identifies and 80rejects invalid calls that use the SMC64 calling convention but that originate 81from an AArch32 caller. 82 83The EL3 runtime services framework uses the call type and OEN to identify a 84specific handler for each SMC call, but it is expected that an individual 85handler will be responsible for all SMC Functions within a given service type. 86 87Getting started 88--------------- 89 90ARM Trusted Firmware has a `services`_ directory in the source tree under which 91each owning entity can place the implementation of its runtime service. The 92`PSCI`_ implementation is located here in the `lib/psci`_ directory. 93 94Runtime service sources will need to include the `runtime\_svc.h`_ header file. 95 96Registering a runtime service 97----------------------------- 98 99A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying 100the name of the service, the range of OENs covered, the type of service and 101initialization and call handler functions. 102 103:: 104 105 #define DECLARE_RT_SVC(_name, _start, _end, _type, _setup, _smch) 106 107- ``_name`` is used to identify the data structure declared by this macro, and 108 is also used for diagnostic purposes 109 110- ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in 111 `smcc.h`_ 112 113- ``_type`` must be one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD`` 114 115- ``_setup`` is the initialization function with the ``rt_svc_init`` signature: 116 117 .. code:: c 118 119 typedef int32_t (*rt_svc_init)(void); 120 121- ``_smch`` is the SMC handler function with the ``rt_svc_handle`` signature: 122 123 .. code:: c 124 125 typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid, 126 u_register_t x1, u_register_t x2, 127 u_register_t x3, u_register_t x4, 128 void *cookie, 129 void *handle, 130 u_register_t flags); 131 132Details of the requirements and behavior of the two callbacks is provided in 133the following sections. 134 135During initialization the services framework validates each declared service 136to ensure that the following conditions are met: 137 138#. The ``_start`` OEN is not greater than the ``_end`` OEN 139#. The ``_end`` OEN does not exceed the maximum OEN value (63) 140#. The ``_type`` is one of ``SMC_TYPE_FAST`` or ``SMC_TYPE_YIELD`` 141#. ``_setup`` and ``_smch`` routines have been specified 142 143`std\_svc\_setup.c`_ provides an example of registering a runtime service: 144 145.. code:: c 146 147 /* Register Standard Service Calls as runtime service */ 148 DECLARE_RT_SVC( 149 std_svc, 150 OEN_STD_START, 151 OEN_STD_END, 152 SMC_TYPE_FAST, 153 std_svc_setup, 154 std_svc_smc_handler 155 ); 156 157Initializing a runtime service 158------------------------------ 159 160Runtime services are initialized once, during cold boot, by the primary CPU 161after platform and architectural initialization is complete. The framework 162performs basic validation of the declared service before calling 163the service initialization function (``_setup`` in the declaration). This 164function must carry out any essential EL3 initialization prior to receiving a 165SMC Function call via the handler function. 166 167On success, the initialization function must return ``0``. Any other return value 168will cause the framework to issue a diagnostic: 169 170:: 171 172 Error initializing runtime service <name of the service> 173 174and then ignore the service - the system will continue to boot but SMC calls 175will not be passed to the service handler and instead return the *Unknown SMC 176Function ID* result ``0xFFFFFFFF``. 177 178If the system must not be allowed to proceed without the service, the 179initialization function must itself cause the firmware boot to be halted. 180 181If the service uses per-CPU data this must either be initialized for all CPUs 182during this call, or be done lazily when a CPU first issues an SMC call to that 183service. 184 185Handling runtime service requests 186--------------------------------- 187 188SMC calls for a service are forwarded by the framework to the service's SMC 189handler function (``_smch`` in the service declaration). This function must have 190the following signature: 191 192.. code:: c 193 194 typedef uintptr_t (*rt_svc_handle_t)(uint32_t smc_fid, 195 u_register_t x1, u_register_t x2, 196 u_register_t x3, u_register_t x4, 197 void *cookie, 198 void *handle, 199 u_register_t flags); 200 201The handler is responsible for: 202 203#. Determining that ``smc_fid`` is a valid and supported SMC Function ID, 204 otherwise completing the request with the *Unknown SMC Function ID*: 205 206 .. code:: c 207 208 SMC_RET1(handle, SMC_UNK); 209 210#. Determining if the requested function is valid for the calling security 211 state. SMC Calls can be made from both the normal and trusted worlds and 212 the framework will forward all calls to the service handler. 213 214 The ``flags`` parameter to this function indicates the caller security state 215 in bit[0], where a value of ``1`` indicates a non-secure caller. The 216 ``is_caller_secure(flags)`` and ``is_caller_non_secure(flags)`` can be used to 217 test this condition. 218 219 If invalid, the request should be completed with: 220 221 .. code:: c 222 223 SMC_RET1(handle, SMC_UNK); 224 225#. Truncating parameters for calls made using the SMC32 calling convention. 226 Such calls can be determined by checking the CC field in bit[30] of the 227 ``smc_fid`` parameter, for example by using: 228 229 :: 230 231 if (GET_SMC_CC(smc_fid) == SMC_32) ... 232 233 For such calls, the upper bits of the parameters x1-x4 and the saved 234 parameters X5-X7 are UNDEFINED and must be explicitly ignored by the 235 handler. This can be done by truncating the values to a suitable 32-bit 236 integer type before use, for example by ensuring that functions defined 237 to handle individual SMC Functions use appropriate 32-bit parameters. 238 239#. Providing the service requested by the SMC Function, utilizing the 240 immediate parameters x1-x4 and/or the additional saved parameters X5-X7. 241 The latter can be retrieved using the ``SMC_GET_GP(handle, ref)`` function, 242 supplying the appropriate ``CTX_GPREG_Xn`` reference, e.g. 243 244 .. code:: c 245 246 uint64_t x6 = SMC_GET_GP(handle, CTX_GPREG_X6); 247 248#. Implementing the standard SMC32 Functions that provide information about 249 the implementation of the service. These are the Call Count, Implementor 250 UID and Revision Details for each service documented in section 6 of the 251 `SMCCC`_. 252 253 The ARM Trusted Firmware expects owning entities to follow this 254 recommendation. 255 256#. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits 257 of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The 258 framework provides a family of macros to set the multi-register return 259 value and complete the handler: 260 261 .. code:: c 262 263 SMC_RET1(handle, x0); 264 SMC_RET2(handle, x0, x1); 265 SMC_RET3(handle, x0, x1, x2); 266 SMC_RET4(handle, x0, x1, x2, x3); 267 268The ``cookie`` parameter to the handler is reserved for future use and can be 269ignored. The ``handle`` is returned by the SMC handler - completion of the 270handler function must always be via one of the ``SMC_RETn()`` macros. 271 272NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow 273all of the above requirements yet. 274 275Services that contain multiple sub-services 276------------------------------------------- 277 278It is possible that a single owning entity implements multiple sub-services. For 279example, the Standard calls service handles ``0x84000000``-``0x8400FFFF`` and 280``0xC4000000``-``0xC400FFFF`` functions. Within that range, the `PSCI`_ service 281handles the ``0x84000000``-``0x8400001F`` and ``0xC4000000``-``0xC400001F`` functions. 282In that respect, `PSCI`_ is a 'sub-service' of the Standard calls service. In 283future, there could be additional such sub-services in the Standard calls 284service which perform independent functions. 285 286In this situation it may be valuable to introduce a second level framework to 287enable independent implementation of sub-services. Such a framework might look 288very similar to the current runtime services framework, but using a different 289part of the SMC Function ID to identify the sub-service. Trusted Firmware does 290not provide such a framework at present. 291 292Secure-EL1 Payload Dispatcher service (SPD) 293------------------------------------------- 294 295Services that handle SMC Functions targeting a Trusted OS, Trusted Application, 296or other Secure-EL1 Payload are special. These services need to manage the 297Secure-EL1 context, provide the *Secure Monitor* functionality of switching 298between the normal and secure worlds, deliver SMC Calls through to Secure-EL1 299and generally manage the Secure-EL1 Payload through CPU power-state transitions. 300 301TODO: Provide details of the additional work required to implement a SPD and 302the BL31 support for these services. Or a reference to the document that will 303provide this information.... 304 305-------------- 306 307*Copyright (c) 2014-2015, ARM Limited and Contributors. All rights reserved.* 308 309.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html 310.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf 311.. _Firmware Design: ./firmware-design.rst 312.. _services: ../services 313.. _lib/psci: ../lib/psci 314.. _runtime\_svc.h: ../include/common/runtime_svc.h 315.. _smcc.h: ../include/lib/smcc.h 316.. _std\_svc\_setup.c: ../services/std_svc/std_svc_setup.c 317