1RMM-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.4 version of Boot Interface ABI and RMM-EL3
56services specification and the 0.3 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 4KB 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_RANGE``,Number of CPUs reported by EL3 larger than maximum supported by RMM,-3
163   ``E_RMM_BOOT_CPU_ID_OUT_OF_RANGE``,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 former independent of the latter.
185The current version for the Boot Manifest is ``v0.3`` and the rules explained
186in :ref:`rmm_el3_ifc_versioning` apply on this version as well.
187
188The Boot Manifest v0.3 has the following fields:
189
190   - version : Version of the Manifest (v0.3)
191   - plat_data : Pointer to the platform specific data and not specified by this
192     document. These data are optional and can be NULL.
193   - plat_dram : Structure encoding the NS DRAM information on the platform. This
194     field is optional and platform can choose to zero out this structure if
195     RMM does not need EL3 to send this information during the boot.
196   - plat_console : Structure encoding the list of consoles for RMM use on the
197     platform. This field is optional and platform can choose to not populate
198     the console list if this is not needed by the RMM for this platform.
199
200For the current version of the Boot Manifest, the core manifest contains a pointer
201to the platform data. EL3 must ensure that the whole Boot Manifest, including
202the platform data, if available, fits inside the RMM EL3 shared buffer.
203
204For the data structure specification of Boot Manifest, refer to
205:ref:`rmm_el3_manifest_struct`
206
207.. _runtime_services_and_interface:
208
209RMM-EL3 Runtime Interface
210__________________________
211
212This section defines the RMM-EL3 runtime interface which specifies the ABI for
213EL3 services expected by RMM at runtime as well as the register save and
214restore convention between EL3 and RMM as part of RMI call handling. It is
215important to note that RMM is allowed to invoke EL3-RMM runtime interface
216services during the boot phase as well. The EL3 runtime service handling must
217not result in a world switch to another world unless specified. Both the RMM
218and EL3 are allowed to make suitable optimizations based on this assumption.
219
220If the interface requires the use of memory, then the memory references should
221be within the shared buffer communicated as part of the boot interface. See
222:ref:`rmm_cold_boot_interface` for properties of this shared buffer which both
223EL3 and RMM must adhere to.
224
225RMM-EL3 runtime service return codes
226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
227
228The return codes from EL3 to RMM is a 32 bit signed integer which encapsulates
229error condition as described in the following table:
230
231.. csv-table::
232   :header: "Error code", "Description", "ID"
233   :widths: 2 4 1
234
235   ``E_RMM_OK``,No errors detected,0
236   ``E_RMM_UNK``,Unknown/Generic error,-1
237   ``E_RMM_BAD_ADDR``,The value of an address used as argument was invalid,-2
238   ``E_RMM_BAD_PAS``,Incorrect PAS,-3
239   ``E_RMM_NOMEM``,Not enough memory to perform an operation,-4
240   ``E_RMM_INVAL``,The value of an argument was invalid,-5
241   ``E_RMM_AGAIN``,The resource is busy. Try again.,-6
242
243If multiple failure conditions are detected in an RMM to EL3 command, then EL3
244is allowed to return an error code corresponding to any of the failure
245conditions.
246
247RMM-EL3 runtime services
248~~~~~~~~~~~~~~~~~~~~~~~~
249
250The following table summarizes the RMM runtime services that need to be
251implemented by EL3 Firmware.
252
253.. csv-table::
254   :header: "FID", "Command"
255   :widths: 2 5
256
257   0xC400018F,``RMM_RMI_REQ_COMPLETE``
258   0xC40001B0,``RMM_GTSI_DELEGATE``
259   0xC40001B1,``RMM_GTSI_UNDELEGATE``
260   0xC40001B2,``RMM_ATTEST_GET_REALM_KEY``
261   0xC40001B3,``RMM_ATTEST_GET_PLAT_TOKEN``
262   0xC40001B4,``RMM_EL3_FEATURES``
263   0xC40001B5,``RMM_EL3_TOKEN_SIGN``
264
265RMM_RMI_REQ_COMPLETE command
266============================
267
268Notifies the completion of an RMI call to the Non-Secure world.
269
270This call is the only function currently in RMM-EL3 runtime interface which
271results in a world switch to NS. This call is the reply to the original RMI
272call and it is forwarded by EL3 to the NS world.
273
274FID
275---
276
277``0xC400018F``
278
279Input values
280------------
281
282.. csv-table::
283   :header: "Name", "Register", "Field", "Type", "Description"
284   :widths: 1 1 1 1 5
285
286   fid,x0,[63:0],UInt64,Command FID
287   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
288
289Output values
290-------------
291
292This call does not return.
293
294Failure conditions
295------------------
296
297Since this call does not return to RMM, there is no failure condition which
298can be notified back to RMM.
299
300RMM_GTSI_DELEGATE command
301=========================
302
303Delegate a memory granule by changing its PAS from Non-Secure to Realm.
304
305FID
306---
307
308``0xC40001B0``
309
310Input values
311------------
312
313.. csv-table::
314   :header: "Name", "Register", "Field", "Type", "Description"
315   :widths: 1 1 1 1 5
316
317   fid,x0,[63:0],UInt64,Command FID
318   base_pa,x1,[63:0],Address,PA of the start of the granule to be delegated
319
320Output values
321-------------
322
323.. csv-table::
324   :header: "Name", "Register", "Field", "Type", "Description"
325   :widths: 1 1 1 2 4
326
327   Result,x0,[63:0],Error Code,Command return status
328
329Failure conditions
330------------------
331
332The table below shows all the possible error codes returned in ``Result`` upon
333a failure. The errors are ordered by condition check.
334
335.. csv-table::
336   :header: "ID", "Condition"
337   :widths: 1 5
338
339   ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address
340   ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Non-Secure PAS
341   ``E_RMM_OK``,No errors detected
342
343RMM_GTSI_UNDELEGATE command
344===========================
345
346Undelegate a memory granule by changing its PAS from Realm to Non-Secure.
347
348FID
349---
350
351``0xC40001B1``
352
353Input values
354------------
355
356.. csv-table::
357   :header: "Name", "Register", "Field", "Type", "Description"
358   :widths: 1 1 1 1 5
359
360   fid,x0,[63:0],UInt64,Command FID
361   base_pa,x1,[63:0],Address,PA of the start of the granule to be undelegated
362
363Output values
364-------------
365
366.. csv-table::
367   :header: "Name", "Register", "Field", "Type", "Description"
368   :widths: 1 1 1 2 4
369
370   Result,x0,[63:0],Error Code,Command return status
371
372Failure conditions
373------------------
374
375The table below shows all the possible error codes returned in ``Result`` upon
376a failure. The errors are ordered by condition check.
377
378.. csv-table::
379   :header: "ID", "Condition"
380   :widths: 1 5
381
382   ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address
383   ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Realm PAS
384   ``E_RMM_OK``,No errors detected
385
386RMM_ATTEST_GET_REALM_KEY command
387================================
388
389Retrieve the Realm Attestation Token Signing key from EL3.
390
391FID
392---
393
394``0xC40001B2``
395
396Input values
397------------
398
399.. csv-table::
400   :header: "Name", "Register", "Field", "Type", "Description"
401   :widths: 1 1 1 1 5
402
403   fid,x0,[63:0],UInt64,Command FID
404   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
405   buf_size,x2,[63:0],Size,Size in bytes of the Realm Attestation Key buffer. ``bufPa + bufSize`` must lie within the shared buffer
406   ecc_curve,x3,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves`
407
408Output values
409-------------
410
411.. csv-table::
412   :header: "Name", "Register", "Field", "Type", "Description"
413   :widths: 1 1 1 1 5
414
415   Result,x0,[63:0],Error Code,Command return status
416   keySize,x1,[63:0],Size,Size of the Realm Attestation Key
417
418Failure conditions
419------------------
420
421The table below shows all the possible error codes returned in ``Result`` upon
422a failure. The errors are ordered by condition check.
423
424.. csv-table::
425   :header: "ID", "Condition"
426   :widths: 1 5
427
428   ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer
429   ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer
430   ``E_RMM_INVAL``,``Curve`` is not one of the listed in :ref:`ecc_curves`
431   ``E_RMM_UNK``,An unknown error occurred whilst processing the command
432   ``E_RMM_OK``,No errors detected
433
434.. _ecc_curves:
435
436Supported ECC Curves
437--------------------
438
439.. csv-table::
440   :header: "ID", "Curve"
441   :widths: 1 5
442
443   0,ECC SECP384R1
444
445RMM_ATTEST_GET_PLAT_TOKEN command
446=================================
447
448Retrieve the Platform Token from EL3. If the entire token does not fit in the
449buffer, EL3 returns a hunk of the token (via ``tokenHunkSize`` parameter) and
450indicates the remaining bytes that are pending retrieval (via ``remainingSize``
451parameter). The challenge object for the platform token must be populated in
452the buffer for the first call of this command and the size of the object is
453indicated by ``c_size`` parameter. Subsequent calls to retrieve remaining hunks of
454the token must be made with ``c_size`` as 0.
455
456If ``c_size`` is not 0, this command could cause regeneration of platform token
457and will return token hunk corresponding to beginning of the token.
458
459It is valid for the calls of this command to return ``E_RMM_AGAIN`` error,
460which is an indication to the caller to retry this command again. Depending on the
461platform, this mechanism can be used to implement queuing to HES, if HES is
462involved in platform token generation.
463
464FID
465---
466
467``0xC40001B3``
468
469Input values
470------------
471
472.. csv-table::
473   :header: "Name", "Register", "Field", "Type", "Description"
474   :widths: 1 1 1 1 5
475
476   fid,x0,[63:0],UInt64,Command FID
477   buf_pa,x1,[63:0],Address,"PA of the platform attestation token. The challenge object must be passed in this buffer for the first call of this command. Any subsequent calls, if required to retrieve the full token, should not have this object. The PA must belong to the shared buffer."
478   buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`` must lie within the shared buffer
479   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. Any subsequent calls, if required to retrieve the full token, should set this size to 0."
480
481Output values
482-------------
483
484.. csv-table::
485   :header: "Name", "Register", "Field", "Type", "Description"
486   :widths: 1 1 1 1 5
487
488   Result,x0,[63:0],Error Code,Command return status
489   tokenHunkSize,x1,[63:0],Size,Size of the platform token hunk retrieved
490   remainingSize,x2,[63:0],Size,Remaining bytes of the token that are pending retrieval
491
492Failure conditions
493------------------
494
495The table below shows all the possible error codes returned in ``Result`` upon
496a failure. The errors are ordered by condition check.
497
498.. csv-table::
499   :header: "ID", "Condition"
500   :widths: 1 5
501
502   ``E_RMM_AGAIN``,Resource for Platform token retrieval is busy. Try again.
503   ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer
504   ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer
505   ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm for the first call to this command
506   ``E_RMM_INVAL``,``CSize`` is not 0 for subsequent calls to retrieve remaining hunks of the token
507   ``E_RMM_UNK``,An unknown error occurred whilst processing the command
508   ``E_RMM_OK``,No errors detected
509
510RMM_EL3_FEATURES command
511========================
512
513This command provides a mechanism to discover features and ABIs supported by the
514RMM-EL3 interface, for a given version. This command is helpful when there are
515platform specific optional RMM-EL3 interfaces and features exposed by vendor
516specific EL3 firmware, and a generic RMM that can modify its behavior based on
517discovery of EL3 features.
518
519The features can be discovered by specifying the feature register index that
520has fields defined to indicate presence or absence of features and other
521relevant information. The feature register index is specified in the
522``feat_reg_idx`` parameter. Each feature register is a 64 bit register.
523
524This command is available from v0.4 of the RMM-EL3 interface.
525
526The following is the register definition for feature register index 0 for
527v0.4 of the interface:
528
529RMM-EL3 Feature Resister 0
530--------------------------
531
532.. code-block:: none
533
534    63      32      31      16       15      8       7       1       0
535    +-------+-------+-------+-------+-------+-------+-------+-------+
536    |       |       |       |       |       |       |       |       |
537    |       |       |       |       |       |       |       |       |
538    +-------+-------+-------+-------+-------+-------+-------+-------+
539                                                             ^
540                                                             |
541                                                 RMMD_EL3_TOKEN_SIGN
542
543**Bit Fields:**
544
545- **Bit 0**: `RMMD_EL3_TOKEN_SIGN`
546    - When set to 1, the `RMMD_EL3_TOKEN_SIGN` feature is enabled.
547    - When cleared (0), the feature is disabled.
548- **Bits [1:63]**: Reserved (must be zero)
549
550FID
551---
552
553``0xC40001B4``
554
555
556Input values
557------------
558
559.. csv-table:: Input values for RMM_EL3_FEATURES
560   :header: "Name", "Register", "Field", "Type", "Description"
561   :widths: 1 1 1 1 5
562
563   fid,x0,[63:0],UInt64,Command FID
564   feat_reg_idx,x1,[63:0],UInt64, "Feature register index. For v0.4, a value of 0 is the only
565   acceptable value"
566
567
568Output values
569-------------
570
571.. csv-table:: Output values for RMM_EL3_FEATURES
572   :header: "Name", "Register", "Field", "Type", "Description"
573   :widths: 1 1 1 1 5
574
575   Result,x0,[63:0],Error Code,Command return status
576   feat_reg,x1,[63:0],Value,Value of the register as defined above
577
578Failure conditions
579------------------
580
581The table below shows all the possible error codes returned in ``Result`` upon
582a failure. The errors are ordered by condition check.
583
584.. csv-table:: Failure conditions for RMM_EL3_FEATURES
585   :header: "ID", "Condition"
586   :widths: 1 5
587
588   ``E_RMM_INVAL``,``feat_reg_idx`` is out of valid range
589   ``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4"
590   ``E_RMM_OK``,No errors detected
591
592RMM_EL3_TOKEN_SIGN command
593==========================
594
595This command is an optional command that can be discovered using the RMM_EL3_FEATURES command.
596This command is used to send requests related to realm attestation token signing requests to EL3.
597The command supports 3 opcodes:
598
599   - RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP
600   - RMM_EL3_TOKEN_SIGN_PULL_RESP_OP
601   - RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP
602
603The above opcodes can be used to send realm attestation token signing requests to EL3 and get their
604response, so that the realm attestation token can be constructed.
605
606This command is useful when the RMM may not have access to the private portion of the realm
607attestation key and needs signing services from EL3 or CCA HES, or other platform specific
608mechanisms to perform signing.
609
610The RMM-EL3 interface for this command is modeled as two separate queues, one for signing requests
611and one for retrieving the signed responses. It is possible that the queue in EL3 is full or EL3 is busy and
612unable to service the RMM requests, in which case the RMM is expected to retry the push operation
613for requests and pop operation for responses.
614
615FID
616---
617
618``0xC40001B5``
619
620Input values
621------------
622
623.. csv-table:: Input values for RMM_EL3_TOKEN_SIGN
624   :header: "Name", "Register", "Field", "Type", "Description"
625   :widths: 1 1 1 1 5
626
627   fid,x0,[63:0],UInt64,Command FID
628   opcode,x1,[63:0],UInt64,"
629   Opcode that is one of:
630
631    - RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP: 0x1 -
632      Opcode to push a token signing request to EL3 using struct el3_token_sign_request as described above
633    - RMM_EL3_TOKEN_SIGN_PULL_RESP_OP: 0x2 -
634      Opcode to pull a token signing response from EL3 using struct el3_token_sign_response as described above
635    - RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP: 0x3 -
636      Opcode to get the realm attestation public key
637
638   "
639   buf_pa,x2,[63:0],Address,"PA where the request structure is stored for the opcode RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP, the response structure needs to be populated for the opcode RMM_EL3_TOKEN_SIGN_PULL_RESP_OP, or where the public key must be populated for the opcode RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP. The PA must belong to the RMM-EL3 shared buffer"
640   buf_size,x3,[63:0],Size,Size in bytes of the input buffer in ``buf_pa``. ``buf_pa + buf_size`` must lie within the shared buffer
641   ecc_curve,x4,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves`. This parameter is valid on for the opcode RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP
642
643Output values
644-------------
645
646.. csv-table:: Output values for RMM_EL3_TOKEN_SIGN
647   :header: "Name", "Register", "Field", "Type", "Description"
648   :widths: 1 1 1 1 5
649
650   Result,x0,[63:0],Error Code,Command return status. Valid for all opcodes listed in input values
651   retval1,x1,[63:0],Value, "If opcode is RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP, then returns length of
652   public key returned. Otherwise, reserved"
653
654
655Failure conditions
656------------------
657
658The table below shows all the possible error codes returned in ``Result`` upon
659a failure. The errors are ordered by condition check.
660
661.. csv-table:: Failure conditions for RMM_EL3_TOKEN_SIGN
662   :header: "ID", "Condition"
663   :widths: 1 5
664
665   ``E_RMM_INVAL``,"if opcode is invalid or buffer address and length passed to the EL3 are not in valid range
666   corresponding to the RMM-EL3 shared buffer, or if the curve used for opcode
667   RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP is not the ECC P384 curve"
668   ``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4"
669   ``E_RMM_AGAIN``,"For opcode RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP, if the request is not queued since
670   the EL3 queue is full, or if the response is not ready yet, for other opcodes"
671   ``E_RMM_OK``,No errors detected
672
673
674RMM-EL3 world switch register save restore convention
675_____________________________________________________
676
677As part of NS world switch, EL3 is expected to maintain a register context
678specific to each world and will save and restore the registers
679appropriately. This section captures the contract between EL3 and RMM on the
680register set to be saved and restored.
681
682EL3 must maintain a separate register context for the following:
683
684   #. General purpose registers (x0-x30) and ``sp_el0``, ``sp_el2`` stack pointers
685   #. 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.
686
687As part of SMC forwarding between the NS world and Realm world, EL3 allows x0-x7 to be passed
688as arguments to Realm and x0-x4 to be used for return arguments back to Non Secure.
689As per SMCCCv1.2, x4 must be preserved if not being used as return argument by the SMC function
690and it is the responsibility of RMM to preserve this or use this as a return argument.
691EL3 will always copy x0-x4 from Realm context to NS Context.
692
693EL3 must save and restore the following as part of world switch:
694   #. EL2 system registers with the exception of ``zcr_el2`` register.
695   #. PAuth key registers (APIA, APIB, APDA, APDB, APGA).
696
697EL3 will not save some registers as mentioned in the below list. It is the
698responsibility of RMM to ensure that these are appropriately saved if the
699Realm World makes use of them:
700
701   #. FP/SIMD registers
702   #. SVE registers
703   #. SME registers
704   #. EL1/0 registers with the exception of PAuth key registers as mentioned above.
705   #. zcr_el2 register.
706
707It is essential that EL3 honors this contract to maintain the Confidentiality and integrity
708of the Realm world.
709
710SMCCC v1.3 allows NS world to specify whether SVE context is in use. In this
711case, RMM could choose to not save the incoming SVE context but must ensure
712to clear SVE registers if they have been used in Realm World. The same applies
713to SME registers.
714
715Types
716_____
717
718.. _rmm_el3_manifest_struct:
719
720RMM-EL3 Boot Manifest structure
721~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
722
723The RMM-EL3 Boot Manifest v0.3 structure contains platform boot information passed
724from EL3 to RMM. The size of the Boot Manifest is 64 bytes.
725
726The members of the RMM-EL3 Boot Manifest structure are shown in the following
727table:
728
729+--------------+--------+----------------+----------------------------------------+
730|   Name       | Offset |     Type       |               Description              |
731+==============+========+================+========================================+
732| version      |   0    |   uint32_t     | Boot Manifest version                  |
733+--------------+--------+----------------+----------------------------------------+
734| padding      |   4    |   uint32_t     | Reserved, set to 0                     |
735+--------------+--------+----------------+----------------------------------------+
736| plat_data    |   8    |   uintptr_t    | Pointer to Platform Data section       |
737+--------------+--------+----------------+----------------------------------------+
738| plat_dram    |   16   | ns_dram_info   | NS DRAM Layout Info structure          |
739+--------------+--------+----------------+----------------------------------------+
740| plat_console |   40   | console_list   | List of consoles available to RMM      |
741+--------------+--------+----------------+----------------------------------------+
742
743.. _ns_dram_info_struct:
744
745NS DRAM Layout Info structure
746~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
747
748NS DRAM Layout Info structure contains information about platform Non-secure
749DRAM layout. The members of this structure are shown in the table below:
750
751+-----------+--------+----------------+----------------------------------------+
752|   Name    | Offset |     Type       |               Description              |
753+===========+========+================+========================================+
754| num_banks |   0    |   uint64_t     | Number of NS DRAM banks                |
755+-----------+--------+----------------+----------------------------------------+
756| banks     |   8    | ns_dram_bank * | Pointer to 'ns_dram_bank'[] array      |
757+-----------+--------+----------------+----------------------------------------+
758| checksum  |   16   |   uint64_t     | Checksum                               |
759+-----------+--------+----------------+----------------------------------------+
760
761Checksum is calculated as two's complement sum of 'num_banks', 'banks' pointer
762and DRAM banks data array pointed by it.
763
764.. _ns_dram_bank_struct:
765
766NS DRAM Bank structure
767~~~~~~~~~~~~~~~~~~~~~~
768
769NS DRAM Bank structure contains information about each Non-secure DRAM bank:
770
771+-----------+--------+----------------+----------------------------------------+
772|   Name    | Offset |     Type       |               Description              |
773+===========+========+================+========================================+
774|   base    |   0    |   uintptr_t    | Base address                           |
775+-----------+--------+----------------+----------------------------------------+
776|   size    |   8    |   uint64_t     | Size of bank in bytes                  |
777+-----------+--------+----------------+----------------------------------------+
778
779.. _console_list_struct:
780
781Console List structure
782~~~~~~~~~~~~~~~~~~~~~~
783
784Console List structure contains information about the available consoles for RMM.
785The members of this structure are shown in the table below:
786
787+--------------+--------+----------------+----------------------------------------+
788|   Name       | Offset |     Type       |               Description              |
789+==============+========+================+========================================+
790| num_consoles |   0    |   uint64_t     | Number of consoles                     |
791+--------------+--------+----------------+----------------------------------------+
792| consoles     |   8    | console_info * | Pointer to 'console_info'[] array      |
793+--------------+--------+----------------+----------------------------------------+
794| checksum     |   16   |   uint64_t     | Checksum                               |
795+--------------+--------+----------------+----------------------------------------+
796
797Checksum is calculated as two's complement sum of 'num_consoles', 'consoles'
798pointer and the consoles array pointed by it.
799
800.. _console_info_struct:
801
802Console Info structure
803~~~~~~~~~~~~~~~~~~~~~~
804
805Console Info structure contains information about each Console available to RMM.
806
807+-----------+--------+---------------+----------------------------------------+
808|   Name    | Offset |     Type      |               Description              |
809+===========+========+===============+========================================+
810| base      |   0    |   uintptr_t   | Console Base address                   |
811+-----------+--------+---------------+----------------------------------------+
812| map_pages |   8    |   uint64_t    | Num of pages to map for console MMIO   |
813+-----------+--------+---------------+----------------------------------------+
814| name      |   16   |   char[]      | Name of console                        |
815+-----------+--------+---------------+----------------------------------------+
816| clk_in_hz |   24   |   uint64_t    | UART clock (in hz) for console         |
817+-----------+--------+---------------+----------------------------------------+
818| baud_rate |   32   |   uint64_t    | Baud rate                              |
819+-----------+--------+---------------+----------------------------------------+
820| flags     |   40   |   uint64_t    | Additional flags (RES0)                |
821+-----------+--------+---------------+----------------------------------------+
822
823.. _el3_token_sign_request_struct:
824
825EL3 Token Sign Request structure
826~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
827
828This structure represents a realm attestation toekn signing request.
829
830+-------------+--------+---------------+-----------------------------------------+
831|   Name      | Offset |     Type      |               Description               |
832+=============+========+===============+=========================================+
833| sig_alg_id  |   0    |   uint32_t    | Algorithm idenfier for the sign request.|
834|             |        |               | - 0x0: ECC SECP384R1 (ECDSA)            |
835|             |        |               | - Other values reserved                 |
836+-------------+--------+---------------+-----------------------------------------+
837| rec_granule |   8    |   uint64_t    | Identifier used by RMM to associate     |
838|             |        |               | a signing request to a realm. Must not  |
839|             |        |               | be interpreted or modified.             |
840+-------------+--------+---------------+-----------------------------------------+
841| req_ticket  |   16   |   uint64_t    | Value used by RMM to associate request  |
842|             |        |               | and responses. Must not be interpreted  |
843|             |        |               | or modified.                            |
844+-------------+--------+---------------+-----------------------------------------+
845| hash_alg_id |   24   |   uint32_t    | Hash algorithm for data in `hash_buf`   |
846|             |        |               | - 0x1: SHA2-384                         |
847|             |        |               | - All other values reserved.            |
848+-------------+--------+---------------+-----------------------------------------+
849| hash_buf    |   32   |   uint8_t[]   | TBS (to-be-signed) Hash of length       |
850|             |        |               | defined by hash algorithm `hash_alg_id` |
851+-------------+--------+---------------+-----------------------------------------+
852
853.. _el3_token_sign_response_struct:
854
855EL3 Token Sign Response structure
856~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
857
858This structure represents a realm attestation token signing response.
859
860+---------------+--------+---------------+-----------------------------------------+
861|   Name        | Offset |     Type      |               Description               |
862+===============+========+===============+=========================================+
863| rec_granule   |   0    |   uint64_t    | Identifier used by RMM to associate     |
864|               |        |               | a signing request to a realm. Must not  |
865|               |        |               | be interpreted or modified.             |
866+---------------+--------+---------------+-----------------------------------------+
867| req_ticket    |   8    |   uint64_t    | Value used by RMM to associate request  |
868|               |        |               | and responses. Must not be interpreted  |
869|               |        |               | or modified.                            |
870+---------------+--------+---------------+-----------------------------------------+
871| sig_len       |   16   |   uint16_t    | Length of the `signature_buf` field     |
872+---------------+--------+---------------+-----------------------------------------+
873| signature_buf |   18   |   uint8_t[]   | Signature                               |
874+---------------+--------+---------------+-----------------------------------------+
875