stm32h7xx-hal

The HAL supports several families of the STM32H7 series. When selecting a feature, ensure it matches your hardware revision.

Supported Families

• stm32h743v (Revision V: covers stm32h743, stm32h742, stm32h750)
• stm32h753v
• stm32h747cm7 (covers stm32h747, stm32h757)
• stm32h7b3
• stm32h7b0
• stm32h7a3
• stm32h735 (covers stm32h723, stm32h725, stm32h730, stm32h733, stm32h735)

Hardware Revisions (Revision V vs Revision Y)

For stm32h742, stm32h743, stm32h750, and stm32h753, ST released a Revision V in 2019 which contains breaking hardware changes.

• Revision V: Use the feature gate with the v suffix (e.g., stm32h743v).
• Revision Y (Old): Use the feature gate without the v suffix (e.g., stm32h743).

Limitations

• Dual Core: On dual-core parts (Cortex M7 + Cortex M4), currently only the Cortex M7 core is supported.
• Unsupported: STM32H7R3/7S3 are not directly supported.

To build a custom application using stm32h7xx-hal, follow these steps to set up a new binary crate:

1. Install the target: Ensure the Rust cross-compiler is installed:

   rustup target add thumbv7em-none-eabihf

2. Initialize crate: Run cargo init to create a new binary crate.
3. Configure Cargo: Create a .cargo/config.toml file and set target = "thumbv7em-none-eabihf" to ensure cross-compilation.
4. Linker Script: Copy a memory.x file into your project root. This file is required by the linker to define memory boundaries.
5. Add HAL Dependency: In Cargo.toml, add stm32h7xx-hal and ensure the features array matches your specific chip (e.g., stm32h743v).
6. Implement Code: Copy logic from existing examples (like blinky.rs) into src/main.rs, adjusting for your specific board requirements.

[dependencies.stm32h7xx-hal]
version = "^0"
features = ["stm32h743v"]

The stm32h7xx-hal provides a Hardware Abstraction Layer for STM32H7 microcontrollers, organized into several functional modules. Many modules require specific Cargo features to be enabled.

Setup and Configuration

• Power Configuration
• Reset and Clock Control

Digital IO

• General Purpose Input / Output
• External interrupt controller

Analog IO

• Analog to Digital Converter (ADC)
• Digital to Analog Converter (DAC)

Digital Busses

• Inter Integrated Circuit (I2C)
• Serial Peripheral Interface (SPI)
• Serial Data (USART/UART)
• Serial Audio Interface
• Quad or Octo SPI (Feature: xspi)
• Ethernet (Feature: ethernet)
• USB HS (Feature: usb_hs)
• LCD-TFT Display Controller (Feature: ltdc)
• MIPI DSI (Feature: dsi, STM32H747/757 only)
• CAN and CAN-FD (Feature: can)

External Memory

• Flexible Memory Controller (FMC) (Feature: fmc)
• SD Card (SDMMC) (Feature: sdmmc; use sdmmc-fatfs for FAT16/32 support)

Timing functions

• Pulse Width Modulation (PWM)
• Quadrature Encoder Interface
• Real-Time Clock (Feature: rtc)
• Timers
• Delays

Others

• Direct Memory Access (DMA)
• Cyclic Redundancy Check (CRC) (Feature: crc)
• Random Number Generator (Implements rand_core::RngCore under feature rand)
• Embedded Flash Memory
• System Window Watchdog
• Independent Watchdog

The DoubleBufferedStream trait extends Stream to support advanced DMA features like double buffering, circular buffering, and memory/peripheral increments.

Safety Warnings:

• set_peripheral_address: The provided address must be a valid peripheral hardware address and must not be accessed by the application once set.
• set_memory_address: The provided buffer must not be accessed by the application once provided; the DMA peripheral logically owns the memory.
• set_memory_size / set_peripheral_size: The size must match the alignment of the buffer used in the transfer.

Key Features:

• Buffering: Enable/disable double buffering (set_double_buffer), circular buffering (set_circular_buffer), and half-transfer interrupts (set_half_transfer_interrupt_enable).
• Addressing: Set memory/peripheral addresses and increments (set_memory_increment, set_peripheral_increment).
• Transfer Control: Set the number of transfers (set_number_of_transfers) and the direction (set_direction).
• Buffer Tracking: Use get_current_buffer and get_inactive_buffer to manage buffers in double-buffer mode.

pub trait DoubleBufferedStream: Stream + Sealed {
    unsafe fn set_peripheral_address(&mut self, value: usize);
    unsafe fn set_memory_address(&mut self, buffer: CurrentBuffer, value: usize);
    fn set_half_transfer_interrupt_enable(&mut self, transfer_complete_interrupt: bool);
    fn clear_half_transfer_interrupt(&mut self);
    fn get_half_transfer_flag() -> bool;
    fn get_memory_address(&self, buffer: CurrentBuffer) -> usize;
    fn set_memory_increment(&mut self, increment: bool);
    fn set_peripheral_increment(&mut self, increment: bool);
    fn set_number_of_transfers(&mut self, value: u16);
    fn get_number_of_transfers() -> u16;
    unsafe fn set_memory_size(&mut self, size: u8);
    unsafe fn set_peripheral_size(&mut self, size: u8);
    fn set_direction(&mut self, direction: DmaDirection);
    fn set_circular_buffer(&mut self, circular_buffer: bool);
    fn set_double_buffer(&mut self, double_buffer: bool);
    fn get_current_buffer() -> CurrentBuffer;
    fn get_inactive_buffer() -> Option<CurrentBuffer>;
}

The Stream trait is the base abstraction for all DMA streams. It provides methods for basic configuration, interrupt management, and stream control (enabling/disabling).

Key capabilities include:

• Configuration: Apply a stream-specific Config using apply_config.
• Interrupt Management: Clear interrupts (clear_interrupts, clear_transfer_complete_flag, etc.), enable/disable interrupts (enable_interrupts, disable_interrupts), and check status (get_transfer_complete_flag, get_interrupts_enable).
• Control: Enable the stream via enable (unsafe) and disable it via disable (which also clears interrupt flags if the stream is active).
• Priority & Request: Set the DMA request line via set_request_line and priority via set_priority.

pub trait Stream: Sealed {
    type Config;
    type Interrupts: Copy + Debug;

    fn apply_config(&mut self, config: Self::Config);
    fn clear_interrupts(&mut self);
    fn clear_transfer_complete_flag(&mut self);
    fn clear_transfer_complete_interrupt(&mut self);
    fn clear_transfer_error_interrupt(&mut self);
    fn get_transfer_complete_flag() -> bool;
    unsafe fn enable(&mut self);
    fn is_enabled() -> bool;
    fn disable(&mut self);
    fn set_request_line(&mut self, request_line: u8);
    fn set_priority(&mut self, priority: config::Priority);
    fn disable_interrupts(&mut self);
    fn enable_interrupts(&mut self, interrupts: Self::Interrupts);
    fn get_interrupts_enable() -> Self::Interrupts;
    fn set_transfer_complete_interrupt_enable(&mut self, transfer_complete_interrupt: bool);
    fn set_transfer_error_interrupt_enable(&mut self, transfer_error_interrupt: bool);
}

The MasterStream trait is used for Master DMA (MDMA) operations. It provides fine-grained control over source/destination addresses, burst sizes, and trigger modes.

Safety Warnings:

• set_source_address / set_destination_address: Must have the same alignment as configured for the transfer.
• set_source_burst_size / set_destination_burst_size: Must be less than the transfer length.
• set_transfer_length / set_block_bytes: Must be a multiple of both the source and destination size.
• set_source_offset / set_destination_offset: If the source/destination is TCM/AHB and the burst is not a single transfer, the address must be aligned with the offset.

Key Features:

• Triggering: Set software/hardware triggers (set_software_triggered, set_trigger_selection) and trigger modes (set_trigger_mode).
• Transfer Details: Manage block bytes (set_block_bytes, get_block_bytes) and source/destination sizes and offsets.
• Interrupts: Manage buffer transfer complete (tcie), block transfer complete (btie), and block repeat transfer complete (brtie) interrupts.

pub trait MasterStream: Stream + Sealed {
    unsafe fn set_source_address(&mut self, value: usize);
    unsafe fn set_destination_address(&mut self, value: usize);
    unsafe fn set_source_burst_size(&mut self, value: u8);
    unsafe fn set_destination_burst_size(&mut self, value: u8);
    fn get_source_burst_size() -> u8;
    fn get_destination_burst_size() -> u8;
    fn set_software_triggered(&mut self, sw_triggered: bool);
    fn set_trigger_selection(&mut self, trigger: u8);
    fn set_trigger_mode(&mut self, trigger_mode: mdma::MdmaTrigger);
    unsafe fn set_transfer_length(&mut self, value: u8);
    fn get_transfer_length() -> u8;
    unsafe fn set_block_bytes(&mut self, value: u32);
    fn get_block_bytes() -> u32;
    fn source_destination_size_offset(
        config: &Self::Config,
        peripheral_size: mdma::MdmaSize,
        memory_size: mdma::MdmaSize,
        direction: DmaDirection,
    ) -> ((mdma::MdmaSize, mdma::MdmaSize), (mdma::MdmaSize, mdma::MdmaSize));
    unsafe fn set_source_size(&mut self, size: mdma::MdmaSize);
    fn get_source_size() -> mdma::MdmaSize;
    unsafe fn set_source_offset(&mut self, offset: mdma::MdmaSize);
    unsafe fn set_destination_size(&mut self, size: mdma::MdmaSize);
    fn get_destination_size() -> mdma::MdmaSize;
    unsafe fn set_destination_offset(&mut self, offset: mdma::MdmaSize);
    fn set_buffer_transfer_complete_interrupt_enable(&mut self, buffer_transfer_complete_interrupt: bool);
    fn clear_buffer_transfer_complete_interrupt(&mut self);
    fn get_buffer_transfer_complete_flag() -> bool;
    fn set_block_transfer_complete_interrupt_enable(&mut self, transfer_complete_interrupt: bool);
    fn clear_block_transfer_complete_interrupt(&mut self);
    fn get_block_transfer_complete_flag() -> bool;
    fn set_block_repeat_transfer_complete_interrupt_enable(&mut self, transfer_complete_interrupt: bool);
    fn clear_block_repeat_transfer_complete_interrupt(&mut self);
    fn get_block_repeat_transfer_complete_flag() -> bool;
}