Cortex M

https://docs.rs/cortex-m/latest/
Admin
Cortex M is a Rust crate providing low-level access to Cortex-M processors, including core...
Tokens:472,696
Snippets:3,128
Trust Score:9.7
Update:10 months ago
Show doc for...
Tokens:
Raw
### Bootload Function

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.bootload_search=

The bootload function reads the initial stack pointer and reset vector, sets up the main stack, and jumps to the reset vector to start the execution of the application.

```APIDOC
## bootload

### Description
Bootload. Reads the initial stack pointer value and reset vector from the provided vector table address, sets the active stack to the main stack, sets the main stack pointer to the new initial stack pointer, then jumps to the reset vector.

### Method
`unsafe fn`

### Parameters
#### Path Parameters
- **vector_table** (*const u32*) - Required - A pointer to the vector table containing the initial stack pointer and reset vector.

### Safety
The provided `vector_table` must point to a valid vector table, with a valid stack pointer as the first word and a valid reset vector as the second word.

### Response Example
This function has a return type of `!` which indicates it never returns.
```

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

### I2C Write Contract Example

Source: https://docs.rs/cortex-m/latest/cortex_m/prelude/trait._embedded_hal_blocking_i2c_Write_search=std%3A%3Avec

Illustrates the I2C contract for a blocking write operation. It shows the sequence of Master and Slave actions, including start conditions, slave address, acknowledge signals, data bytes, and stop conditions.

```text
Master: ST SAD+W     B0     B1     ... BN     SP
Slave:           SAK    SAK    SAK ...    SAK

Where
  * `ST` = start condition
  * `SAD+W` = slave address followed by bit 0 to indicate writing
  * `SAK` = slave acknowledge
  * `Bi` = ith byte of data
  * `SP` = stop condition

```

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

### Rust Example: RegisterBlock Documentation

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/nvic/index_search=

This snippet illustrates how Rust documentation for a RegisterBlock struct might look, providing a summary of its purpose as a register block. This is a common pattern in embedded Rust development for hardware abstraction.

```Rust
/// Register block
///
/// Summary of the register block's functionality.
pub struct RegisterBlock {
    // Fields representing registers would go here
    // pub reg1: RWRegister<u32>,
    // pub reg2: RORegister<u16>,
}

impl RegisterBlock {
    // Methods for interacting with the registers
}

```

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

### System Handler Priority Management (Rust)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB_search=std%3A%3Avec

Provides functions to get and set the hardware priority of system handlers. Note that hardware priority may differ from logical priority levels. Setting priorities can impact critical sections and memory safety.

```rust
pub fn get_priority(system_handler: SystemHandler) -> u8
pub unsafe fn set_priority(&mut self, system_handler: SystemHandler, prio: u8)
```

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

### Bootstrap

Source: https://docs.rs/cortex-m/latest/src/cortex_m/asm.rs

Initializes the system by setting the main stack pointer and jumping to a specified entry point. This function is unsafe and requires valid memory pointers.

```APIDOC
## POST /armv8-m/bootstrap

### Description
Initializes the main stack and jumps to the reset vector.

### Method
POST

### Endpoint
/armv8-m/bootstrap

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **msp** (*const u32) - Required - Pointer to the main stack initialization address.
- **rv** (*const u32) - Required - Pointer to the reset vector (entry point).

### Request Example
{
  "msp": "0x20000000",
  "rv": "0x80000005"
}

### Response
#### Success Response (200)
This function enters an infinite loop or jumps to the reset vector and does not return.

#### Response Example
None
```

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

### Example Usage of _embedded_hal_timer_CountDown Trait for Delays in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/prelude/trait._embedded_hal_timer_CountDown_search=

Demonstrates how to use the _embedded_hal_timer_CountDown trait to create timed delays within an embedded Rust application. The example utilizes the `start` and `wait` methods, along with the `block!` macro, to pause execution for a specified duration, illustrated with LED control.

```rust
extern crate embedded_hal as hal;
#[macro_use(block)]
extern crate nb;

use hal::prelude::*;

fn main() {
    let mut led: Led = {
        // ..
    };
    let mut timer: Timer6 = {
        // ..
    };

    Led.on();
    timer.start(1.s());
    block!(timer.wait()); // blocks for 1 second
    Led.off();
}
```

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

### Use singleton macro in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/macro.singleton_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Example demonstrating the usage of the `singleton!` macro in Rust. It shows how to initialize a static mutable boolean and the potential panic if called multiple times within the same program lifetime. It also illustrates how to assign a debug-only name to a singleton.

```rust
use cortex_m::singleton;

fn main() {
    // OK if `main` is executed only once
    let x: &'static mut bool = singleton!(: bool = false).unwrap();

    let y = alias();
    // BAD this second call to `alias` will definitively `panic!`
    let y_alias = alias();
}

fn alias() -> &'static mut bool {
    singleton!(: bool = false).unwrap()
}

fn singleton_with_name() {
    // A name only for debugging purposes
    singleton!(FOO_BUFFER: [u8; 1024] = [0u8; 1024]);
}
```

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

### cortex_m::asm::bootload

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.bootload_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The bootload function initiates the boot process by reading the initial stack pointer and reset vector from a provided vector table. It then sets up the main stack and jumps to the reset vector.

```APIDOC
## Function bootload

### Description
Bootload. Reads the initial stack pointer value and reset vector from the provided vector table address, sets the active stack to the main stack, sets the main stack pointer to the new initial stack pointer, then jumps to the reset vector.

### Method
`unsafe fn bootload(vector_table: *const u32) -> !`

### Endpoint
`cortex_m::asm::bootload`

### Safety
The provided `vector_table` must point to a valid vector table, with a valid stack pointer as the first word and a valid reset vector as the second word.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (not directly executable without a full context)
// let vector_table_address: *const u32 = 0x10000;
// unsafe { cortex_m::asm::bootload(vector_table_address) };
```

### Response
#### Success Response (200)
This function does not return. It jumps to the reset vector.

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

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

### Get Interrupt Priority - Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.NVIC

Retrieves the NVIC priority of a given interrupt. Note that NVIC priorities are encoded in the highest bits of a byte, where lower numerical values indicate higher priority. For example, 16 has higher priority than 32.

```rust
pub fn get_priority<I>(interrupt: I) -> u8
where I: InterruptNumber,
```

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

### Rust: Get and Set CPI Count for Cortex-M DWT

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/dwt.rs_search=

Provides functions to get and set the CPI (Cycle Per Instruction) count for the DWT unit. These functions are conditional and not available on ARMv6M. Getting the count involves an unsafe atomic read, while setting requires an unsafe write to the register.

```rust
/// Get the CPI count
///
/// Counts additional cycles required to execute multi-cycle instructions,
/// except those recorded by [`lsu_count`], and counts any instruction fetch
/// stalls.
///
/// [`lsu_count`]: DWT::lsu_count
#[cfg(not(armv6m))]
#[inline]
pub fn cpi_count() -> u8 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).cpicnt.read() as u8 }
}

/// Set the CPI count
#[cfg(not(armv6m))]
#[inline]
pub fn set_cpi_count(&mut self, count: u8) {
    unsafe { self.cpicnt.write(count as u32) }
}
```

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

### Initiate System Reset (Rust)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB_search=std%3A%3Avec

Requests a system reset for the MCU. This function is non-returning as it initiates a hard reset of the system.

```rust
pub fn sys_reset() -> !
```

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

### Generic Implementations for FPB in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.FPB_search=u32+-%3E+bool

Showcases various blanket implementations for the `FPB` struct, including `Any`, `Borrow`, `BorrowMut`, `From`, `Into`, `TryFrom`, and `TryInto`. These traits facilitate general-purpose data handling and conversions.

```rust
impl<T> Any for T where T: 'static + ?Sized { fn type_id(&self) -> TypeId }
impl<T> Borrow<T> for T where T: ?Sized { fn borrow(&self) -> &T }
impl<T> BorrowMut<T> for T where T: ?Sized { fn borrow_mut(&mut self) -> &mut T }
impl<T> From<T> for T { fn from(t: T) -> T }
impl<T, U> Into<U> for T where U: From<T> { fn into(self) -> U }
impl<T, U> TryFrom<U> for T where U: Into<T> { type Error = Infallible; fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> }
impl<T, U> TryInto<U> for T where U: TryFrom<T> { type Error = <U as TryFrom<T>>::Error; fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error> }
```

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

### SAU Peripheral API

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SAU_search=u32+-%3E+bool

Provides methods for interacting with the Security Attribution Unit (SAU) peripheral, including getting the number of regions, enabling the SAU, and setting or getting specific SAU regions.

```APIDOC
## SAU Peripheral API

### Description

This section details the API for the Security Attribution Unit (SAU) peripheral. It allows for management of security regions, enabling the SAU, and retrieving information about the configured regions.

### Methods

#### `region_numbers`

- **Description**: Get the number of implemented SAU regions.
- **Method**: `&self` (Read-only access)
- **Returns**: `u8` - The number of available SAU regions.

#### `enable`

- **Description**: Enable the SAU.
- **Method**: `&mut self` (Requires mutable access)

#### `set_region`

- **Description**: Set a SAU region to a specific region number. SAU regions must be 32-byte aligned and their sizes must be a multiple of 32 bytes. This means the 5 least significant bits of the base address must be zero, and the 5 least significant bits of the limit address must be one. The region number must be valid. This operation is performed under a critical section.
- **Method**: `&mut self` (Requires mutable access)
- **Parameters**:
  - `region_number` (u8) - The number of the SAU region to configure.
  - `region` (SauRegion) - The configuration for the SAU region.
- **Returns**: `Result<(), SauError>` - Ok if the region was set successfully, Err otherwise.

#### `get_region`

- **Description**: Get the configuration of a specific SAU region. The region number must be valid. This operation is performed under a critical section.
- **Method**: `&mut self` (Requires mutable access)
- **Parameters**:
  - `region_number` (u8) - The number of the SAU region to retrieve.
- **Returns**: `Result<SauRegion, SauError>` - Ok with the SauRegion configuration, Err if the region number is invalid or an error occurs.

### Constants

#### `PTR`

- **Description**: A constant pointer to the SAU register block.
- **Type**: `*const RegisterBlock`
- **Address**: `0xe000edd0`

#### `ptr()` (Deprecated)

- **Description**: Deprecated function to get a pointer to the SAU register block. Use `PTR` instead.
- **Method**: `const fn`
- **Returns**: `*const RegisterBlock`
```

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

### Check if test range is valid

Source: https://docs.rs/cortex-m/latest/src/cortex_m/cmse.rs_search=

Validates if the test start and end addresses are the same. This is a preliminary check to ensure the range for testing is properly defined. It returns an Option containing the start address if they are equal, otherwise None.

```rust
            if test_start != test_end {
                None
            } else {
                Some(test_start)
            }
```

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

### Bootstrap System Initialization

Source: https://docs.rs/cortex-m/latest/src/cortex_m/asm.rs_search=std%3A%3Avec

Initializes the system by setting the main stack pointer, clearing stack selection, and jumping to a given code address. This function is crucial for the initial startup of embedded systems. It requires `unsafe` as it manipulates stack pointers and performs jumps to arbitrary code addresses, with strict requirements on the validity of input pointers.

```rust
/// Bootstrap.
///
/// Clears CONTROL.SPSEL (setting the main stack to be the active stack),
/// updates the main stack pointer to the address in `msp`, then jumps
/// to the address in `rv`.
///
/// # Safety
///
/// `msp` and `rv` must point to valid stack memory and executable code,
/// respectively.
#[inline]
pub unsafe fn bootstrap(msp: *const u32, rv: *const u32) -> ! {
    // Ensure thumb mode is set.
    let rv = (rv as u32) | 1;
    let msp = msp as u32;
    call_asm!(__bootstrap(msp: u32, rv: u32) -> !);
}
```

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

### Get Sleep Count (Rust)

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/dwt.rs_search=std%3A%3Avec

Gets the total processor cycles spent in sleep mode. The exact behavior of this counter is implementation-defined, but it generally tracks cycles during low-power states. Available for non-ARMv6m architectures via unsafe atomic reads.

```rust
pub fn sleep_count() -> u8 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).sleepcnt.read() as u8 }
}
```

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

### bootload Function

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.bootload

Details the `bootload` function, including its safety requirements and how it manipulates stack pointers and jumps to the reset vector.

```APIDOC
## bootload

### Description
Bootload. Reads the initial stack pointer value and reset vector from the provided vector table address, sets the active stack to the main stack, sets the main stack pointer to the new initial stack pointer, then jumps to the reset vector.

### Method
`unsafe fn bootload(vector_table: *const u32) -> !`

### Endpoint
N/A (This is a function within a Rust crate, not a web API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (requires a valid vector table address)
// unsafe { cortex_m::asm::bootload(0x08000000 as *const u32); }
```

### Response
#### Success Response (200)
This function does not return a value in the traditional sense; it jumps to the reset vector, effectively starting program execution.

#### Response Example
N/A

## §Safety
The provided `vector_table` must point to a valid vector table, with a valid stack pointer as the first word and a valid reset vector as the second word.
```

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

### Rust: Get and Set Sleep Count for Cortex-M DWT

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/dwt.rs_search=

Provides functionality to get the total processor cycles spent sleeping and to set this count. This is applicable to non-ARMv6M architectures. The description notes that the exact counting mechanism for sleep cycles is implementation-defined.

```rust
/// Get the total number of cycles that the processor is sleeping
///
/// ARM recommends that this counter counts all cycles when the processor is sleeping,
/// regardless of whether a WFI or WFE instruction, or the sleep-on-exit functionality,
/// caused the entry to sleep mode.
/// However, all sleep features are implementation defined and therefore when
/// this counter counts is implementation defined.
#[cfg(not(armv6m))]
#[inline]
pub fn sleep_count() -> u8 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).sleepcnt.read() as u8 }
}

/// Set the sleep count
#[cfg(not(armv6m))]
#[inline]
pub fn set_sleep_count(&mut self, count: u8) {
    unsafe { self.sleepcnt.write(count as u32) }
}
```

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

### Rust Example: Basic Vector Interrupt Controller (NVIC)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/nvic/index_search=

This snippet demonstrates a basic interaction with the Nested Vector Interrupt Controller (NVIC) in Rust for the Cortex-M architecture. It assumes the cortex-m crate is available and outlines typical usage patterns for managing interrupts.

```Rust
use cortex_m::peripheral::NVIC;

fn main() {
    // Placeholder for actual NVIC interaction
    // Example: let mut nvic = NVIC::new();
    // Example: nvic.enable(interrupt::TIMER0);
    // Example: nvic.disable(interrupt::UART0);
    println!("NVIC example placeholder.");
}
```

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

### Get IRQ Number for Cortex-M Exception in Rust

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/scb.rs

This Rust code defines an `Exception` enum for Cortex-M processor core exceptions and provides a method `irqn` to get the corresponding negative IRQ number for each exception type. This is useful for system-level debugging and exception handling logic.

```rust
impl Exception {
    /// Returns the IRQ number of this `Exception`
    ///
    /// The return value is always within the closed range `[-1, -14]`
    #[inline]
    pub fn irqn(self) -> i8 {
        match self {
            Exception::NonMaskableInt => -14,
            Exception::HardFault => -13,
            #[cfg(not(armv6m))]
            Exception::MemoryManagement => -12,
            #[cfg(not(armv6m))]
            Exception::BusFault => -11,
            #[cfg(not(armv6m))]
            Exception::UsageFault => -10,
            #[cfg(any(armv8m, native))]
            Exception::SecureFault => -9,
            Exception::SVCall => -5,
            #[cfg(not(armv6m))]
            Exception::DebugMonitor => -4,
            Exception::PendSV => -2,
            Exception::SysTick => -1,
        }
    }
}

```

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

### Rust: Get and Set LSU Count for Cortex-M DWT

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/dwt.rs_search=

Enables getting and setting the count of additional cycles required for load or store instructions by the DWT unit. These functions are restricted to non-ARMv6M targets. Reading is an atomic operation without side effects, while writing is performed within an unsafe block.

```rust
/// Get the additional cycles required to execute all load or store instructions
#[cfg(not(armv6m))]
#[inline]
pub fn lsu_count() -> u8 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).lsucnt.read() as u8 }
}

/// Set the lsu count
#[cfg(not(armv6m))]
#[inline]
pub fn set_lsu_count(&mut self, count: u8) {
    unsafe { self.lsucnt.write(count as u32) }
}
```

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

### Demonstrate Peripherals::take() returning None on subsequent calls in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/index

Illustrates the singleton nature of peripherals by showing that `Peripherals::take().unwrap()` will panic on the second call because the first call consumes the unique instance, returning `None`.

```rust
let ok = Peripherals::take().unwrap();
// This next line would panic because Peripherals::take() returns None
// let panics = Peripherals::take().unwrap();
```

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

### Get DWT Exception Count (Rust)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.DWT_search=std%3A%3Avec

Retrieves the total cycles spent in exception processing.

```rust
pub fn exception_count() -> u8
```

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

### Get SysTick Current Value

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/syst.rs_search=std%3A%3Avec

Reads the current value of the SysTick counter. This value decrements from the reload value down to zero.

```rust
/// Gets current value
#[inline]
pub fn get_current() -> u32 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).cvr.read() }
}

```

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

### Generic Type Conversions in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.FPB

Demonstrates various generic trait implementations for type conversions, including `From`, `Into`, `Borrow`, `BorrowMut`, `TryFrom`, and `TryInto`. These traits facilitate flexible data handling and conversions between different types within Rust programs.

```rust
impl<T> Borrow<T> for T where T: ?Sized {
    fn borrow(&self) -> &T {
        // Immutably borrows from an owned value.
    }
}

impl<T> BorrowMut<T> for T where T: ?Sized {
    fn borrow_mut(&mut self) -> &mut T {
        // Mutably borrows from an owned value.
    }
}

impl<T> From<T> for T {
    fn from(t: T) -> T {
        // Returns the argument unchanged.
    }
}

impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U {
        // Calls `U::from(self)`.
    }
}

impl<T, U> TryFrom<U> for T where U: Into<T> {
    type Error = Infallible;

    fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> {
        // Performs the conversion.
    }
}

impl<T, U> TryInto<U> for T where U: TryFrom<T> {
    type Error = <U as TryFrom<T>>::Error;

    fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error> {
        // Performs the conversion.
    }
}
```

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

### Get SysTick Reload Value

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/syst.rs_search=std%3A%3Avec

Reads the reload value configured for the SysTick counter. This value determines the period of the SysTick timer.

```rust
/// Gets reload value
#[inline]
pub fn get_reload() -> u32 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).rvr.read() }
}

```

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

### Cortex-M API Reference

Source: https://docs.rs/cortex-m/latest/cortex_m/all_search=std%3A%3Avec

This section details the various components available in the cortex-m crate, including data structures, enumerations, traits, macros, and functions.

```APIDOC
## Cortex-M API Components

This documentation outlines the available components within the `cortex-m` Rust crate.

### Structs

- `cmse::TestTarget`: Represents a test target in CMSE.
- `delay::Delay`: A delay provider.
- `interrupt::CriticalSection`: Represents a critical section for interrupt management.
- `interrupt::Mutex`: A mutex for critical sections.
- `itm::Aligned`: Aligned data for ITM.
- `peripheral::Peripherals`: The main struct for accessing all peripherals.
- `peripheral::NVIC`: Nested Vectored Interrupt Controller.
- `peripheral::SYST`: System Timer.
- `register::control::Control`: Access to the CONTROL register.
- `register::fpscr::Fpscr`: Floating-Point Status and Control Register.

### Enums

- `cmse::AccessType`: Defines access types for CMSE.
- `peripheral::cpuid::CsselrCacheType`: Cache type for CPUID.
- `peripheral::sau::SauError`: Errors related to the SAU.
- `peripheral::sau::SauRegionAttribute`: Attributes for SAU regions.
- `peripheral::scb::Exception`: System exceptions.
- `peripheral::scb::FpuAccessMode`: FPU access modes.
- `peripheral::scb::SystemHandler`: System handlers.
- `peripheral::syst::SystClkSource`: System timer clock sources.
- `register::control::Fpca`: FPU context access.
- `register::control::Npriv`: Privilege level.
- `register::control::Spsel`: Stack pointer selection.
- `register::faultmask::Faultmask`: Fault mask state.
- `register::fpscr::RMode`: Rounding mode for FPU.
- `register::primask::Primask`: Primask state.

### Traits

- `interrupt::InterruptNumber`: Trait for interrupt numbers.
- `interrupt::Nr`: Trait for interrupt numbers (alternative).
- `prelude::_embedded_hal_PwmPin`: PWM output pin functionality.
- `prelude::_embedded_hal_blocking_delay_DelayMs`: Blocking delay in milliseconds.
- `prelude::_embedded_hal_blocking_delay_DelayUs`: Blocking delay in microseconds.
- `prelude::_embedded_hal_blocking_i2c_Read`: Blocking I2C read.
- `prelude::_embedded_hal_blocking_i2c_Write`: Blocking I2C write.
- `prelude::_embedded_hal_blocking_i2c_WriteRead`: Blocking I2C write-read.
- `prelude::_embedded_hal_blocking_serial_Write`: Blocking serial write.
- `prelude::_embedded_hal_blocking_spi_Transfer`: Blocking SPI transfer.
- `prelude::_embedded_hal_blocking_spi_Write`: Blocking SPI write.
- `prelude::_embedded_hal_digital_OutputPin`: Digital output pin functionality.
- `prelude::_embedded_hal_serial_Read`: Serial read functionality.
- `prelude::_embedded_hal_serial_Write`: Serial write functionality.
- `prelude::_embedded_hal_spi_FullDuplex`: Full-duplex SPI functionality.
- `prelude::_embedded_hal_timer_CountDown`: Count-down timer functionality.

### Macros

- `iprint`: Formatted printing to ITM.
- `iprintln`: Formatted printing with a newline to ITM.
- `singleton`: Macro for creating singleton objects.

### Functions

- `asm::bkpt`: Breakpoint instruction.
- `asm::nop`: No operation instruction.
- `asm::dmb`: Data Memory Barrier.
- `asm::dsb`: Data Synchronization Barrier.
- `asm::isb`: Instruction Synchronization Barrier.
- `asm::wfe`: Wait For Event.
- `asm::wfi`: Wait For Interrupt.
- `interrupt::enable`: Enable interrupts.
- `interrupt::disable`: Disable interrupts.
- `interrupt::free`: Execute a closure in a free (uninterruptible) context.
- `itm::write_aligned`: Write aligned data to ITM.
- `register::basepri::read`: Read the BASEPRI register.
- `register::basepri::write`: Write to the BASEPRI register.
- `register::control::read`: Read the CONTROL register.
- `register::control::write`: Write to the CONTROL register.
- `register::fpscr::read`: Read the FPSCR register.
- `register::fpscr::write`: Write to the FPSCR register.
- `register::msp::read`: Read the Main Stack Pointer.
- `register::psp::read`: Read the Process Stack Pointer.
- `register::primask::read`: Read the PRIMASK register.

```

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

### Rust: Implement bootload from vector table using cortex-m::asm

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.bootload_search=std%3A%3Avec

The `bootload` function reads the initial stack pointer and reset vector from a given vector table address. It then sets up the main stack and jumps to the reset vector. The `vector_table` must point to a valid table containing a stack pointer and reset vector. This function is unsafe due to direct memory manipulation.

```rust
pub unsafe fn bootload(vector_table: *const u32) -> !

```

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

### GET /register/psplim

Source: https://docs.rs/cortex-m/latest/cortex_m/register/psplim/fn.read_search=u32+-%3E+bool

Reads the CPU register for PSPLim. This function provides access to the Program Stack Limit register.

```APIDOC
## GET /register/psplim

### Description
Reads the CPU register for PSPLim. This function provides access to the Program Stack Limit register.

### Method
GET

### Endpoint
/register/psplim

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **psplim** (u32) - The value of the PSPLim register.

#### Response Example
{
  "psplim": 1024
}
```

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

### Cortex-M Macros

Source: https://docs.rs/cortex-m/latest/cortex_m/all_search=

List of available macros in the cortex-m crate.

```APIDOC
## Macros

### iprint
- Description: Prints formatted output to the ITM.

### iprintln
- Description: Prints formatted output with a newline to the ITM.

### singleton
- Description: Macro for creating singletons.
```

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

### Get DWT LSU Count (Rust)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.DWT_search=std%3A%3Avec

Retrieves the additional cycles required to execute load or store instructions.

```rust
pub fn lsu_count() -> u8
```

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

### Clean Cortex-M D-Cache by Slice

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/scb.rs

Cleans the Data Cache (D-Cache) for a given slice of memory. This ensures that all cached modifications within the slice are written back to main memory. It delegates the core logic to `clean_dcache_by_address`, calculating the start address and total size of the slice. Similar to other cleaning operations, alignment of the slice's start address and its size to cache line boundaries is recommended for efficiency and to prevent unintended data cleaning.

```rust
#[inline]
pub fn clean_dcache_by_slice<T>(&mut self, slice: &[T]) {
    self.clean_dcache_by_address(
        slice.as_ptr() as usize,
        slice.len() * core::mem::size_of::<T>(),
    );
}
```

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

### cortex-m Assembly Module

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/index

This section details various assembly instructions available in the cortex-m crate. These instructions offer low-level control over the processor, including debugging, synchronization, and event handling.

```APIDOC
## Module asm

### Description
Miscellaneous assembly instructions for controlling the processor, managing memory, and handling events.

### Functions

#### bkpt

*   **Description**: Puts the processor in Debug state. Debuggers can pick this up as a “breakpoint”.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### bootload

*   **Description**: Initiates the bootload process.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### bootstrap

*   **Description**: Initializes the system bootstrap process.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### bx_ns

*   **Description**: Performs a Branch and Exchange to Non-secure state.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### delay

*   **Description**: Blocks the program for a specified number of CPU cycles.
*   **Parameters**:
    *   `cycles` (usize) - Required - The minimum number of CPU cycles to delay.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### dmb

*   **Description**: Data Memory Barrier. Ensures that memory accesses complete before proceeding.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### dsb

*   **Description**: Data Synchronization Barrier. Ensures that all memory accesses prior to the instruction are completed before subsequent instructions execute.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### isb

*   **Description**: Instruction Synchronization Barrier. Flushes the instruction pipeline and ensures that instructions subsequent to the barrier are fetched and executed correctly.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### nop

*   **Description**: No-operation. A placeholder instruction that does nothing. Useful to prevent delay loops from being optimized away.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### semihosting_syscall

*   **Description**: Executes a semihosting system call.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### sev

*   **Description**: Send Event. Signals an event to other processors or cores.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### tt

*   **Description**: Test Target instruction.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### tta

*   **Description**: Test Target Alternate Domain instruction.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### ttat

*   **Description**: Test Target Alternate Domain Unprivileged instruction.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### ttt

*   **Description**: Test Target Unprivileged instruction.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### udf

*   **Description**: Generate an Undefined Instruction exception.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### wfe

*   **Description**: Wait For Event. Puts the processor into a low-power state until an event is signaled.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

#### wfi

*   **Description**: Wait For Interrupt. Puts the processor into a low-power state until an interrupt occurs.
*   **Method**: N/A (Function call)
*   **Endpoint**: N/A

```

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

### Get DWT Fold Count (Rust)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.DWT_search=std%3A%3Avec

Retrieves the folded instruction count. This counter increments for each instruction that takes zero cycles to execute.

```rust
pub fn fold_count() -> u8
```

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

### Semihosting Syscall

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.semihosting_syscall_search=std%3A%3Avec

Provides semihosting syscalls. This method is used by cortex-m-semihosting to provide semihosting syscalls.

```APIDOC
## semihosting_syscall

### Description
Semihosting syscall. This method is used by cortex-m-semihosting to provide semihosting syscalls.

### Method
Unsafe Function Signature

### Endpoint
cortex_m::asm::semihosting_syscall

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// This is a function signature, not a direct request example.
// Example usage would depend on the cortex-m-semihosting crate.
pub unsafe fn semihosting_syscall(nr: u32, arg: u32) -> u32;
```

### Response
#### Success Response (200)
- **return_value** (u32) - The result of the syscall.

#### Response Example
```json
{
  "return_value": 0 // Example return value
}
```
```

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

### Get DWT Cycle Count (Rust - Modern)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.DWT_search=std%3A%3Avec

Retrieves the current clock cycle count from the DWT. This method follows the C-GETTER convention.

```rust
pub fn cycle_count() -> u32
```

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

### cortex_m::asm::bootload

Source: https://docs.rs/cortex-m/latest/cortex_m/asm/fn.bootload_search=std%3A%3Avec

The `bootload` function initializes the stack pointer and jumps to the reset vector using a provided vector table. It is essential for the initial startup sequence of embedded systems.

```APIDOC
## unsafe fn bootload

### Description
Bootload. Reads the initial stack pointer value and reset vector from the provided vector table address, sets the active stack to the main stack, sets the main stack pointer to the new initial stack pointer, then jumps to the reset vector.

### Method
`unsafe fn`

### Endpoint
`cortex_m::asm::bootload`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
// Example usage (requires a valid vector table pointer)
// let vector_table_ptr: *const u32 = ...;
// unsafe { cortex_m::asm::bootload(vector_table_ptr) };
```

### Response
#### Success Response (200)
This function does not return; it jumps to the reset vector.

#### Response Example
N/A

## §Safety
The provided `vector_table` must point to a valid vector table, with a valid stack pointer as the first word and a valid reset vector as the second word.
```

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

### ICB Pointer Function (Deprecated)

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.ICB

A deprecated function to get a pointer to the ICB register block. Use the associated constant `PTR` instead.

```rust
pub fn ptr() -> *mut RegisterBlock
```

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

### Rust Example: Generic Type Search Pattern

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/nvic/index_search=

Demonstrates a common search pattern in Rust documentation, focusing on generic types and transformations. This pattern is often seen when looking for functions that operate on or return specific types, especially with generics like Option<T>.

```Rust
// Example search patterns:
// std::vec
// u32 -> bool
// Option<T>, (T -> U) -> Option<U>

// Actual code demonstrating such a pattern:
fn transform_option<T, U>(input: Option<T>, transform: impl FnOnce(T) -> U) -> Option<U> {
    input.map(transform)
}

fn main() {
    let value: Option<i32> = Some(5);
    let transformed_value = transform_option(value, |x| x * 2);
    println!("{:?}", transformed_value);

    let no_value: Option<i32> = None;
    let transformed_no_value = transform_option(no_value, |x| x * 2);
    println!("{:?}", transformed_no_value);
}

```

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

### Enable SysTick Counter

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/syst.rs_search=std%3A%3Avec

Starts the SysTick counter. It's recommended to set the reload value and clear the current value before enabling the counter for proper initialization.

```rust
/// Enables counter
///
/// *NOTE* The reference manual indicates that:
///
/// "The SysTick counter reload and current value are undefined at reset, the correct
/// initialization sequence for the SysTick counter is:
///
/// - Program reload value
/// - Clear current value
/// - Program Control and Status register"
///
/// The sequence translates to `self.set_reload(x); self.clear_current(); self.enable_counter()`
#[inline]
pub fn enable_counter(&mut self) {
    unsafe { self.csr.modify(|v| v | SYST_CSR_ENABLE) }
}

```

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

### Ctrl Trait Implementations

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/sau/struct.Ctrl_search=std%3A%3Avec

Documentation for the trait implementations available for the Ctrl struct.

```APIDOC
## Trait Implementations for Ctrl

### `impl<T> BitRange<T> for Ctrl`

#### `fn bit_range(&self, msb: usize, lsb: usize) -> T`
Get a range of bits.

#### `fn set_bit_range(&mut self, msb: usize, lsb: usize, value: T)`
Set a range of bits.

### `impl Clone for Ctrl`

#### `fn clone(&self) -> Ctrl`
Returns a duplicate of the value.

#### `fn clone_from(&mut self, source: &Self)`
Performs copy-assignment from `source`.

### `impl Copy for Ctrl`

### Auto Trait Implementations
* `Freeze`
* `RefUnwindSafe`
* `Send`
* `Sync`
* `Unpin`
* `UnwindSafe`

### Blanket Implementations
* `impl<T> Any for T`
    * `fn type_id(&self) -> TypeId`
* `impl<T> Bit for T`
    * `fn bit(&self, bit: usize) -> bool`
    * `fn set_bit(&mut self, bit: usize, value: bool)`
* `impl<T> Borrow<T> for T`
    * `fn borrow(&self) -> &T`
* `impl<T> BorrowMut<T> for T`
    * `fn borrow_mut(&mut self) -> &mut T`
* `impl<T> CloneToUninit for T` (Nightly-only experimental API)
    * `unsafe fn clone_to_uninit(&self, dest: *mut u8)`
* `impl<T> From<T> for T`
    * `fn from(t: T) -> T`
* `impl<T, U> Into<U> for T`
    * `fn into(self) -> U`
* `impl<T, U> TryFrom<U> for T`
    * `type Error = Infallible`
    * `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`
* `impl<T, U> TryInto<U> for T`
    * `type Error = <U as TryFrom<T>>::Error`
    * `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`
```

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

### Get SysTick Clock Source

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/syst.rs_search=std%3A%3Avec

Retrieves the current clock source for the SysTick timer. This method takes `&mut self` because reading the CSR can clear the wrap flag.

```rust
/// Gets clock source
///
/// *NOTE* This takes `&mut self` because the read operation is side effectful and can clear the
/// bit that indicates that the timer has wrapped (cf. `SYST.has_wrapped`)
#[inline]
pub fn get_clock_source(&mut self) -> SystClkSource {
    // NOTE(unsafe) atomic read with no side effects
    if self.csr.read() & SYST_CSR_CLKSOURCE != 0 {
        SystClkSource::Core
    } else {
        SystClkSource::External
    }
}

```

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

### Creating a Singleton with Macro

Source: https://docs.rs/cortex-m/latest/index

Demonstrates the use of the `singleton!` macro to create a mutable reference to a statically allocated value. This is often used for managing global mutable state in embedded Rust applications.

```rust
use cortex_m::singleton;

struct MyState {
    counter: u32,
}

fn initialize_state() {
    let mut state = singleton!(my_state: MyState = MyState { counter: 0 });
    state.counter += 1;
}

fn main() {
    initialize_state();
    // Accessing the singleton later
    let state = singleton!(my_state: MyState);
    println!("Counter: {}", state.counter);
}
```

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

### FPU Pointer Function in Rust

Source: https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.FPU_search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

A deprecated function to get a pointer to the FPU register block. It is recommended to use the associated constant `PTR` instead.

```rust
pub const fn ptr() -> *const RegisterBlock
```

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

### Cortex-M Macros API

Source: https://docs.rs/cortex-m/latest/cortex_m/all

Documentation for the macros provided by the cortex-m crate, useful for simplified logging and object instantiation.

```APIDOC
## Macros

- **iprint**: Macro for performing inline printing, typically to a debug console.
- **iprintln**: Macro for performing inline printing with a newline, typically to a debug console.
- **singleton**: Macro for creating a singleton instance of a type, ensuring only one instance exists.
```

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

### GET /scb/vect_active

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/scb.rs_search=u32+-%3E+bool

Retrieves the currently active exception number from the SCB. This can be the Thread Mode, a processor core exception, or a device-specific interrupt.

```APIDOC
## GET /scb/vect_active

### Description
Retrieves the currently active exception number from the SCB. This can be the Thread Mode, a processor core exception, or a device-specific interrupt.

### Method
GET

### Endpoint
/scb/vect_active

### Parameters
None

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **VectActive** (enum) - The active exception status. Possible values include:
    - `ThreadMode`
    - `Exception(Exception)` where `Exception` can be one of `NonMaskableInt`, `HardFault`, `MemoryManagement`, `BusFault`, `UsageFault`, `SecureFault`, `SVCall`, `DebugMonitor`, `PendSV`, `SysTick`.
    - `Interrupt { irqn: u8 }` where `irqn` is the device-specific interrupt number.

#### Response Example
```json
{
  "status": "Success",
  "data": {
    "type": "Exception",
    "value": "HardFault"
  }
}
```

#### Error Response (e.g., 500)
- **error** (string) - A message describing the error.

#### Error Response Example
```json
{
  "status": "Error",
  "message": "Failed to read SCB CSR register"
}
```
```

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

### Bootload

Source: https://docs.rs/cortex-m/latest/src/cortex_m/asm.rs

Loads the initial stack pointer and reset vector from a given vector table address and then calls the bootstrap function. This is an unsafe operation.

```APIDOC
## POST /armv8-m/bootload

### Description
Loads initial stack and reset vector from a vector table and starts the bootstrap process.

### Method
POST

### Endpoint
/armv8-m/bootload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vector_table** (*const u32) - Required - Pointer to the base address of the vector table.

### Request Example
{
  "vector_table": "0x10000000"
}

### Response
#### Success Response (200)
This function initiates the bootstrap process and does not return.

#### Response Example
None
```

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

### Safe Wrappers for Cortex-M Instructions (Rust)

Source: https://docs.rs/cortex-m/latest/src/cortex_m/lib.rs_search=u32+-%3E+bool

This snippet illustrates the use of safe wrappers for Cortex-M specific instructions, such as `bkpt` (breakpoint). These wrappers abstract away the direct assembly calls, providing a safer interface for debugging and control flow management within embedded applications.

```Rust
#![no_std]

use cortex_m::asm;

fn main() {
    // Example: Triggering a breakpoint instruction
    // asm::bkpt();

    // Other examples might include memory barriers or synchronization primitives
    // asm::dmb(); // Data Memory Barrier
    // asm::dsb(); // Data Synchronization Barrier
    // asm::isb(); // Instruction Synchronization Barrier
}

```

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

### Rust Control: Get Register Bits

Source: https://docs.rs/cortex-m/latest/cortex_m/register/control/struct.Control_search=

Returns the current contents of the control register as a 32-bit unsigned integer. This allows for reading the register's state.

```rust
pub fn bits(self) -> u32
```

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

### SysTick Get Reload Value

Source: https://docs.rs/cortex-m/latest/src/cortex_m/peripheral/syst.rs_search=u32+-%3E+bool

Reads and returns the reload value that is currently set for the SysTick timer. This is a static method as reading the reload value has no side effects.

```rust
/// Gets reload value
#[inline]
pub fn get_reload() -> u32 {
    // NOTE(unsafe) atomic read with no side effects
    unsafe { (*Self::PTR).rvr.read() }
}
```
Tokens:
Raw