docs/components/rmm-el3-comms-spec.rst

25 compatibility with the register arguments passed as part of Boot Interface and
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.
55 This document specifies the 0.8 version of Boot Interface ABI and RMM-EL3
56 services specification and the 0.5 version of the Boot Manifest.
63 This section deals with the Boot Interface part of the specification.
65 One of the goals of the Boot Interface is to allow EL3 firmware to pass
69 images in the boot sequence and remain agnostic of any particular format used
72 The Boot Interface ABI defines a set of register conventions and
83 entered from EL3 as part of RMI handling.
99 …x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of C…
101 …x2,Maximum number of CPUs to be supported at runtime. RMM should ensure that it can support this m…
102 …L3 firmware and RMM. This buffer must be of 4KB size (1 page). The Boot Manifest must be present a…
103 …x4,"Activation token. Should be set to 0 on the initial boot of the system. For a subsequent warm …
114 during the lifetime of the system and that it can be used for runtime
125 communication requires the use of the shared area, it is expected that RMM needs
126 to do the necessary concurrency protection to prevent the use of the same buffer
145 …x0,Linear index of this PE. This index starts from 0 and must be less than the maximum number of C…
146 …x1,"Activation token. Should be set to 0 on the initial boot of the system. For a subsequent warm …
153 ``RMM_BOOT_COMPLETE`` SMC call. The first argument of this SMC call will
167 …``E_RMM_BOOT_CPUS_OUT_OF_RANGE``,Number of CPUs reported by EL3 larger than maximum supported by R…
168 …``E_RMM_BOOT_CPU_ID_OUT_OF_RANGE``,Current CPU Id is higher or equal than the number of CPUs suppo…
188 This Boot Manifest is versioned independently of the Boot Interface, to help
189 evolve the former independent of the latter.
195    - version : Version of the Manifest (v0.4)
201    - plat_console : Structure encoding the list of consoles for RMM use on the
205 For the current version of the Boot Manifest, the core manifest contains a pointer
209 For the data structure specification of Boot Manifest, refer to
219 restore convention between EL3 and RMM as part of RMI call handling. It is
225 If the interface requires the use of memory, then the memory references should
226 be within the shared buffer communicated as part of the boot interface. See
227 :ref:`rmm_cold_boot_interface` for properties of this shared buffer which both
242    ``E_RMM_BAD_ADDR``,The value of an address used as argument was invalid,-2
245    ``E_RMM_INVAL``,The value of an argument was invalid,-5
249 is allowed to return an error code corresponding to any of the failure
279 Notifies the completion of an RMI call to the Non-Secure world.
329    base_pa,x1,[63:0],Address,PA of the start of the granule to be delegated
372    base_pa,x1,[63:0],Address,PA of the start of the granule to be undelegated
416 …buf_size,x2,[63:0],Size,Size in bytes of the Realm Attestation Key buffer. ``bufPa + bufSize`` mus…
417 …ecc_curve,x3,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs…
427    keySize,x1,[63:0],Size,Size of the Realm Attestation Key
441    ``E_RMM_INVAL``,``Curve`` is not one of the listed in :ref:`ecc_curves`
460 buffer, EL3 returns a hunk of the token (via ``tokenHunkSize`` parameter) and
463 the buffer for the first call of this command and the size of the object is
464 indicated by ``c_size`` parameter. Subsequent calls to retrieve remaining hunks of
467 If ``c_size`` is not 0, this command could cause regeneration of platform token
468 and will return token hunk corresponding to beginning of the token.
470 It is valid for the calls of this command to return ``E_RMM_AGAIN`` error,
488 …,x1,[63:0],Address,"PA of the platform attestation token. The challenge object must be passed in t…
489 …buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`…
490 …c_size,x3,[63:0],Size,"Size in bytes of the challenge object. It corresponds to the size of one of…
500    tokenHunkSize,x1,[63:0],Size,Size of the platform token hunk retrieved
501    remainingSize,x2,[63:0],Size,Remaining bytes of the token that are pending retrieval
516 …``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm for the first c…
517    ``E_RMM_INVAL``,``CSize`` is not 0 for subsequent calls to retrieve remaining hunks of the token
528 discovery of EL3 features.
531 has fields defined to indicate presence or absence of features and other
535 This command is available from v0.4 of the RMM-EL3 interface.
538 v0.4 of the interface:
575    feat_reg_idx,x1,[63:0],UInt64, "Feature register index. For v0.4, a value of 0 is the only
587    feat_reg,x1,[63:0],Value,Value of the register as defined above
599    ``E_RMM_INVAL``,``feat_reg_idx`` is out of valid range
617 This command is useful when the RMM may not have access to the private portion of the realm
640    Opcode that is one of:
651 …buf_size,x3,[63:0],Size,Size in bytes of the input buffer in ``buf_pa``. ``buf_pa + buf_size`` mus…
652 …ecc_curve,x4,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs…
662    retval1,x1,[63:0],Value, "If opcode is RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP, then returns length of
688 associated with a given MECID. After the execution of this command, all memory
690 This command is available from v0.8 of the RMM-EL3 interface.
736 Set the key/IV info at Root port for an IDE stream as part of Device Assignment flow. This
737 command is available from v0.6 of the RMM-EL3 interface.
740 for description of the IDE setup sequence and how this will be invoked by RMM.
765    KeqQW0,x4,[63:0],UInt64,Quad word of key [63:0]
766    KeqQW1,x5,[63:0],UInt64,Quad word of key [127:64]
767    KeqQW2,x6,[63:0],UInt64,Quad word of key [191:128]
768    KeqQW3,x7,[63:0],UInt64,Quad word of key [255:192]
769    IFVQW0,x8,[63:0],UInt64,Quad word of IV [63:0]
770    IFVQW1,x9,[63:0],UInt64,Quad word of IV [95:64]
805 Activate the IDE stream at Root Port once the keys have been programmed as part of
806 Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface.
809 for description of the IDE setup sequence and info on how this will be invoked by RMM.
866 Deactivate the IDE stream at Root Port as part of Device Assignment flow. This command is
867 available from v0.6 of the RMM-EL3 interface.
870 for description of the IDE setup sequence and info on how this will be invoked by RMM.
927 Retrieve the response from Root Port to a previous non-blocking IDE-KM SMC request as part of
928 Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface.
931 for description of the IDE setup sequence and info on how this will be invoked by RMM.
933 The response from this call could correspond to any of the last pending requests and the
995 be freed again, and they must happen during the cold/warm boot phase of RMM.
997 for instance depending on the number of cores or the amount of memory installed.
998 This command is available from v0.7 of the RMM-EL3 interface.
1013    size,x1,[63:0],Size,"required size of the memory region, in bytes"
1014 …args,x2,[63:56],UInt64,"alignment requirement, in bits. A value of 16 would return a 64 KB aligned…
1027    address,x1,[63:0],Address, "Physical address of the reserved memory area."
1042    ``E_RMM_NOMEM``,"size of region is larger than the available memory"
1048 As part of NS world switch, EL3 is expected to maintain a register context
1058 As part of SMC forwarding between the NS world and Realm world, EL3 allows x0-x7 to be passed
1061 and it is the responsibility of RMM to preserve this or use this as a return argument.
1064 EL3 must save and restore the following as part of world switch:
1065    #. EL2 system registers with the exception of ``zcr_el2`` register.
1069 responsibility of RMM to ensure that these are appropriately saved if the
1070 Realm World makes use of them:
1075    #. EL1/0 registers with the exception of PAuth key registers as mentioned above.
1079 of the Realm world.
1095 from EL3 to RMM. The size of the Boot Manifest is 160 bytes.
1097 The members of the RMM-EL3 Boot Manifest structure are shown in the following
1111 | plat_console      |   40   |   console_list    | List of consoles available to RMM            |
1117 | plat_smmu         |   112  |     smmu_list     | List of SMMUs available to RMM               |
1120 | plat_root_complex |   136  | root_complex_list | List of PCIe root complexes available to RMM |
1130 The members of this structure are shown in the table below:
1135 | num_banks |   0    |    uint64_t   | Number of memory banks/device regions  |
1142 Checksum is calculated as two's complement sum of 'num_banks', 'banks' pointer
1157 | size |   8    | uint64_t | Size of memory bank/device region in bytes |
1166 The members of this structure are shown in the table below:
1171 | num_consoles |   0    |   uint64_t     | Number of consoles                |
1178 Checksum is calculated as two's complement sum of 'num_consoles', 'consoles'
1193 | map_pages |   8    | uint64_t | Num of pages to map for console MMIO |
1195 | name      |   16   | char[8]  | Name of console                      |
1210 The members of this structure are shown in the table below:
1215 | num_smmus |   0    |   uint64_t  | Number of SMMUs                |
1243 The members of this structure are shown in the table below.
1248 | num_root_complex |   0    |      uint64_t       | Number of root complexes            |
1259 The checksum calculation of Root Complex List structure includes all data structures
1268 The table below describes the members of this structure as per v0.1.
1279 | num_root_ports  |   12   |     uint32_t     | Number of root ports                |
1301 | num_bdf_mappings |   4    |     uint32_t       | Number of BDF mappings                |
1317 | mapping_base |   0    | uint16_t | Base of BDF mapping (inclusive)                      |
1319 | mapping_top  |   2    | uint16_t | Top of BDF mapping (exclusive)                       |
1353 | hash_buf    |   32   |   uint8_t[]   | TBS (to-be-signed) Hash of length       |
1375 | sig_len       |   16   |   uint16_t    | Length of the `signature_buf` field     |