Embassy Boot STM32

https://docs.embassy.dev/embassy-boot-stm32/
Admin
Embassy Boot STM32 is a bootloader for STM32 microcontrollers that enables firmware updates and...
Tokens:15,324
Snippets:109
Trust Score:8.2
Update:7 months ago
Show doc for...
Tokens:
Raw
### Example: Bootloader Config Initialization (Rust)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Demonstrates how to initialize a `BootLoaderConfig` using flash memory partitions derived from linker script symbols. This example assumes a shared flash interface for all partitions and shows the typical setup for bootloader configuration.

```rust
// Assume `active_flash`, `dfu_flash`, and `state_flash` all share the same flash memory interface.
let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
let flash = Mutex::new(RefCell::new(layout.bank1_region));

let config = BootLoaderConfig::from_linkerfile_blocking(&flash, &flash, &flash);
// `config` can now be used to create a `BootLoader` instance for managing boot operations.
```

--------------------------------

### Get Current Firmware State

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdater

Asynchronously retrieves the current state of the firmware. This is particularly useful after a potential firmware swap to perform verifications and self-tests on the new image before confirming it by calling `mark_booted`.

```rust
pub async fn get_state(&mut self) -> Result<State, FirmwareUpdaterError>
```

--------------------------------

### Get BlockingFirmwareUpdater State

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Retrieves the current state of the firmware updater. This is useful for performing verifications and self-tests on a newly updated image before marking it as booted.

```rust
pub fn get_state(&mut self) -> Result<State, FirmwareUpdaterError>
```

--------------------------------

### Read Data from DFU Storage

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdater

Asynchronously reads a specified number of bytes from the DFU storage peripheral, starting at a given offset. The read data is placed into the provided buffer. Errors are returned if the arguments are not aligned or are out of bounds.

```rust
pub async fn read_dfu(
 &mut self,
 offset: u32,
 buf: &mut [u8],
) -> Result<(), FirmwareUpdaterError>
```

--------------------------------

### Read DFU Storage

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Reads a slice of data from the DFU storage peripheral. The read operation starts at a specified offset and reads a given number of bytes into the provided buffer. Errors occur if arguments are misaligned or out of bounds.

```rust
pub fn read_dfu(
 &mut self,
 offset: u32,
 buf: &mut [u8],
 ) -> Result<(), FirmwareUpdaterError>
```

--------------------------------

### Write Firmware Data

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Writes firmware data to the device's firmware area starting at a specified offset. This function handles sector erasures and data writes, ensuring the device is in a proper state for updates. It requires the data to be a multiple of NorFlash WRITE_SIZE.

```rust
pub fn write_firmware(
 &mut self,
 offset: usize,
 data: &[u8],
 ) -> Result<(), FirmwareUpdaterError>
```

--------------------------------

### Embassy Boot STM32 - Structs

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/embassy_boot_stm32/index

Documentation for the core structs used in the embassy-boot-stm32 project.

```APIDOC
## Structs

### AlignedBuffer

**Description:** Buffer aligned to 32 byte boundary, largest known alignment requirement for embassy-boot.

### BlockingFirmwareState

**Description:** Manages the state partition of the firmware update.

### BlockingFirmwareUpdater

**Description:** Blocking FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.

### BootLoader

**Description:** A bootloader for STM32 devices.

### BootLoaderConfig

**Description:** Bootloader flash configuration holding the three flashes used by the bootloader.

### FirmwareState

**Description:** Manages the state partition of the firmware update.

### FirmwareUpdater

**Description:** FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.

### FirmwareUpdaterConfig

**Description:** Firmware updater flash configuration holding the two flashes used by the updater.
```

--------------------------------

### Initialize FirmwareUpdater Instance

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdater

Creates a new instance of the FirmwareUpdater. This function takes a configuration object and a mutable byte slice for aligned data, setting up the updater with partition ranges for both the update and state partitions.

```rust
pub fn new( config: FirmwareUpdaterConfig<DFU, STATE>,
 aligned: &'d mut [u8],
) -> FirmwareUpdater<'d, DFU, STATE>
```

--------------------------------

### Initialize BlockingFirmwareState in Rust

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareState

Demonstrates how to initialize the `BlockingFirmwareState` struct for managing firmware updates. It requires a mutable buffer aligned to the flash's write size. This can be done using `new` with existing flash and buffer, or `from_config` which also takes a `FirmwareUpdaterConfig`.

```rust
pub fn new( state: STATE, aligned: &'d mut [u8], ) -> BlockingFirmwareState<'d, STATE>

pub fn from_config<DFU>( config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8], ) -> BlockingFirmwareState<'d, STATE>
where
    DFU: NorFlash,

```

--------------------------------

### Initialize BlockingFirmwareUpdater

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Creates a new instance of BlockingFirmwareUpdater. It takes a configuration, an aligned buffer for state, and returns the updater instance. The aligned buffer must meet specific size and alignment requirements.

```rust
pub fn new( config: FirmwareUpdaterConfig<DFU, STATE>,
 aligned: &'d mut [u8],
 ) -> BlockingFirmwareUpdater<'d, DFU, STATE>
```

--------------------------------

### BootLoader Structure and Methods

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoader

Documentation for the `BootLoader` struct, its fields, and associated methods for firmware preparation and loading.

```APIDOC
## Struct BootLoader

### Description
A bootloader for STM32 devices.

### Fields
- **state** (State) - The reported state of the bootloader after preparing for boot.

### Methods
#### `prepare`
- **Description**: Inspects the bootloader state and performs actions required before booting, such as swapping firmware.
- **Method**: `pub fn prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash, const BUFFER_SIZE: usize>`
- **Parameters**: `config: BootLoaderConfig<ACTIVE, DFU, STATE>`

#### `try_prepare`
- **Description**: Inspects the bootloader state and performs actions required before booting, such as swapping firmware. Returns a `Result` indicating success or failure.
- **Method**: `pub fn try_prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash, const BUFFER_SIZE: usize>`
- **Parameters**: `config: BootLoaderConfig<ACTIVE, DFU, STATE>`
- **Returns**: `Result<Self, BootError>`

#### `load`
- **Description**: Boots the application. This modifies the stack pointer and reset vector and will run code placed in the active partition.
- **Method**: `pub unsafe fn load(self, start: u32) -> !`
- **Parameters**: `start: u32`
- **Safety**: This method modifies the stack pointer and reset vector and will run code placed in the active partition.
```

--------------------------------

### Embassy Boot STM32 Overview

Source: https://docs.embassy.dev/embassy-boot-stm32/git

This section provides a high-level overview of the embassy-boot-stm32 crate, its purpose, and its key features.

```APIDOC
## Embassy Boot STM32

An Embassy project.
An adaptation of `embassy-boot` for STM32.

### Features

* Configure bootloader partitions based on linker script.
* Load applications from active partition.

### Structs

*   **AlignedBuffer**: Buffer aligned to 32 byte boundary, largest known alignment requirement for embassy-boot.
*   **BlockingFirmwareState**: Manages the state partition of the firmware update.
*   **BlockingFirmwareUpdater**: Blocking FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.
*   **BootLoader**: A bootloader for STM32 devices.
*   **BootLoaderConfig**: Bootloader flash configuration holding the three flashes used by the bootloader.
*   **FirmwareState**: Manages the state partition of the firmware update.
*   **FirmwareUpdater**: FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.
*   **FirmwareUpdaterConfig**: Firmware updater flash configuration holding the two flashes used by the updater.

### Enums

*   **BootError**: Errors returned by bootloader.
*   **State**: The state of the bootloader after running prepare.
```

--------------------------------

### Initialize Bootloader Config from Linkerfile (Rust)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Constructs a `BootLoaderConfig` using flash memory regions defined by linker script symbols. This method is crucial for setting up the bootloader's flash partitions, ensuring correct memory addressing for active, DFU, and state data. It utilizes `BlockingPartition` for synchronous flash access.

```rust
pub fn from_linkerfile_blocking(
    active_flash: &'a Mutex<NoopRawMutex, RefCell<ACTIVE>>,
    dfu_flash: &'a Mutex<NoopRawMutex, RefCell<DFU>>,
    state_flash: &'a Mutex<NoopRawMutex, RefCell<STATE>>,
) -> BootLoaderConfig<BlockingPartition<'a, NoopRawMutex, ACTIVE>, BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>
```

--------------------------------

### Initialize FirmwareUpdaterConfig from Linkerfile (Async)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdaterConfig

Creates a FirmwareUpdaterConfig using asynchronous flash partitions derived from linker script symbols. This method is suitable for non-blocking operations.

```rust
pub fn from_linkerfile(
    dfu_flash: &'a Mutex<NoopRawMutex, DFU>,
    state_flash: &'a Mutex<NoopRawMutex, STATE>,
) -> FirmwareUpdaterConfig<Partition<'a, NoopRawMutex, DFU>, Partition<'a, NoopRawMutex, STATE>>
```

--------------------------------

### Embassy Boot STM32 - Enums

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/embassy_boot_stm32/index

Documentation for the enums used in the embassy-boot-stm32 project.

```APIDOC
## Enums

### BootError

**Description:** Errors returned by bootloader.

### State

**Description:** The state of the bootloader after running prepare.
```

--------------------------------

### Generic Type Implementations

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Documentation for blanket implementations that apply to any type `T`, including `Any`, `Borrow`, `BorrowMut`, `From`, `Into`, `Same`, `TryFrom`, and `TryInto`.

```APIDOC
## Blanket Implementations

### `impl<T> Any for T`

**Description**: Implements the `Any` trait for any type `T` that is `'static + ?Sized`. This allows for runtime type identification.

#### `fn type_id(&self) -> TypeId`

**Description**: Gets the `TypeId` of `self`. This method is part of the `Any` trait.

### `impl<T> Borrow<T> for T`

**Description**: Implements the `Borrow` trait for any type `T`. This allows immutable borrowing of a value.

#### `fn borrow(&self) -> &T`

**Description**: Immutably borrows the value. This method is part of the `Borrow` trait.

### `impl<T> BorrowMut<T> for T`

**Description**: Implements the `BorrowMut` trait for any type `T`. This allows mutable borrowing of a value.

#### `fn borrow_mut(&mut self) -> &mut T`

**Description**: Mutably borrows the value. This method is part of the `BorrowMut` trait.

### `impl<T> From<T> for T`

**Description**: Implements the `From` trait for any type `T` to itself. This allows conversion from `T` to `T`.

#### `fn from(t: T) -> T`

**Description**: Returns the argument unchanged. This method is part of the `From` trait.

### `impl<T, U> Into<U> for T`

**Description**: Implements the `Into` trait for type `T` into type `U`, provided that `U` implements `From<T>`.

#### `fn into(self) -> U`

**Description**: Calls `U::from(self)`. The conversion behavior is determined by the `From<T> for U` implementation.

### `impl<T> Same for T`

**Description**: Implements the `Same` trait for any type `T`. This trait is used for identity comparisons.

#### `type Output = T`

**Description**: The associated type `Output` is always `Self`.

### `impl<T, U> TryFrom<U> for T`

**Description**: Implements the `TryFrom` trait for converting type `U` into type `T`, provided `U` implements `Into<T>`.

#### `type Error = Infallible`

**Description**: The associated `Error` type is `Infallible`, indicating that conversion errors are not expected under normal circumstances.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`

**Description**: Attempts to perform the conversion from `U` to `T`. This method is part of the `TryFrom` trait.

### `impl<T, U> TryInto<U> for T`

**Description**: Implements the `TryInto` trait for converting type `T` into type `U`, provided `U` implements `TryFrom<T>`.

#### `type Error = <U as TryFrom<T>>::Error`

**Description**: The associated `Error` type is the same as the error type for `TryFrom<T>` conversion.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`

**Description**: Attempts to perform the conversion from `T` to `U`. This method is part of the `TryInto` trait.
```

--------------------------------

### Manage Firmware Update State in Rust

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareState

Provides functions to interact with the firmware update state. `get_state` retrieves the current state, `mark_updated` prepares for a firmware swap on the next boot, `mark_dfu` triggers USB DFU mode, and `mark_booted` confirms a successful boot and prevents rollback.

```rust
pub fn get_state(&mut self) -> Result<State, FirmwareUpdaterError>

pub fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError>

pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError>

pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError>

```

--------------------------------

### FirmwareState Struct and Methods (Rust)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareState

Defines the FirmwareState struct for managing firmware update partitions on STM32 devices. It includes methods for initialization, retrieving the current state, marking for updates, DFU mode, and successful booting. Requires a STATE type implementing NorFlash and a buffer for magic content and state partition.

```rust
pub struct FirmwareState<'d, STATE> { /* private fields */ }

impl<'d, STATE>
where
    STATE: NorFlash,
{
    pub fn from_config<DFU>(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> FirmwareState<'d, STATE>
    where
        DFU: NorFlash,
    {
        /* ... */
    }

    pub fn new(state: STATE, aligned: &'d mut [u8]) -> FirmwareState<'d, STATE>
    {
        /* ... */
    }

    pub async fn get_state(&mut self) -> Result<State, FirmwareUpdaterError>
    {
        /* ... */
    }

    pub async fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError>
    {
        /* ... */
    }

    pub async fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError>
    {
        /* ... */
    }

    pub async fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError>
    {
        /* ... */
    }
}

```

--------------------------------

### Blanket Implementations

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Details various blanket implementations, including `Any`, `Borrow`, `BorrowMut`, `From`, `Into`, `Same`, `TryFrom`, and `TryInto` traits.

```APIDOC
## Blanket Implementations

### Description
This section covers a range of blanket implementations that apply to various types, including `Any`, `Borrow`, `BorrowMut`, `From`, `Into`, `Same`, `TryFrom`, and `TryInto`.

### Method
N/A (These are trait implementations, not direct API endpoints)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

```APIDOC
## `Any` Trait Implementation

### Description
Provides the `Any` trait implementation for any type `T` that is `'static` and not dynamically sized.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `type_id` Method
- **Description**: Gets the `TypeId` of `self`.
- **Signature**: `fn type_id(&self) -> TypeId`
```

```APIDOC
## `Borrow` Trait Implementation

### Description
Provides the `Borrow<T>` trait implementation for any type `T`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `borrow` Method
- **Description**: Immutably borrows from an owned value.
- **Signature**: `fn borrow(&self) -> &T`
```

```APIDOC
## `BorrowMut` Trait Implementation

### Description
Provides the `BorrowMut<T>` trait implementation for any type `T`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `borrow_mut` Method
- **Description**: Mutably borrows from an owned value.
- **Signature**: `fn borrow_mut(&mut self) -> &mut T`
```

```APIDOC
## `From<T>` for `T` Trait Implementation

### Description
Provides the `From<T>` for `T` trait implementation.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `from` Method
- **Description**: Returns the argument unchanged.
- **Signature**: `fn from(t: T) -> T`
```

```APIDOC
## `Into<U>` for `T` Trait Implementation

### Description
Provides the `Into<U>` for `T` trait implementation, where `U` implements `From<T>`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `into` Method
- **Description**: Calls `U::from(self)`. The conversion behavior is determined by the `From<T> for U` implementation.
- **Signature**: `fn into(self) -> U`
```

```APIDOC
## `Same` Trait Implementation

### Description
Provides the `Same` trait implementation for any type `T`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `Output` Associated Type
- **Description**: Should always be `Self`.
- **Type**: `T`
```

```APIDOC
## `TryFrom<U>` for `T` Trait Implementation

### Description
Provides the `TryFrom<U>` for `T` trait implementation, where `U` implements `Into<T>`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `Error` Associated Type
- **Description**: The type returned in the event of a conversion error.
- **Type**: `Infallible`

#### `try_from` Method
- **Description**: Performs the conversion.
- **Signature**: `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`
```

```APIDOC
## `TryInto<U>` for `T` Trait Implementation

### Description
Provides the `TryInto<U>` for `T` trait implementation, where `U` implements `TryFrom<T>`.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### `Error` Associated Type
- **Description**: The type returned in the event of a conversion error.
- **Type**: `<U as TryFrom<T>>::Error`

#### `try_into` Method
- **Description**: Performs the conversion.
- **Signature**: `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`
```

--------------------------------

### Implement Sync for BootLoaderConfig

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Implements the `Sync` trait for `BootLoaderConfig`. This allows `BootLoaderConfig` instances to be safely shared across multiple threads, provided that the `ACTIVE`, `DFU`, and `STATE` type parameters also implement `Sync`.

```rust
impl<ACTIVE, DFU, STATE> Sync for BootLoaderConfig<ACTIVE, DFU, STATE>
where ACTIVE: Sync, DFU: Sync, STATE: Sync,
```

--------------------------------

### Prepare for DFU Update

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Prepares for an incoming DFU update by erasing the entire DFU area. It returns a mutable reference to the DFU partition, allowing for optimized update processes at the cost of increased complexity.

```rust
pub fn prepare_update(&mut self) -> Result<&mut DFU, FirmwareUpdaterError>
```

--------------------------------

### Embassy Boot STM32 - Core Concepts

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/index

This section details the main structures and enums used within the embassy-boot-stm32 crate for managing bootloader operations and firmware updates.

```APIDOC
## Core Structures and Enums

### Description

This documentation outlines the key data structures and enumerations provided by the `embassy-boot-stm32` crate. These components are essential for configuring and managing the bootloader, handling firmware updates, and tracking the state of the boot process on STM32 devices.

### Structures

#### `AlignedBuffer`
- **Description**: A buffer that is aligned to a 32-byte boundary, designed to meet the largest known alignment requirements for `embassy-boot`.

#### `BlockingFirmwareState`
- **Description**: Manages the state partition of the firmware update process, ensuring state integrity in a blocking manner.

#### `BlockingFirmwareUpdater`
- **Description**: Provides a blocking API for applications to interact with the BootLoader, preventing corruption of the internal bootloader state.

#### `BootLoader`
- **Description**: Represents the main bootloader functionality for STM32 devices.

#### `BootLoaderConfig`
- **Description**: Configuration structure for the bootloader, specifying the flash memory layout used by the bootloader.

#### `FirmwareState`
- **Description**: Manages the state partition of the firmware update process.

#### `FirmwareUpdater`
- **Description**: Provides an application API for interacting with the BootLoader, allowing firmware updates.

#### `FirmwareUpdaterConfig`
- **Description**: Configuration structure for the firmware updater, specifying the flash memory layout used by the updater.

### Enums

#### `BootError`
- **Description**: Enumerates the possible errors that can be returned by the bootloader operations.

#### `State`
- **Description**: Represents the state of the bootloader after the `prepare` function has been executed.
```

--------------------------------

### BootLoaderConfig Struct

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Configuration structure for the bootloader, managing active, DFU, and state flash partitions.

```APIDOC
## Struct BootLoaderConfig

### Description
Bootloader flash configuration holding the three flashes used by the bootloader. If only a single flash is actually used, then that flash should be partitioned into three partitions before use. The easiest way to do this is to use `BootLoaderConfig::from_linkerfile_blocking` which will partition the provided flash according to symbols defined in the linkerfile.

### Fields
*   **active** (ACTIVE) - Flash type used for the active partition - the partition which will be booted from.
*   **dfu** (DFU) - Flash type used for the dfu partition - the partition which will be swapped in when requested.
*   **state** (STATE) - Flash type used for the state partition.

### Implementations
#### impl<'a, ACTIVE, DFU, STATE> BootLoaderConfig<BlockingPartition<'a, NoopRawMutex, ACTIVE>, BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>
where ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash

##### pub fn from_linkerfile_blocking(
    active_flash: &'a Mutex<NoopRawMutex, RefCell<ACTIVE>>,
    dfu_flash: &'a Mutex<NoopRawMutex, RefCell<DFU>>,
    state_flash: &'a Mutex<NoopRawMutex, RefCell<STATE>>,
) -> BootLoaderConfig<BlockingPartition<'a, NoopRawMutex, ACTIVE>, BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>

###### Description
Constructs a `BootLoaderConfig` instance from flash memory and address symbols defined in the linker file. This method initializes `BlockingPartition` instances for the active, DFU (Device Firmware Update), and state partitions, leveraging start and end addresses specified by the linker. These partitions are critical for managing firmware updates, application state, and boot operations within the bootloader.

###### Parameters
*   **active_flash** (Mutex<NoopRawMutex, RefCell<ACTIVE>>) - A reference to a mutex-protected `RefCell` for the active partition’s flash interface.
*   **dfu_flash** (Mutex<NoopRawMutex, RefCell<DFU>>) - A reference to a mutex-protected `RefCell` for the DFU partition’s flash interface.
*   **state_flash** (Mutex<NoopRawMutex, RefCell<STATE>>) - A reference to a mutex-protected `RefCell` for the state partition’s flash interface.

###### Safety
The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses of the bootloader’s partitions in flash memory. It is crucial that these addresses are accurately defined in the memory.x file to prevent undefined behavior. The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory interfaces provided are compatible with these regions.

###### Returns
A `BootLoaderConfig` instance with `BlockingPartition` instances for the active, DFU, and state partitions.

###### Example
```rust
// Assume `active_flash`, `dfu_flash`, and `state_flash` all share the same flash memory interface.
let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
let flash = Mutex::new(RefCell::new(layout.bank1_region));

let config = BootLoaderConfig::from_linkerfile_blocking(&flash, &flash, &flash);
// `config` can now be used to create a `BootLoader` instance for managing boot operations.
```

Working examples can be found in the bootloader examples folder.
```

--------------------------------

### Embassy Boot STM32 - Core Concepts

Source: https://docs.embassy.dev/embassy-boot-stm32/index

This section details the core structs and enums used by the embassy-boot-stm32 bootloader for managing firmware updates and device state.

```APIDOC
## Structs

### `AlignedBuffer`

**Description**: Buffer aligned to 32 byte boundary, largest known alignment requirement for embassy-boot.

### `BlockingFirmwareState`

**Description**: Manages the state partition of the firmware update.

### `BlockingFirmwareUpdater`

**Description**: Blocking FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.

### `BootLoader`

**Description**: A bootloader for STM32 devices.

### `BootLoaderConfig`

**Description**: Bootloader flash configuration holding the three flashes used by the bootloader.

### `FirmwareState`

**Description**: Manages the state partition of the firmware update.

### `FirmwareUpdater`

**Description**: FirmwareUpdater is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.

### `FirmwareUpdaterConfig`

**Description**: Firmware updater flash configuration holding the two flashes used by the updater.

## Enums

### `BootError`

**Description**: Errors returned by bootloader.

### `State`

**Description**: The state of the bootloader after running prepare.
```

--------------------------------

### Prepare Bootloader for STM32

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoader

Provides functions to prepare the STM32 bootloader before booting new firmware. This includes inspecting the bootloader state and potentially swapping firmware images. It requires generic types for flash memory and a buffer size.

```rust
pub fn prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash, const BUFFER_SIZE: usize>( config: BootLoaderConfig<ACTIVE, DFU, STATE>, ) -> Self
```

```rust
pub fn try_prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash, const BUFFER_SIZE: usize>( config: BootLoaderConfig<ACTIVE, DFU, STATE>, ) -> Result<Self, BootError>
```

--------------------------------

### BlockingFirmwareState API

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareState

Manages the state partition of the firmware update process. This struct can be used independently for detailed control or as part of a larger updater.

```APIDOC
## Struct BlockingFirmwareState

### Description
Manages the state partition of the firmware update. Can be used standalone for more fine grained control, or as part of the updater.

### Methods

#### `from_config`

##### Description
Creates a firmware state instance from a `FirmwareUpdaterConfig`, with a buffer for magic content and state partition.

##### Signature
`pub fn from_config<DFU>(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> BlockingFirmwareState<'d, STATE>`

##### Parameters
- `config` (FirmwareUpdaterConfig<DFU, STATE>): The configuration for the firmware updater.
- `aligned` (&'d mut [u8]): A mutable byte slice buffer for magic content and state partition. Must be of size `STATE::WRITE_SIZE` and adhere to alignment rules.

##### Safety
The `aligned` buffer must have a size of `STATE::WRITE_SIZE`, and follow the alignment rules for the flash being read from and written to.

#### `new`

##### Description
Creates a firmware state instance with a buffer for magic content and state partition.

##### Signature
`pub fn new(state: STATE, aligned: &'d mut [u8]) -> BlockingFirmwareState<'d, STATE>`

##### Parameters
- `state` (STATE): The state partition object implementing `NorFlash`.
- `aligned` (&'d mut [u8]): A mutable byte slice buffer for magic content and state partition. Must be of size `STATE::WRITE_SIZE` and adhere to alignment rules.

##### Safety
The `aligned` buffer must have a size of `STATE::WRITE_SIZE`, and follow the alignment rules for the flash being read from and written to.

#### `get_state`

##### Description
Obtains the current firmware state. Useful for performing verifications and self-tests after a firmware swap before marking the new image as booted.

##### Signature
`pub fn get_state(&mut self) -> Result<State, FirmwareUpdaterError>`

##### Returns
- `Ok(State)`: The current state of the firmware.
- `Err(FirmwareUpdaterError)`: An error occurred while retrieving the state.

#### `mark_updated`

##### Description
Marks the system to trigger a firmware swap on the next boot.

##### Signature
`pub fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError>`

##### Returns
- `Ok(())`: The update mark was set successfully.
- `Err(FirmwareUpdaterError)`: An error occurred while marking for update.

#### `mark_dfu`

##### Description
Marks the system to trigger a USB DFU (Device Firmware Upgrade) mode on the next boot.

##### Signature
`pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError>`

##### Returns
- `Ok(())`: The DFU mark was set successfully.
- `Err(FirmwareUpdaterError)`: An error occurred while marking for DFU.

#### `mark_booted`

##### Description
Marks the current firmware boot as successful, preventing rollback on the next reset.

##### Signature
`pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError>`

##### Returns
- `Ok(())`: The boot was marked successfully.
- `Err(FirmwareUpdaterError)`: An error occurred while marking the boot.
```

--------------------------------

### Initialize FirmwareUpdaterConfig from Linkerfile (Blocking)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdaterConfig

Constructs a FirmwareUpdaterConfig using blocking flash partitions, typically initialized from linker script symbols. This method is intended for synchronous operations and requires careful handling of memory addresses.

```rust
pub fn from_linkerfile_blocking(
    dfu_flash: &'a Mutex<NoopRawMutex, RefCell<DFU>>,
    state_flash: &'a Mutex<NoopRawMutex, RefCell<STATE>>,
) -> FirmwareUpdaterConfig<BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>
```

--------------------------------

### Embassy Boot STM32 State Enum Implementations

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/enum.State

Provides implementations for the State enum, including Debug for formatting, From<T> for conversion from byte arrays, and PartialEq/Eq for equality comparisons. These implementations enable the enum to be used effectively within the Embassy bootloader context.

```rust
impl Debug for State
fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<T> From<T> for State where T: AsRef<[u8]>
fn from(magic: T) -> State

impl PartialEq for State
fn eq(&self, other: &State) -> bool

impl Eq for State

impl StructuralPartialEq for State
```

--------------------------------

### Implement From<T> for T

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdaterConfig

A trivial implementation of `From<T>` for `T`, meaning a value of type `T` can be converted into itself. The `from` function simply returns the input value unchanged. This is often a base case for more complex conversion logic.

```rust
impl<T> From<T> for T

fn from(t: T) -> T
```

--------------------------------

### Implement Sync for BlockingFirmwareUpdater

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This snippet demonstrates the implementation of the `Sync` trait for `BlockingFirmwareUpdater`. The `Sync` trait signifies that a type can be safely shared between threads. Similar to `Send`, this implementation is generic and requires `DFU` and `STATE` to also implement `Sync`.

```rust
impl<'d, DFU, STATE> Sync for BlockingFirmwareUpdater<'d, DFU, STATE>
where
    DFU: Sync,
    STATE: Sync,
```

--------------------------------

### Verify Firmware with Digest

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Verifies the firmware update in DFU storage using a specified digest algorithm. It requires the update length, a chunk buffer for processing, and an output buffer for the digest result.

```rust
pub fn hash<D>(
 &mut self,
 update_len: u32,
 chunk_buf: &mut [u8],
 output: &mut [u8],
 ) -> Result<(), FirmwareUpdaterError>
where
    D: Digest,
```

--------------------------------

### Define Bootloader Flash Configuration (Rust)

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

Defines the `BootLoaderConfig` struct to manage flash memory partitions for bootloader operations, including active application, DFU, and state storage. It requires generic types for each partition, allowing flexibility in flash implementation.

```rust
pub struct BootLoaderConfig<ACTIVE, DFU, STATE> {
    pub active: ACTIVE,
    pub dfu: DFU,
    pub state: STATE,
}
```

--------------------------------

### Implement Same for T

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This code demonstrates a blanket implementation of the `Same` trait for any type `T`. The `Same` trait is used to indicate that a type is the same as itself. The associated type `Output` is defined as `T`.

```rust
impl<T> Same for T {
    type Output = T
}
```

--------------------------------

### FirmwareUpdater API

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdater

Provides methods for creating, managing, and performing firmware updates using the Embassy bootloader.

```APIDOC
## `FirmwareUpdater` Struct

### Description

`FirmwareUpdater` is an application API for interacting with the BootLoader without the ability to ‘mess up’ the internal bootloader state.

### Methods

#### `new`

- **Description**: Create a firmware updater instance with partition ranges for the update and state partitions.
- **Method**: `new`
- **Parameters**:
  - `config` (FirmwareUpdaterConfig<DFU, STATE>) - Required - Configuration for the firmware updater.
  - `aligned` (&'d mut [u8]) - Required - A mutable byte slice for aligned operations.
- **Returns**: `FirmwareUpdater<'d, DFU, STATE>`

#### `get_state`

- **Description**: Obtain the current state of the firmware updater. This is useful to check if the bootloader has just done a swap, in order to do verifications and self-tests of the new image before calling `mark_booted`.
- **Method**: `get_state`
- **Returns**: `Result<State, FirmwareUpdaterError>`

#### `hash`

- **Description**: Verify the update in DFU with any digest.
- **Method**: `hash`
- **Parameters**:
  - `update_len` (u32) - Required - The length of the update to hash.
  - `chunk_buf` (&mut [u8]) - Required - A mutable buffer for chunks during hashing.
  - `output` (&mut [u8]) - Required - A buffer to store the resulting hash.
- **Generic Type**: `D` where `D: Digest`
- **Returns**: `Result<(), FirmwareUpdaterError>`

#### `read_dfu`

- **Description**: Read a slice of data from the DFU storage peripheral, starting the read operation at the given address offset, and reading `buf.len()` bytes.
- **Method**: `read_dfu`
- **Parameters**:
  - `offset` (u32) - Required - The starting offset for reading.
  - `buf` (&mut [u8]) - Required - The buffer to read data into.
- **Returns**: `Result<(), FirmwareUpdaterError>`
- **Errors**: Returns an error if the arguments are not aligned or out of bounds.

#### `mark_updated`

- **Description**: Mark to trigger firmware swap on next boot.
- **Method**: `mark_updated`
- **Returns**: `Result<(), FirmwareUpdaterError>`

#### `mark_dfu`

- **Description**: Mark to trigger USB DFU on next boot.
- **Method**: `mark_dfu`
- **Returns**: `Result<(), FirmwareUpdaterError>`

#### `mark_booted`

- **Description**: Mark firmware boot successful and stop rollback on reset.
- **Method**: `mark_booted`
- **Returns**: `Result<(), FirmwareUpdaterError>`

#### `write_firmware`

- **Description**: Writes firmware data to the device. This function writes the given data to the firmware area starting at the specified offset. It handles sector erasures and data writes while verifying the device is in a proper state for firmware updates. The function ensures that only unerased sectors are erased before writing and efficiently handles the writing process across sector boundaries and in various configurations (data size, sector size, etc.).
- **Method**: `write_firmware`
- **Parameters**:
  - `offset` (usize) - Required - The starting offset within the firmware area where data writing should begin.
  - `data` (&[u8]) - Required - A slice of bytes representing the firmware data to be written. It must be a multiple of NorFlash WRITE_SIZE.
- **Returns**: `Result<(), FirmwareUpdaterError>`
- **Errors**: This function will return an error if:
  - The device is not in a proper state to receive firmware updates (e.g., not booted).
  - There is a failure erasing a sector before writing.
  - There is a failure writing data to the device.

#### `prepare_update`

- **Description**: Prepare for an incoming DFU update by erasing the entire DFU area and returning its `Partition`. Using this instead of `write_firmware` allows for an optimized API in exchange for added complexity.
- **Method**: `prepare_update`
- **Returns**: `Result<&mut DFU, FirmwareUpdaterError>`

```

--------------------------------

### Implement TryInto<U> for T

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdaterConfig

Implements the `TryInto<U>` trait for type `T` whenever `U` implements `TryFrom<T>`. This provides a fallible conversion from `T` to `U` using the `try_into` method. The method returns a `Result`, encapsulating potential conversion errors.

```rust
impl<T, U>
where
    U: TryFrom<T>,
    TryInto<U> for T

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Embassy Boot STM32 State Enum Definition

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/enum.State

Defines the possible states of the bootloader after running the prepare function. These states include Boot, Swap, Revert, and DfuDetach, each representing a specific stage or action within the bootloader process.

```rust
pub enum State {
    Boot,
    Swap,
    Revert,
    DfuDetach,
}
```

--------------------------------

### Firmware Update Operations

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This section details the implementations for sending, synchronizing, and managing the unpinning of firmware updates.

```APIDOC
## BlockingFirmwareUpdater Implementations

### `impl<'d, DFU, STATE> Send for BlockingFirmwareUpdater<'d, DFU, STATE>`

**Description**: Implements the `Send` trait for `BlockingFirmwareUpdater`, allowing firmware data to be sent across threads.

### `impl<'d, DFU, STATE> Sync for BlockingFirmwareUpdater<'d, DFU, STATE>`

**Description**: Implements the `Sync` trait for `BlockingFirmwareUpdater`, enabling safe shared access to firmware updaters across multiple threads.

### `impl<'d, DFU, STATE> Unpin for BlockingFirmwareUpdater<'d, DFU, STATE>`

**Description**: Implements the `Unpin` trait for `BlockingFirmwareUpdater`, indicating that the type does not move its own data when sent to another thread.
```

--------------------------------

### Mark Firmware as Booted

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Marks the current firmware boot as successful, preventing rollback on the next reset. This should be called after verifying the new firmware.

```rust
pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError>
```

--------------------------------

### Implement Unpin for BlockingFirmwareUpdater

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This code shows the implementation of the `Unpin` trait for `BlockingFirmwareUpdater`. The `Unpin` trait indicates that a type does not require special handling when moved, which is important for certain asynchronous operations. The implementation is generic and requires `DFU` and `STATE` to also implement `Unpin`.

```rust
impl<'d, DFU, STATE> Unpin for BlockingFirmwareUpdater<'d, DFU, STATE>
where
    DFU: Unpin,
    STATE: Unpin,
```

--------------------------------

### Mark Firmware for Update

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

Marks the firmware to trigger a firmware swap on the next boot. This operation is part of the firmware update process.

```rust
pub fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError>
```

--------------------------------

### BootLoaderConfig Trait Implementations

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BootLoaderConfig

This section details the Sync, Unpin, and UnwindSafe trait implementations for the BootLoaderConfig generic struct.

```APIDOC
## Trait Implementations for BootLoaderConfig

### Description
Provides implementations for `Sync`, `Unpin`, and `UnwindSafe` traits for the `BootLoaderConfig` struct, which is generic over `ACTIVE`, `DFU`, and `STATE` types.

### Method
N/A (These are trait implementations, not direct API endpoints)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Implement Borrow for T

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This code demonstrates a blanket implementation of the `Borrow` trait for any type `T`. The `Borrow` trait allows an owned value to be borrowed immutably. The implementation provides a `borrow` method that returns an immutable reference to `T`.

```rust
impl<T> Borrow<T> for T
where
    T: ?Sized,
{
    fn borrow(&self) -> &T
}
```

--------------------------------

### Implement Any for Generic Type T

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.FirmwareUpdaterConfig

Implements the `Any` trait for any type `T` that is `'static` and `?Sized`. The `Any` trait allows for runtime type identification, enabling downcasting and dynamic dispatch. The `type_id` method returns the unique `TypeId` of the instance.

```rust
impl<T> Any for T
where
    T: 'static + ?Sized,

fn type_id(&self) -> TypeId
```

--------------------------------

### Implement Send for BlockingFirmwareUpdater

Source: https://docs.embassy.dev/embassy-boot-stm32/0.6.0/default/struct.BlockingFirmwareUpdater

This snippet shows the implementation of the `Send` trait for the `BlockingFirmwareUpdater` struct. The `Send` trait indicates that a type can be safely transferred between threads. This implementation is generic over the `DFU` and `STATE` types, requiring them to also implement `Send`.

```rust
impl<'d, DFU, STATE> Send for BlockingFirmwareUpdater<'d, DFU, STATE>
where
    DFU: Send,
    STATE: Send,
```
Tokens:
Raw