Skip to content

Commit

Permalink
Update Image Loading Doc (#78)
Browse files Browse the repository at this point in the history 
* Update Image Loading Doc

- Update the API, user will choose which image to load by specifying the
image id.
- MCU FW will not need to get the metadata of the image from flash or
PLDM, instead it will issue a Mailbox command to get the load address
- Remove the example usage, since there's only API to use.

* Add step to get the offset of the image using mailbox command

It is needed to get the offset of the image from caliptra so that MCU
can read the correct location in flash or in the downloaded PLDM image
  • Loading branch information
@mlvisaya
mlvisaya authored Jan 8, 2025
1 parent ae37e04 commit ee04979
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 49 deletions.
66 changes: 19 additions & 47 deletions docs/src/image_loading.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
The Image Loading module is a component of the MCU Runtime SDK designed for managing SOC images. This module provides APIs for:

- Loading SOC images to target components. The SOC images could come from a [flash storage](./flash_layout.md) or from another platform capable of streaming images through PLDM T5 (e.g., a BMC Recovery Agent).
- Retrieving the SOC Image Metadata (as defined in the [SOC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md) documentation)
- Verifying and authenticating the SOC Images through the Caliptra Core. Images that are loaded to the target SOC components will be authenticated using a mailbox command to the Caliptra core and are verified against the measurements in the SOC Manifest.

The diagram below provides an **example** of how the Caliptra subsystem, integrated with custom SOC elements (highlighted in green), facilitates the loading of SOC images to vendor components.
Expand Down Expand Up @@ -34,14 +33,14 @@ The sequence diagram below shows the high level steps of loading MCU RT image an
* *Black Arrows indicates actions taken by the PLDM FW Update Agent*

<p align="center">
<!--- https://www.plantuml.com/plantuml/uml/ZLFVRzem47xtNt7hNZQf3OEjFyf3LKOBhTI82gWsQQqcannWoN6YvCBM_VMx60muCBgNnFPzz-Exk--w89bJcMZnZkQO82GoBqJ6RofIcJG4HrsfLKQvF09PWBluaD5T1pfHP15ytkyFeLHwalwkKExi8yFkapNoVyS0es4dTDQVrSM7335A5vY_mdsZPs7kmOSzFjo4qFi6p-OfYoKXT6Peo3fK9X_SqxAOMviz2M5IzgYYhllGXc5fZ3ApzGiC1w5em0RAzMvGVB40mOUJ7--pCiyqlbnPJ3E0-qJE44PfcKVyGuqHFPiFDdkZgk_ZdXAEhRaDhG0w9StJNFr1a2Q6XrJ6MsMDcVTU1f-3EWc75kxEfUOOlrovfhRX2pkXZ5zXckOm6dGXb4PDiI0XDIrxMNrEjbnE0sReGL4NkEgj_Muwuhcrwcuc5i81N6chZMh3cO_U9R5XVhvi6HgUkIJq_0wHlzWcRqSwNexkt-GlWwQ7_3_kbyozvcRY7UfE4Rn2dsfmuMmEo_9a60_YZdE24zQ17ZMvWcwQi33y_h24R8X50Ilvsv278l6YZP3Wzljjjz4Vm5T5DRGJ0YzNFuLVYbCMI7MjECWD4aQ4CInZWIeEeJcpxOdJ5IZ31PjuC9q2oOb6KPDiypJmPJjsgfteSXtvZ458kS85lX7UZtzSBGZxdrS36py2cZB1N99AZRz4Bj_sb2zucVfhFY6IZ2L97fFcr3P4VRlsHscz5OMNxPe_PQB_0W00 -->
<!--- https://www.plantuml.com/plantuml/uml/ZPDHRzem4CVV_IbktSichM5qQxVoK9NHqbPgn0HKcxHMaqaEiEGuaNDXwpxzBWO33epr9R5plxlS_-p_PKdIKfLfyOhcc25aqfQYu6ygKOKq14SzgLL1LXw1BC5lGcHqsuLkaZY2r_lp8PPAJ_BVDUNN8Hdt7boGtpi160sxiO_-h3SXCiGaNw1zXhjMts7-GuXzlR-AeVyD7ir3aKf2wCxGa4keGo7SrxASkvXR2M5opgYhhkVGWM5bZ3ApzHSO3cBHWWtA_MuetZX0yEBun-kYieN6fml7j2Euo-GCOPHNDk4NQapeqRnnVs_L_RtTqy8x5-x0IGJTYkQvLNyGf4dXFfVfLbjZrhrNmOUeASBJmk-vLOlfquKVQWS-SXBAz1cckONHe0UnD6gA9GcfQJdB-d6ybN8QjQCGHLtYQhRkkPb8a7RIJ3Ef41xmhQrkL0VEGdfNn4Rvf-N8q91A966GTqZyvstnxaZ7owFxj_Zpg1sGBzD-pjeRQIRTaUuTmLVeVGCNFkPPjYTZV12t_4_mnZemepPtqCipDaOu7xQGAx4eOML_L_9G9Rve8oIu_dxTQzqCu8kY1ksDm9Vh9eTVoYAKI4slUEGA2HF259QrG9M7QFwpcudt5IZ33PjqC9q2oOb6qR1i-pGARJlshfteQbtvZ24agt21_oalBj6aLQR_0W00 -->
<img src="images/image_loading_sequence.svg" alt="flash_config" width="100%">
</p>

The following steps are done for every SOC image:

<p align="center">
<!--- https://www.plantuml.com/plantuml/uml/TLB1RjD04BtlLxmM2S41bmOua4FLO5gAH0GYIa4Y5ThQOsSbUzVQ7LFQhsUys4bNIdsmP_QzcNdxnkU1jUU-RTGHRwabjDe7rScPAKodBUCurutfsEjZw80fIIchgmKMHH4P4X-knrARvjRzZQmnJfdBV1r1-IgLGj--V5pYyWSsTjsLcWcBcYn7zW2bvCj6Xst4OfI2rsHBvv6xjdDswb5CcPAdSQv39HpwG_uUgwyvJAjhKhhX_zEEEg_hLeF9FO1zJseuVlNhsMtJqytPhjiSf--pqmoVX_AJlAgLeYRGA2k-doYQFIuInKeysL57y-QOlSwWUzuwRnxeHHJvsvGlrQwNb7WgRyvaAS9Eb4nhcIXJBZmPVatULFUu4eKm5kE2nVuxmzjeoL9RKr7WoDdOQDYau811wRZ7TtYJuJjnxor2NnGKWdgE4TtVE5_FiHhXlHM9whSPLiIu-7cHdtno-60OhjflTcCBvpq5oKfZQx3Roqt59RkOlSiWtUwC9mJYOHSOVX1rBb7VDly0_ -->
<!--- https://www.plantuml.com/plantuml/uml/ZLHjRzCm4FxkNt4R4e8FPAoyxyEq4ZQ6H0MYT23HgVAIIshXs95zOMo_7iU9brcaNLkfzUMUv_pSo-N44ZVKL9BjqHehX8eRoshtJ6IYvefWF-LIr6JuFd0BmOWXy_CfJBFC8znvd0ypBkIL_jkYmZb6pjA5Txf_ncBNryyVPd3s0vPgKUUS4AObAlBerXM3poItQ-_pfzXvWIhN1b9TrLg565cmcFj8hMie70R_eBc1-PSKHCLBPCm9U_RhqPLiyFAup-083jyaK2AjF6QbYy8YFUaCaJzbZqEkZcamlpmEzJY2XwWiG0DrkFDj0ZlSrojD5_ypDYNphbCaDSzNFCyDMhjRCjkesvEPF4_WFcayXH5Srwd9OGBV3LUsGDEb2491jcxKRykuf6v0zch3oue3eRu5CWsozd5yWOlKVk5J6-GWBSek2aDfiHyb_pl2ceomL1xL-6x6F2KY30neKnflpSHHU4DhRSGjxjAJpPGxAO7YbjQXNzpJ5BShZleoWGiqehY1SrUDjjhz2m2MwbhGsg_CZ2jHe2MFMIg_K471I3SsJyUh1BuXDKQ1RR9iotpCU_TGlKZrwmJcI73wypGz-AZXlI3GnR3vIvLfOz0wAnUg1DA3t5XSt4gtmYxQjJ085cdeuOaxDPNy1m00 -->
<img src="images/image_loading_sequence_loop.svg" alt="flash_config" width="80%">
</p>
The following outlines the steps carried out by the MCU RT during the SOC boot process:
Expand All @@ -68,23 +67,22 @@ The following outlines the steps carried out by the MCU RT during the SOC boot p
14. The EXEC/GO bit sets a Caliptra wire to MCU (as a consequence of setting the EXEC/GO bit in the previous step). When MCU detects this event, it sets a parameter using the FW HandOff table to indicate the image source (i.e. the image source where it booted from).
15. MCU switches to MCU RT
16. MCU RT retrieves the image source from HandOff table
17. BMC or a similar platform component will now do MCTP enumeration flow to MCU over I3C. This will be used for transfering SOC images via PLDM.
18. Retrieve SOC Images Metadata

1. If Image is coming from PLDM, retrieve Image Metadata Collection (from the PLDM SoC Manifest component) through PLDM T5 flow.
2. If Image is coming from flash, read Flash Image Metadata Collection section of the SOC Manifest.
For every image that needs to be loaded, user initiates a call to load an image identified by an image_id:

For every image listed in the Metadata collection:
17. MCU RT issues a mailbox command to get the offset of the image (with respect to the start of the SOC manifest).
18. Caliptra RT responds with the image offset.
19. MCU RT issues a mailbox command to get the load address of the image with the given image_id
20. Caliptra RT responds with the load address if it exists
21. MCU RT reads a chunk of the image into a local buffer and writes it directly the image to the target load address. (In the example custom SOC design, this will be the Vendor RAM or Vendor Cfg Storage). This is done until all chunks are copied to the destination.
22. MCU RT sends a Caliptra mailbox command to authorize the image in the SHA Acc identified by the image_id in the image metadata.
23. Caliptra RT sends the image to the SHA Acc.
24. Caliptra RT verifies the computed hash in SHA acc versus the one in the SOC manifest corresponding to the image_id given.
25. Once verified, Caliptra RT returns Success response to MCU via the mailbox.

19. Retrieve the SOC Image (could be Firmware or Configuration payload). MCU RT writes directly the image to the target load address as specified in the image metadata. (In the example custom SOC design, this will be the Vendor RAM or Vendor Cfg Storage)
20. MCU RT sends a Caliptra mailbox command to authorize the image in the SHA Acc identified by the image_id in the image metadata.
21. Caliptra RT sends the image to the SHA Acc.
22. Caliptra RT verifies the computed hash in SHA acc versus the one in the SOC manifest corresponding to the image_id given.
23. Once verified, Caliptra RT returns Success response to MCU via the mailbox.

Steps 24-25, are SOC design-specific options One option is to use the Caliptra 'Go' register to set the corresponding 'Go' wire to allow the target component to process the loaded image.
24. MCU RT sets the corresponding Go bit in Caliptra register corresponding to the image component.
25. The Go bit sets the corresponding wire that indicates the component can process the loaded image.
Steps 26-27, are SOC design-specific options One option is to use the Caliptra 'Go' register to set the corresponding 'Go' wire to allow the target component to process the loaded image.
26. MCU RT sets the corresponding Go bit in Caliptra register corresponding to the image component.
27. The Go bit sets the corresponding wire that indicates the component can process the loaded image.

## Architecture

Expand All @@ -107,40 +105,14 @@ The APIs are presented as methods of the ImageLoader trait.

/// Trait defining the Image Loading module
pub trait ImageLoader {
/// Retrieves the Image Metadata collection from the image source.
/// The ImageLoader module automatically selects the appropriate image source based on the parameter passed by MCU ROM in the HandOff FW table.
///
/// # Returns
/// - `Ok(ImageMetadataCollection)`: The ImageMetadataCollection if successfully retrieved.
/// - `Err(DynError)`: An error if retrieval fails.
async fn get_imc(&self) -> Result<ImageMetadataCollection, DynError>;

/// Loads the specified image to a storage mapped to the AXI bus memory map.
/// If the image will be loaded directly to the target component, the AXI mapped load address in the image metadata can be used.
///
/// # Parameters
/// image_id: The unsigned integer identifier of the image.
///
/// # Returns
/// - `Ok()`: Image has been loaded and authorized succesfully.
/// - `Err(DynError)`: Indication of the failure to load or authorize the image.
async fn load_and_authorize(&self, image_id: u32, address: u64) -> Result<(), DynError>;
async fn load_and_authorize(&self, image_id: u32) -> Result<(), DynError>;
}
```

## Using ImageLoader in the Application

This section describes how to use ImageLoader to load an image.

1. Retrieve the SOC manifest from flash using ImageLoader.

```rust
loader.get_imc().await?
```

3. Load and authorize the image

```rust
for entry in &imc.image_metadata_entries {
loader.load_and_authorize(entry.image_identifier, entry.load_address).await?;
// Call API to indicate to target component that image has been authenticated and is ready to be executed / processed.

}
```
Loading

0 comments on commit ee04979

Please sign in to comment.