blob: 4d0016b84c858ca93b47695ef89a007f58440a58 [file] [log] [blame]
Dan Handley610e7e12018-03-01 18:44:00 +00001Trusted Firmware-A EL3 runtime service writer's guide
2=====================================================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
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
Dan Handley610e7e12018-03-01 18:44:00 +000016Firmware component of Trusted Firmware-A (TF-A), BL31.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010017
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
Dan Handley610e7e12018-03-01 18:44:00 +000030Arm to support `PSCI`_, Secure Monitor for a Trusted OS and SoC specific
Douglas Raillardd7c21b72017-06-28 15:23:03 +010031software. 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
Dan Handley610e7e12018-03-01 18:44:00 +000056 Fast 0 Arm Architecture calls
Douglas Raillardd7c21b72017-06-28 15:23:03 +010057 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
Dan Handley610e7e12018-03-01 18:44:00 +000065 Yielding 0- 1 Reserved for existing Armv7-A calls
Douglas Raillardd7c21b72017-06-28 15:23:03 +010066 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
Dan Handley610e7e12018-03-01 18:44:00 +000075services defined by Arm standards, such as `PSCI`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010076
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
Dan Handley610e7e12018-03-01 18:44:00 +000090TF-A has a `services`_ directory in the source tree under which
Douglas Raillardd7c21b72017-06-28 15:23:03 +010091each 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
Dan Handley610e7e12018-03-01 18:44:00 +0000253 TF-A expects owning entities to follow this recommendation.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100254
255#. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits
256 of return value in SMC64 using X0-X3 and 128 bits in SMC32 using W0-W3. The
257 framework provides a family of macros to set the multi-register return
258 value and complete the handler:
259
260 .. code:: c
261
262 SMC_RET1(handle, x0);
263 SMC_RET2(handle, x0, x1);
264 SMC_RET3(handle, x0, x1, x2);
265 SMC_RET4(handle, x0, x1, x2, x3);
266
267The ``cookie`` parameter to the handler is reserved for future use and can be
268ignored. The ``handle`` is returned by the SMC handler - completion of the
269handler function must always be via one of the ``SMC_RETn()`` macros.
270
271NOTE: The PSCI and Test Secure-EL1 Payload Dispatcher services do not follow
272all of the above requirements yet.
273
274Services that contain multiple sub-services
275-------------------------------------------
276
277It is possible that a single owning entity implements multiple sub-services. For
278example, the Standard calls service handles ``0x84000000``-``0x8400FFFF`` and
279``0xC4000000``-``0xC400FFFF`` functions. Within that range, the `PSCI`_ service
280handles the ``0x84000000``-``0x8400001F`` and ``0xC4000000``-``0xC400001F`` functions.
281In that respect, `PSCI`_ is a 'sub-service' of the Standard calls service. In
282future, there could be additional such sub-services in the Standard calls
283service which perform independent functions.
284
285In this situation it may be valuable to introduce a second level framework to
286enable independent implementation of sub-services. Such a framework might look
287very similar to the current runtime services framework, but using a different
Dan Handley610e7e12018-03-01 18:44:00 +0000288part of the SMC Function ID to identify the sub-service. TF-A does not provide
289such a framework at present.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100290
291Secure-EL1 Payload Dispatcher service (SPD)
292-------------------------------------------
293
294Services that handle SMC Functions targeting a Trusted OS, Trusted Application,
295or other Secure-EL1 Payload are special. These services need to manage the
296Secure-EL1 context, provide the *Secure Monitor* functionality of switching
297between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
298and generally manage the Secure-EL1 Payload through CPU power-state transitions.
299
300TODO: Provide details of the additional work required to implement a SPD and
301the BL31 support for these services. Or a reference to the document that will
302provide this information....
303
304--------------
305
Dan Handley610e7e12018-03-01 18:44:00 +0000306*Copyright (c) 2014-2018, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100307
308.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
309.. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
310.. _Firmware Design: ./firmware-design.rst
311.. _services: ../services
312.. _lib/psci: ../lib/psci
313.. _runtime\_svc.h: ../include/common/runtime_svc.h
314.. _smcc.h: ../include/lib/smcc.h
315.. _std\_svc\_setup.c: ../services/std_svc/std_svc_setup.c