• Home
  • Raw
  • Download

Lines Matching refs:the

15 This document describes how to add a runtime service to the EL3 Runtime
18 Software executing in the normal world and in the trusted world at exception
19 levels lower than EL3 will request runtime services using the Secure Monitor
20 Call (SMC) instruction. These requests will follow the convention described in
21 the SMC Calling Convention PDD (`SMCCC`_). The `SMCCC`_ assigns function
25 SMC Functions are grouped together based on the implementor of the service, for
26 example a subset of the Function IDs are designated as "OEM Calls" (see `SMCCC`_
27 for full details). The EL3 runtime services framework in BL31 enables the
29 into the BL31 image. This simplifies the integration of common software from
32 dispatched to their respective service implementation - the `Firmware Design`_
35 The interface and operation of the runtime services depends heavily on the
36 concepts and definitions described in the `SMCCC`_, in particular SMC Function
37 IDs, Owning Entity Numbers (OEN), Fast and Standard calls, and the SMC32 and
47 with the SMC call type, which is either *Fast* or *Yielding*. Fast calls are
51 legacy 32-bit software that predates the `SMCCC`_.
70 Each individual entity can allocate the valid identifiers within the entity
72 the same type. For example, two SoC providers can use the same Function ID
73 within the SiP Service calls OEN range to mean different things - as these
74 calls should be specific to the SoC. The Standard Runtime Calls OEN is used for
77 The SMC Function ID also indicates whether the call has followed the SMC32
78 calling convention, where all parameters are 32-bit, or the SMC64 calling
79 convention, where the parameters are 64-bit. The framework identifies and
80 rejects invalid calls that use the SMC64 calling convention but that originate
83 The EL3 runtime services framework uses the call type and OEN to identify a
90 ARM Trusted Firmware has a `services`_ directory in the source tree under which
91 each owning entity can place the implementation of its runtime service. The
92 `PSCI`_ implementation is located here in the `lib/psci`_ directory.
94 Runtime service sources will need to include the `runtime\_svc.h`_ header file.
99 A runtime service is registered using the ``DECLARE_RT_SVC()`` macro, specifying
100 the name of the service, the range of OENs covered, the type of service and
107 - ``_name`` is used to identify the data structure declared by this macro, and
110 - ``_start`` and ``_end`` values must be based on the ``OEN_*`` values defined in
115 - ``_setup`` is the initialization function with the ``rt_svc_init`` signature:
121 - ``_smch`` is the SMC handler function with the ``rt_svc_handle`` signature:
132 Details of the requirements and behavior of the two callbacks is provided in
133 the following sections.
135 During initialization the services framework validates each declared service
136 to ensure that the following conditions are met:
138 #. The ``_start`` OEN is not greater than the ``_end`` OEN
139 #. The ``_end`` OEN does not exceed the maximum OEN value (63)
160 Runtime services are initialized once, during cold boot, by the primary CPU
162 performs basic validation of the declared service before calling
163 the service initialization function (``_setup`` in the declaration). This
165 SMC Function call via the handler function.
167 On success, the initialization function must return ``0``. Any other return value
168 will cause the framework to issue a diagnostic:
172 Error initializing runtime service <name of the service>
174 and then ignore the service - the system will continue to boot but SMC calls
175 will not be passed to the service handler and instead return the *Unknown SMC
178 If the system must not be allowed to proceed without the service, the
179 initialization function must itself cause the firmware boot to be halted.
181 If the service uses per-CPU data this must either be initialized for all CPUs
188 SMC calls for a service are forwarded by the framework to the service's SMC
189 handler function (``_smch`` in the service declaration). This function must have
190 the following signature:
204 otherwise completing the request with the *Unknown SMC Function ID*:
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.
214 The ``flags`` parameter to this function indicates the caller security state
219 If invalid, the request should be completed with:
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
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
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.
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
256 #. Returning the result to the caller. The `SMCCC`_ allows for up to 256 bits
258 framework provides a family of macros to set the multi-register return
259 value and complete the handler:
268 The ``cookie`` parameter to the handler is reserved for future use and can be
269 ignored. The ``handle`` is returned by the SMC handler - completion of the
270 handler function must always be via one of the ``SMC_RETn()`` macros.
273 all of the above requirements yet.
279 example, the Standard calls service handles ``0x84000000``-``0x8400FFFF`` and
280 ``0xC4000000``-``0xC400FFFF`` functions. Within that range, the `PSCI`_ service
281 handles the ``0x84000000``-``0x8400001F`` and ``0xC4000000``-``0xC400001F`` functions.
282 In that respect, `PSCI`_ is a 'sub-service' of the Standard calls service. In
283 future, there could be additional such sub-services in the Standard calls
288 very similar to the current runtime services framework, but using a different
289 part of the SMC Function ID to identify the sub-service. Trusted Firmware does
296 or other Secure-EL1 Payload are special. These services need to manage the
297 Secure-EL1 context, provide the *Secure Monitor* functionality of switching
298 between the normal and secure worlds, deliver SMC Calls through to Secure-EL1
299 and generally manage the Secure-EL1 Payload through CPU power-state transitions.
301 TODO: Provide details of the additional work required to implement a SPD and
302 the BL31 support for these services. Or a reference to the document that will