From 78146cdad783a8001f056ea976155ee1ebbcf2ff Mon Sep 17 00:00:00 2001 From: Marco Visaya Date: Fri, 10 Jan 2025 15:10:12 -0800 Subject: [PATCH 1/4] Add mailbox commands used by MCU Image Loading MCU would need the load address and the offset location of the image during image loading as described in: https://github.com/chipsalliance/caliptra-mcu-sw/blob/main/docs/src/image_loading.md Since caliptra core stores the manifest, the MCU would send mailbox commands to caliptra core to retrieve this information. --- runtime/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/runtime/README.md b/runtime/README.md index 2b3dd9c944..8208576a33 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -997,6 +997,49 @@ Command Code: `0x4154_5348` ("ATSH") | fips_status | u32 | Indicates if the command is FIPS approved or an error. | | auth_req_result | u32 |AUTHORIZE_IMAGE (0xDEADC0DE), IMAGE_NOT_AUTHORIZED (0x21523F21) or IMAGE_HASH_MISMATCH (0x8BFB95CB) +### GET_IMAGE_LOAD_ADDRESS + +The MCU uses this command to retrieve the AXI load address of a SoC Image identified by the firmware id. The address is retrieved from the SoC Manifest loaded by Caliptra. + +Command Code: `0x494D_4C41` ("IMLA") + +*Table: `GET_IMAGE_LOAD_ADDRESS` input arguments* + +| **Name** | **Type** | **Description** +| -------------- | -------------- | --------------------------------------------------------------------------- +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. +| fw_id | u8[4] | Firmware id of the image, in little-endian format + +*Table: `GET_IMAGE_LOAD_ADDRESS` output arguments* + +| **Name** | **Type** | **Description** +| ----------------- | -------------- | -------------------------------------------------------------------------- +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. +| fips_status | u32 | Indicates if the command is FIPS approved or an error. +| load_address_high | u32 | The higher 4 bytes of the 64-bit AXI load address. +| load_address_low | u32 | The lower 4 bytes of the 64-bit AXI load address. + +### GET_IMAGE_LOCATION_OFFSET + +The MCU uses this command to retrieve the offset where it can find the location of the image blob for a SoC Image from the flash storage partition or firmware update package. + +Command Code: `0x494D_4C4F` ("IMLO") + +*Table: `GET_IMAGE_LOCATION_OFFSET` input arguments* + +| **Name** | **Type** | **Description** +| -------------- | -------------- | --------------------------------------------------------------------------- +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. +| fw_id | u8[4] | Firmware id of the image, in little-endian format + +*Table: `GET_IMAGE_LOCATION_OFFSET` output arguments* + +| **Name** | **Type** | **Description** +| ----------------- | -------------- | -------------------------------------------------------------------------- +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. +| fips_status | u32 | Indicates if the command is FIPS approved or an error. +| offset | u32 | The offset in flash storage partition or firmware update package offset where the SoC image resides. + ## Mailbox commands: Cryptographic Mailbox (2.0) These commands are used by the [Cryptograhic Mailbox](#cryptographic-mailbox-commands-new-in-20) system. From 65adc5863bcc91a900002adc1314c300412779e6 Mon Sep 17 00:00:00 2001 From: Marco Visaya Date: Tue, 14 Jan 2025 10:24:15 -0800 Subject: [PATCH 2/4] Add command to get image size --- runtime/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/runtime/README.md b/runtime/README.md index 8208576a33..f9ae7ad014 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -1040,6 +1040,27 @@ Command Code: `0x494D_4C4F` ("IMLO") | fips_status | u32 | Indicates if the command is FIPS approved or an error. | offset | u32 | The offset in flash storage partition or firmware update package offset where the SoC image resides. +### GET_IMAGE_SIZE + +The MCU uses this command to retrieve the size (in bytes) of a SoC Image. + +Command Code: `0x494D_535A` ("IMSZ") + +*Table: `GET_IMAGE_SIZE` input arguments* + +| **Name** | **Type** | **Description** +| -------------- | -------------- | --------------------------------------------------------------------------- +| chksum | u32 | Checksum over other input arguments, computed by the caller. Little endian. +| fw_id | u8[4] | Firmware id of the image, in little-endian format + +*Table: `GET_IMAGE_SIZE` output arguments* + +| **Name** | **Type** | **Description** +| ----------------- | -------------- | -------------------------------------------------------------------------- +| chksum | u32 | Checksum over other output arguments, computed by Caliptra. Little endian. +| fips_status | u32 | Indicates if the command is FIPS approved or an error. +| size | u32 | The size in bytes of the SoC Image + ## Mailbox commands: Cryptographic Mailbox (2.0) These commands are used by the [Cryptograhic Mailbox](#cryptographic-mailbox-commands-new-in-20) system. From 5f0f9d63e74be1fcd7ab86a800c3b757de9d642f Mon Sep 17 00:00:00 2001 From: Marco Visaya Date: Tue, 14 Jan 2025 12:47:02 -0800 Subject: [PATCH 3/4] Remove SVN field, since it's per manifest, not per image --- runtime/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/runtime/README.md b/runtime/README.md index f9ae7ad014..ee7347545e 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -981,7 +981,6 @@ Command Code: `0x4154_5348` ("ATSH") | fw_id | u8[4] | Firmware id of the image, in little-endian format | | measurement | u8[48] | Digest of the image requested for authorization | | context | u8[48] | Context field for `svn`; e.g., a hash of the public key that authenticated the SVN. | -| svn | u32 | SVN | | flags | u32 | See AUTHORIZE_AND_STASH_FLAGS below | | source | u32 | Enumeration values: { InRequest(1), ShaAcc (2) } | From 850f2cae17d4cebae598a4da47ceb856dca93f0d Mon Sep 17 00:00:00 2001 From: Marco Visaya Date: Tue, 14 Jan 2025 12:50:36 -0800 Subject: [PATCH 4/4] Change GET_IMAGE_LOCATION_OFFSET description for clarity --- runtime/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runtime/README.md b/runtime/README.md index ee7347545e..1728eaa08c 100644 --- a/runtime/README.md +++ b/runtime/README.md @@ -1020,7 +1020,7 @@ Command Code: `0x494D_4C41` ("IMLA") ### GET_IMAGE_LOCATION_OFFSET -The MCU uses this command to retrieve the offset where it can find the location of the image blob for a SoC Image from the flash storage partition or firmware update package. +The MCU uses this command to obtain the offset necessary to locate the image blob for a SoC Image within the flash storage partition or firmware update package. Command Code: `0x494D_4C4F` ("IMLO")