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 2.0 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 x4,"Activation token. Should be set to 0 on the initial boot of the system. For a subsequent warm boot or when using Live Firmware Activation, the activation token should be set to the value returned by RMM for this CPU during the initial boot (in x2)." 104 105During cold boot, EL3 firmware needs to allocate a 4KB page that will be 106passed to RMM in x3. This memory will be used as shared buffer for communication 107between EL3 and RMM. It must be assigned to Realm world and must be mapped with 108Normal memory attributes (IWB-OWB-ISH) at EL3. At boot, this memory will be 109used to populate the Boot Manifest. Since the Boot Manifest can be accessed by 110RMM prior to enabling its MMU, EL3 must ensure that proper cache maintenance 111operations are performed after the Boot Manifest is populated. 112 113EL3 should also ensure that this shared buffer is always available for use by RMM 114during the lifetime of the system and that it can be used for runtime 115communication between RMM and EL3. For example, when RMM invokes attestation 116service commands in EL3, this buffer can be used to exchange data between RMM 117and EL3. It is also allowed for RMM to invoke runtime services provided by EL3 118utilizing this buffer during the boot phase, prior to return back to EL3 via 119RMM_BOOT_COMPLETE SMC. 120 121RMM should map this memory page into its Stage 1 page-tables using Normal 122memory attributes. 123 124During runtime, it is the RMM which initiates any communication with EL3. If that 125communication requires the use of the shared area, it is expected that RMM needs 126to do the necessary concurrency protection to prevent the use of the same buffer 127by other PEs. 128 129The following sequence diagram shows how a generic EL3 Firmware would boot RMM. 130 131.. image:: ../resources/diagrams/rmm_cold_boot_generic.png 132 133Warm Boot Interface 134~~~~~~~~~~~~~~~~~~~ 135 136At warm boot, RMM is already initialized and only some per-CPU initialization 137is still pending. The only argument that is required by RMM at this stage is 138the CPU Id, which will be passed through register x0 whilst x1 to x3 are RES0. 139This is summarized in the following table: 140 141.. csv-table:: 142 :header: "Register", "Value" 143 :widths: 1, 5 144 145 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). 146 x1,"Activation token. Should be set to 0 on the initial boot of the system. For a subsequent warm boot or when using Live Firmware Activation, the activation token should be set to the value returned by RMM for this CPU during the initial boot (in x2)." 147 x2 - x3,RES0 148 149Boot error handling and return values 150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 151 152After boot up and initialization, RMM returns control back to EL3 through a 153``RMM_BOOT_COMPLETE`` SMC call. The first argument of this SMC call will 154be returned in x1 and it will encode a signed integer with the error reason. 155x2 will contain the per-CPU activation token, which is an opaque value that 156should be passed back to RMM when doing Live Firmware Activations or on a 157subsequent warm boot. 158The following table describes possible values for the error code in x1: 159 160.. csv-table:: 161 :header: "Error code", "Description", "ID" 162 :widths: 2 4 1 163 164 ``E_RMM_BOOT_SUCCESS``,Boot successful,0 165 ``E_RMM_BOOT_ERR_UNKNOWN``,Unknown error,-1 166 ``E_RMM_BOOT_VERSION_NOT_VALID``,Boot Interface version reported by EL3 is not supported by RMM,-2 167 ``E_RMM_BOOT_CPUS_OUT_OF_RANGE``,Number of CPUs reported by EL3 larger than maximum supported by RMM,-3 168 ``E_RMM_BOOT_CPU_ID_OUT_OF_RANGE``,Current CPU Id is higher or equal than the number of CPUs supported by RMM,-4 169 ``E_RMM_BOOT_INVALID_SHARED_BUFFER``,Invalid pointer to shared memory area,-5 170 ``E_RMM_BOOT_MANIFEST_VERSION_NOT_SUPPORTED``,Version reported by the Boot Manifest not supported by RMM,-6 171 ``E_RMM_BOOT_MANIFEST_DATA_ERROR``,Error parsing core Boot Manifest,-7 172 173For any error detected in RMM during cold or warm boot, RMM will return back to 174EL3 using ``RMM_BOOT_COMPLETE`` SMC with an appropriate error code. It is 175expected that EL3 will take necessary action to disable Realm world for further 176entry from NS Host on receiving an error. This will be done across all the PEs 177in the system so as to present a symmetric view to the NS Host. Any further 178warm boot by any PE should not enter RMM using the warm boot interface. 179 180.. _rmm_el3_boot_manifest: 181 182Boot Manifest 183~~~~~~~~~~~~~ 184 185During cold boot, EL3 Firmware passes a memory Boot Manifest to RMM containing 186platform information. 187 188This Boot Manifest is versioned independently of the Boot Interface, to help 189evolve the former independent of the latter. 190The current version for the Boot Manifest is ``v0.4`` and the rules explained 191in :ref:`rmm_el3_ifc_versioning` apply on this version as well. 192 193The Boot Manifest v0.4 has the following fields: 194 195 - version : Version of the Manifest (v0.4) 196 - plat_data : Pointer to the platform specific data and not specified by this 197 document. These data are optional and can be NULL. 198 - plat_dram : Structure encoding the NS DRAM information on the platform. This 199 field is optional and platform can choose to zero out this structure if 200 RMM does not need EL3 to send this information during the boot. 201 - plat_console : Structure encoding the list of consoles for RMM use on the 202 platform. This field is optional and platform can choose to not populate 203 the console list if this is not needed by the RMM for this platform. 204 205For the current version of the Boot Manifest, the core manifest contains a pointer 206to the platform data. EL3 must ensure that the whole Boot Manifest, including 207the platform data, if available, fits inside the RMM EL3 shared buffer. 208 209For the data structure specification of Boot Manifest, refer to 210:ref:`rmm_el3_manifest_struct` 211 212.. _runtime_services_and_interface: 213 214RMM-EL3 Runtime Interface 215__________________________ 216 217This section defines the RMM-EL3 runtime interface which specifies the ABI for 218EL3 services expected by RMM at runtime as well as the register save and 219restore convention between EL3 and RMM as part of RMI call handling. It is 220important to note that RMM is allowed to invoke EL3-RMM runtime interface 221services during the boot phase as well. The EL3 runtime service handling must 222not result in a world switch to another world unless specified. Both the RMM 223and EL3 are allowed to make suitable optimizations based on this assumption. 224 225If the interface requires the use of memory, then the memory references should 226be 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 228EL3 and RMM must adhere to. 229 230RMM-EL3 runtime service return codes 231~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 232 233The return codes from EL3 to RMM is a 32 bit signed integer which encapsulates 234error condition as described in the following table: 235 236.. csv-table:: 237 :header: "Error code", "Description", "ID" 238 :widths: 2 4 1 239 240 ``E_RMM_OK``,No errors detected,0 241 ``E_RMM_UNK``,Unknown/Generic error,-1 242 ``E_RMM_BAD_ADDR``,The value of an address used as argument was invalid,-2 243 ``E_RMM_BAD_PAS``,Incorrect PAS,-3 244 ``E_RMM_NOMEM``,Not enough memory to perform an operation,-4 245 ``E_RMM_INVAL``,The value of an argument was invalid,-5 246 ``E_RMM_AGAIN``,The resource is busy. Try again.,-6 247 248If multiple failure conditions are detected in an RMM to EL3 command, then EL3 249is allowed to return an error code corresponding to any of the failure 250conditions. 251 252RMM-EL3 runtime services 253~~~~~~~~~~~~~~~~~~~~~~~~ 254 255The following table summarizes the RMM runtime services that need to be 256implemented by EL3 Firmware. 257 258.. csv-table:: 259 :header: "FID", "Command" 260 :widths: 2 5 261 262 0xC400018F,``RMM_RMI_REQ_COMPLETE`` 263 0xC40001B0,``RMM_GTSI_DELEGATE`` 264 0xC40001B1,``RMM_GTSI_UNDELEGATE`` 265 0xC40001B2,``RMM_ATTEST_GET_REALM_KEY`` 266 0xC40001B3,``RMM_ATTEST_GET_PLAT_TOKEN`` 267 0xC40001B4,``RMM_EL3_FEATURES`` 268 0xC40001B5,``RMM_EL3_TOKEN_SIGN`` 269 0xC40001B6,``RMM_MECID_KEY_UPDATE`` 270 0xC40001B7,``RMM_IDE_KEY_PROG`` 271 0xC40001B8,``RMM_IDE_KEY_SET_GO`` 272 0xC40001B9,``RMM_IDE_KEY_SET_STOP`` 273 0xC40001BA,``RMM_IDE_KM_PULL_RESPONSE`` 274 0xC40001BB,``RMM_RESERVE_MEMORY`` 275 276RMM_RMI_REQ_COMPLETE command 277============================ 278 279Notifies the completion of an RMI call to the Non-Secure world. 280 281This call is the only function currently in RMM-EL3 runtime interface which 282results in a world switch to NS. This call is the reply to the original RMI 283call and it is forwarded by EL3 to the NS world. 284 285FID 286--- 287 288``0xC400018F`` 289 290Input values 291------------ 292 293.. csv-table:: 294 :header: "Name", "Register", "Field", "Type", "Description" 295 :widths: 1 1 1 1 5 296 297 fid,x0,[63:0],UInt64,Command FID 298 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 299 300Output values 301------------- 302 303This call does not return. 304 305Failure conditions 306------------------ 307 308Since this call does not return to RMM, there is no failure condition which 309can be notified back to RMM. 310 311RMM_GTSI_DELEGATE command 312========================= 313 314Delegate a memory granule by changing its PAS from Non-Secure to Realm. 315 316FID 317--- 318 319``0xC40001B0`` 320 321Input values 322------------ 323 324.. csv-table:: 325 :header: "Name", "Register", "Field", "Type", "Description" 326 :widths: 1 1 1 1 5 327 328 fid,x0,[63:0],UInt64,Command FID 329 base_pa,x1,[63:0],Address,PA of the start of the granule to be delegated 330 331Output values 332------------- 333 334.. csv-table:: 335 :header: "Name", "Register", "Field", "Type", "Description" 336 :widths: 1 1 1 2 4 337 338 Result,x0,[63:0],Error Code,Command return status 339 340Failure conditions 341------------------ 342 343The table below shows all the possible error codes returned in ``Result`` upon 344a failure. The errors are ordered by condition check. 345 346.. csv-table:: 347 :header: "ID", "Condition" 348 :widths: 1 5 349 350 ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address 351 ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Non-Secure PAS 352 ``E_RMM_OK``,No errors detected 353 354RMM_GTSI_UNDELEGATE command 355=========================== 356 357Undelegate a memory granule by changing its PAS from Realm to Non-Secure. 358 359FID 360--- 361 362``0xC40001B1`` 363 364Input values 365------------ 366 367.. csv-table:: 368 :header: "Name", "Register", "Field", "Type", "Description" 369 :widths: 1 1 1 1 5 370 371 fid,x0,[63:0],UInt64,Command FID 372 base_pa,x1,[63:0],Address,PA of the start of the granule to be undelegated 373 374Output values 375------------- 376 377.. csv-table:: 378 :header: "Name", "Register", "Field", "Type", "Description" 379 :widths: 1 1 1 2 4 380 381 Result,x0,[63:0],Error Code,Command return status 382 383Failure conditions 384------------------ 385 386The table below shows all the possible error codes returned in ``Result`` upon 387a failure. The errors are ordered by condition check. 388 389.. csv-table:: 390 :header: "ID", "Condition" 391 :widths: 1 5 392 393 ``E_RMM_BAD_ADDR``,``PA`` does not correspond to a valid granule address 394 ``E_RMM_BAD_PAS``,The granule pointed by ``PA`` does not belong to Realm PAS 395 ``E_RMM_OK``,No errors detected 396 397RMM_ATTEST_GET_REALM_KEY command 398================================ 399 400Retrieve the Realm Attestation Token Signing key from EL3. 401 402FID 403--- 404 405``0xC40001B2`` 406 407Input values 408------------ 409 410.. csv-table:: 411 :header: "Name", "Register", "Field", "Type", "Description" 412 :widths: 1 1 1 1 5 413 414 fid,x0,[63:0],UInt64,Command FID 415 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 416 buf_size,x2,[63:0],Size,Size in bytes of the Realm Attestation Key buffer. ``bufPa + bufSize`` must lie within the shared buffer 417 ecc_curve,x3,[63:0],Enum,Type of the elliptic curve to which the requested attestation key belongs to. See :ref:`ecc_curves` 418 419Output values 420------------- 421 422.. csv-table:: 423 :header: "Name", "Register", "Field", "Type", "Description" 424 :widths: 1 1 1 1 5 425 426 Result,x0,[63:0],Error Code,Command return status 427 keySize,x1,[63:0],Size,Size of the Realm Attestation Key 428 429Failure conditions 430------------------ 431 432The table below shows all the possible error codes returned in ``Result`` upon 433a failure. The errors are ordered by condition check. 434 435.. csv-table:: 436 :header: "ID", "Condition" 437 :widths: 1 5 438 439 ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer 440 ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer 441 ``E_RMM_INVAL``,``Curve`` is not one of the listed in :ref:`ecc_curves` 442 ``E_RMM_UNK``,An unknown error occurred whilst processing the command 443 ``E_RMM_OK``,No errors detected 444 445.. _ecc_curves: 446 447Supported ECC Curves 448-------------------- 449 450.. csv-table:: 451 :header: "ID", "Curve" 452 :widths: 1 5 453 454 0,ECC SECP384R1 455 456RMM_ATTEST_GET_PLAT_TOKEN command 457================================= 458 459Retrieve the Platform Token from EL3. If the entire token does not fit in the 460buffer, EL3 returns a hunk of the token (via ``tokenHunkSize`` parameter) and 461indicates the remaining bytes that are pending retrieval (via ``remainingSize`` 462parameter). The challenge object for the platform token must be populated in 463the buffer for the first call of this command and the size of the object is 464indicated by ``c_size`` parameter. Subsequent calls to retrieve remaining hunks of 465the token must be made with ``c_size`` as 0. 466 467If ``c_size`` is not 0, this command could cause regeneration of platform token 468and will return token hunk corresponding to beginning of the token. 469 470It is valid for the calls of this command to return ``E_RMM_AGAIN`` error, 471which is an indication to the caller to retry this command again. Depending on the 472platform, this mechanism can be used to implement queuing to HES, if HES is 473involved in platform token generation. 474 475FID 476--- 477 478``0xC40001B3`` 479 480Input values 481------------ 482 483.. csv-table:: 484 :header: "Name", "Register", "Field", "Type", "Description" 485 :widths: 1 1 1 1 5 486 487 fid,x0,[63:0],UInt64,Command FID 488 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." 489 buf_size,x2,[63:0],Size,Size in bytes of the platform attestation token buffer. ``bufPa + bufSize`` must lie within the shared buffer 490 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." 491 492Output values 493------------- 494 495.. csv-table:: 496 :header: "Name", "Register", "Field", "Type", "Description" 497 :widths: 1 1 1 1 5 498 499 Result,x0,[63:0],Error Code,Command return status 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 502 503Failure conditions 504------------------ 505 506The table below shows all the possible error codes returned in ``Result`` upon 507a failure. The errors are ordered by condition check. 508 509.. csv-table:: 510 :header: "ID", "Condition" 511 :widths: 1 5 512 513 ``E_RMM_AGAIN``,Resource for Platform token retrieval is busy. Try again. 514 ``E_RMM_BAD_ADDR``,``PA`` is outside the shared buffer 515 ``E_RMM_INVAL``,``PA + BSize`` is outside the shared buffer 516 ``E_RMM_INVAL``,``CSize`` does not represent the size of a supported SHA algorithm for the first call to this command 517 ``E_RMM_INVAL``,``CSize`` is not 0 for subsequent calls to retrieve remaining hunks of the token 518 ``E_RMM_UNK``,An unknown error occurred whilst processing the command 519 ``E_RMM_OK``,No errors detected 520 521RMM_EL3_FEATURES command 522======================== 523 524This command provides a mechanism to discover features and ABIs supported by the 525RMM-EL3 interface, for a given version. This command is helpful when there are 526platform specific optional RMM-EL3 interfaces and features exposed by vendor 527specific EL3 firmware, and a generic RMM that can modify its behavior based on 528discovery of EL3 features. 529 530The features can be discovered by specifying the feature register index that 531has fields defined to indicate presence or absence of features and other 532relevant information. The feature register index is specified in the 533``feat_reg_idx`` parameter. Each feature register is a 64 bit register. 534 535This command is available from v0.4 of the RMM-EL3 interface. 536 537The following is the register definition for feature register index 0 for 538v0.4 of the interface: 539 540RMM-EL3 Feature Resister 0 541-------------------------- 542 543.. code-block:: none 544 545 63 32 31 16 15 8 7 1 0 546 +-------+-------+-------+-------+-------+-------+-------+-------+ 547 | | | | | | | | | 548 | | | | | | | | | 549 +-------+-------+-------+-------+-------+-------+-------+-------+ 550 ^ 551 | 552 RMMD_EL3_TOKEN_SIGN 553 554**Bit Fields:** 555 556- **Bit 0**: `RMMD_EL3_TOKEN_SIGN` 557 - When set to 1, the `RMMD_EL3_TOKEN_SIGN` feature is enabled. 558 - When cleared (0), the feature is disabled. 559- **Bits [1:63]**: Reserved (must be zero) 560 561FID 562--- 563 564``0xC40001B4`` 565 566 567Input values 568------------ 569 570.. csv-table:: Input values for RMM_EL3_FEATURES 571 :header: "Name", "Register", "Field", "Type", "Description" 572 :widths: 1 1 1 1 5 573 574 fid,x0,[63:0],UInt64,Command FID 575 feat_reg_idx,x1,[63:0],UInt64, "Feature register index. For v0.4, a value of 0 is the only 576 acceptable value" 577 578 579Output values 580------------- 581 582.. csv-table:: Output values for RMM_EL3_FEATURES 583 :header: "Name", "Register", "Field", "Type", "Description" 584 :widths: 1 1 1 1 5 585 586 Result,x0,[63:0],Error Code,Command return status 587 feat_reg,x1,[63:0],Value,Value of the register as defined above 588 589Failure conditions 590------------------ 591 592The table below shows all the possible error codes returned in ``Result`` upon 593a failure. The errors are ordered by condition check. 594 595.. csv-table:: Failure conditions for RMM_EL3_FEATURES 596 :header: "ID", "Condition" 597 :widths: 1 5 598 599 ``E_RMM_INVAL``,``feat_reg_idx`` is out of valid range 600 ``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4" 601 ``E_RMM_OK``,No errors detected 602 603RMM_EL3_TOKEN_SIGN command 604========================== 605 606This command is an optional command that can be discovered using the RMM_EL3_FEATURES command. 607This command is used to send requests related to realm attestation token signing requests to EL3. 608The command supports 3 opcodes: 609 610 - RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP 611 - RMM_EL3_TOKEN_SIGN_PULL_RESP_OP 612 - RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP 613 614The above opcodes can be used to send realm attestation token signing requests to EL3 and get their 615response, so that the realm attestation token can be constructed. 616 617This command is useful when the RMM may not have access to the private portion of the realm 618attestation key and needs signing services from EL3 or CCA HES, or other platform specific 619mechanisms to perform signing. 620 621The RMM-EL3 interface for this command is modeled as two separate queues, one for signing requests 622and one for retrieving the signed responses. It is possible that the queue in EL3 is full or EL3 is busy and 623unable to service the RMM requests, in which case the RMM is expected to retry the push operation 624for requests and pop operation for responses. 625 626FID 627--- 628 629``0xC40001B5`` 630 631Input values 632------------ 633 634.. csv-table:: Input values for RMM_EL3_TOKEN_SIGN 635 :header: "Name", "Register", "Field", "Type", "Description" 636 :widths: 1 1 1 1 5 637 638 fid,x0,[63:0],UInt64,Command FID 639 opcode,x1,[63:0],UInt64," 640 Opcode that is one of: 641 642 - RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP: 0x1 - 643 Opcode to push a token signing request to EL3 using struct el3_token_sign_request as described above 644 - RMM_EL3_TOKEN_SIGN_PULL_RESP_OP: 0x2 - 645 Opcode to pull a token signing response from EL3 using struct el3_token_sign_response as described above 646 - RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP: 0x3 - 647 Opcode to get the realm attestation public key 648 649 " 650 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" 651 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 652 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 653 654Output values 655------------- 656 657.. csv-table:: Output values for RMM_EL3_TOKEN_SIGN 658 :header: "Name", "Register", "Field", "Type", "Description" 659 :widths: 1 1 1 1 5 660 661 Result,x0,[63:0],Error Code,Command return status. Valid for all opcodes listed in input values 662 retval1,x1,[63:0],Value, "If opcode is RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP, then returns length of 663 public key returned. Otherwise, reserved" 664 665 666Failure conditions 667------------------ 668 669The table below shows all the possible error codes returned in ``Result`` upon 670a failure. The errors are ordered by condition check. 671 672.. csv-table:: Failure conditions for RMM_EL3_TOKEN_SIGN 673 :header: "ID", "Condition" 674 :widths: 1 5 675 676 ``E_RMM_INVAL``,"if opcode is invalid or buffer address and length passed to the EL3 are not in valid range 677 corresponding to the RMM-EL3 shared buffer, or if the curve used for opcode 678 RMM_EL3_TOKEN_SIGN_GET_RAK_PUB_OP is not the ECC P384 curve" 679 ``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.4" 680 ``E_RMM_AGAIN``,"For opcode RMM_EL3_TOKEN_SIGN_PUSH_REQ_OP, if the request is not queued since 681 the EL3 queue is full, or if the response is not ready yet, for other opcodes" 682 ``E_RMM_OK``,No errors detected 683 684RMM_MEC_REFRESH command 685======================= 686 687This command updates the tweak for the encryption key/programs a new encryption key 688associated with a given MECID. After the execution of this command, all memory 689accesses associated with the MECID are encrypted/decrypted using the new key. 690This command is available from v0.8 of the RMM-EL3 interface. 691 692FID 693--- 694 695``0xC40001B6`` 696 697Input values 698------------ 699 700.. csv-table:: Input values for RMM_MEC_REFRESH 701 :header: "Name", "Register", "Field", "Type", "Description" 702 :widths: 1 1 1 1 5 703 704 fid,x0,[63:0],UInt64,Command FID 705 mecid,x1,[47:32],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." 706 mecid,x1,[31:1],UInt64, "Reserved, MBZ" 707 reason,x1,[0],UInt64, "reason is a single bit field used to indicate the reason for the MEC refresh. Values are: 0 (Realm creation), 1 (Realm destruction)." 708 709Output values 710------------- 711 712.. csv-table:: Output values for RMM_MEC_REFRESH 713 :header: "Name", "Register", "Field", "Type", "Description" 714 :widths: 1 1 1 1 5 715 716 Result,x0,[63:0],Error Code,"Command return status. Valid for all opcodes listed in input values" 717 718 719Failure conditions 720------------------ 721 722The table below shows all the possible error codes returned in ``Result`` upon 723a failure. The errors are ordered by condition check. 724 725.. csv-table:: Failure conditions for RMM_MEC_REFRESH 726 :header: "ID", "Condition" 727 :widths: 1 5 728 729 ``E_RMM_INVAL``, "If a field in the x1 register is incorrectly encoded or if MECID is invalid (larger than the common MECID width, determined by MECIDR_EL2.MECIDWidthm1 + 1 or by other system components, whichever is lower)" 730 ``E_RMM_UNK``, "An unknown error occurred whilst processing the command, FEAT_MEC is not present in hardware or the SMC is not present if the version is < 0.8." 731 ``E_RMM_OK``, "No errors detected" 732 733RMM_IDE_KEY_PROG command 734========================= 735 736Set the key/IV info at Root port for an IDE stream as part of Device Assignment flow. This 737command is available from v0.6 of the RMM-EL3 interface. 738 739Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 740for description of the IDE setup sequence and how this will be invoked by RMM. 741 742The key is 256 bits and IV is 96 bits. The caller needs 743to call this SMC to program this key to the Rx, Tx ports and for each sub-stream 744corresponding to a single keyset. 745 746FID 747--- 748 749``0xC40001B7`` 750 751Input values 752------------ 753 754.. csv-table:: Input values for RMM_IDE_KEY_PROG 755 :header: "Name", "Register", "Field", "Type", "Description" 756 :widths: 1 1 1 1 5 757 758 fid,x0,[63:0],UInt64,Command FID 759 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 760 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 761 "Keyset[12]: 762 Dir[11]: 763 Substream[10:8]: 764 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream informationKey set: can be 0 or 1unused bits MBZ. 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] 771 request_id,x10,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 772 cookie,x11,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 773 774 775Output values 776------------- 777 778.. csv-table:: Output values for RMM_IDE_KEY_PROG 779 :header: "Name", "Register", "Field", "Type", "Description" 780 :widths: 1 1 1 1 5 781 782 Result,x0,[63:0],Error Code,Command return status 783 784Failure conditions 785------------------ 786 787The table below shows all the possible error codes returned in ``Result`` upon 788a failure. The errors are ordered by condition check. 789 790.. csv-table:: Failure conditions for RMM_IDE_KEY_PROG 791 :header: "ID", "Condition" 792 :widths: 1 5 793 794 ``E_RMM_OK``,The Key programming is successful. 795 ``E_RMM_FAULT``,The Key programming is not successful. 796 ``E_RMM_INVAL``,The Key programming arguments are incorrect. 797 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 798 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 799 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 800 801 802RMM_IDE_KEY_SET_GO command 803========================== 804 805Activate the IDE stream at Root Port once the keys have been programmed as part of 806Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface. 807 808Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 809for description of the IDE setup sequence and info on how this will be invoked by RMM. 810 811The caller(RMM) needs to ensure the EL3_IDE_KEY_PROG() call had succeeded prior to this call. 812 813FID 814--- 815 816``0xC40001B8`` 817 818Input values 819------------ 820 821.. csv-table:: Input values for RMM_IDE_KEY_SET_GO 822 :header: "Name", "Register", "Field", "Type", "Description" 823 :widths: 1 1 1 1 5 824 825 fid,x0,[63:0],UInt64,Command FID 826 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 827 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 828 "Keyset[12]: 829 Dir[11]: 830 Substream[10:8]: 831 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ. 832 request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 833 cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 834 835 836Output values 837------------- 838 839.. csv-table:: Output values for RMM_IDE_KEY_SET_GO 840 :header: "Name", "Register", "Field", "Type", "Description" 841 :widths: 1 1 1 1 5 842 843 Result,x0,[63:0],Error Code,Command return status 844 845Failure conditions 846------------------ 847 848The table below shows all the possible error codes returned in ``Result`` upon 849a failure. The errors are ordered by condition check. 850 851.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_GO 852 :header: "ID", "Condition" 853 :widths: 1 5 854 855 ``E_RMM_OK``,The Key set go is successful. 856 ``E_RMM_FAULT``,The Key set go is not successful. 857 ``E_RMM_INVAL``,Incorrect arguments. 858 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 859 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 860 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 861 862 863RMM_IDE_KEY_SET_STOP command 864============================ 865 866Deactivate the IDE stream at Root Port as part of Device Assignment flow. This command is 867available from v0.6 of the RMM-EL3 interface. 868 869Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 870for description of the IDE setup sequence and info on how this will be invoked by RMM. 871 872This SMC is used to tear down an IDE Stream. 873 874FID 875--- 876 877``0xC40001B9`` 878 879Input values 880------------ 881 882.. csv-table:: Input values for RMM_IDE_KEY_SET_STOP 883 :header: "Name", "Register", "Field", "Type", "Description" 884 :widths: 1 1 1 1 5 885 886 fid,x0,[63:0],UInt64,Command FID 887 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 888 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 889 "Keyset[12]: 890 Dir[11]: 891 Substream[10:8]: 892 StreamID[7:0]",x3,[63:0],UInt64,IDE selective stream information. Key set can be 0 or 1. Unused bits MBZ. 893 request_id,x4,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 894 cookie,x5,[63:0],UInt64,Used only in non-blocking mode. Ignored in blocking mode. 895 896 897Output values 898------------- 899 900.. csv-table:: Output values for RMM_IDE_KEY_SET_STOP 901 :header: "Name", "Register", "Field", "Type", "Description" 902 :widths: 1 1 1 1 5 903 904 Result,x0,[63:0],Error Code,Command return status 905 906Failure conditions 907------------------ 908 909The table below shows all the possible error codes returned in ``Result`` upon 910a failure. The errors are ordered by condition check. 911 912.. csv-table:: Failure conditions for RMM_IDE_KEY_SET_STOP 913 :header: "ID", "Condition" 914 :widths: 1 5 915 916 ``E_RMM_OK``,The Key set stop is successful. 917 ``E_RMM_FAULT``,The Key set stop is not successful. 918 ``E_RMM_INVAL``,Incorrect arguments. 919 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 920 ``E_RMM_AGAIN``,Returned only for non-blocking mode. IDE-KM interface is busy or request is full. Retry required. 921 ``E_RMM_INPROGRESS``,Returned only for non-blocking mode. The caller must issue RMM_IDE_KM_PULL_RESPONSE SMC to pull the response. 922 923 924RMM_IDE_KM_PULL_RESPONSE command 925================================ 926 927Retrieve the response from Root Port to a previous non-blocking IDE-KM SMC request as part of 928Device Assignment flow. This command is available from v0.6 of the RMM-EL3 interface. 929 930Please refer to `IDE-KM RFC <https://github.com/TF-RMM/tf-rmm/wiki/RFC:-EL3-RMM-IDE-KM-Interface>`_ 931for description of the IDE setup sequence and info on how this will be invoked by RMM. 932 933The response from this call could correspond to any of the last pending requests and the 934RMM needs to identify the request and populate the response. For blocking calls, this SMC 935always returns E_RMM_UNK. 936 937FID 938--- 939 940``0xC40001BA`` 941 942Input values 943------------ 944 945.. csv-table:: Input values for RMM_IDE_KM_PULL_RESPONSE 946 :header: "Name", "Register", "Field", "Type", "Description" 947 :widths: 1 1 1 1 5 948 949 fid,x0,[63:0],UInt64,Command FID 950 ecam_address,x1,[63:0],UInt64,Used to identify the root complex(RC) 951 rp_id,x2,[63:0],UInt64,Used to identify the root port within the root complex(RC) 952 953 954Output values 955------------- 956 957.. csv-table:: Output values for RMM_IDE_KM_PULL_RESPONSE 958 :header: "Name", "Register", "Field", "Type", "Description" 959 :widths: 1 1 1 1 5 960 961 Result,x0,[63:0],Error Code,Command return status 962 Result,x1,[63:0],Error Code,Retrieved response corresponding to previous IDE_KM requests. 963 Result,x2,[63:0],value,passthrough from requested SMC 964 Result,x3,[63:0],value,passthrough from requested SMC 965 966Failure conditions 967------------------ 968 969The table below shows all the possible error codes returned in ``Result`` upon 970a failure. The errors are ordered by condition check. 971 972.. csv-table:: Failure conditions for RMM_IDE_KM_PULL_RESPONSE(x0) 973 :header: "ID", "Condition" 974 :widths: 1 5 975 976 ``E_RMM_OK``,Response is retrieved successfully. 977 ``E_RMM_INVAL``,Arguments to pull response SMC is not correct. 978 ``E_RMM_UNK``,Unknown error or the SMC is not present if the version is < 0.6. 979 ``E_RMM_AGAIN``,IDE-KM response queue is empty and no response is available. 980 981.. csv-table:: Failure conditions for RMM_IDE_KM_PULL_RESPONSE(x1) 982 :header: "ID", "Condition" 983 :widths: 1 5 984 985 ``E_RMM_OK``,The previous request was successful. 986 ``E_RMM_FAULT``,The previous request was not successful. 987 ``E_RMM_INVAL``,Arguments to previous request were incorrect. 988 ``E_RMM_UNK``,Previous request returned unknown error. 989 990RMM_RESERVE_MEMORY command 991========================== 992 993This command is used to reserve memory for the RMM, during RMM boot time. 994This is not a fully featured dynamic memory allocator, since reservations cannot 995be freed again, and they must happen during the cold/warm boot phase of RMM. 996However it allows to size data structures in RMM based on runtime decisions, 997for instance depending on the number of cores or the amount of memory installed. 998This command is available from v0.7 of the RMM-EL3 interface. 999 1000FID 1001--- 1002 1003``0xC40001BB`` 1004 1005Input values 1006------------ 1007 1008.. csv-table:: Input values for RMM_RESERVE_MEMORY 1009 :header: "Name", "Register", "Field", "Type", "Description" 1010 :widths: 1 1 1 1 5 1011 1012 fid,x0,[63:0],UInt64,Command FID 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 base address." 1015 args,x2,[55:32],UInt64,reserved 1016 args,x2,[31:1],UInt64,"flags (reserved)" 1017 args,x2,[0],UInt64,"flags: local CPU: Determines whether the reservation should be taken from a pool close to the calling CPU." 1018 1019Output values 1020------------- 1021 1022.. csv-table:: Output values for RMM_RESERVE_MEMORY 1023 :header: "Name", "Register", "Field", "Type", "Description" 1024 :widths: 1 1 1 1 5 1025 1026 Result,x0,[63:0],Error Code,Command return status. 1027 address,x1,[63:0],Address, "Physical address of the reserved memory area." 1028 1029 1030Failure conditions 1031------------------ 1032 1033The table below shows all the possible error codes returned in ``Result`` upon 1034a failure. The errors are ordered by condition check. 1035 1036.. csv-table:: Failure conditions for RMM_RESERVE_MEMORY 1037 :header: "ID", "Condition" 1038 :widths: 1 5 1039 1040 ``E_RMM_INVAL``,"unrecognised flag bit" 1041 ``E_RMM_UNK``,"if the SMC is not present, if interface version is <0.7" 1042 ``E_RMM_NOMEM``,"size of region is larger than the available memory" 1043 ``E_RMM_OK``,No errors detected 1044 1045EL3–RMM Register Context Management Contract 1046_____________________________________________ 1047 1048As part of the Non-secure (NS) <-> Realm world switch, EL3 shall maintain a 1049separate register context for each world. During a world transition, EL3 1050shall save and restore the required register state to ensure correct 1051execution, isolation, and security. 1052 1053Register Context Managed by EL3 1054~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1055 1056EL3 shall maintain a distinct register context per world and shall save 1057and restore the following registers during a world switch. 1058 1059**General-Purpose and Stack Registers** 1060 1061* General-purpose registers: ``x0–x30`` 1062* Stack pointers: 1063 * ``SP_EL0`` 1064 * ``SP_EL2`` 1065 1066**EL2 System Registers** 1067 1068EL3 shall save and restore all EL2 system registers corresponding to 1069features enabled by EL3 (that is, registers with the ``_EL2`` 1070architectural suffix), excluding the registers listed below (see 1071:ref:`el2_registers_excluded`). 1072 1073**Pointer Authentication Registers** 1074 1075EL3 shall save and restore the following Pointer Authentication (PAuth) 1076key registers: 1077 1078* ``APIA`` 1079* ``APIB`` 1080* ``APDA`` 1081* ``APDB`` 1082* ``APGA`` 1083 1084.. _el2_registers_excluded: 1085 1086Registers Not Managed by EL3 1087~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1088 1089EL3 shall not save or restore the registers listed below. If the Realm 1090world makes use of any of the registers below, the Realm Management 1091Monitor (RMM) is responsible for ensuring their correct preservation. 1092 1093**EL2 Registers Excluded from EL3 Management** 1094 1095* EL2 physical timer registers 1096* EL2 virtual timer registers 1097* ``ZCR_EL2`` 1098* ``ICC_SRE_EL2`` if interface version is >= 1.0 1099* ``ICH_HCR_EL2`` if interface version is >= 1.0 1100* ``ICH_VMCR_EL2`` if interface version is >= 1.0 1101 1102**Additional Registers Outside EL3 Scope** 1103 1104* FP/SIMD registers 1105* SVE registers 1106* SME registers 1107* EL1 and EL0 system registers (except the PAuth key registers listed 1108 above) 1109 1110SMCCC Compliance 1111~~~~~~~~~~~~~~~~~ 1112 1113During SMC forwarding between the Non-secure world and the Realm world: 1114 1115* EL3 shall forward registers ``x0–x7`` from the Non-secure context to 1116 the Realm context as SMC input arguments. 1117* EL3 populates return values in registers ``x0–x7`` on return back to Non-Secure. 1118 1119In accordance with SMCCC v1.2: 1120 1121* Register ``x4-x7`` shall be preserved if it is not used to return a 1122 result. 1123* The responsibility for preserving ``x4-x7``, when required, lies with 1124 RMM. 1125 1126In accordance with SMCCC v1.3: 1127 1128* The Non-secure world may specify whether SVE context is in use. 1129* If the SVE context is marked as not in use by the Non-secure world, RMM may choose not to 1130 preserve the incoming SVE state, 1131 even if SVE registers are used during Realm execution. 1132 Before returning to the Non-secure world, the SVE register state is cleared in this case 1133* The same requirements apply to SME registers. 1134 1135Note: 1136 1137Communication between NS world and RMM as defined by the RMM specification expects 1138a maximum of registers x0–x7 for input arguments and returns results in x0–x7. 1139If a future RMM specification requires extended input or output beyond this register set, 1140this section of EL3–RMM contract will be updated. 1141 1142Security Requirement 1143~~~~~~~~~~~~~~~~~~~~ 1144 1145EL3 shall adhere to this contract to preserve the confidentiality and 1146integrity of the Realm world during world transitions. Non-compliance 1147may cause state corruption or cross-world information leakage. 1148 1149Types 1150_____ 1151 1152.. _rmm_el3_manifest_struct: 1153 1154RMM-EL3 Boot Manifest structure 1155~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1156 1157The RMM-EL3 Boot Manifest v0.5 structure contains platform boot information passed 1158from EL3 to RMM. The size of the Boot Manifest is 160 bytes. 1159 1160The members of the RMM-EL3 Boot Manifest structure are shown in the following 1161table: 1162 1163+-------------------+--------+-------------------+----------------------------------------------+ 1164| Name | Offset | Type | Description | 1165+===================+========+===================+==============================================+ 1166| version | 0 | uint32_t | Boot Manifest version | 1167+-------------------+--------+-------------------+----------------------------------------------+ 1168| padding | 4 | uint32_t | Reserved, set to 0 | 1169+-------------------+--------+-------------------+----------------------------------------------+ 1170| plat_data | 8 | uint64_t | Pointer to Platform Data section | 1171+-------------------+--------+-------------------+----------------------------------------------+ 1172| plat_dram | 16 | memory_info | NS DRAM Layout Info structure | 1173+-------------------+--------+-------------------+----------------------------------------------+ 1174| plat_console | 40 | console_list | List of consoles available to RMM | 1175+-------------------+--------+-------------------+----------------------------------------------+ 1176| plat_ncoh_region | 64 | memory_info | Device non-coherent ranges Info structure | 1177+-------------------+--------+-------------------+----------------------------------------------+ 1178| plat_coh_region | 88 | memory_info | Device coherent ranges Info structure | 1179+-------------------+--------+-------------------+----------------------------------------------+ 1180| plat_smmu | 112 | smmu_list | List of SMMUs available to RMM | 1181| | | | (from Boot Manifest v0.5) | 1182+-------------------+--------+-------------------+----------------------------------------------+ 1183| plat_root_complex | 136 | root_complex_list | List of PCIe root complexes available to RMM | 1184| | | | (from Boot Manifest v0.5) | 1185+-------------------+--------+-------------------+----------------------------------------------+ 1186 1187.. _memory_info_struct: 1188 1189Memory Info structure 1190~~~~~~~~~~~~~~~~~~~~~ 1191 1192Memory Info structure contains information about platform memory layout. 1193The members of this structure are shown in the table below: 1194 1195+-----------+--------+---------------+----------------------------------------+ 1196| Name | Offset | Type | Description | 1197+===========+========+===============+========================================+ 1198| num_banks | 0 | uint64_t | Number of memory banks/device regions | 1199+-----------+--------+---------------+----------------------------------------+ 1200| banks | 8 | memory_bank * | Pointer to 'memory_bank'[] array | 1201+-----------+--------+---------------+----------------------------------------+ 1202| checksum | 16 | uint64_t | Checksum | 1203+-----------+--------+---------------+----------------------------------------+ 1204 1205Checksum is calculated as two's complement sum of 'num_banks', 'banks' pointer 1206and memory banks data array pointed by it. 1207 1208.. _memory_bank_struct: 1209 1210Memory Bank/Device region structure 1211~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1212 1213Memory Bank structure contains information about each memory bank/device region: 1214 1215+------+--------+----------+--------------------------------------------+ 1216| Name | Offset | Type | Description | 1217+======+========+==========+============================================+ 1218| base | 0 | uint64_t | Base address | 1219+------+--------+----------+--------------------------------------------+ 1220| size | 8 | uint64_t | Size of memory bank/device region in bytes | 1221+------+--------+----------+--------------------------------------------+ 1222 1223.. _console_list_struct: 1224 1225Console List structure 1226~~~~~~~~~~~~~~~~~~~~~~ 1227 1228Console List structure contains information about the available consoles for RMM. 1229The members of this structure are shown in the table below: 1230 1231+--------------+--------+----------------+-----------------------------------+ 1232| Name | Offset | Type | Description | 1233+==============+========+================+===================================+ 1234| num_consoles | 0 | uint64_t | Number of consoles | 1235+--------------+--------+----------------+-----------------------------------+ 1236| consoles | 8 | console_info * | Pointer to 'console_info'[] array | 1237+--------------+--------+----------------+-----------------------------------+ 1238| checksum | 16 | uint64_t | Checksum | 1239+--------------+--------+----------------+-----------------------------------+ 1240 1241Checksum is calculated as two's complement sum of 'num_consoles', 'consoles' 1242pointer and the consoles array pointed by it. 1243 1244.. _console_info_struct: 1245 1246Console Info structure 1247~~~~~~~~~~~~~~~~~~~~~~ 1248 1249Console Info structure contains information about each Console available to RMM. 1250 1251+-----------+--------+----------+--------------------------------------+ 1252| Name | Offset | Type | Description | 1253+===========+========+==========+======================================+ 1254| base | 0 | uint64_t | Console Base address | 1255+-----------+--------+----------+--------------------------------------+ 1256| map_pages | 8 | uint64_t | Num of pages to map for console MMIO | 1257+-----------+--------+----------+--------------------------------------+ 1258| name | 16 | char[8] | Name of console | 1259+-----------+--------+----------+--------------------------------------+ 1260| clk_in_hz | 24 | uint64_t | UART clock (in Hz) for console | 1261+-----------+--------+----------+--------------------------------------+ 1262| baud_rate | 32 | uint64_t | Baud rate | 1263+-----------+--------+----------+--------------------------------------+ 1264| flags | 40 | uint64_t | Additional flags (RES0) | 1265+-----------+--------+----------+--------------------------------------+ 1266 1267.. _smmu_list_struct: 1268 1269SMMU List structure 1270~~~~~~~~~~~~~~~~~~~ 1271 1272SMMU List structure contains information about SMMUs available for RMM. 1273The members of this structure are shown in the table below: 1274 1275+-----------+--------+-------------+--------------------------------+ 1276| Name | Offset | Type | Description | 1277+===========+========+=============+================================+ 1278| num_smmus | 0 | uint64_t | Number of SMMUs | 1279+-----------+--------+-------------+--------------------------------+ 1280| smmus | 8 | smmu_info * | Pointer to 'smmu_info'[] array | 1281+-----------+--------+-------------+--------------------------------+ 1282| checksum | 16 | uint64_t | Checksum | 1283+-----------+--------+-------------+--------------------------------+ 1284 1285.. _smmu_info_struct: 1286 1287SMMU Info structure 1288~~~~~~~~~~~~~~~~~~~ 1289 1290SMMU Info structure contains information about each SMMU available to RMM. 1291 1292+-------------+--------+----------+-------------------------------+ 1293| Name | Offset | Type | Description | 1294+=============+========+==========+===============================+ 1295| smmu_base | 0 | uint64_t | SMMU Base address | 1296+-------------+--------+----------+-------------------------------+ 1297| smmu_r_base | 8 | uint64_t | SMMU Realm Pages base address | 1298+-------------+--------+----------+-------------------------------+ 1299 1300.. _root_complex_list_struct: 1301 1302Root Complex List structure 1303~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1304 1305Root Complex List structure contains information about PCIe root complexes available for RMM. 1306The members of this structure are shown in the table below. 1307 1308+------------------+--------+---------------------+-------------------------------------+ 1309| Name | Offset | Type | Description | 1310+==================+========+=====================+=====================================+ 1311| num_root_complex | 0 | uint64_t | Number of root complexes | 1312+------------------+--------+---------------------+-------------------------------------+ 1313| rc_info_version | 8 | uint32_t | Root Complex Info structure version | 1314+------------------+--------+---------------------+-------------------------------------+ 1315| padding | 12 | uint32_t | Reserved, set to 0 | 1316+------------------+--------+---------------------+-------------------------------------+ 1317| root_complex | 16 | root_complex_info * | Pointer to 'root_complex'[] array | 1318+------------------+--------+---------------------+-------------------------------------+ 1319| checksum | 24 | uint64_t | Checksum | 1320+------------------+--------+---------------------+-------------------------------------+ 1321 1322The checksum calculation of Root Complex List structure includes all data structures 1323referenced by 'root_complex_info' pointer. 1324 1325.. _root_complex_info_struct: 1326 1327Root Complex Info structure 1328~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1329 1330Root Complex Info structure contains information about each PCIe root complex available to RMM. 1331The table below describes the members of this structure as per v0.1. 1332 1333+-----------------+--------+------------------+-------------------------------------+ 1334| Name | Offset | Type | Description | 1335+=================+========+==================+=====================================+ 1336| ecam_base | 0 | uint64_t | PCIe ECAM Base address | 1337+-----------------+--------+------------------+-------------------------------------+ 1338| segment | 8 | uint8_t | PCIe segment identifier | 1339+-----------------+--------+------------------+-------------------------------------+ 1340| padding[3] | 9 | uint8_t | Reserved, set to 0 | 1341+-----------------+--------+------------------+-------------------------------------+ 1342| num_root_ports | 12 | uint32_t | Number of root ports | 1343+-----------------+--------+------------------+-------------------------------------+ 1344| root_ports | 16 | root_port_info * | Pointer to 'root_port_info'[] array | 1345+-----------------+--------+------------------+-------------------------------------+ 1346 1347The Root Complex Info structure version uses the same numbering scheme as described in 1348:ref:`rmm_el3_ifc_versioning`. 1349 1350.. _root_port_info_struct: 1351 1352Root Port Info structure 1353~~~~~~~~~~~~~~~~~~~~~~~~ 1354 1355Root Complex Info structure contains information about each root port in PCIe root complex. 1356 1357+------------------+--------+--------------------+---------------------------------------+ 1358| Name | Offset | Type | Description | 1359+==================+========+====================+=======================================+ 1360| root_port_id | 0 | uint16_t | Root Port identifier | 1361+------------------+--------+--------------------+---------------------------------------+ 1362| padding | 2 | uint16_t | Reserved, set to 0 | 1363+------------------+--------+--------------------+---------------------------------------+ 1364| num_bdf_mappings | 4 | uint32_t | Number of BDF mappings | 1365+------------------+--------+--------------------+---------------------------------------+ 1366| bdf_mappings | 8 | bdf_mapping_info * | Pointer to 'bdf_mapping_info'[] array | 1367+------------------+--------+--------------------+---------------------------------------+ 1368 1369.. _bdf_mapping_info_struct: 1370 1371BDF Mapping Info structure 1372~~~~~~~~~~~~~~~~~~~~~~~~~~ 1373 1374BDF Mapping Info structure contains information about each Device-Bus-Function (BDF) mapping 1375for PCIe root port. 1376 1377+--------------+--------+----------+------------------------------------------------------+ 1378| Name | Offset | Type | Description | 1379+==============+========+==========+======================================================+ 1380| mapping_base | 0 | uint16_t | Base of BDF mapping (inclusive) | 1381+--------------+--------+----------+------------------------------------------------------+ 1382| mapping_top | 2 | uint16_t | Top of BDF mapping (exclusive) | 1383+--------------+--------+----------+------------------------------------------------------+ 1384| mapping_off | 4 | uint16_t | Mapping offset, as per Arm Base System Architecture: | 1385| | | | StreamID = RequesterID[N-1:0] + (1<<N)*Constant_B | 1386+--------------+--------+----------+------------------------------------------------------+ 1387| smmu_idx | 6 | uint16_t | SMMU index in 'smmu_info'[] array | 1388+--------------+--------+----------+------------------------------------------------------+ 1389 1390.. _el3_token_sign_request_struct: 1391 1392EL3 Token Sign Request structure 1393~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1394 1395This structure represents a realm attestation token signing request. 1396 1397+-------------+--------+---------------+-----------------------------------------+ 1398| Name | Offset | Type | Description | 1399+=============+========+===============+=========================================+ 1400| sig_alg_id | 0 | uint32_t | Algorithm idenfier for the sign request.| 1401| | | | - 0x0: ECC SECP384R1 (ECDSA) | 1402| | | | - Other values reserved | 1403+-------------+--------+---------------+-----------------------------------------+ 1404| rec_granule | 8 | uint64_t | Identifier used by RMM to associate | 1405| | | | a signing request to a realm. Must not | 1406| | | | be interpreted or modified. | 1407+-------------+--------+---------------+-----------------------------------------+ 1408| req_ticket | 16 | uint64_t | Value used by RMM to associate request | 1409| | | | and responses. Must not be interpreted | 1410| | | | or modified. | 1411+-------------+--------+---------------+-----------------------------------------+ 1412| hash_alg_id | 24 | uint32_t | Hash algorithm for data in `hash_buf` | 1413| | | | - 0x1: SHA2-384 | 1414| | | | - All other values reserved. | 1415+-------------+--------+---------------+-----------------------------------------+ 1416| hash_buf | 32 | uint8_t[] | TBS (to-be-signed) Hash of length | 1417| | | | defined by hash algorithm `hash_alg_id` | 1418+-------------+--------+---------------+-----------------------------------------+ 1419 1420.. _el3_token_sign_response_struct: 1421 1422EL3 Token Sign Response structure 1423~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1424 1425This structure represents a realm attestation token signing response. 1426 1427+---------------+--------+---------------+-----------------------------------------+ 1428| Name | Offset | Type | Description | 1429+===============+========+===============+=========================================+ 1430| rec_granule | 0 | uint64_t | Identifier used by RMM to associate | 1431| | | | a signing request to a realm. Must not | 1432| | | | be interpreted or modified. | 1433+---------------+--------+---------------+-----------------------------------------+ 1434| req_ticket | 8 | uint64_t | Value used by RMM to associate request | 1435| | | | and responses. Must not be interpreted | 1436| | | | or modified. | 1437+---------------+--------+---------------+-----------------------------------------+ 1438| sig_len | 16 | uint16_t | Length of the `signature_buf` field | 1439+---------------+--------+---------------+-----------------------------------------+ 1440| signature_buf | 18 | uint8_t[] | Signature | 1441+---------------+--------+---------------+-----------------------------------------+ 1442
