From f78e9f95d836b618ac94233aa6b4618eeb471b07 Mon Sep 17 00:00:00 2001 From: Christopher Swenson Date: Tue, 19 Nov 2024 10:17:05 -0800 Subject: [PATCH] docs: Do some cleanup and rearrangement (#26) --- docs/src/SUMMARY.md | 5 +- docs/src/{spi.md => flash_controller.md} | 86 +++----- docs/src/flash_layout.md | 105 +++++++--- docs/src/images/flash_layout.svg | 192 ------------------ docs/src/images/pldm_update_package.svg | 174 ---------------- docs/src/mctp.md | 61 +++--- docs/src/pldm.md | 3 - ...pldm_update_package.md => pldm_package.md} | 137 ++++++++----- docs/src/spdm.md | 87 ++++---- 9 files changed, 258 insertions(+), 592 deletions(-) rename docs/src/{spi.md => flash_controller.md} (82%) delete mode 100644 docs/src/images/flash_layout.svg delete mode 100755 docs/src/images/pldm_update_package.svg delete mode 100644 docs/src/pldm.md rename docs/src/{pldm_update_package.md => pldm_package.md} (52%) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index e245cc1..0660bf6 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -3,9 +3,8 @@ - [MCU General Specification](./mcu.md) - [ROM Specification](./rom.md) - [Runtime Specification](./runtime.md) - - [SPI](./spi.md) + - [PLDM Package](./pldm_package.md) - [Flash Layout](./flash_layout.md) + - [Flash Controller](./flash_controller.md) - [MCTP](./mctp.md) - - [PLDM](./pldm.md) - - [PLDM Firmware Update Package](./pldm_update_package.md) - [SPDM](./spdm.md) diff --git a/docs/src/spi.md b/docs/src/flash_controller.md similarity index 82% rename from docs/src/spi.md rename to docs/src/flash_controller.md index 23b731f..bca4cb7 100644 --- a/docs/src/spi.md +++ b/docs/src/flash_controller.md @@ -1,8 +1,12 @@ -# SPI Flash Stack +# Flash Controller ## Overview -The SPI flash stack in the Caliptra MCU firmware is designed to provide efficient and reliable communication with flash devices, which is the foundation to enable flash-based boot flow. This document outlines the different SPI flash configurations being supported, the stack architecture, component interface and userspace API to interact with the SPI flash stack. +The Flash Controller stack in the Caliptra MCU firmware is designed to provide efficient and reliable communication with flash devices, which is the foundation to enable flash-based boot flow. + +We will primarily be targetting SPI flash controllers, so we will use that as our primary example throughout. + +This document outlines the different SPI flash configurations being supported, the stack architecture, component interface and userspace API to interact with the SPI flash stack. ## SPI Flash Configurations @@ -57,23 +61,11 @@ The SPI flash stack design leverages TockOS's kernel space support for flash and It is defined in SPI flash syscall library to provide async interface (read, write, erase) to underlying flash devices. ```Rust -///spi_flash/src/lib.rs +/// spi_flash/src/lib.rs /// /// A structure representing an asynchronous SPI flash memory interface. -/// -/// This structure is generic over two types: -/// - `S`: A type that implements the `Syscalls` trait, representing the system calls interface. -/// - `C`: A type that implements the `Config` trait, representing the configuration for the SPI flash. -/// By default, this is set to `DefaultConfig`. -/// -/// # Fields -/// -/// - `syscall`: A marker for the `Syscalls` type, used to indicate that this type is used without storing it. -/// - `config`: A marker for the `Config` type, used to indicate that this type is used without storing it. -/// - `driver_num`: The driver number associated with this SPI flash interface. -pub struct AsyncSpiFlash { - syscall: PhantomData, - config: PhantomData, +struct AsyncSpiFlash { + // The driver number associated with this SPI flash interface. driver_num: u32, } @@ -81,22 +73,13 @@ pub struct AsyncSpiFlash { /// /// This struct provides methods to interact with SPI flash memory in an asynchronous manner, /// allowing for non-blocking read, write, and erase operations. -/// -/// # Type Parameters -/// -/// * `S`: A type that implements the `Syscalls` trait, representing the system calls interface. -/// * `C`: A type that implements the `Config` trait, representing the configuration interface. -impl AsyncSpiFlash { +impl AsyncSpiFlash { /// Creates a new instance of `AsyncSpiFlash`. /// /// # Arguments /// /// * `driver_num` - The driver number associated with the SPI flash. - /// - /// # Returns - /// - /// A new instance of `AsyncSpiFlash`. - pub fn new(driver_num: u32) -> Self {}; + fn new(driver_num: u32) -> Self {}; /// Checks if the SPI flash exists. /// @@ -104,7 +87,7 @@ impl AsyncSpiFlash { /// /// * `Ok(())` if the SPI flash exists. /// * `Err(ErrorCode)` if there is an error. - pub fn exists() -> Result<(), ErrorCode> {}; + fn exists() -> Result<(), ErrorCode> {}; /// Reads an arbitrary number of bytes from the flash memory. /// @@ -121,7 +104,7 @@ impl AsyncSpiFlash { /// /// * `Ok(())` if the read operation is successful. /// * `Err(ErrorCode)` if there is an error. - pub async fn read(&self, address: usize, len: usize, buf: &mut [u8]) -> Result<(), ErrorCode> {}; + async fn read(&self, address: usize, len: usize, buf: &mut [u8]) -> Result<(), ErrorCode>; /// Writes an arbitrary number of bytes to the flash memory. /// @@ -137,7 +120,7 @@ impl AsyncSpiFlash { /// /// * `Ok(())` if the write operation is successful. /// * `Err(ErrorCode)` if there is an error. - pub async fn write(&self, address: usize, buf: &[u8]) -> Result<(), ErrorCode> {}; + async fn write(&self, address: usize, buf: &[u8]) -> Result<(), ErrorCode>; /// Erases an arbitrary number of bytes from the flash memory. /// @@ -152,7 +135,7 @@ impl AsyncSpiFlash { /// /// * `Ok(())` if the erase operation is successful. /// * `Err(ErrorCode)` if there is an error. - pub async fn erase(&self, address: usize, len: usize) -> Result<(), ErrorCode> {}; + async fn erase(&self, address: usize, len: usize) -> Result<(), ErrorCode>; } ``` @@ -165,7 +148,6 @@ impl AsyncSpiFlash { /// defined by a start address and a size. /// /// # Type Parameters -/// - `'a`: The lifetime of the flash memory and client references. /// - `F`: The type of the flash memory, which must implement the `Flash` trait. /// /// # Fields @@ -173,11 +155,11 @@ impl AsyncSpiFlash { /// - `start_address`: The starting address of the flash partition. /// - `size`: The size of the flash partition. /// - `client`: An optional reference to a client that implements the `FlashPartitionClient` trait. -pub struct FlashPartition<'a, F: Flash + 'a> { - flash_user: &'a FlashUser<'a, F>, +struct FlashPartition { + flash_user: &FlashUser, start_address: usize, size: usize, - client: OptionalCell<&'a dyn FlashPartitionClient>, + client: OptionalCell<&dyn FlashPartitionClient>, } /// A partition of a flash memory device. @@ -188,11 +170,7 @@ pub struct FlashPartition<'a, F: Flash + 'a> { /// # Type Parameters /// /// - `F`: A type that implements the `Flash` trait. -/// -/// # Lifetimes -/// -/// - `'a`: The lifetime of the flash memory device and its user. -impl<'a, F: Flash + 'a> FlashPartition<'a, F> { +impl FlashPartition { /// Creates a new `FlashPartition`. /// /// # Arguments @@ -204,18 +182,18 @@ impl<'a, F: Flash + 'a> FlashPartition<'a, F> { /// # Returns /// /// A new `FlashPartition` instance. - pub fn new( - flash_user: &'a FlashUser<'a, F>, + fn new( + flash_user: &FlashUser<, F>, start_address: usize, size: usize, - ) -> FlashPartition<'a, F> {} + ) -> FlashPartition {} /// Sets the client for the flash partition. /// /// # Arguments /// /// - `client`: A reference to an object that implements the `FlashPartitionClient` trait. - pub fn set_client(&self, client: &'a dyn FlashPartitionClient) {} + fn set_client(&self, client: &dyn FlashPartitionClient) {} /// Reads data from the flash partition. /// @@ -228,7 +206,7 @@ impl<'a, F: Flash + 'a> FlashPartition<'a, F> { /// # Returns /// /// A `Result` indicating success or an error code. - pub fn read( + fn read( &self, buffer: &'static mut [u8], offset: usize, @@ -246,7 +224,7 @@ impl<'a, F: Flash + 'a> FlashPartition<'a, F> { /// # Returns /// /// A `Result` indicating success or an error code. - pub fn write( + fn write( &self, buffer: &'static mut [u8], offset: usize, @@ -263,13 +241,13 @@ impl<'a, F: Flash + 'a> FlashPartition<'a, F> { /// # Returns /// /// A `Result` indicating success or an error code. - pub fn erase(&self, offset: usize, length: usize) -> Result<(), ErrorCode> {} + fn erase(&self, offset: usize, length: usize) -> Result<(), ErrorCode> {} } /// Implementation of the `SyscallDriver` trait for the `FlashPartition` struct. /// This implementation provides support for reading, writing, and erasing flash memory, /// as well as allowing read/write and read-only buffers, and subscribing to callbacks. -impl<'a, F: Flash + 'a> SyscallDriver for FlashPartition<'a, F> { +impl SyscallDriver for FlashPartition< F> { /// /// Handles commands from userspace. /// @@ -371,12 +349,4 @@ impl<'a, F: Flash + 'a> SyscallDriver for FlashPartition<'a, F> { ### Flash Controller Driver Capsule -This module is vendor-specific. The common trait to be implemented is within `kernel::hil::flash::Flash`. - -## Flash-based KV store - -TBD - -## Flash-based logging - -TBD +This module is vendor-specific. The common trait to be implemented is within `kernel::hil::flash::Flash`. \ No newline at end of file diff --git a/docs/src/flash_layout.md b/docs/src/flash_layout.md index c6c985d..3802272 100644 --- a/docs/src/flash_layout.md +++ b/docs/src/flash_layout.md @@ -1,51 +1,90 @@ -## SPI Flash Layout +# SPI Flash Layout Overall, the SPI Flash consists of a Header, Checksum and an Image Payload (which includes the image information and the image binary). -The specific images of the flash consists of the Caliptra FW, MCU RT, SOC Manifest, and other SOC images, if any. +The specific images of the flash consists of the Caliptra FW, MCU RT, SoC Manifest, and other SoC images, if any. -![Typical SPI Flash Layout](images/flash_layout.svg) +## Typical flash Layout -*Note: All fields are little endian unless specified* +*Note: All fields are little-endian byte-ordered unless specified otherwise.* -### Header +A typical overall flash layout is: -The Header section contains the metadata for the images stored in the flash. +| Flash Layout | +| ------------ | +| Header | +| Checksum | +| Payload | -| Field | Size (bytes) | Description | -| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Magic Number | 4 | A unique identifier to mark the start of the header.
The value must be 0x464C5348 ('FLSH' in ASCII) | -| Header Version | 2 | The header version format, allowing for backward compatibility if the package format changes over time.
(Current version is 0x0001) | -| Image Count | 2 | The number of image stored in the flash.
Each image will have its own image information section. | +The Payload contains the following fields: -### Checksum +| Payload | +| ------------------------------ | +| Image Info (Caliptra FMC + RT) | +| Image Info (SoC Manifest) | +| Image Info (MCU RT) | +| Image Info (SoC Image 1) | +| ... | +| Image Info (SoC Image N) | +| Caliptra FMC + RT Package | +| SoC Manifest | +| MCU RT | +| SoC Image 1 | +| ... | +| SoC Image N | -The checksum section contains integrity checksums for the header and the payload sections. +* Caliptra FMC and RT (refer to the [Caliptra Firmware Image Bundle Format](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/rom/dev/README.md#firmware-image-bundle)) +* SoC Manifest (refer to the description of the [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)) +* MCU RT: This is the image binary of the MCU Runtime firmware +* Other SoC images (if any) -| Field | Size (bytes) | Description | -| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Header Checksum | 4 | The integrity checksum of the Header section.
It is calculated starting at the first byte of the Header until the last byte of the Image Count field.
For this specification, The CRC-32 algorithm with polynomial 0x04C11DB7 (as used by IEEE 802.3)
is used for checksum computation, processing one byte at a time with the least significant bit first. | -| Payload Checksum | 4 | The integrity checksum of the payload section.
It is calculated starting at the first byte of the first image information until the last byte of the last image.
For this specification, The CRC-32 algorithm with polynomial 0x04C11DB7 (as used by IEEE 802.3)
is used for checksum computation, processing one byte at a time with the least significant bit first. | +## Header -### Image Information +The Header section contains the metadata for the images stored in the flash. -The Image Information section is repeated for each image and provides detailed manifest data specific to that image. +| Field | Size (bytes) | Description | +| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | +| Magic Number | 4 | A unique identifier to mark the start of the header.
The value must be `0x464C5348` (`"FLSH"` in ASCII) | +| Header Version | 2 | The header version format, allowing for backward compatibility if the package format changes over time.
(Current version is `0x0001`) | +| Image Count | 2 | The number of image stored in the flash.
Each image will have its own image information section. | -| Field | Size (bytes) | Descr | -| ------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier | 4 | Vendor selected unique value to distinguish between images.

0x0001: Caliptra FMC+RT 
0x0002: SOC Manifest: 
0x0003: MCU RT
0x1000-0xFFFF - Reserved for other Vendor-defined SOC images  | -| ImageLocationOffset | 4 | Offset in Bytes from byte 0 of the header to where the image content begins. | -| Size | 4 | Size in bytes of the image. This is the actual size of the image without padding.
The image itself as written to the flash should be 4-byte aligned and additional
padding will be required to guarantee alignment. | +## Checksum -### Image +The checksum section contains integrity checksums for the header and the payload sections. -The images (raw binary data) are appended after the Image Information section, and should be in the same order to their corresponding Image Information. +| Field | Size (bytes) | Description | +| ---------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- | +| Header Checksum | 4 | The integrity checksum of the Header section. | +| | | It is calculated starting at the first byte of the Header until the last byte of the Image Count field. | +| | | For this specification, The CRC-32 algorithm with polynomial 0x04C11DB7 (as used by IEEE 802.3) | +| | | is used for checksum computation, processing one byte at a time with the least significant bit first. | +| Payload Checksum | 4 | The integrity checksum of the payload section. | +| | | It is calculated starting at the first byte of the first image information until the last byte of the last image. | +| | | For this specification, The CRC-32 algorithm with polynomial `0x04C11DB7` (as used by IEEE 802.3) | +| | | is used for checksum computation, processing one byte at a time with the least significant bit first. | -| Field | Size (bytes) | Description | -| ----- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Data | N | Image content.
Note: The image should be 4-byte aligned. 
If the size of a firmware image is not a multiple of 4 bytes,
zero padding bytes should be added to meet the alignment requirement.  | +## Image Information -* Caliptra FMC and RT (refer to the [Caliptra Firmware Image Bundle Format](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/rom/dev/README.md#firmware-image-bundle)) -* SOC Manifest (refer to the description of the [SOC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md)) -* MCU RT: This is the image binary of the MCU Realtime firmware -* Other SOC images (if any) +The Image Information section is repeated for each image and provides detailed manifest data specific to that image. + +| Field | Size (bytes) | Descr | +| ------------------- | ------------ | -------------------------------------------------------------------------------------- | +| Identifier | 4 | Vendor selected unique value to distinguish between images. | +| | | `0x0001`: Caliptra FMC+RT | +| | | `0x0002`: SoC Manifest: | +| | | `0x0003`: MCU RT
`0x1000`-`0xFFFF` - Reserved for other Vendor-defined SoC images | +| ImageLocationOffset | 4 | Offset in bytes from byte 0 of the header to where the image content begins. | +| Size | 4 | Size in bytes of the image. This is the actual size of the image without padding. | +| | | The image itself as written to the flash should be 4-byte aligned and additional | +| | | padding will be required to guarantee alignment. | + +## Image + +The images (raw binary data) are appended after the Image Information section, and should be in the same order as their corresponding Image Information. + +| Field | Size (bytes) | Description | +| ----- | ------------ | --------------------------------------------------------------------- | +| Data | N | Image content. | +| | | Note: The image should be 4-byte aligned. | +| | | If the size of a firmware image is not a multiple of 4 bytes, | +| | | `0x00` padding bytes will be added to meet the alignment requirement. | diff --git a/docs/src/images/flash_layout.svg b/docs/src/images/flash_layout.svg deleted file mode 100644 index 6194132..0000000 --- a/docs/src/images/flash_layout.svg +++ /dev/null @@ -1,192 +0,0 @@ - - - - - - - - - - Page-1 - - - Sheet.1 - SPI Flash - - - - SPI Flash - - Rectangle.157 - Image Info (Caliptra FMC + RT) - - - - - - - Image Info (Caliptra FMC + RT) - - Rectangle.159 - Header - - - - - - - Header - - Rectangle.166 - Image Info (SOC Manifest) - - - - - - - Image Info (SOC Manifest) - - Rectangle.167 - Image Info (MCU RT) - - - - - - - Image Info (MCU RT) - - Rectangle.168 - Image Info (SOC Image 1) - - - - - - - Image Info (SOC Image 1) - - Rectangle.169 - Checksum - - - - - - - Checksum - - Rectangle.170 - ... - - - - - - - ... - - Rectangle.171 - Image Info (SOC Image n) - - - - - - - Image Info (SOC Image n) - - Right Brace.174 - - - - - - - Sheet.11 - Payload - - - - Payload - - Rectangle.176 - Caliptra FMC + RT Package - - - - - - - Caliptra FMC + RT Package - - Rectangle.177 - MCU RT - - - - - - - MCU RT - - Rectangle.178 - SOC Manifest - - - - - - - SOC Manifest - - Rectangle.179 - SOC Image 1 - - - - - - - SOC Image 1 - - Rectangle.181 - SOC Image n - - - - - - - SOC Image n - - Rectangle.183 - ... - - - - - - - ... - - diff --git a/docs/src/images/pldm_update_package.svg b/docs/src/images/pldm_update_package.svg deleted file mode 100755 index e6fa489..0000000 --- a/docs/src/images/pldm_update_package.svg +++ /dev/null @@ -1,174 +0,0 @@ - - - - - - - - - - Page-1 - - - Rectangle.44 - Package Header Information - - - - - - - Package Header Information - - Rectangle.45 - Firmware Dev ID Descriptors - - - - - - - Firmware Dev ID Descriptors - - Rectangle.46 - Component Image Information - - - - - - - Component Image Information - - Rectangle.47 - Package Header Checksum - - - - - - - Package Header Checksum - - Rectangle.48 - Package Payload Checksum - - - - - - - Package Payload Checksum - - Rectangle.49 - Component 1 (Caliptra FMC + RT) - - - - - - - Component 1 (Caliptra FMC + RT) - - Rectangle.51 - Component 2 (SOC Manifest) - - - - - - - Component 2 (SOC Manifest) - - Rectangle.52 - Component 3 (MCU RT Package) - - - - - - - Component 3 (MCU RT Package) - - Sheet.56 - PLDM FW Update Package - - - - PLDM FW Update Package - - Rectangle.83 - Component 4 (SOC Image Package 1) - - - - - - - Component 4 (SOC Image Package 1) - - Rectangle.84 - ... - - - - - - - ... - - Rectangle.85 - Component n (SOC Image Package n) - - - - - - - Component n (SOC Image Package n) - - Rectangle.109 - Component: Streaming Boot Image (Full Flash) - - - - - - - Component: Streaming Boot Image (Full Flash) - - Rectangle.184 - Downstream Dev ID Descriptors - - - - - - - Downstream Dev ID Descriptors - - diff --git a/docs/src/mctp.md b/docs/src/mctp.md index 751517c..d991b73 100644 --- a/docs/src/mctp.md +++ b/docs/src/mctp.md @@ -1,12 +1,12 @@ # MCTP Stack -The Caliptra subsystem supports SPDM, PLDM, and Caliptra Vendor-defined message protocols over MCTP. +The Caliptra subsystem supports SPDM, PLDM, and Caliptra vendor-defined message protocols over MCTP. -The MCTP base protocol is implemented as a Tock Capsule driver, which also handles the essential MCTP Control messages. +The MCTP base protocol is implemented as a Tock Capsule, which also handles the essential MCTP Control messages. Additionally, it offers a syscall interface to userspace, enabling the sending and receiving of MCTP messages for other supported protocols. Caliptra MCTP endpoint has only one EID and supports dynamic assignment by the MCTP bus owner. MCTP Packets are delivered over physical I3C medium using I3C transfers. Caliptra MCTP endpoint always plays the role of I3C Target and is -managed by an external I3C controller. Minimum transmission size is based on the MCTP baseline MTU (for I3C it is 69 bytes : 64 bytes MCTP payload + 4 bytes MCTP header + 1 byte PEC). Larger than the baseline transfer may be possible after discovery and negotiation with the I3C controller. The negotiated MTU size will be queried from the I3C Target peripheral driver by MCTP capsule. +managed by an external I3C controller. Minimum transmission size is based on the MCTP baseline MTU (for I3C it is 69 bytes: 64 bytes MCTP payload + 4 bytes MCTP header + 1 byte PEC). Larger than the baseline transfer may be possible after discovery and negotiation with the I3C controller. The negotiated MTU size will be queried from the I3C Target peripheral driver by MCTP capsule. ## MCTP Receive sequence @@ -81,13 +81,11 @@ sequenceDiagram ``` - The send stack is as shown in the picture below: ![The MCTP Send stack](images/MCTP_tx_stack.svg) - ## Syscall Library in userspace Userspace applications can use syscall library in to send and receive MCTP messages. The following APIs are provided by the MCTP syscall library. Each user space application will instantiate the `AsyncMctp` module with appropriate driver number. The `AsyncMctp` module provides the following APIs to send and receive MCTP messages. @@ -95,7 +93,7 @@ Each user space application will instantiate the `AsyncMctp` module with appropr ```Rust //! The MCTP library provides the interface to send and receive MCTP messages. //! The MCTP library is implemented as an async library to allow the userspace application to send and receive MCTP messages asynchronously. -//! +//! //! Usage //! ----- //!```Rust @@ -103,7 +101,7 @@ Each user space application will instantiate the `AsyncMctp` module with appropr //! //! const SPDM_MESSAGE_TYPE: u8 = 0x5; //! const SECURE_SPDM_MESSAGE_TYPE: u8 = 0x6; -//! +//! //! #[embassy_executor::task] //! async fn async_main() { //! /// Initialize the MCTP driver with the driver number @@ -155,12 +153,12 @@ impl Mctp { pub fn new(drv_num: u32) -> Self; pub fn exists() -> Result<(), ErrorCode>; /// Receive the MCTP request from the source EID - /// + /// /// # Arguments - /// * `source_eid` - The source EID from which the request is to be received. + /// * `source_eid` - The source EID from which the request is to be received. /// * `message_types` - The message types to receive. This is needed for SPDM to receive both SPDM(0x5) and secured SPDM(0x6) messages /// * `msg_payload` - The buffer to store the received message payload - /// + /// /// # Returns /// * `MessageInfo` - The message information containing the EID, message tag, message type, and payload length on success /// * `ErrorCode` - The error code on failure @@ -188,7 +186,7 @@ impl Mctp { /// * `u8` - The message tag assigned to the request /// * `ErrorCode` - The error code on failure pub async fn send_request(&self, dest_eid: u8, msg_payload: &[u8]) -> Result; - + /// Receive the MCTP response from the source EID /// /// # Arguments @@ -214,11 +212,9 @@ pub enum NUM { MctpSpdm = 0xA0000, MctpPldm = 0xA0001, MctpVenDef = 0xA0002, - ... } - /// mctp/driver.rs pub const MCTP_SPDM_DRIVER_NUM: usize = driver::NUM::MctpSpdm; pub const MCTP_PLDM_DRIVER_NUM: usize = driver::NUM::MctpPldm; @@ -241,7 +237,7 @@ The following are the list of system calls provided by the MCTP Capsule. - Argument: Slice containing the MCTP message payload to be transmitted. 3. Subscribe - - Subscribe number 0: + - Subscribe number 0: - Description: Callback when message is received. - Argument 1: The callback - Argument 2: App specific data @@ -253,7 +249,6 @@ The following are the list of system calls provided by the MCTP Capsule. 4. Command - Command number 0: - Description: Existence check - - Arguments: - Command number 1: - Description: Receive Request - Argument1 : Source EID @@ -266,7 +261,7 @@ The following are the list of system calls provided by the MCTP Capsule. - Description: Send Request - Argument1 : Destination EID - Argument2 : Message Tag - - Command number 4: + - Command number 4: - Description: Send Response - Argument1 : Destination EID - Argument2 : Message Tag @@ -284,12 +279,12 @@ struct OperationCtx { msg_tag : u8, peer_eid : u8, is_busy: bool, - op_type:OperationType, + op_type:OperationType, } #[derive(default)] pub struct App { - pending_op_ctx: OperationCtx, + pending_op_ctx: OperationCtx, bound_msg_type : u8, } @@ -307,16 +302,16 @@ pub struct VirtualMCTPDriver { ```Rust /// The trait that provides an interface to send the MCTP messages to MCTP kernel stack. pub trait MCTPSender { - /// Sets the client for the `MCTPSender` instance. - /// In this case it is MCTPTxState which is instantiated at the time of + /// Sets the client for the `MCTPSender` instance. + /// In this case it is MCTPTxState which is instantiated at the time of fn set_client(&self, client: &dyn MCTPSendClient); /// Sends the message to the MCTP kernel stack. fn send_msg(&self, dest_eid: u8, msg_tag: u8, msg_payload: SubSliceMut<'static, u8>); } -/// This is the trait implemented by VirtualMCTPDriver instance to get notified after -/// message is sent. +/// This is the trait implemented by VirtualMCTPDriver instance to get notified after +/// message is sent. /// The 'send_done' function in this trait is invoked after the MCTPSender /// has completed sending the requested message. pub trait MCTPSendClient { @@ -338,7 +333,7 @@ pub struct MCTPTxState { ### MCTP Receive state ```Rust -/// This is the trait implemented by VirtualMCTPDriver instance to get notified of +/// This is the trait implemented by VirtualMCTPDriver instance to get notified of /// the messages received on corresponding message_type. pub trait MCTPRxClient { fn receive(&self, dst_eid: u8, msg_type: u8, msg_Tag: u8, msg_payload: &[u8]); @@ -353,7 +348,6 @@ pub struct MCTPRxState { /// next MCTPRxState node next: ListLink, } - ``` ## MCTP Mux Layer @@ -364,7 +358,7 @@ If the message originates from the device (with `msg_tag` = 0x8), a new msg_tag For response messages, where `msg_tag` values range between 0 and 7, the same value is used to encapsulate the MCTP transport header on each packet. MCTP Mux layer is the single receive client for the MCTP Device Layer. This layer is instantiated with a single contiguous buffer for Rx packet of size `kernel::hil:i3c::MAX_TRANSMISSION_UNIT`. -The Rx buffer is provided to the I3C target driver layer to receive the packets when the I3C controller initiates a private write transfer to the I3C Target. +The Rx buffer is provided to the I3C target driver layer to receive the packets when the I3C controller initiates a private write transfer to the I3C Target. The virtualized upper layer ensures that only one message is transmitted per driver instance at a time. Receive is event based. The received packet in the Rx buffer is matched against the pending receive requests by the use @@ -392,12 +386,12 @@ pub struct MuxMCTPDriver { ``` ## MCTP Transport binding layer -The following is the generic interface for the MCTP physical transport binding layer. +The following is the generic interface for the MCTP physical transport binding layer. Implementer of this trait will add physical medium specific header/trailer to the MCTP packet. ```Rust -/// This trait contains the interface definition -/// for sending the MCTP packet through MCTP transport binding layer. +/// This trait contains the interface definition +/// for sending the MCTP packet through MCTP transport binding layer. pub trait MCTPTransportBinding { /// Set the client that will be called when the packet is transmitted. fn set_tx_client(&self, client: &TxClient); @@ -414,14 +408,14 @@ pub trait MCTPTransportBinding { fn enable(); fn disable(); - /// Get the maximum transmission unit (MTU) size. + /// Get the maximum transmission unit (MTU) size. fn get_mtu_size() -> usize; } ``` MCTP I3C Transport binding layer is responsible for checking the PEC for received packets and adding the PEC for transmitted packets over the I3C medium. -It is mostly a passthrough for the MCTP Base layer except, it will need the I3C target device address for PEC calculation. +It is mostly a passthrough for the MCTP Base layer except, it will need the I3C target device address for PEC calculation. -This layer is also a sole Rx and Tx client for the I3C Target device driver. +This layer is also a sole Rx and Tx client for the I3C Target device driver. ```Rust pub struct MCTPI3CBinding { @@ -443,8 +437,8 @@ The following trait defined standard and shared interface for I3C Target hardwar pub trait TxClient { /// Called when the packet has been transmitted. (Calls this after the ACK is received from Controller) - fn send_done(&self, - tx_buffer: &'static mut [u8], + fn send_done(&self, + tx_buffer: &'static mut [u8], acked: bool, result : Result<(), ErrorCode>); } @@ -484,4 +478,3 @@ I fn get_address() -> u8; } ``` - diff --git a/docs/src/pldm.md b/docs/src/pldm.md deleted file mode 100644 index 07d4431..0000000 --- a/docs/src/pldm.md +++ /dev/null @@ -1,3 +0,0 @@ -# PLDM Support - -TBD \ No newline at end of file diff --git a/docs/src/pldm_update_package.md b/docs/src/pldm_package.md similarity index 52% rename from docs/src/pldm_update_package.md rename to docs/src/pldm_package.md index f8531ea..de856a2 100644 --- a/docs/src/pldm_update_package.md +++ b/docs/src/pldm_package.md @@ -4,7 +4,21 @@ This section describes the PLDM Update Package used for Caliptra streaming boot The update package follows the [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf). -![General SPI Flash Layout](images/pldm_update_package.svg) +| PLDM FW Update Package | +| ----------------------------------------------------- | +| Package Header Information | +| Firmware Dev ID Descriptors | +| Downstream Dev ID Descriptors | +| Component Image Information | +| Package Header Checksum | +| Package Payload Checksum | +| Component 1 (Caliptra FMC + RT) | +| Component 2 (SoC Manifest) | +| Component 3 (MCU RT) | +| Component 4 (SoC Image 1) | +| ... | +| Component N (SoC Image N-3) | +| Component N + 1 (Streaming Boot Image for full flash) | The PLDM FW Update Package contains: @@ -14,37 +28,56 @@ The PLDM FW Update Package contains: 4. Other SOC Images, if any 5. A full image of the flash containing all images (see [SPI Flash Layout Documentation](https://github.com/chipsalliance/caliptra-mcu-sw/blob/main/docs/src/flash_layout.md)) -*Note: All fields are little endian unless specified* +*Note: All fields are little-endian byte-ordered unless specified otherwise.* ### Package Header Information -| Field | Size | Definition | -| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| PackageHeaderIdentifier | 16 | Set to 7B291C996DB64208801B0202E6463C78 (v1.3.0 UUID)
This field is Big Endian. | -| PackageHeaderFormatRevision | 1 | Set to 0x04 (v1.3.0 header format revision) | -| PackageHeaderSize | 2 | The total byte count of this header structure, including fields within the Package Header Information,
Firmware Device Identification Area, Downstream Device Identification Area,
Component Image Information Area, and Checksum sections. | -| PackageReleaseDateTime | 13 | The date and time when this package was released.
Refer to the PLDM Base Specification for field format definition. | -| ComponentBitmapBitLength | 2 | Number of bits used to represent the bitmap in the ApplicableComponents field for a matching device.
This value is a multiple of 8 and is large enough to contain a bit for each component in the package. | -| PackageVersionStringType | 1 | The type of string used in the PackageVersionString field.
Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | -| PackageVersionStringLength | 1 | Length, in bytes, of the PackageVersionString field. | -| PackageVersionString | Variable | Package version information, up to 255 bytes.
Contains a variable type string describing the version of this firmware update package. | +| Field | Size | Definition | +| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| PackageHeaderIdentifier | 16 | Set to `0x7B291C996DB64208801B0202E6463C78` (v1.3.0 UUID) (big endian) | +| PackageHeaderFormatRevision | 1 | Set to `0x04 `(v1.3.0 header format revision) | +| PackageHeaderSize | 2 | The total byte count of this header structure, including fields within the Package Header Information, | +| | | Firmware Device Identification Area, Downstream Device Identification Area, | +| | | Component Image Information Area, and Checksum sections. | +| PackageReleaseDateTime | 13 | The date and time when this package was released. | +| | | Refer to the PLDM Base Specification for field format definition. | +| ComponentBitmapBitLength | 2 | Number of bits used to represent the bitmap in the ApplicableComponents field for a matching device. | +| | | This value is a multiple of 8 and is large enough to contain a bit for each component in the package. | +| PackageVersionStringType | 1 | The type of string used in the PackageVersionString field. | +| | | Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | +| PackageVersionStringLength | 1 | Length, in bytes, of the PackageVersionString field. | +| PackageVersionString | Variable | Package version information, up to 255 bytes. | +| | | Contains a variable type string describing the version of this firmware update package. | ### Firmware Device ID Descriptor -| Field | Size | Definition | -| ------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| RecordLength | 2 | The total length in bytes for this record.
The length includes the RecordLength, DescriptorCount, DeviceUpdateOptionFlags,
ComponentImageSetVersionStringType, ComponentSetVersionStringLength,
FirmwareDevicePackageDataLength, ApplicableComponents,
ComponentImageSetVersionString, RecordDescriptors,
and FirmwareDevicePackageData fields. | -| DescriptorCount | 1 | The number of descriptors included within the RecordDescriptors field for this record. | -| DeviceUpdateOptionFlags | 4 | 32-bit field where each bit represents an update option.

bit1 is set to 1 (Support Flashless/Streaming Boot)

For other options, refer to DeviceUpdateOptionFlags description in [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf). | -| ComponentImageSetVersionStringType | 1 | The type of string used in the ComponentImageSetVersionString field.
Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | -| ComponentImageSetVersionStringLength | 1 | Length, in bytes, of the ComponentImageSetVersionString. | -| FirmwareDevicePackageDataLength | 2 | Length in bytes of the FirmwareDevicePackageData field.
If no data is provided, set to 0x0000. | -| ReferenceManifestLength | 4 | Length in bytes of the ReferenceManifestData field.
If no data is provided, set to 0x00000000. | -| ApplicableComponents | Variable | Bitmap indicating which firmware components apply to devices matching this Device Identifier record.
A set bit indicates the Nth component in the payload is applicable to this device.

bit 0: Caliptra FMC + RT
bit 1: SOC Manifest
bit 2 : MCU RT
bit 3 to n: Reserved for other SOC images
bit n+1: Full SPI Flash image used in streaming boot | -| ComponentImageSetVersionString | Variable | Component Image Set version information, up to 255 bytes.
Describes the version of component images applicable to the firmware device indicated in this record. | -| RecordDescriptors | Variable | These descriptors are defined by the vendor (i.e. integrators of Caliptra ROT)
Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 7 for details of these fields and the values that can be selected. | -| FirmwareDevicePackageData | Variable | Optional data provided within the firmware update package for the FD during the update process.
If FirmwareDevicePackageDataLength is 0x0000, this field contains no data. | -| ReferenceManifestData | Variable | Optional data field containing a Reference Manifest for the firmware update.
If present, it describes the firmware update provided by this package.
If ReferenceManifestLength is 0x00000000, this field contains no data. | +| Field | Size | Definition | +| ------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| RecordLength | 2 | The total length in bytes for this record. The length includes the RecordLength, DescriptorCount, DeviceUpdateOptionFlags, ComponentImageSetVersionStringType, ComponentSetVersionStringLength, FirmwareDevicePackageDataLength, ApplicableComponents, ComponentImageSetVersionString, and RecordDescriptors, and FirmwareDevicePackageData fields. | +| DescriptorCount | 1 | The number of descriptors included within the RecordDescriptors field for this record. | +| DeviceUpdateOptionFlags | 4 | 32-bit field where each bit represents an update option. | +| | | bit 1 is set to 1 (Support Flashless/Streaming Boot) | +| | | For other options, refer to DeviceUpdateOptionFlags description in [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf). | +| ComponentImageSetVersionStringType | 1 | The type of string used in the ComponentImageSetVersionString field. Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | +| ComponentImageSetVersionStringLength | 1 | Length, in bytes, of the ComponentImageSetVersionString. | +| FirmwareDevicePackageDataLength | 2 | Length in bytes of the FirmwareDevicePackageData field. | +| | | If no data is provided, set to `0x0000`. | +| ReferenceManifestLength | 4 | Length in bytes of the ReferenceManifestData field. If no data is provided, set to `0x00000000`. | +| ApplicableComponents | Variable | Bitmap indicating which firmware components apply to devices matching this Device Identifier record. A set bit indicates the Nth component in the payload is applicable to this device. | +| | | bit 0: Caliptra FMC + RT | +| | | bit 1: SOC Manifest | +| | | bit 2 : MCU RT | +| | | bit 3 to N: Reserved for other SoC images | +| | | bit N+1: Full SPI Flash image used in streaming boot | +| ComponentImageSetVersionString | Variable | Component Image Set version information, up to 255 bytes. | +| | | Describes the version of component images applicable to the firmware device indicated in this record. | +| RecordDescriptors | Variable | These descriptors are defined by the vendor (i.e. integrators of Caliptra ROT) | +| | | Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 7 for details of these fields and the values that can be selected. | +| FirmwareDevicePackageData | Variable | Optional data provided within the firmware update package for the FD during the update process. | +| | | If FirmwareDevicePackageDataLength is `0x0000`, this field contains no data. | +| ReferenceManifestData | Variable | Optional data field containing a Reference Manifest for the firmware update. | +| | | If present, it describes the firmware update provided by this package. | +| | | If ReferenceManifestLength is `0x00000000`, this field contains no data. | ### Downstream Device ID Descriptor @@ -63,36 +96,42 @@ There are no Downstream Device ID records for this package ### Component Image Information Record -| Field | Size | Definition | -| ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| ComponentClassification | 2 | 0x000A :For Caliptra FMC+RT  (Firmware)
0x0001: For SOC Manifest  (Other)
0x000A: For MCU RT: (Firmware)
For other SOC images, Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 32 for values. | -| ComponentIdentifier | 2 | Unique value selected by the FD vendor to distinguish between component images.
0x0001: Caliptra FMC+RT 
0x0002: SOC Manifest: 
0x0003: MCU RT
0x1000-0xFFFF - Reserved for other Vendor-defined SOC images | -| ComponentComparisonStamp | 4 | Value used as a comparison in determining if a firmware component is down-level or up-level.
When ComponentOptions bit 1 is set, this field should use a comparison stamp format (e.g., MajorMinorRevisionPatch).
If not set, use 0xFFFFFFFF. | -| ComponentOptions | 2 | Refer to ComponentOptions definition in[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | -| RequestedComponentActivationMethod | 2 | Refer to RequestedComponentActivationMethoddefinition in[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | -| ComponentLocationOffset | 4 | Offset in bytes from byte 0 of the package header to where the component image begins. | -| ComponentSize | 4 | Size in bytes of the Component image. | -| ComponentVersionStringType | 1 | Type of string used in the ComponentVersionString field. Refer to[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | -| ComponentVersionStringLength | 1 | Length, in bytes, of the ComponentVersionString. | -| ComponentVersionString | Variable | Component version information, up to 255 bytes. Contains a variable type string describing the component version. | -| ComponentOpaqueDataLength | 4 | Length in bytes of the ComponentOpaqueData field. If no data is provided, set to 0x00000000. | -| ComponentOpaqueData | Variable | Optional data transferred to the FD/FDP during the firmware update | -| | | | +| Field | Size | Definition | +| ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ComponentClassification | 2 | `0x000A`: For Caliptra FMC+RT  (Firmware) | +| | | `0x0001`: For SoC Manifest  (Other) | +| | | `0x000A`: For MCU RT: (Firmware) | +| | | For other SoC images, Refer to [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 32 for values. | +| ComponentIdentifier | 2 | Unique value selected by the FD vendor to distinguish between component images. | +| | | `0x0001`: Caliptra FMC+RT | +| | | `0x0002`: SoC Manifest: | +| | | `0x0003`: MCU RT | +| | | `0x1000`-`0xFFFF` - Reserved for other vendor-defined SoC images | +| ComponentComparisonStamp | 4 | Value used as a comparison in determining if a firmware component is down-level or up-level. When ComponentOptions bit 1 is set, this field should use a comparison stamp format (e.g., MajorMinorRevisionPatch). If not set, use `0xFFFFFFFF`. | +| ComponentOptions | 2 | Refer to ComponentOptions definition in [DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | +| RequestedComponentActivationMethod | 2 | Refer to RequestedComponentActivationMethoddefinition in[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) | +| ComponentLocationOffset | 4 | Offset in bytes from byte 0 of the package header to where the component image begins. | +| ComponentSize | 4 | Size in bytes of the Component image. | +| ComponentVersionStringType | 1 | Type of string used in the ComponentVersionString field. Refer to[DMTF Firmware Update Specification v.1.3.0](https://www.dmtf.org/sites/default/files/standards/documents/DSP0267_1.3.0.pdf) Table 33 for values. | +| ComponentVersionStringLength | 1 | Length, in bytes, of the ComponentVersionString. | +| ComponentVersionString | Variable | Component version information, up to 255 bytes. Contains a variable type string describing the component version. | +| ComponentOpaqueDataLength | 4 | Length in bytes of the ComponentOpaqueData field. If no data is provided, set to 0x00000000. | +| ComponentOpaqueData | Variable | Optional data transferred to the FD/FDP during the firmware update | ## Checksum -| Field | Size | Definition | -| ---------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Field | Size | Definition | +| ---------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PackageHeaderChecksum | 4 | The integrity checksum of the PLDM Package Header. It is calculated starting at the first byte of the PLDM Firmware Update Header and includes all bytes of the package header structure except for the bytes in this field and the PackagePayloadChecksum field. The CRC-32 algorithm with polynomial `0x04C11DB7` (as used by IEEE 802.3) is used for checksum computation, processing one byte at a time with the least significant bit first. | -| PackagePayloadChecksum | 4 | The integrity checksum of the PLDM Package Payload. It is calculated starting at the first byte immediately following this field and includes all bytes of the firmware package payload structure, including any padding between component images. The CRC-32 algorithm with polynomial `0x04C11DB7` (as used by IEEE 802.3) is used for checksum computation, processing one byte at a time with the least significant bit first. | +| PackagePayloadChecksum | 4 | The integrity checksum of the PLDM Package Payload. It is calculated starting at the first byte immediately following this field and includes all bytes of the firmware package payload structure, including any padding between component images. The CRC-32 algorithm with polynomial `0x04C11DB7` (as used by IEEE 802.3) is used for checksum computation, processing one byte at a time with the least significant bit first. | ## Component 1 - Caliptra FMC + RT -This is the package bundle for the Caliptra FMC + RT defined in [Caliptra Firmware Image Bundle Format](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/rom/dev/README.md#firmware-image-bundle)) +This is the package bundle for the Caliptra FMC + RT defined in [Caliptra Firmware Image Bundle Format](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/rom/dev/README.md#firmware-image-bundle). ## Component 2 - SOC Manifest -This is the SOC Manifest defined in [SOC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md). +This is the SoC Manifest defined in [SoC Manifest](https://github.com/chipsalliance/caliptra-sw/blob/main-2.x/auth-manifest/README.md). It provides the signature verification and specific data needed to decode the image. @@ -100,10 +139,10 @@ It provides the signature verification and specific data needed to decode the im This is the Image binary of the MCU Realtime firmware. -## Component 4 to n - SOC Images +## Component 4 to N - SoC Images -These are reserved for vendor SOC images, if any. +These are reserved for vendor SoC images, if any. -## Component n + 1 - Full SPI Flash image +## Component N + 1 - Full SPI Flash image This component contains the full flash image as defined in the [SPI Flash Layout Documentation](https://github.com/chipsalliance/caliptra-mcu-sw/blob/main/docs/src/flash_layout.md) from the Header section until the end of the images section. This is can be used for loading all the images at once for streaming boot. diff --git a/docs/src/spdm.md b/docs/src/spdm.md index 8873dbc..bccac5e 100644 --- a/docs/src/spdm.md +++ b/docs/src/spdm.md @@ -1,13 +1,13 @@ # SPDM The Security Protocol and Data Model (SPDM) is a protocol designed to ensure secure communication between hardware components by focusing on mutual authentication and the establishment of secure channels over potentially insecure media. SPDM enables devices to verify each other's identities and configurations, leveraging X.509v3 certificates to ensure cryptographic security. Designed for interoperability, it can work across various transport and physical media, often utilizing the Management Component Transport Protocol (MCTP). This protocol is especially valuable in environments where secure hardware communication is crucial, such as data centers and enterprise systems. -## Specifications: -| Specification | Document Link | -|-------------------------------------------------|---------------| -| Security Protocol and Data Model | [DSP0274](https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_1.3.2.pdf) | -| Secured Messages using SPDM | [DSP0277](https://www.dmtf.org/sites/default/files/standards/documents/DSP0277_1.2.0.pdf) | -| SPDM over MCTP Binding Specification | [DSP0275](https://www.dmtf.org/sites/default/files/standards/documents/DSP0275_1.0.2.pdf) | -| Secured Messages using SPDM over MCTP Binding | [DSP0276](https://www.dmtf.org/sites/default/files/standards/documents/DSP0276_1.2.0.pdf) | +## Specifications +| Specification | Document Link | +| --------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Security Protocol and Data Model | [DSP0274](https://www.dmtf.org/sites/default/files/standards/documents/DSP0274_1.3.2.pdf) | +| Secured Messages using SPDM | [DSP0277](https://www.dmtf.org/sites/default/files/standards/documents/DSP0277_1.2.0.pdf) | +| SPDM over MCTP Binding Specification | [DSP0275](https://www.dmtf.org/sites/default/files/standards/documents/DSP0275_1.0.2.pdf) | +| Secured Messages using SPDM over MCTP Binding | [DSP0276](https://www.dmtf.org/sites/default/files/standards/documents/DSP0276_1.2.0.pdf) | ## SPDM Protocol Sequence ```mermaid @@ -52,31 +52,26 @@ sequenceDiagram ## Class Diagram -```plaintext - +----------------+ - | MCTP Transport | - +--------+-------+ - ^ - processRequest() / sendResponse() - | -+--------------------+ | -| SPDM Responder |<-----+ -+--------------------+ -| - transcriptMgr | processSecureMessage() -| - sessionMgr |------------------------+ -+--------------------+ | -| + processRequest() | | -| + sendResponse() | | -+--------------------+ | - | | - | | - v v -+--------------------+ +--------------------+ -| Transcript Manager |<---------------| Secure Session Mgr | -+--------------------+ +--------------------+ -| + Trait Methods | | + TraitMethods | -+--------------------+ | - transcriptMgr | - +--------------------+ +```mermaid +classDiagram + direction RL + MCTP Transport <|--|> SPDMResponder: processRequest() / sendResponse() + SecureSessionMgr <|-- SPDMResponder: processSecureMessage() + TranscriptMgr <|-- SPDMResponder + TranscriptMgr <|-- SecureSessionMgr + class SPDMResponder{ + - transcriptMgr + - sessionMgr + + processRequest() + + sendResponse() + } + class SecureSessionMgr { + -transcriptMgr + +TraitMethods + } + class TranscriptMgr{ + +TraitMethods + } ``` ## SPDM Responder @@ -85,18 +80,18 @@ The Responder is responsible for receiving and processing requests from the Requ ### Responder supported messages The SPDM Responder supports the following messages: -| Message | Description | -|------------------------|---------------------------------------------------------------------------------| -| VERSION | Retrieves version information | -| CAPABILITIES | Retrieves SPDM capabilities | -| ALGORITHMS | Retrieves the negotiated algorithms | -| DIGESTS | Retrieves digest of the certificate chains | -| CERTIFICATE | Retrieves certificate chains | -| MEASUREMENTS | Retrieves measurements of elements such as intenral state | -| KEY_EXCHANGE_RSP | Retrieves the responder's public key information | -| FINISH_RSP | Provide key confirmation, bind the identity of each party to the exchanged keys | -| END_SESSION_ACK | End session acknowledgment | -| ERROR | Error message | +| Message | Description | +| ------------------ | ------------------------------------------------------------------------------- | +| `VERSION` | Retrieves version information | +| `CAPABILITIES` | Retrieves SPDM capabilities | +| `ALGORITHMS` | Retrieves the negotiated algorithms | +| `DIGESTS` | Retrieves digest of the certificate chains | +| `CERTIFICATE` | Retrieves certificate chains | +| `MEASUREMENTS` | Retrieves measurements of elements such as intenral state | +| `KEY_EXCHANGE_RSP` | Retrieves the responder's public key information | +| `FINISH_RSP` | Provide key confirmation, bind the identity of each party to the exchanged keys | +| `END_SESSION_ACK` | End session acknowledgment | +| `ERROR` | Error message | ### Responder Interface @@ -155,7 +150,7 @@ pub trait SpdmTranscriptManager { /// - `session_idx`: SPDM session index. /// /// # Returns - /// - `Result<(), SpdmError>`: + /// - `Result<(), SpdmError>`: /// Returns `Ok(())` if the message was added to the transcript successfully, or an error code. async fn update( &self, @@ -217,7 +212,7 @@ pub trait SpdmSecureSessionManager { /// - `connection_info`: SPDM connection info. /// /// # Returns - /// - `Option<&SpdmSecureSession>`: + /// - `Option<&SpdmSecureSession>`: /// A pointer to the created SPDM secure session or `None` if the session could not be created. fn create_session( &self,