Crate esp_hal_procmacros

source ·
Expand description

§Overview

Procedural macros for use with the esp-hal family of HAL packages. In general, you should not need to depend on this package directly, as the relevant procmacros are re-exported by the various HAL packages.

Provides macros for:

  • Placing statics and functions into RAM
  • Marking interrupt handlers
  • Automatically creating an embassy executor instance and spawning the defined entry point

These macros offer developers a convenient way to control memory placement and define interrupt handlers in their embedded applications, allowing for optimized memory usage and precise handling of hardware interrupts.

Key Components:

  • interrupt - Attribute macro for marking interrupt handlers. Interrupt handlers are used to handle specific hardware interrupts generated by peripherals.
    The macro allows users to specify the interrupt name explicitly or use the function name to match the interrupt.
  • main - Creates a new `executor`` instance and declares an application entry point spawning the corresponding function body as an async task.
  • ram - Attribute macro for placing statics and functions into specific memory sections, such as SRAM or RTC RAM (slow or fast) with different initialization options. Supported options are:
    • rtc_fast - Use RTC fast RAM
    • rtc_slow - Use RTC slow RAM (not all targets support slow RTC RAM)
    • uninitialized - Skip initialization of the memory
    • zeroed - Initialize the memory to zero

§Examples

§main macro

Requires the embassy feature to be enabled.

#[main]
async fn main(spawner: Spawner) {
    // Your application's entry point
}
§ram macro

Requires the ram feature to be enabled.

#[ram(rtc_fast)]
static mut SOME_INITED_DATA: [u8; 2] = [0xaa, 0xbb];

#[ram(rtc_fast, uninitialized)]
static mut SOME_UNINITED_DATA: [u8; 2] = [0; 2];

#[ram(rtc_fast, zeroed)]
static mut SOME_ZEROED_DATA: [u8; 8] = [0; 8];

§Feature Flags

  • embassy — Provide a #[main] procmacro to mark the entry point for Embassy applications.
  • enum-dispatch — Provide enum dispatch helpers.
  • interrupt — Provide an #[interrupt] procmacro for defining interrupt service routines.
  • ram — Provide a #[ram] procmacro to place functions in RAM instead of flash.
  • rtc_slow — Indicates the target devices has RTC slow memory available.

§Low-power Core Feature Flags

  • has-lp-core — Indicate that the SoC contains an LP core.
  • has-ulp-core — Indicate that the SoC contains a ULP core.
  • is-lp-core — Provide an #[entry] macro for running applications on the ESP32-C6’s LP core.
  • is-ulp-core — Provide an #[entry] macro for running applications on the ESP32-S2/S3’s ULP core.

Macros§

Attribute Macros§

  • entry
  • handler
    Mark a function as an interrupt handler.
  • main
    Creates a new executor instance and declares an application entry point spawning the corresponding function body as an async task.
  • ram
    This attribute allows placing statics and functions into ram.