blob: b767958334dc9ab9c86339256f6ab87752d87c38 [file] [log] [blame]
Javier Almansa Sobrino37bf69c2022-04-07 18:26:49 +01001RMM-EL3 Communication interface
2*******************************
3
4This document defines the communication interface between RMM and EL3.
5There are two parts in this interface: the boot interface and the runtime
6interface.
7
8The Boot Interface defines the ABI between EL3 and RMM when the CPU enters
9R-EL2 for the first time after boot. The cold boot interface defines the ABI
10for the cold boot path and the warm boot interface defines the same for the
11warm path.
12
13The RMM-EL3 runtime interface defines the ABI for EL3 services which can be
14invoked by RMM as well as the register save-restore convention when handling an
15SMC call from NS.
16
17The below sections discuss these interfaces more in detail.
18
19.. _rmm_el3_ifc_versioning:
20
21RMM-EL3 Interface versioning
22____________________________
23
24The RMM Boot and Runtime Interface uses a version number to check
25compatibility with the register arguments passed as part of Boot Interface and
26RMM-EL3 runtime interface.
27
28The Boot Manifest, discussed later in section :ref:`rmm_el3_boot_manifest`,
29uses a separate version number but with the same scheme.
30
31The version number is a 32-bit type with the following fields:
32
33.. csv-table::
34 :header: "Bits", "Value"
35
36 [0:15],``VERSION_MINOR``
37 [16:30],``VERSION_MAJOR``
38 [31],RES0
39
40The version numbers are sequentially increased and the rules for updating them
41are explained below:
42
43 - ``VERSION_MAJOR``: This value is increased when changes break
44 compatibility with previous versions. If the changes
45 on the ABI are compatible with the previous one, ``VERSION_MAJOR``
46 remains unchanged.
47
48 - ``VERSION_MINOR``: This value is increased on any change that is backwards
49 compatible with the previous version. When ``VERSION_MAJOR`` is increased,
50 ``VERSION_MINOR`` must be set to 0.
51
52 - ``RES0``: Bit 31 of the version number is reserved 0 as to maintain
53 consistency with the versioning schemes used in other parts of RMM.
54
55This document specifies the 0.1 version of Boot Interface ABI and RMM-EL3
56services specification and the 0.1 version of the Boot Manifest.
57
58.. _rmm_el3_boot_interface:
59
60RMM Boot Interface
61__________________
62
63This section deals with the Boot Interface part of the specification.
64
65One of the goals of the Boot Interface is to allow EL3 firmware to pass
66down into RMM certain platform specific information dynamically. This allows
67RMM to be less platform dependent and be more generic across platform
68variations. It also allows RMM to be decoupled from the other boot loader
69images in the boot sequence and remain agnostic of any particular format used
70for configuration files.
71
72The Boot Interface ABI defines a set of register conventions and
73also a memory based manifest file to pass information from EL3 to RMM. The
74boot manifest and the associated platform data in it can be dynamically created
75by EL3 and there is no restriction on how the data can be obtained (e.g by DTB,
76hoblist or other).
77
78The register convention and the manifest are versioned separately to manage
79future enhancements and compatibility.
80
81RMM completes the boot by issuing the ``RMM_BOOT_COMPLETE`` SMC (0xC40001CF)
82back to EL3. After the RMM has finished the boot process, it can only be
83entered from EL3 as part of RMI handling.
84
85If RMM returns an error during boot (in any CPU), then RMM must not be entered
86from any CPU.
87
88.. _rmm_cold_boot_interface:
89
90Cold Boot Interface
91~~~~~~~~~~~~~~~~~~~
92
93During cold boot RMM expects the following register values:
94
95.. csv-table::
96 :header: "Register", "Value"
97 :widths: 1, 5
98
99 x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of CPUs to be supported at runtime (see x2).
100 x1,Version for this Boot Interface as defined in :ref:`rmm_el3_ifc_versioning`.
101 x2,Maximum number of CPUs to be supported at runtime. RMM should ensure that it can support this maximum number.
102 x3,Base address for the shared buffer used for communication between EL3 firmware and RMM. This buffer must be of 4KB size (1 page). The boot manifest must be present at the base of this shared buffer during cold boot.
103
104During cold boot, EL3 firmware needs to allocate a 4K page that will be
105passed to RMM in x3. This memory will be used as shared buffer for communication
106between EL3 and RMM. It must be assigned to Realm world and must be mapped with
107Normal memory attributes (IWB-OWB-ISH) at EL3. At boot, this memory will be
108used to populate the Boot Manifest. Since the Boot Manifest can be accessed by
109RMM prior to enabling its MMU, EL3 must ensure that proper cache maintenance
110operations are performed after the Boot Manifest is populated.
111
112EL3 should also ensure that this shared buffer is always available for use by RMM
113during the lifetime of the system and that it can be used for runtime
114communication between RMM and EL3. For example, when RMM invokes attestation
115service commands in EL3, this buffer can be used to exchange data between RMM
116and EL3. It is also allowed for RMM to invoke runtime services provided by EL3
117utilizing this buffer during the boot phase, prior to return back to EL3 via
118RMM_BOOT_COMPLETE SMC.
119
120RMM should map this memory page into its Stage 1 page-tables using Normal
121memory attributes.
122
123During runtime, it is the RMM which initiates any communication with EL3. If that
124communication requires the use of the shared area, it is expected that RMM needs
125to do the necessary concurrency protection to prevent the use of the same buffer
126by other PEs.
127
128The following sequence diagram shows how a generic EL3 Firmware would boot RMM.
129
130.. image:: ../resources/diagrams/rmm_cold_boot_generic.png
131
132Warm Boot Interface
133~~~~~~~~~~~~~~~~~~~
134
135At warm boot, RMM is already initialized and only some per-CPU initialization
136is still pending. The only argument that is required by RMM at this stage is
137the CPU Id, which will be passed through register x0 whilst x1 to x3 are RES0.
138This is summarized in the following table:
139
140.. csv-table::
141 :header: "Register", "Value"
142 :widths: 1, 5
143
144 x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of CPUs to be supported at runtime (see x2).
145 x1 - x3,RES0
146
147Boot error handling and return values
148~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
149
150After boot up and initialization, RMM returns control back to EL3 through a
151``RMM_BOOT_COMPLETE`` SMC call. The only argument of this SMC call will
152be returned in x1 and it will encode a signed integer with the error reason
153as per the following table:
154
155.. csv-table::
156 :header: "Error code", "Description", "ID"
157 :widths: 2 4 1
158
159 ``E_RMM_BOOT_SUCCESS``,Boot successful,0
160 ``E_RMM_BOOT_ERR_UNKNOWN``,Unknown error,-1
161 ``E_RMM_BOOT_VERSION_NOT_VALID``,Boot Interface version reported by EL3 is not supported by RMM,-2
162 ``E_RMM_BOOT_CPUS_OUT_OF_RAGE``,Number of CPUs reported by EL3 larger than maximum supported by RMM,-3
163 ``E_RMM_BOOT_CPU_ID_OUT_OF_RAGE``,Current CPU Id is higher or equal than the number of CPUs supported by RMM,-4
164 ``E_RMM_BOOT_INVALID_SHARED_BUFFER``,Invalid pointer to shared memory area,-5
165 ``E_RMM_BOOT_MANIFEST_VERSION_NOT_SUPPORTED``,Version reported by the boot manifest not supported by RMM,-6
166 ``E_RMM_BOOT_MANIFEST_DATA_ERROR``,Error parsing core boot manifest,-7
167
168For any error detected in RMM during cold or warm boot, RMM will return back to
169EL3 using ``RMM_BOOT_COMPLETE`` SMC with an appropriate error code. It is
170expected that EL3 will take necessary action to disable Realm world for further
171entry from NS Host on receiving an error. This will be done across all the PEs
172in the system so as to present a symmetric view to the NS Host. Any further
173warm boot by any PE should not enter RMM using the warm boot interface.
174
175.. _rmm_el3_boot_manifest:
176
177Boot Manifest
178~~~~~~~~~~~~~
179
180During cold boot, EL3 Firmware passes a memory boot manifest to RMM containing
181platform information.
182
183This boot manifest is versioned independently of the boot interface, to help
184evolve the boot manifest independent of the rest of Boot Manifest.
185The current version for the boot manifest is ``v0.1`` and the rules explained
186in :ref:`rmm_el3_ifc_versioning` apply on this version as well.
187
188The boot manifest is divided into two different components:
189
190 - Core Manifest: This is the generic parameters passed to RMM by EL3 common to all platforms.
191 - Platform data: This is defined by the platform owner and contains information specific to that platform.
192
193For the current version of the manifest, the core manifest contains a pointer
194to the platform data. EL3 must ensure that the whole boot manifest,
195including the platform data, if available, fits inside the RMM EL3 shared
196buffer.
197
198For the type specification of the RMM Boot Manifest v0.1, refer to
199:ref:`rmm_el3_manifest_struct`
200
201.. _runtime_services_and_interface:
202
Javier Almansa Sobrinof809b162022-07-04 17:06:36 +0100203RMM-EL3 Runtime Interface
Javier Almansa Sobrino37bf69c2022-04-07 18:26:49 +0100204__________________________
205
206This section defines the RMM-EL3 runtime interface which specifies the ABI for
207EL3 services expected by RMM at runtime as well as the register save and
208restore convention between EL3 and RMM as part of RMI call handling. It is
209important to note that RMM is allowed to invoke EL3-RMM runtime interface
210services during the boot phase as well. The EL3 runtime service handling must
211not result in a world switch to another world unless specified. Both the RMM
212and EL3 are allowed to make suitable optimizations based on this assumption.
213
214If the interface requires the use of memory, then the memory references should
215be within the shared buffer communicated as part of the boot interface. See
216:ref:`rmm_cold_boot_interface` for properties of this shared buffer which both
217EL3 and RMM must adhere to.
218
219RMM-EL3 runtime service return codes
220~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221
222The return codes from EL3 to RMM is a 32 bit signed integer which encapsulates
223error condition as described in the following table:
224
225.. csv-table::
226 :header: "Error code", "Description", "ID"
227 :widths: 2 4 1
228
229 ``E_RMM_OK``,No errors detected,0
230 ``E_RMM_UNK``,Unknown/Generic error,-1
231 ``E_RMM_BAD_ADDR``,The value of an address used as argument was invalid,-2
232 ``E_RMM_BAD_PAS``,Incorrect PAS,-3
233 ``E_RMM_NOMEM``,Not enough memory to perform an operation,-4
234 ``E_RMM_INVAL``,The value of an argument was invalid,-5
235
236If multiple failure conditions are detected in an RMM to EL3 command, then EL3
237is allowed to return an error code corresponding to any of the failure
238conditions.
239
240RMM-EL3 runtime services
241~~~~~~~~~~~~~~~~~~~~~~~~
242
243The following table summarizes the RMM runtime services that need to be
244implemented by EL3 Firmware.
245
246.. csv-table::
247 :header: "FID", "Command"
248 :widths: 2 5
249
Javier Almansa Sobrinof809b162022-07-04 17:06:36 +0100250 0xC400018F,``RMM_RMI_REQ_COMPLETE``
251 0xC40001B0,``RMM_GTSI_DELEGATE``
252 0xC40001B1,``RMM_GTSI_UNDELEGATE``
Javier Almansa Sobrino37bf69c2022-04-07 18:26:49 +0100253 0xC40001B2,``RMM_ATTEST_GET_REALM_KEY``
254 0xC40001B3,``RMM_ATTEST_GET_PLAT_TOKEN``
255
Javier Almansa Sobrinof809b162022-07-04 17:06:36 +0100256RMM_RMI_REQ_COMPLETE command
257============================
258
259Notifies the completion of an RMI call to the Non-Secure world.
260
261This call is the only function currently in RMM-EL3 runtime interface which
262results in a world switch to NS. This call is the reply to the original RMI
263call and it is forwarded by EL3 to the NS world.
264
265FID
266---
267
268``0xC400018F``
269
270Input values
271------------
272
273.. csv-table::
274 :header: "Name", "Register", "Field", "Type", "Description"
275 :widths: 1 1 1 1 5
276
277 fid,x0,[63:0],UInt64,Command FID
278 err_code,x1,[63:0],RmiCommandReturnCode,Error code returned by the RMI service invoked by NS World. See Realm Management Monitor specification for more info
279
280Output values
281-------------
282
283This call does not return.
284
285Failure conditions
286------------------
287
288Since this call does not return to RMM, there is no failure condition which
289can be notified back to RMM.
290
291RMM_GTSI_DELEGATE command
292=========================
293
294Delegate a memory granule by changing its PAS from Non-Secure to Realm.
295
296FID
297---
298
299``0xC40001B0``
300
301Input values
302------------
303
304.. csv-table::
305 :header: "Name", "Register", "Field", "Type", "Description"
306 :widths: 1 1 1 1 5
307
308 fid,x0,[63:0],UInt64,Command FID
309 base_pa,x1,[63:0],Address,PA of the start of the granule to be delegated
310
311Output values
312-------------
313
314.. csv-table::
315 :header: "Name", "Register", "Field", "Type", "Description"
316 :widths: 1 1 1 2 4
317
318 Result,x0,[63:0],Error Code,Command return status
319
320Failure conditions
321------------------
322
323The table below shows all the possible error codes returned in ``Result`` upon
324a failure. The errors are ordered by condition check.
325
326.. csv-table::
327 :header: "ID", "Condition"
328 :widths: 1 5
329
330 ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address
331 ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Non-Secure PAS
332 ``E_RMM_OK``,No errors detected
333
334RMM_GTSI_UNDELEGATE command
335===========================
336
337Undelegate a memory granule by changing its PAS from Realm to Non-Secure.
338
339FID
340---
341
342``0xC40001B1``
343
344Input values
345------------
346
347.. csv-table::
348 :header: "Name", "Register", "Field", "Type", "Description"
349 :widths: 1 1 1 1 5
350
351 fid,x0,[63:0],UInt64,Command FID
352 base_pa,x1,[63:0],Address,PA of the start of the granule to be undelegated
353
354Output values
355-------------
356
357.. csv-table::
358 :header: "Name", "Register", "Field", "Type", "Description"
359 :widths: 1 1 1 2 4
360
361 Result,x0,[63:0],Error Code,Command return status
362
363Failure conditions
364------------------
365
366The table below shows all the possible error codes returned in ``Result`` upon
367a failure. The errors are ordered by condition check.
368
369.. csv-table::
370 :header: "ID", "Condition"
371 :widths: 1 5
372
373 ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address
374 ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Realm PAS
375 ``E_RMM_OK``,No errors detected
376
Javier Almansa Sobrino37bf69c2022-04-07 18:26:49 +0100377RMM_ATTEST_GET_REALM_KEY command
378================================
379
380Retrieve the Realm Attestation Token Signing key from EL3.
381
382FID
383---
384
385``0xC40001B2``
386
387Input values
388------------
389
390.. csv-table::
391 :header: "Name", "Register", "Field", "Type", "Description"
392 :widths: 1 1 1 1 5
393
394 fid,x0,[63:0],UInt64,Command FID
395 buf_pa,x1,[63:0],Address,PA where the Realm Attestation Key must be stored by EL3. The PA must belong to the shared buffer
396 buf_size,x2,[63:0],Size,Size in bytes of the Realm Attestation Key buffer. ``bufPa + bufSize`` must lie within the shared buffer
397 ecc_curve,x3,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves`
398
399Output values
400-------------
401
402.. csv-table::
403 :header: "Name", "Register", "Field", "Type", "Description"
404 :widths: 1 1 1 1 5
405
406 Result,x0,[63:0],Error Code,Command return status
407 keySize,x1,[63:0],Size,Size of the Realm Attestation Key
408
409Failure conditions
410------------------
411
412The table below shows all the possible error codes returned in ``Result`` upon
413a failure. The errors are ordered by condition check.
414
415.. csv-table::
416 :header: "ID", "Condition"
417 :widths: 1 5
418
419 ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer
420 ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer
421 ``E_RMM_INVAL``,``Curve`` is not one of the listed in :ref:`ecc_curves`
422 ``E_RMM_UNK``,An unknown error occurred whilst processing the command
423 ``E_RMM_OK``,No errors detected
424
425.. _ecc_curves:
426
427Supported ECC Curves
428--------------------
429
430.. csv-table::
431 :header: "ID", "Curve"
432 :widths: 1 5
433
434 0,ECC SECP384R1
435
436RMM_ATTEST_GET_PLAT_TOKEN command
437=================================
438
439Retrieve the Platform Token from EL3.
440
441FID
442---
443
444``0xC40001B3``
445
446Input values
447------------
448
449.. csv-table::
450 :header: "Name", "Register", "Field", "Type", "Description"
451 :widths: 1 1 1 1 5
452
453 fid,x0,[63:0],UInt64,Command FID
454 buf_pa,x1,[63:0],Address,PA of the platform attestation token. The challenge object is passed in this buffer. The PA must belong to the shared buffer
455 buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`` must lie within the shared buffer
456 c_size,x3,[63:0],Size,Size in bytes of the challenge object. It corresponds to the size of one of the defined SHA algorithms
457
458Output values
459-------------
460
461.. csv-table::
462 :header: "Name", "Register", "Field", "Type", "Description"
463 :widths: 1 1 1 1 5
464
465 Result,x0,[63:0],Error Code,Command return status
466 tokenSize,x1,[63:0],Size,Size of the platform token
467
468Failure conditions
469------------------
470
471The table below shows all the possible error codes returned in ``Result`` upon
472a failure. The errors are ordered by condition check.
473
474.. csv-table::
475 :header: "ID", "Condition"
476 :widths: 1 5
477
478 ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer
479 ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer
480 ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm
481 ``E_RMM_UNK``,An unknown error occurred whilst processing the command
482 ``E_RMM_OK``,No errors detected
483
484RMM-EL3 world switch register save restore convention
485_____________________________________________________
486
487As part of NS world switch, EL3 is expected to maintain a register context
488specific to each world and will save and restore the registers
489appropriately. This section captures the contract between EL3 and RMM on the
490register set to be saved and restored.
491
492EL3 must maintain a separate register context for the following:
493
494 #. General purpose registers (x0-x30) and ``sp_el0``, ``sp_el2`` stack pointers
495 #. EL2 system register context for all enabled features by EL3. These include system registers with the ``_EL2`` prefix. The EL2 physical and virtual timer registers must not be included in this.
496
497It is the responsibility of EL3 that the above registers will not be leaked to
498the NS Host and to maintain the confidentiality of the Realm World.
499
500EL3 will not save some registers as mentioned in the below list. It is the
501responsibility of RMM to ensure that these are appropriately saved if the
502Realm World makes use of them:
503
504 #. FP/SIMD registers
505 #. SVE registers
506 #. SME registers
507 #. EL1/0 registers
508
509SMCCC v1.3 allows NS world to specify whether SVE context is in use. In this
510case, RMM could choose to not save the incoming SVE context but must ensure
511to clear SVE registers if they have been used in Realm World. The same applies
512to SME registers.
513
514Types
515_____
516
517.. _rmm_el3_manifest_struct:
518
519RMM-EL3 Boot Manifest Version
520~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
521
522The RMM-EL3 Boot Manifest structure contains platform boot information passed
523from EL3 to RMM. The width of the Boot Manifest is 128 bits
524
525.. image:: ../resources/diagrams/rmm_el3_manifest_struct.png
526
527The members of the RMM-EL3 Boot Manifest structure are shown in the following
528table:
529
530.. csv-table::
531 :header: "Name", "Range", "Type", Description
532 :widths: 2 1 1 4
533
534 ``Version Minor``,15:0,uint16_t,Version Minor part of the Boot Manifest Version.
535 ``Version Major``,30:16,uint16_t,Version Major part of the Boot Manifest Version.
536 ``RES0``,31,bit,Reserved. Set to 0.
537 ``Platform Data``,127:64,Address,Pointer to the Platform Data section of the Boot Manifest.