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.6 version of Boot Interface ABI and RMM-EL3 56services specification and the 0.5 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.4`` and the rules explained 186in :ref:`rmm_el3_ifc_versioning` apply on this version as well. 187 188The Boot Manifest v0.4 has the following fields: 189 190 - version : Version of the Manifest (v0.4) 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_MECID_KEY_UPDATE command 675============================ 676 677This command updates the tweak for the encryption key/programs a new encryption key 678associated with a given MECID. After the execution of this command, all memory 679accesses associated with the MECID are encrypted/decrypted using the new key. 680This command is available from v0.5 of the RMM-EL3 interface. 681 682FID 683--- 684 685``0xC40001B6`` 686 687Input values 688------------ 689 690.. csv-table:: Input values for RMM_MECID_KEY_UPDATE 691 :header: "Name", "Register", "Field", "Type", "Description" 692 :widths: 1 1 1 1 5 693 694 fid,x0,[63:0],UInt64,Command FID 695 mecid,x1,[15:0],UInt64,"mecid is a 16-bit value between 0 and 65,535 that identifies the MECID for which the encryption key is to be updated. Value has to be a valid MECID as per field MECIDWidthm1 read from MECIDR_EL2. Bits [63:16] must be 0." 696 697Output values 698------------- 699 700.. csv-table:: Output values for RMM_MECID_KEY_UPDATE 701 :header: "Name", "Register", "Field", "Type", "Description" 702 :widths: 1 1 1 1 5 703 704 Result,x0,[63:0],Error Code,Command return status. Valid for all opcodes listed in input values 705 706 707Failure conditions 708------------------ 709 710The table below shows all the possible error codes returned in ``Result`` upon 711a failure. The errors are ordered by condition check. 712 713.. csv-table:: Failure conditions for RMM_MECID_KEY_UPDATE 714 :header: "ID", "Condition" 715 :widths: 1 5 716 717 ``E_RMM_INVAL``,"if mecid is invalid (larger than 65,535 or than the maximum MECID width, determined by MECIDR_EL2.MECIDWidthm1)" 718 ``E_RMM_UNK``,"An unknown error occurred whilst processing the command or the SMC is not present if interface version is <0.5" 719 ``E_RMM_OK``,No errors detected 720 721 722RMM_IDE_KEY_PROG command 723========================= 724 725Set the key/IV info at Root port for an IDE stream as part of Device Assignment flow. This 726command is available from v0.6 of the RMM-EL3 interface. 727 728Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 729for description of the IDE setup sequence and how this will be invoked by RMM. 730 731The key is 256 bits and IV is 96 bits. The caller needs 732to call this SMC to program this key to the Rx, Tx ports and for each sub-stream 733corresponding to a single keyset. 734 735FID 736--- 737 738``0xC40001B7`` 739 740Input values 741------------ 742 743.. csv-table:: Input values for RMM_IDE_KEY_PROG 744 :header: "Name", "Register", "Field", "Type", "Description" 745 :widths: 1 1 1 1 5 746 747 fid,x0,[63:0],UInt64,Command FID 748 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 749 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 750 "Keyset[12]: 751 Dir[11]: 752 Substream[10:8]: 753 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream informationKey set: can be 0 or 1unused bits MBZ. 754 KeqQW0,x4,[63:0],UInt64,Quad word of key [63:0] 755 KeqQW1,x5,[63:0],UInt64,Quad word of key [127:64] 756 KeqQW2,x6,[63:0],UInt64,Quad word of key [191:128] 757 KeqQW3,x7,[63:0],UInt64,Quad word of key [255:192] 758 IFVQW0,x8,[63:0],UInt64,Quad word of IV [63:0] 759 IFVQW1,x9,[63:0],UInt64,Quad word of IV [95:64] 760 request_id,x10,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 761 cookie,x11,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 762 763 764Output values 765------------- 766 767.. csv-table:: Output values for RMM_IDE_KEY_PROG 768 :header: "Name", "Register", "Field", "Type", "Description" 769 :widths: 1 1 1 1 5 770 771 Result,x0,[63:0],Error Code,Command return status 772 773Failure conditions 774------------------ 775 776The table below shows all the possible error codes returned in ``Result`` upon 777a failure. The errors are ordered by condition check. 778 779.. csv-table:: Failure conditions for RMM_IDE_KEY_PROG 780 :header: "ID", "Condition" 781 :widths: 1 5 782 783 ``E_RMM_OK``,The Key programming is successful. 784 ``E_RMM_FAULT``,The Key programming is not successful. 785 ``E_RMM_INVAL``,The Key programming arguments are incorrect. 786 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 787 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 788 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 789 790 791RMM_IDE_KEY_SET_GO command 792========================== 793 794Activate the IDE stream at Root Port once the keys have been programmed as part of 795Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface. 796 797Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 798for description of the IDE setup sequence and info on how this will be invoked by RMM. 799 800The caller(RMM) needs to ensure the EL3_IDE_KEY_PROG() call had succeeded prior to this call. 801 802FID 803--- 804 805``0xC40001B8`` 806 807Input values 808------------ 809 810.. csv-table:: Input values for RMM_IDE_KEY_SET_GO 811 :header: "Name", "Register", "Field", "Type", "Description" 812 :widths: 1 1 1 1 5 813 814 fid,x0,[63:0],UInt64,Command FID 815 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 816 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 817 "Keyset[12]: 818 Dir[11]: 819 Substream[10:8]: 820 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ. 821 request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 822 cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 823 824 825Output values 826------------- 827 828.. csv-table:: Output values for RMM_IDE_KEY_SET_GO 829 :header: "Name", "Register", "Field", "Type", "Description" 830 :widths: 1 1 1 1 5 831 832 Result,x0,[63:0],Error Code,Command return status 833 834Failure conditions 835------------------ 836 837The table below shows all the possible error codes returned in ``Result`` upon 838a failure. The errors are ordered by condition check. 839 840.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_GO 841 :header: "ID", "Condition" 842 :widths: 1 5 843 844 ``E_RMM_OK``,The Key set go is successful. 845 ``E_RMM_FAULT``,The Key set go is not successful. 846 ``E_RMM_INVAL``,Incorrect arguments. 847 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 848 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 849 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 850 851 852RMM_IDE_KEY_SET_STOP command 853============================ 854 855Deactivate the IDE stream at Root Port as part of Device Assignment flow. This command is 856available from v0.6 of the RMM-EL3 interface. 857 858Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 859for description of the IDE setup sequence and info on how this will be invoked by RMM. 860 861This SMC is used to tear down an IDE Stream. 862 863FID 864--- 865 866``0xC40001B9`` 867 868Input values 869------------ 870 871.. csv-table:: Input values for RMM_IDE_KEY_SET_STOP 872 :header: "Name", "Register", "Field", "Type", "Description" 873 :widths: 1 1 1 1 5 874 875 fid,x0,[63:0],UInt64,Command FID 876 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 877 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 878 "Keyset[12]: 879 Dir[11]: 880 Substream[10:8]: 881 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ. 882 request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 883 cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 884 885 886Output values 887------------- 888 889.. csv-table:: Output values for RMM_IDE_KEY_SET_STOP 890 :header: "Name", "Register", "Field", "Type", "Description" 891 :widths: 1 1 1 1 5 892 893 Result,x0,[63:0],Error Code,Command return status 894 895Failure conditions 896------------------ 897 898The table below shows all the possible error codes returned in ``Result`` upon 899a failure. The errors are ordered by condition check. 900 901.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_STOP 902 :header: "ID", "Condition" 903 :widths: 1 5 904 905 ``E_RMM_OK``,The Key set stop is successful. 906 ``E_RMM_FAULT``,The Key set stop is not successful. 907 ``E_RMM_INVAL``,Incorrect arguments. 908 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 909 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 910 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 911 912 913RMM_IDE_KM_PULL_RESPONSE command 914================================ 915 916Retrieve the response from Root Port to a previous non-blocking IDE-KM SMC request as part of 917Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface. 918 919Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 920for description of the IDE setup sequence and info on how this will be invoked by RMM. 921 922The response from this call could correspond to any of the last pending requests and the 923RMM needs to identify the request and populate the response. For blocking calls, this SMC 924always returns E_RMM_UNK. 925 926FID 927--- 928 929``0xC40001BA`` 930 931Input values 932------------ 933 934.. csv-table:: Input values for RMM_IDE_KM_PULL_RESPONSE 935 :header: "Name", "Register", "Field", "Type", "Description" 936 :widths: 1 1 1 1 5 937 938 fid,x0,[63:0],UInt64,Command FID 939 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 940 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 941 942 943Output values 944------------- 945 946.. csv-table:: Output values for RMM_IDE_KM_PULL_RESPONSE 947 :header: "Name", "Register", "Field", "Type", "Description" 948 :widths: 1 1 1 1 5 949 950 Result,x0,[63:0],Error Code,Command return status 951 Result,x1,[63:0],Error Code,Retrieved response corresponding to previous IDE_KM requests. 952 Result,x2,[63:0],value,passthrough from requested SMC 953 Result,x3,[63:0],value,passthrough from requested SMC 954 955Failure conditions 956------------------ 957 958The table below shows all the possible error codes returned in ``Result`` upon 959a failure. The errors are ordered by condition check. 960 961.. csv-table:: Failure conditions for RMM_IDE_KM_PULL_RESPONSE(x0) 962 :header: "ID", "Condition" 963 :widths: 1 5 964 965 ``E_RMM_OK``,Response is retrieved successfully. 966 ``E_RMM_INVAL``,Arguments to pull response SMC is not correct. 967 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 968 ``E_RMM_AGAIN``,IDE-KM response queue is empty and no response is available. 969 970.. csv-table:: Failure conditions for RMM_IDE_KM_PULL_RESPONSE(x1) 971 :header: "ID", "Condition" 972 :widths: 1 5 973 974 ``E_RMM_OK``,The previous request was successful. 975 ``E_RMM_FAULT``,The previous request was not successful. 976 ``E_RMM_INVAL``,Arguments to previous request were incorrect. 977 ``E_RMM_UNK``,Previous request returned unknown error. 978 979RMM-EL3 world switch register save restore convention 980_____________________________________________________ 981 982As part of NS world switch, EL3 is expected to maintain a register context 983specific to each world and will save and restore the registers 984appropriately. This section captures the contract between EL3 and RMM on the 985register set to be saved and restored. 986 987EL3 must maintain a separate register context for the following: 988 989 #. General purpose registers (x0-x30) and ``sp_el0``, ``sp_el2`` stack pointers 990 #. 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. 991 992As part of SMC forwarding between the NS world and Realm world, EL3 allows x0-x7 to be passed 993as arguments to Realm and x0-x4 to be used for return arguments back to Non Secure. 994As per SMCCCv1.2, x4 must be preserved if not being used as return argument by the SMC function 995and it is the responsibility of RMM to preserve this or use this as a return argument. 996EL3 will always copy x0-x4 from Realm context to NS Context. 997 998EL3 must save and restore the following as part of world switch: 999 #. EL2 system registers with the exception of ``zcr_el2`` register. 1000 #. PAuth key registers (APIA, APIB, APDA, APDB, APGA). 1001 1002EL3 will not save some registers as mentioned in the below list. It is the 1003responsibility of RMM to ensure that these are appropriately saved if the 1004Realm World makes use of them: 1005 1006 #. FP/SIMD registers 1007 #. SVE registers 1008 #. SME registers 1009 #. EL1/0 registers with the exception of PAuth key registers as mentioned above. 1010 #. zcr_el2 register. 1011 1012It is essential that EL3 honors this contract to maintain the Confidentiality and integrity 1013of the Realm world. 1014 1015SMCCC v1.3 allows NS world to specify whether SVE context is in use. In this 1016case, RMM could choose to not save the incoming SVE context but must ensure 1017to clear SVE registers if they have been used in Realm World. The same applies 1018to SME registers. 1019 1020Types 1021_____ 1022 1023.. _rmm_el3_manifest_struct: 1024 1025RMM-EL3 Boot Manifest structure 1026~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1027 1028The RMM-EL3 Boot Manifest v0.5 structure contains platform boot information passed 1029from EL3 to RMM. The size of the Boot Manifest is 160 bytes. 1030 1031The members of the RMM-EL3 Boot Manifest structure are shown in the following 1032table: 1033 1034+-------------------+--------+-------------------+----------------------------------------------+ 1035| Name | Offset | Type | Description | 1036+===================+========+===================+==============================================+ 1037| version | 0 | uint32_t | Boot Manifest version | 1038+-------------------+--------+-------------------+----------------------------------------------+ 1039| padding | 4 | uint32_t | Reserved, set to 0 | 1040+-------------------+--------+-------------------+----------------------------------------------+ 1041| plat_data | 8 | uint64_t | Pointer to Platform Data section | 1042+-------------------+--------+-------------------+----------------------------------------------+ 1043| plat_dram | 16 | memory_info | NS DRAM Layout Info structure | 1044+-------------------+--------+-------------------+----------------------------------------------+ 1045| plat_console | 40 | console_list | List of consoles available to RMM | 1046+-------------------+--------+-------------------+----------------------------------------------+ 1047| plat_ncoh_region | 64 | memory_info | Device non-coherent ranges Info structure | 1048+-------------------+--------+-------------------+----------------------------------------------+ 1049| plat_coh_region | 88 | memory_info | Device coherent ranges Info structure | 1050+-------------------+--------+-------------------+----------------------------------------------+ 1051| plat_smmu | 112 | smmu_list | List of SMMUs available to RMM | 1052| | | | (from Boot Manifest v0.5) | 1053+-------------------+--------+-------------------+----------------------------------------------+ 1054| plat_root_complex | 136 | root_complex_list | List of PCIe root complexes available to RMM | 1055| | | | (from Boot Manifest v0.5) | 1056+-------------------+--------+-------------------+----------------------------------------------+ 1057 1058.. _memory_info_struct: 1059 1060Memory Info structure 1061~~~~~~~~~~~~~~~~~~~~~ 1062 1063Memory Info structure contains information about platform memory layout. 1064The members of this structure are shown in the table below: 1065 1066+-----------+--------+---------------+----------------------------------------+ 1067| Name | Offset | Type | Description | 1068+===========+========+===============+========================================+ 1069| num_banks | 0 | uint64_t | Number of memory banks/device regions | 1070+-----------+--------+---------------+----------------------------------------+ 1071| banks | 8 | memory_bank * | Pointer to 'memory_bank'[] array | 1072+-----------+--------+---------------+----------------------------------------+ 1073| checksum | 16 | uint64_t | Checksum | 1074+-----------+--------+---------------+----------------------------------------+ 1075 1076Checksum is calculated as two's complement sum of 'num_banks', 'banks' pointer 1077and memory banks data array pointed by it. 1078 1079.. _memory_bank_struct: 1080 1081Memory Bank/Device region structure 1082~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1083 1084Memory Bank structure contains information about each memory bank/device region: 1085 1086+------+--------+----------+--------------------------------------------+ 1087| Name | Offset | Type | Description | 1088+======+========+==========+============================================+ 1089| base | 0 | uint64_t | Base address | 1090+------+--------+----------+--------------------------------------------+ 1091| size | 8 | uint64_t | Size of memory bank/device region in bytes | 1092+------+--------+----------+--------------------------------------------+ 1093 1094.. _console_list_struct: 1095 1096Console List structure 1097~~~~~~~~~~~~~~~~~~~~~~ 1098 1099Console List structure contains information about the available consoles for RMM. 1100The members of this structure are shown in the table below: 1101 1102+--------------+--------+----------------+-----------------------------------+ 1103| Name | Offset | Type | Description | 1104+==============+========+================+===================================+ 1105| num_consoles | 0 | uint64_t | Number of consoles | 1106+--------------+--------+----------------+-----------------------------------+ 1107| consoles | 8 | console_info * | Pointer to 'console_info'[] array | 1108+--------------+--------+----------------+-----------------------------------+ 1109| checksum | 16 | uint64_t | Checksum | 1110+--------------+--------+----------------+-----------------------------------+ 1111 1112Checksum is calculated as two's complement sum of 'num_consoles', 'consoles' 1113pointer and the consoles array pointed by it. 1114 1115.. _console_info_struct: 1116 1117Console Info structure 1118~~~~~~~~~~~~~~~~~~~~~~ 1119 1120Console Info structure contains information about each Console available to RMM. 1121 1122+-----------+--------+----------+--------------------------------------+ 1123| Name | Offset | Type | Description | 1124+===========+========+==========+======================================+ 1125| base | 0 | uint64_t | Console Base address | 1126+-----------+--------+----------+--------------------------------------+ 1127| map_pages | 8 | uint64_t | Num of pages to map for console MMIO | 1128+-----------+--------+----------+--------------------------------------+ 1129| name | 16 | char[8] | Name of console | 1130+-----------+--------+----------+--------------------------------------+ 1131| clk_in_hz | 24 | uint64_t | UART clock (in Hz) for console | 1132+-----------+--------+----------+--------------------------------------+ 1133| baud_rate | 32 | uint64_t | Baud rate | 1134+-----------+--------+----------+--------------------------------------+ 1135| flags | 40 | uint64_t | Additional flags (RES0) | 1136+-----------+--------+----------+--------------------------------------+ 1137 1138.. _smmu_list_struct: 1139 1140SMMU List structure 1141~~~~~~~~~~~~~~~~~~~ 1142 1143SMMU List structure contains information about SMMUs available for RMM. 1144The members of this structure are shown in the table below: 1145 1146+-----------+--------+-------------+--------------------------------+ 1147| Name | Offset | Type | Description | 1148+===========+========+=============+================================+ 1149| num_smmus | 0 | uint64_t | Number of SMMUs | 1150+-----------+--------+-------------+--------------------------------+ 1151| smmus | 8 | smmu_info * | Pointer to 'smmu_info'[] array | 1152+-----------+--------+-------------+--------------------------------+ 1153| checksum | 16 | uint64_t | Checksum | 1154+-----------+--------+-------------+--------------------------------+ 1155 1156.. _smmu_info_struct: 1157 1158SMMU Info structure 1159~~~~~~~~~~~~~~~~~~~ 1160 1161SMMU Info structure contains information about each SMMU available to RMM. 1162 1163+-------------+--------+----------+-------------------------------+ 1164| Name | Offset | Type | Description | 1165+=============+========+==========+===============================+ 1166| smmu_base | 0 | uint64_t | SMMU Base address | 1167+-------------+--------+----------+-------------------------------+ 1168| smmu_r_base | 8 | uint64_t | SMMU Realm Pages base address | 1169+-------------+--------+----------+-------------------------------+ 1170 1171.. _root_complex_list_struct: 1172 1173Root Complex List structure 1174~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1175 1176Root Complex List structure contains information about PCIe root complexes available for RMM. 1177The members of this structure are shown in the table below. 1178 1179+------------------+--------+---------------------+-------------------------------------+ 1180| Name | Offset | Type | Description | 1181+==================+========+=====================+=====================================+ 1182| num_root_complex | 0 | uint64_t | Number of root complexes | 1183+------------------+--------+---------------------+-------------------------------------+ 1184| rc_info_version | 8 | uint32_t | Root Complex Info structure version | 1185+------------------+--------+---------------------+-------------------------------------+ 1186| padding | 12 | uint32_t | Reserved, set to 0 | 1187+------------------+--------+---------------------+-------------------------------------+ 1188| root_complex | 16 | root_complex_info * | Pointer to 'root_complex'[] array | 1189+------------------+--------+---------------------+-------------------------------------+ 1190| checksum | 24 | uint64_t | Checksum | 1191+------------------+--------+---------------------+-------------------------------------+ 1192 1193The checksum calculation of Root Complex List structure includes all data structures 1194referenced by 'root_complex_info' pointer. 1195 1196.. _root_complex_info_struct: 1197 1198Root Complex Info structure 1199~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1200 1201Root Complex Info structure contains information about each PCIe root complex available to RMM. 1202The table below describes the members of this structure as per v0.1. 1203 1204+-----------------+--------+------------------+-------------------------------------+ 1205| Name | Offset | Type | Description | 1206+=================+========+==================+=====================================+ 1207| ecam_base | 0 | uint64_t | PCIe ECAM Base address | 1208+-----------------+--------+------------------+-------------------------------------+ 1209| segment | 8 | uint8_t | PCIe segment identifier | 1210+-----------------+--------+------------------+-------------------------------------+ 1211| padding[3] | 9 | uint8_t | Reserved, set to 0 | 1212+-----------------+--------+------------------+-------------------------------------+ 1213| num_root_ports | 12 | uint32_t | Number of root ports | 1214+-----------------+--------+------------------+-------------------------------------+ 1215| root_ports | 16 | root_port_info * | Pointer to 'root_port_info'[] array | 1216+-----------------+--------+------------------+-------------------------------------+ 1217 1218The Root Complex Info structure version uses the same numbering scheme as described in 1219:ref:`rmm_el3_ifc_versioning`. 1220 1221.. _root_port_info_struct: 1222 1223Root Port Info structure 1224~~~~~~~~~~~~~~~~~~~~~~~~ 1225 1226Root Complex Info structure contains information about each root port in PCIe root complex. 1227 1228+------------------+--------+--------------------+---------------------------------------+ 1229| Name | Offset | Type | Description | 1230+==================+========+====================+=======================================+ 1231| root_port_id | 0 | uint16_t | Root Port identifier | 1232+------------------+--------+--------------------+---------------------------------------+ 1233| padding | 2 | uint16_t | Reserved, set to 0 | 1234+------------------+--------+--------------------+---------------------------------------+ 1235| num_bdf_mappings | 4 | uint32_t | Number of BDF mappings | 1236+------------------+--------+--------------------+---------------------------------------+ 1237| bdf_mappings | 8 | bdf_mapping_info * | Pointer to 'bdf_mapping_info'[] array | 1238+------------------+--------+--------------------+---------------------------------------+ 1239 1240.. _bdf_mapping_info_struct: 1241 1242BDF Mapping Info structure 1243~~~~~~~~~~~~~~~~~~~~~~~~~~ 1244 1245BDF Mapping Info structure contains information about each Device-Bus-Function (BDF) mapping 1246for PCIe root port. 1247 1248+--------------+--------+----------+------------------------------------------------------+ 1249| Name | Offset | Type | Description | 1250+==============+========+==========+======================================================+ 1251| mapping_base | 0 | uint16_t | Base of BDF mapping (inclusive) | 1252+--------------+--------+----------+------------------------------------------------------+ 1253| mapping_top | 2 | uint16_t | Top of BDF mapping (exclusive) | 1254+--------------+--------+----------+------------------------------------------------------+ 1255| mapping_off | 4 | uint16_t | Mapping offset, as per Arm Base System Architecture: | 1256| | | | StreamID = RequesterID[N-1:0] + (1<<N)*Constant_B | 1257+--------------+--------+----------+------------------------------------------------------+ 1258| smmu_idx | 6 | uint16_t | SMMU index in 'smmu_info'[] array | 1259+--------------+--------+----------+------------------------------------------------------+ 1260 1261.. _el3_token_sign_request_struct: 1262 1263EL3 Token Sign Request structure 1264~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1265 1266This structure represents a realm attestation token signing request. 1267 1268+-------------+--------+---------------+-----------------------------------------+ 1269| Name | Offset | Type | Description | 1270+=============+========+===============+=========================================+ 1271| sig_alg_id | 0 | uint32_t | Algorithm idenfier for the sign request.| 1272| | | | - 0x0: ECC SECP384R1 (ECDSA) | 1273| | | | - Other values reserved | 1274+-------------+--------+---------------+-----------------------------------------+ 1275| rec_granule | 8 | uint64_t | Identifier used by RMM to associate | 1276| | | | a signing request to a realm. Must not | 1277| | | | be interpreted or modified. | 1278+-------------+--------+---------------+-----------------------------------------+ 1279| req_ticket | 16 | uint64_t | Value used by RMM to associate request | 1280| | | | and responses. Must not be interpreted | 1281| | | | or modified. | 1282+-------------+--------+---------------+-----------------------------------------+ 1283| hash_alg_id | 24 | uint32_t | Hash algorithm for data in `hash_buf` | 1284| | | | - 0x1: SHA2-384 | 1285| | | | - All other values reserved. | 1286+-------------+--------+---------------+-----------------------------------------+ 1287| hash_buf | 32 | uint8_t[] | TBS (to-be-signed) Hash of length | 1288| | | | defined by hash algorithm `hash_alg_id` | 1289+-------------+--------+---------------+-----------------------------------------+ 1290 1291.. _el3_token_sign_response_struct: 1292 1293EL3 Token Sign Response structure 1294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1295 1296This structure represents a realm attestation token signing response. 1297 1298+---------------+--------+---------------+-----------------------------------------+ 1299| Name | Offset | Type | Description | 1300+===============+========+===============+=========================================+ 1301| rec_granule | 0 | uint64_t | Identifier used by RMM to associate | 1302| | | | a signing request to a realm. Must not | 1303| | | | be interpreted or modified. | 1304+---------------+--------+---------------+-----------------------------------------+ 1305| req_ticket | 8 | uint64_t | Value used by RMM to associate request | 1306| | | | and responses. Must not be interpreted | 1307| | | | or modified. | 1308+---------------+--------+---------------+-----------------------------------------+ 1309| sig_len | 16 | uint16_t | Length of the `signature_buf` field | 1310+---------------+--------+---------------+-----------------------------------------+ 1311| signature_buf | 18 | uint8_t[] | Signature | 1312+---------------+--------+---------------+-----------------------------------------+ 1313
