DEV Community: Jens

Embassy 下使用温湿度传感器

Jens — Tue, 16 Apr 2024 15:02:05 +0000

本文希望通过 Omar Hiari: Embedded Rust & Embassy: I2C Temperature Sensing with BMP180, 在 Blue Pill 上实现 DHT20 温湿度传感器的控制程序.

1. 接线方法

我们查看 Blue Pill 的接口图发现, 支持 I2C的接口为 (PB6, PB7), (PB11, PB10)

使用 DHT20 温湿度检测器, 使用 I2C 通讯协议, 与 Blue Pill 的接线口分别为如下

VDD -> VDD
SDA -> PB7
GND -> GND
SCL -> PB6 ## 2.代码实现我们暂时仅实现获得温湿度数据并打印的功能, 这只需要一个任务, 我们将它放在主任务中.

我们先获得外围设备结构体

// initialising peripherals
let p = embassy_stm32::init(Default::default());

在获得结构体后, 我们创建 I2c 句柄的实例, 它封装了 I2C 的接收发送过程.

// create an I2C handle
let i2c = i2c::I2c::new(
    p.I2C1,             // periphral: an I2C peripheral
    p.PB6,              // scl: a GPIO pin
    p.PB7,              // sda: a GPIO pin
    I2cIrqs,            // irq: handle to an interrut(
    NoDma,              // tx_dma: an instance to a DMA channel
    NoDma,              // rx_dma: an instance to a DMA channel
    time::hz(100_000),  // frequency
    Default::default(), // config
);

我们现在为 DHT20 编写驱动程序, 通过调用 i2c::I2c 中的 blocking_read 和 blocking_write.
我们将一个 DHT20 传感器抽象为一个设备, 因为不可能有两个设备在同一个 I2C Master-Slave 之间传递信息, 我们通过移动语义转移创建的 i2c 所有权, 使得它 DHT20 设备被创建后, 这个设备 "拥有" 这个 I2C 通道.

为了保证通用性, 我们使用 Generics, 这样能够满足不同的 i2c 实例, 包括不同引脚, 是否使用 DMA 等不同配置, 而不限于我们创建的这个 i2c 的配置. 因为 I2c 中保存了多个外围设备的引用, Rust 为保证所有引用都有效, 我们需要明确申明每个引用的 lifetime. 这里, 我们表明 "i2c同其内部的引用能够 outlive 这个 dht20 设备或一样时间一样长".

pub struct Dht20<'d, T, TXDMA = NoDma, RXDMA = NoDma>
where
    T: i2c::Instance,
{
    i2c: i2c::I2c<'d, T, TXDMA, RXDMA>,
}

impl<'d, T, TXDMA, RXDMA> Dht20<'d, T, TXDMA, RXDMA>
where
    T: i2c::Instance,
{
    pub fn new(i2c: i2c::I2c<'d, T, TXDMA, RXDMA>) -> Self {
        Self { i2c }
    }
}

我们根据 DHT20 设备文档, 完成以下开发
初始化设备

impl<'d, T, TXDMA, RXDMA> Dht20<'d, T, TXDMA, RXDMA>
where
    T: i2c::Instance,
{
    pub async fn init(&mut self) -> Option<()> {
        // wait for >= 100 ms
        Timer::after(Duration::from_millis(100)).await;

        // send initialisation command
        let mut send_buffer: [u8; 3] = [0xE1, 0x08, 0x00];

        while let Err(err) = self.i2c.blocking_write(DHT20_ADDR, &mut send_buffer) {
            error!("send error: {}", err);
        }

        Timer::after(Duration::from_millis(100)).await;

        Some(())
    }
}

读取温湿度值

impl<'d, T, TXDMA, RXDMA> Dht20<'d, T, TXDMA, RXDMA>
where
    T: i2c::Instance,
{
    pub async fn read(&mut self) -> Option<(f32, f32)> {
        // the "messure" command
        let mut send_buffer: [u8; 3] = [0xAC, 0x33, 0x00];
        if let Err(err) = self.i2c.blocking_write(DHT20_ADDR, &mut send_buffer) {
            error!("An error occoured when sending command: {}", err);
            self.reset();
            return None;
        }

        // wait for the messurement to finish
        Timer::after(Duration::from_millis(80)).await;

        // read the result
        let mut read_buffer: [u8; 6] = [0; 6];
        if let Err(err) = self.i2c.blocking_read(DHT20_ADDR, &mut read_buffer) {
            error!("An error when reading result: {}", err);
            return None;
        }
        Self::valid_resault(&read_buffer).unwrap();

        Some((
            Self::parse_humidity(&read_buffer),
            Self::parse_temperature(&read_buffer),
        ))
    }
}

其中有转换温度和湿度数值的辅助函数和判断结果是否有效的检查函数

impl<'d, T, TXDMA, RXDMA> Dht20<'d, T, TXDMA, RXDMA>
where
    T: i2c::Instance,
{
    fn valid_resault(buffer: &[u8]) -> Option<()> {
        assert!(buffer.len() >= 1);
        if buffer[0] & 0x68 == 0x08 {
            Some(())
        } else {
            None
        }
    }

    fn parse_humidity(buffer: &[u8]) -> f32 {
        assert!(buffer.len() == 6);
        let mut hum = buffer[1] as u32;
        hum = (hum << 8) | buffer[2] as u32;
        hum = (hum << 8) | buffer[3] as u32;
        hum >>= 4;
        let hum = hum as f32;
        (hum / (1 << 20) as f32) * 100f32
    }

    fn parse_temperature(buffer: &[u8]) -> f32 {
        assert!(buffer.len() == 6);
        let mut temp: u32 = (buffer[3] & 0x0f) as u32;
        temp = (temp << 8) | (buffer[4] as u32);
        temp = (temp << 8) | buffer[5] as u32;
        let temp = temp as f32;
        (temp / ((1 << 20) as f32)) * 200f32 - 50f32
    }
}

在主任务中我们可以创建这个设备的句柄并且使用它

let mut sensor = Dht20::new(i2c);
if None == sensor.init().await {
    error!("Initialisation Failed")
}
loop {
    if let Some((hum, temp)) = sensor.read().await {
        info!("Humidity: {}, Temperature: {}", hum, temp);
    }
    Timer::after(Duration::from_millis(500)).await;
}

3.演示

视频链接(屏幕录制)

Under the Hook - The Cortex Runtime

Jens — Tue, 16 Apr 2024 14:44:57 +0000

Refer to the cortex-m-rt documentation and its source code for more information.

1. Memory Layout

To understand more about the memory layout on ARM Cortex-M devices, let's look at the link.x.in and memory.x file.

1.1 Linker Script

according to the developer notes in the linker.x.in file, we make a few clarifications

Naming Conventions of Linker Symbols

We need to clarify here, that,

symbols with the _ (single underscore) prefix are semi-public, in the way that:
- users can ONLY override them in the linker script
- users are NOT allowed to reference them in rust code as external symbols
symbols with the __ (double underscore) prefix are private, and
- users should NOT in any way use or modify it

Weak Aliasing at the Linker Script Level

Symbols using PROVIDE are "weak aliases at the linker level", so that "users can override any of these aliases by defining the corresponding symbol themselves" .

EXTERN forces the linker to keep a symbol in the final binary (even if it is not needed)
PROVIDE provides default values that can be overridden by a user linker script For example, the each exception vectors can be overridden with use defined exception! macros

EXTERN(__EXCEPTIONS); /* depends on all the these PROVIDED symbols */

EXTERN(DefaultHandler);

PROVIDE(NonMaskableInt = DefaultHandler);
EXTERN(HardFaultTrampoline);
PROVIDE(MemoryManagement = DefaultHandler);
PROVIDE(BusFault = DefaultHandler);
PROVIDE(UsageFault = DefaultHandler);
PROVIDE(SecureFault = DefaultHandler);
PROVIDE(SVCall = DefaultHandler);
PROVIDE(DebugMonitor = DefaultHandler);
PROVIDE(PendSV = DefaultHandler);
PROVIDE(SysTick = DefaultHandler);

PROVIDE(DefaultHandler = DefaultHandler_);
PROVIDE(HardFault = HardFault_);

Virtual and Load Memory Addresses

The location counter ALWAYS tracks VMA, and
To use LMA, use LOADADDR(...)

Code Section

The .text section only needs to be stored in the FLASH memory because it is only a sequence of read-only executable code.

.text {
    *(.text)
} > FLASH

Since the .text section resides in the FLASH memory, there's no need of a write permission, we do not need to do anything special when booting.

Initialised Data Section

The .data section (for initialised static data). It should be read from the FLASH memory (Read Only) into the RAM (Read/Write). The loader needs to know its compile-time initialised value and its RAM location, so that when loading the data, it will copy it directly from FLASH to RAM.

.data {
    *(.data)
} > RAM AT> FLASH

Here is how the .data section is initialised
The .data section needs to have a copy of initialised values of a static variable stored in FLASH, but it is mutable, so we need to copy it into our memory.
Note that r0 = __sdata and r1 = __edata are assigned as the VMA value (in RAM) of the variable, while r2 = __sidata is the LMA value (in FLASH) of the variable.

3:
    ldr r0, =__sdata
    ldr r1, =__edata
    ldr r2, =__sidata
4:
    cmp r1, r0
    beq 5f
    ldm r2!, {{r3}}
    stm r0!, {{r3}}
    b 4b
5:

Uninitialised Data Section

The .bss section contains all uninitialised static data, it needs not to be stored in the FLASH because the loader only needs to know its address in RAM, such that when loading the address, the loader will assign it the default value.

.bss {
    *(.bss)
} > RAM

Here is how the .bss section is initialised
As is introduced above, .bss saves the uninitialised static variables, it only records its VMA (i.e. the destination address in RAM), and is initialised with zeros, here's the code

1:
    ldr r0, =__sbss
    ldr r1, =__ebss
    movs r2, #0
2:
    cmp r1, r0
    beq 3f
    stm r0!, {{r2}}
    b 2b
3:

Customisable Layout

The user is allowed to customise the memory layout inside the memory.x

device memory
- i.e. the MEMORY section
start of the stack
- It is places at the end of RAM by default (if omitted)
- It grows downwards
start of the code (.text) section
- It is placed at the beginning of FLASH by default (if omitted) Here is an example of such file

/* Linker script for the STM32F303VCT6 */
MEMORY
{
    FLASH : ORIGIN = 0x08000000, LENGTH = 256K

    /* .bss, .data and the heap go in this region */
    RAM : ORIGIN = 0x20000000, LENGTH = 40K

    /* Core coupled (faster) RAM dedicated to hold the stack */
    CCRAM : ORIGIN = 0x10000000, LENGTH = 8K
}

_stack_start = ORIGIN(CCRAM) + LENGTH(CCRAM);

2. The Booting Process

The overall layout can be found in link.x.in

2.1 Initialising the Stack Pointer

We use the _stack_start symbol in the assembly code to load it into out stack pointer

ldr r0, =_stack_start
msr msp, r0

Exception and Interrupt Handling

An overview of ARM Cortex-M exception handling can be found in Chris Coleman: A Practical guide to ARM Cortex-M Exception Handling. Most explanations related to the exception/interrupts and their handling mechanisms are __borrowed_ from this post.

[!info] Exception and Interrupt in ARM
in the ARM documentation, “interrupt” is used to describe a type of “exception”

Vector Table

A vector table stores the address of the handler routines for its corresponding exceptions/interrupts.

The in-memory layout (FLASH memory) of the vector table is as follows.

/* ## Sections in FLASH */
/* ### Vector table */
.vector_table ORIGIN(FLASH) :
{
  __vector_table = .;
  /* Initial Stack Pointer (SP) value.
   * We mask the bottom three bits to force 8-byte alignment.
   * Despite having an assert for this later, it's possible that a separate
   * linker script could override _stack_start after the assert is checked.
   */
  LONG(_stack_start & 0xFFFFFFF8);
  /* Reset vector */
  KEEP(*(.vector_table.reset_vector)); /* this is the `__RESET_VECTOR` symbol */
  /* Exceptions */
  __exceptions = .; /* start of exceptions */
  KEEP(*(.vector_table.exceptions)); /* this is the `__EXCEPTIONS` symbol */
  __eexceptions = .; /* end of exceptions */
  /* Device specific interrupts */
  KEEP(*(.vector_table.interrupts)); /* this is the `__INTERRUPTS` symbol */
} > FLASH

In rust code, each vector is represented by the Vector struct. It is a Union type, can either be a handler pointer or reserved (as in reserved, or not used, by the ARM architecture)

#[repr(C)]
pub union Vector {
    handler: unsafe extern "C" fn(),
    reserved: usize,
}

[!Info] Initial Stack Pointer
the first entry of the index table holds the reset (initial) value of the stack pointer (8-bit aligned).
We can find it in the link.x.in file, where it uses LONG(_stack_start & 0xFFFFFFF8) at the start of the .vector_table section

[!info] The Reset Exception
The Reset routine is executed when a chip resets, it is places at the second entry of the vector table.

Activation of Vector Tables

The address of the memory-mapped register VTOR (Vector Table Offset Register) is 0xe000ed08.

To set its value, we simply write to the address of our vector table (provided by the linker symbol__vector_table) to the corresponding VTOR address.

ldr r0, = 0xe000ed08
ldr r1, =__vector_table
str r1, [r0]

Built-in Exceptions

[!info] SCS: System Control Space

Exception Handlers

For more information, please refer to the Exception Macro Documentation

Exception handlers can ONLY be called by hardware.

Exception handlers are divided into four categories, namely, the DefaultHandler, the HardFault handler, the NonMaskableInt-errupt exception handler , and Other exception handler.

#[derive(Debug, PartialEq)]
enum Exception {
    DefaultHandler,
    HardFault(HardFaultArgs),
    NonMaskableInt,
    Other,
}

The HardFault exception is the catch all exception for assorted system failures
- such as divide-by-zero exception, bad memory accesses etc.
- Finer granularity fault handlers: MemManage, BusFault etc.
- Its arguments are passed as macro arguments
The NonMaskableInt-errrupt exception is interrupt that cannot be disabled by setting PRIMASK or BASEPRIO.
- Besides the Reset exception, it has the highest priority of all other exceptions
- It is NOT generally safe to define handlers for non-maskable interrupt since it may break critical sections
- Its implementation should guarantee that: it does not access any data that is
  - protected by a critical section, and
  - shared with other interrupts that may be preempted by the NMI handler
Other exceptions are
- MemoryManagement
- BusFault
- UsageFault
- SecureFault
- SVCall: invoked when making a supervisor call (svc)
- DebugMonitor
- PendSV: system-level interrupts triggered by software
  - Typically used by a RTOS to manage when the scheduler runs and when context switches take place.
- SysTick: system-level interrupts triggered by software
  - Typically used by a RTOS to manage when the scheduler runs and when context switches take place.

The parsing code makes sure that they are checked

let exn = match &*ident_s {
    "DefaultHandler" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::DefaultHandler
    }
    "HardFault" => Exception::HardFault(parse_macro_input!(args)),
    "NonMaskableInt" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::NonMaskableInt
    }
    // NOTE that at this point we don't check if the exception is available on the target (e.g.
    // MemoryManagement is not available on Cortex-M0)
    "MemoryManagement" | "BusFault" | "UsageFault" | "SecureFault" | "SVCall"
    | "DebugMonitor" | "PendSV" | "SysTick" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::Other
    }
    _ => {
        return parse::Error::new(ident.span(), "This is not a valid exception name")
            .to_compile_error()
            .into();
    }
};

Exception Vector Table

To construct a vector table, we declare a slice with 14 entries of such Vectors, and place it in the .vector_table.exceptions section, which is defined in the linker script.

The entries to the exception vector tables are stored in__EXCEPTIONS (apart from the two above-mentioned entries)

#[cfg_attr(cortex_m, link_section = ".vector_table.exceptions")]
#[no_mangle]
pub static __EXCEPTIONS: [Vector; 14] = [
    // Exception 2: Non Maskable Interrupt.
    Vector {
        handler: NonMaskableInt,
    },
    // Exception 3: Hard Fault Interrupt.
    Vector { handler: HardFault },
    // Exception 4: Memory Management Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: MemoryManagement,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 5: Bus Fault Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector { handler: BusFault },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 6: Usage Fault Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: UsageFault,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 7: Secure Fault Interrupt [only on Armv8-M].
    #[cfg(armv8m)]
    Vector {
        handler: SecureFault,
    },
    #[cfg(not(armv8m))]
    Vector { reserved: 0 },
    // 8-10: Reserved
    Vector { reserved: 0 },
    Vector { reserved: 0 },
    Vector { reserved: 0 },
    // Exception 11: SV Call Interrupt.
    Vector { handler: SVCall },
    // Exception 12: Debug Monitor Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: DebugMonitor,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // 13: Reserved
    Vector { reserved: 0 },
    // Exception 14: Pend SV Interrupt [not on Cortex-M0 variants].
    Vector { handler: PendSV },
    // Exception 15: System Tick Interrupt.
    Vector { handler: SysTick },
];

These handler symbols are by default the DefaultHandler, as declared in the linker script

PROVIDE(NonMaskableInt = DefaultHandler);
PROVIDE(MemoryManagement = DefaultHandler);
PROVIDE(BusFault = DefaultHandler);
PROVIDE(UsageFault = DefaultHandler);
PROVIDE(SecureFault = DefaultHandler);
PROVIDE(SVCall = DefaultHandler);
PROVIDE(DebugMonitor = DefaultHandler);
PROVIDE(PendSV = DefaultHandler);
PROVIDE(SysTick = DefaultHandler);

These are their signatures in rust

extern "C" {
    fn Reset() -> !;
    fn NonMaskableInt();
    fn HardFault();
    #[cfg(not(armv6m))]
    fn MemoryManagement();
    #[cfg(not(armv6m))]
    fn BusFault();
    #[cfg(not(armv6m))]
    fn UsageFault();
    #[cfg(armv8m)]
    fn SecureFault();
    fn SVCall();
    #[cfg(not(armv6m))]
    fn DebugMonitor();
    fn PendSV();
    fn SysTick();
}

External Interrupts

[!info] NVIC: Nested Vectored Interrupt Controller
All external interrupts are configured via the NCIV peripheral

External Interrupt Handlers

For more information, please refer to the Interrupt Macro Documentation

It is allowed to use static variables inside a interrupt handler. Every static variables are shared across each invocation of its handler.
It is achieved by converting static mut into mut &, and passing it as an argument to the interrupt handler (Its signature is extended to incorporate these extra arguments, and the original declarations are removed from the function).

We can use a code snipped of the interrupt macro to explain the process.

Firstly, we extract every static mut declaration in the block statements of the function

pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    let (statics, stmts) = match extract_static_muts(f.block.stmts.iter().cloned()) {
        Err(e) => return e.to_compile_error().into(),
        Ok(x) => x,
    };
    //...
}

/// Extracts `static mut` vars from the beginning of the given statements
fn extract_static_muts(
    stmts: impl IntoIterator<Item = Stmt>,
) -> Result<(Vec<ItemStatic>, Vec<Stmt>), parse::Error> {
    let mut istmts = stmts.into_iter();

    let mut seen = HashSet::new();
    let mut statics = vec![];
    let mut stmts = vec![];
    for stmt in istmts.by_ref() {
        match stmt {
            Stmt::Item(Item::Static(var)) => match var.mutability {
                syn::StaticMutability::Mut(_) => {
                    if seen.contains(&var.ident) {
                        return Err(parse::Error::new(
                            var.ident.span(),
                            format!("the name `{}` is defined multiple times", var.ident),
                        ));
                    }

                    seen.insert(var.ident.clone());
                    statics.push(var);
                }
                _ => stmts.push(Stmt::Item(Item::Static(var))),
            },
            _ => {
                stmts.push(stmt);
                break;
            }
        }
    }

    stmts.extend(istmts);

    Ok((statics, stmts))
}

Then we can push these static mut variables to the input argument list of the function. Note that the input field of a function signature is of type FnArg. It is either a receiver, i.e. all kinds of self, or a typed argument.

/// An argument in a function signature: the `n: usize` in `fn f(n: usize)`.
pub enum FnArg {
    /// The `self` argument of an associated method.
    Receiver(Receiver),
    /// A function argument accepted by pattern and type.
    Typed(PatType),
}

pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    f.sig.inputs.extend(statics.iter().map(|statik| {
        let ident = &statik.ident;
        let ty = &statik.ty;
        let attrs = &statik.attrs;
        syn::parse::<FnArg>(quote!(#[allow(non_snake_case)] #(#attrs)* #ident: &mut #ty).into())
            .unwrap()
    }));
    //...
}

Now, we can construct a wrapper function {interrupt-name}_trampoline as the corresponding interrupt handler by exporting it as {interupt-name}. The wrapper handler calls our user-defined interrupt handler, which is now called __cortex_m_rt_{interrupt-name}. The static mut resources are passed as arguments to our user-defined handler.

The arguments are constructed in a block which evaluates to the &mut value

pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    let resource_args = statics
        .iter()
        .map(|statik| {
            let (ref cfgs, ref attrs) = extract_cfgs(statik.attrs.clone());
            let ident = &statik.ident;
            let ty = &statik.ty;
            let expr = &statik.expr;
            quote! {
                #(#cfgs)*
                {
                    #(#attrs)*
                    static mut #ident: #ty = #expr;
                    &mut #ident
                }
            }
        })
        .collect::<Vec<_>>();

    // ...
}

The final layout of the code generated

pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    quote!(
        #(#cfgs)*
        #(#attrs)*
        #[doc(hidden)]
        #[export_name = #ident_s]
        pub unsafe extern "C" fn #tramp_ident() {
            #ident(
                #(#resource_args),*
            )
        }

        #f
    )
    .into()
    // end of function
}

External Interrupt Vector Table

It is initialised all interrupt handlers to the DefaultHandler declared in src/lib.rs.

#[cfg(all(any(not(feature = "device"), test), not(armv6m)))]
#[cfg_attr(cortex_m, link_section = ".vector_table.interrupts")]
#[no_mangle]
pub static __INTERRUPTS: [unsafe extern "C" fn(); 240] = [{
    extern "C" {
        fn DefaultHandler();
    }

    DefaultHandler
}; 240];

Default Handlers

The library provided default handler is simply an infinite loop

#[no_mangle]
pub unsafe extern "C" fn DefaultHandler_() -> ! {
    #[allow(clippy::empty_loop)]
    loop {}
}

But users can easily override it by providing their own DefaultHandler definitions, since PROVIDE is weak aliasing

PROVIDE(DefaultHandler = DefaultHandler_);

The default handler for HardFault is also an infinite loop

#[cfg_attr(cortex_m, link_section = ".HardFault.default")]
#[no_mangle]
pub unsafe extern "C" fn HardFault_() -> ! {
    #[allow(clippy::empty_loop)]
    loop {}
}

对 RTIC 框架的探索

Jens — Fri, 12 Apr 2024 15:33:07 +0000

本文尝试通过 The RTIC Book, Tjäder 2021: A Zero-Cost Abstraction for Memory Safe Concurrency, Eriksson et al. 2013: Real-Time For the Masses, Step 1: Programming API and Static Priority SRP Kernel Primitives 以及RTIC 源码, 对 RTIC 框架的原理和实现进行简单的解释与分析.

1. RTIC 简介

RTIC (Real-time Interrupt-driven Concurrency) "实时中断驱动并发框架" 旨在使用硬件支持的优先级中断 (特别是 ARM 中的 NVIC 机制, 允许低优先级 ISR 被高优先级 ISR 抢占) 以及 Rust 异步执行器来安全实现 zero-cost 并行抽象, 我们可以把它理解成一个 "调度器".

RTIC 使用了基于优先级的临界区(Priority-based Critical Sections) 保证了高效的无竞争内存共享 (Data-race-free Memory Sharing), 并在编译时能够保证运行期间无死锁 (Deadlock-free Execution)

RTIC 还能够保证所有任务都能够在一个栈中运行.

2. SRP 规则

参考 Eriksson et al. 2013
SRP (Stack Resource Policy) 是一个使不同优先级能够共享同一个执行栈的资源分配规则, 是 Priority Ceiling Protocol (PCP) 的改进方法. RTIC 使用该方法实现对共享资源的分配和申请这些资源的作业调度.

作业 (Job)
- 将作业(Job, $J$) 定义: 为一个有限待执行指令序列
- 作业 "抢占性" (preemptive level) $π\pi$ 定义为: $π(J1)>π(J2)J_{1}, J_{2}: preempts(J_{1}, J_{2}) \iff \pi(J_{1}) \gt \pi(J_{2})$
资源 (Resource, $R$)
- 将所有 有可能 访问资源 $R$ 的任务集合定义为: $L(R)$
- 将资源$R$的 "当前最大访问优先级" (current ceiling) $⌈R⌉\lceil R \rceil$ 定义为: 所有可能访问资源 R 工作(Job) 优先级的最大值 $⌈R⌉:=max(π(J)∣J∈L(R))\lceil R \rceil := max({\pi(J) \vert J \in L(R)})$
系统 "当前最大访问优先级" (current system ceiling)
- 这个 ceiling 是动态变化的, 根据执行任务和任务对资源的占有有关
- 将系统 "当前最大访问优先级" $\prod$ 为: 当前执行作业优先级与所有被占有且未完成资源的 "当前访问最大值" 的最大值 $∏:=max(0∪π(J)∪⌈R⌉∣R∈Rclaimed)\prod := max({0} \cup {\pi(J)} \cup {\lceil R \rceil \vert R \in R_{claimed}})$ 其中 $J$ 为当前执行的作业, $R_{claimed}$ 为所有被占有且未完成的资源. 执行算法:
在锁住资源时, 将满足下面条件的任务停止执行:
$π(J)≤∏\pi(J) \le \prod$
"Disable all tasks at equal or lower priority than the highest of all jobs that take the said resource"
- i.e. 能够成功持锁的任务必须 严格大于 当前的 Priority Ceiling
在释放资源时, 将之前停止的任务恢复

直观图像如下: (From Emil Fresk: RTIC: Real Time Interrupt Driven Concurrency Talk , Slides)

其中 Job1, Job2 共享这个资源, Job3 不使用这个资源. Job1, Job2 对资源进行访问时, 蓝色线条及以下优先级的任务 (除了正在访问的任务外) 都被禁止运行. 可以看到在 Job3 运行完毕后应该让 Job2 运行, 但是因为 Job2 可能会 访问 Job1 正在访问的资源, 它被禁止运行, 直到 Job1 释放资源后, 才被立即执行.

常见的 RTOS 不能使用这样硬件加速的 SAP 抢占式调度的原因是: 他们使用的线程模型 (Threading Model) 并在编译时静态分析出“任务-资源”依赖关系. 而 RTIC 的设计使得静态分析出每个资源的 ceiling 变得可能.

3. ARM Cortex-M 中断机制

在 ARM 架构下, BASEPRI (Base Priority) 寄存器就能够实现 Priority Ceiling 算法, 它会将低于这个寄存器的所有中断全部屏蔽. 我们只需要在进入临界区和离开临界区时修改这个寄存器即可.

这使用到了 ARM 的 NVIC (Nested Vectored Interrupt Controller) 机制, 这是硬件实现的中断优先级机制, 允许高优先级中断 ISR 抢占正在执行的低优先级中断 ISR. 这样的机制使得硬件加速的抢占式优先级调度成为可能.

3.1 NVIC 模块

3.2 中断向量表 (Vector Table)

在 ARM 中, 中断 (Interrupts) 被认为是一种特殊的异常 (Exception). 异常和中断的 ISR 地址被保存在 中断向量表 (Vector Table) 中, 其格式如下 (Cortex-m7)

我们也可以从 cortex-m-rt 中对 .vector_table 段的定义了解它的格式

/* ## Sections in FLASH */
/* ### Vector table */
.vector_table ORIGIN(FLASH) :
{
  __vector_table = .;
  /* Initial Stack Pointer (SP) value.
   * We mask the bottom three bits to force 8-byte alignment.
   * Despite having an assert for this later, it's possible that a separate
   * linker script could override _stack_start after the assert is checked.
   */
  LONG(_stack_start & 0xFFFFFFF8);
  /* Reset vector */
  KEEP(*(.vector_table.reset_vector)); /* this is the `__RESET_VECTOR` symbol */
  /* Exceptions */
  __exceptions = .; /* start of exceptions */
  KEEP(*(.vector_table.exceptions)); /* this is the `__EXCEPTIONS` symbol */
  __eexceptions = .; /* end of exceptions */
  /* Device specific interrupts */
  KEEP(*(.vector_table.interrupts)); /* this is the `__INTERRUPTS` symbol */
} > FLASH

我们从 __vector_table 地址开始, 一次对每一个入口进行讲解

V[0]: 初始化栈指针, 这会在设备启动或重置时设置栈指针 SP
V[1]: 重置行为入口地址, 如果设备被重置, 其指向的函数入口将会被执行
V[2]: NMI (Non-maskable Interrupt) ISR
V[3]: HardFault 异常, 在无法恢复的错误发生时会被触发
- 它相当于一个 catch all
- 其可以细化为 BusFault, UsageFaule, Memory Management Fault 等
V[4]: Memory Management Fault 异常, 被违反 MMU 规则的内存访问触发
V[5]: BusFault 异常
- 例如对为对其的地址进行访问等
V[6]: UsageFaule 异常
- 例如除零异常等
V[11]: SVCall 异常, 在使用系统调用 (Superviosr Call) 时会被触发
V[14]: PendSV 异常, 用于在多个 IRQ 发生时延迟回到用户态 (Thread Mode) 的上下文切换来避免 IRQ 延迟
- 参考这篇文章
V[15]: SysTick 异常, 用于系统时钟
V[16-255]: IRQ 异常, 外部设备中断触发的异常

在 cortex-m-rt 中, 我们定义了 __EXCEPTIONS, __RESET, __INTERRUPTS 等数据结构并将他们放入 .vector_table 段对向量表进行初始化. 并且将中断/异常名称相同的函数作为其入口. 我们如果希望重写中断, 仅需要覆盖定义这些函数即可

PROVIDE(NonMaskableInt = DefaultHandler);
PROVIDE(MemoryManagement = DefaultHandler);
PROVIDE(BusFault = DefaultHandler);
PROVIDE(UsageFault = DefaultHandler);
PROVIDE(SecureFault = DefaultHandler);
PROVIDE(SVCall = DefaultHandler);
PROVIDE(DebugMonitor = DefaultHandler);
PROVIDE(PendSV = DefaultHandler);
PROVIDE(SysTick = DefaultHandler);

4. Rust 异步状态机

在 Rust 中 async/await 语法用于编写可以执行 非阻塞 的异步代码. 这对于 I/O 绑定任务尤其有用, 例如从文件中读取数据或进行网络请求, 在这种情况下, 在等待操作完成时阻塞程序的执行. Rust 中的 async/await 语法建立在状态机之上, 状态机是一个用于管理异步操作执行状态的概念. 我们将一个异步状态机定义为 Future, 对状态机的一次执行通过调用 Future::poll 实现. 如果状态机执行完成, 会返回 Poll::Ready(_) (其中包含计算结果), 如果未执行完成, 会返回 Poll::Pending, 代表这个状态机需要再次调用 Future::poll 进行执行.

调用 Rust 的 async 关键词修饰的函数 async fn foo(...) -> T 会被认为返回了 Future<Output = T>, 这个 Future 对象是 Rust 编译器自动生成的匿名对象.
编译器在 async 函数的每一个 .await 或 yield 语句后生成一个状态, 执行这个语句之前会保存下一个状态所需的所有变量, 状态会保存在 Future 中.

5. 任务 (Tasks)

RTIC 将任务分为 硬件任务 (Hardware Task) 和 软件任务 (Software Task).

任务通过 #[task] 修饰, 对于硬件任务, 需要通过 binds 指定其中断源, 对于软件任务就不需要. 我们需要在每个任务的 #[task] 中声明其优先级 priority, 局部资源 loacal 和共享资源 shared.

所有任务都由中断驱动, 因为 BASEPRI 作为 SRP 调度的. 我们通过保存和恢复 BASEPRI 维护调度的正确性, 每次对执行器的调用都被包裹在 rtic::cortex_basepri::run 中, 如下

#[inline(always)]
pub fn run<F>(priority: u8, f: F)
where
    F: FnOnce(),
{
    if priority == 1 {
        // If the priority of this interrupt is `1` then BASEPRI can only be `0`
        f();
        unsafe { basepri::write(0) }
    } else {
        let initial = basepri::read();
        f();
        unsafe { basepri::write(initial) }
    }
}

5.1 硬件任务 (Hardware Tasks)

硬件任务会绑定一个中断源, 在中断源被触发时, 硬件任务会被以 ISR 被执行. 我们要求硬件任务必须 完整执行, i.e. , "run-to-completion".

对于硬件任务

#[task(binds = SPI3)]
fn hw_task(_cx: hw_task::Context) {
    print!("hello world");
}

其生成的代码为

#[no_mangle]
unsafe fn SPI3() {
    const PRIORITY: u8 = 1u8;
    rtic::export::run(PRIORITY, || hw_task(hw_task::Context::new()));
}
fn hw_task(_cx: hw_task::Context) {
    print!("hello world");
}

5.2 软件任务 (Software Tasks)

软件任务被定义为一个 async 函数, 这说明软件任务使用了 Rust 的异步状态机实现. 那么这个状态机什么时候执行, 被谁执行, 又怎样实现抢占式优先级调度呢?

每一个软件任务都会被分配一个 Executor (执行器), 这个执行器包装了对这个软件任务 Future 的一次执行.

5.2.1 `Executor` 执行器

Future 作为一个状态机, 能够在一次执行中改变其状态. 我们将每一次 .await 或 yield 作为一次保存状态的位置, 在这里我们主动的将 CPU 执行时间让出. 在这两个语句之间的代码会被一次 Future::poll 执行.

Future::poll 返回一个 Poll<T> 对象, 它为一个枚举类型, Poll::Pending 表示状态机未达到完成状态, 需要再次被 poll, Poll::Ready(T) 表示状态机执行完成, 其内容 T 为执行结果.

RTIC 创建了一个 AsyncTaskExecutor 来保存任务的 调度执行状态 (是否可以运行, 是否正在运行)和 状态机状态 (状态节点, 需要的局部变量).

/// Executor for an async task.
pub struct AsyncTaskExecutor<F: Future> {
    // `task` is protected by the `running` flag.
    task: UnsafeCell<MaybeUninit<F>>,
    running: AtomicBool,
    pending: AtomicBool,
}

其中, 我们通过 running 表示任务是否活跃, 仅在初始化 task 前和任务执行完成 (返回 Poll::Ready(_)) 后为 false. 如果 running == false, 则可以修改 task 成员.

因为软件任务为一个异步函数, 返回实现 Future 的对象, 通过调用这个任务函数我们就能够获得对应的 Future. 这样可以将这个 Future 通过 AsyncTaskExecutor::spawn 移动到 AsyncTaskExecutor 中 (所有权可以避免一个 Future 被多个 Executor 使用).

执行器通过对该软件任务的一次执行后返回执行结果. Rust 的 Future::poll(self, cx) -> Poll 接口需要传入一个 Context 对象, 这个对象会被用于在能任务能够继续被执行是唤醒执行器. 比如: 如果任务需要等待一个延迟, 需要在返回 Poll::Pending 前设置一个时钟延迟, 在延迟到期后回调 Context::waker::wake 函数唤醒这个执行器使它能够继续执行 (不一定马上执行).

AsyncTaskExecutor::poll 函数包装了 Future::poll 函数, 在执行前检查任务是否活跃 (AsyncTaskExecutor::is_running), 如果活跃就执行. 如果任务执行完成 (返回 Poll::Ready(_)) 就将状态设置为不活跃 (is_running = false). 函数还接受一个自定义 wake 闭包, 使得调用函数能够自定义唤醒行为.

impl<F: Future> AsyncTaskExecutor<F> {
    /// Poll the future in the executor.
    #[inline(always)]
    pub fn poll(&self, wake: fn()) {
        if self.is_running() && self.check_and_clear_pending() {
            let waker = unsafe { Waker::from_raw(RawWaker::new(wake as *const (), &WAKER_VTABLE)) };
            let mut cx = Context::from_waker(&waker);
            let future = unsafe { Pin::new_unchecked(&mut *(self.task.get() as *mut F)) };

            match future.poll(&mut cx) {
                Poll::Ready(_) => {
                    self.running.store(false, Ordering::Release);
                }
                Poll::Pending => {}
            }
        }
    }
}

我们需要注意 RTIC 的执行器是全局的, 它的创建十分巧妙. 我们在全局声明这个执行器的指针 AsyncTaskExecutorPtr, 此时这个指针为空.

/// Pointer to executor holder.
pub struct AsyncTaskExecutorPtr {
    // Void pointer.
    ptr: AtomicPtr<()>,
}
impl AsyncTaskExecutorPtr {
    pub const fn new() -> Self {
        Self {
            ptr: AtomicPtr::new(core::ptr::null_mut()),
        }
    }
}

这是它的生成代码

// Generate executor definition and priority in global scope
for (name, _) in app.software_tasks.iter() {
    let exec_name = util::internal_task_ident(name, "EXEC");
    items.push(quote!(
        #[allow(non_upper_case_globals)]
        static #exec_name: rtic::export::executor::AsyncTaskExecutorPtr =
            rtic::export::executor::AsyncTaskExecutorPtr::new();
    ));
}

我们在 main 入口中创建一个执行器, 并将这个执行器, 并使用 AsyncTaskExecutorPtr::set_in_main 传入这个执行器在 main 函数栈贞中的地址初始化这个全局指针.

impl AsyncTaskExecutorPtr {
    #[inline(always)]
    pub fn set_in_main<F: Future>(&self, executor: &ManuallyDrop<AsyncTaskExecutor<F>>) {
        self.ptr.store(executor as *const _ as _, Ordering::Relaxed);
    }
}

我们可以在 rtic-macros::main::codegen 中看到它的代码: 创建 executor, 调用 set_in_main 传入它的地址初始化

for (name, _) in app.software_tasks.iter() {
    let exec_name = util::internal_task_ident(name, "EXEC");
    let new_n_args = util::new_n_args_ident(app.software_tasks[name].inputs.len());
    executor_allocations.push(quote!(
        let executor = ::core::mem::ManuallyDrop::new(rtic::export::executor::AsyncTaskExecutor::#new_n_args(#name));
        executors_size += ::core::mem::size_of_val(&executor);
        #exec_name.set_in_main(&executor);
    ));
}

尽管执行器在 main 中创建, 是它的全局变量, 它在整个运行过程中不会被销毁. 因为 main 永远不会退出, 执行完初始化后它会进入循环. 因为它的优先级最低, 当有任务时总会被其他任务抢占, 它可以用来执行 idle 后台任务 (如果有的话) 或者无限循环.

#[no_mangle]
unsafe extern "C" fn main() -> ! { /* ... */}

它的布局如下, 可以在 rtic-macros::main::codegen 中查看

quote!(
    #(#extra_mods_stmts)*
    #[doc(hidden)]
    #[no_mangle]
    unsafe extern "C" fn #main() -> ! {
        #(#assertion_stmts)*
        #(#pre_init_stmts)*
        #[inline(never)]
        fn __rtic_init_resources<F>(f: F) where F: FnOnce() {
            f();
        }
        // Generate allocations for async executors.
        let mut executors_size = 0;
        #(#executor_allocations)*
        #(#msp_check)*
        // Wrap late_init_stmts in a function to ensure that stack space is reclaimed.
        __rtic_init_resources(||{
            let (shared_resources, local_resources) = #init_name(#init_name::Context::new(#init_args));
            #(#post_init_stmts)*
        });
        #call_idle
    }
)

5.2.2 `Dispatcher` 分发器

所有优先级相同的任务会被分配到一个 Dispatcher (分法器) 中, 每一个 Dispatcher 会与一个独一的中断源进行绑定, 注意这个中断源不能够是硬件任务绑定过的中断源. 我们这里讨论优先级 > 0 的 Dispatcher, 因为 0-优先级 Dispatcher 被认为是一个后台任务, 不通过中断驱动.

关于刚才这个限制的检查代码能够在 rtio-macro::syntax::check::app 定义中找到

// check that dispatchers are not used as hardware tasks
for task in app.hardware_tasks.values() {
    let binds = &task.args.binds;
    if app.args.dispatchers.contains_key(binds) {
        return Err(parse::Error::new(
            binds.span(),
            "dispatcher interrupts can't be used as hardware tasks",
        ));
    }
}

每一个 Dispatcher 负责使用轮转调度当前优先级的所有任务.

在静态代码分析时, rtic-macros::syntax::analyze::app 将相同优先级的任务收集成为一个 Channel, 使用 BTreeMap<Priority, Channel> 进行优先级 - 任务的 1:n 映射.

let mut channels = Channels::new();
for (name, spawnee) in &app.software_tasks {
    let spawnee_prio = spawnee.args.priority;
    let channel = channels.entry(spawnee_prio).or_default();
    channel.tasks.insert(name.clone());
    // All inputs are send as we do not know from where they may be spawned.
    spawnee.inputs.iter().for_each(|input| {
        send_types.insert(input.ty.clone());
    });
}

这个 Dispatcher 的布局如下. 其中 dispatcher_name 为中断名, 因为使用 cortex-m-rt 库, 中断名同名函数自动会被作为这个中断的 ISR.

let doc = format!("Interrupt handler to dispatch async tasks at priority {level}");
let attribute = &interrupts.get(&level).expect("UNREACHABLE").1.attrs;
let config = handler_config(app, analysis, dispatcher_name.clone());
items.push(quote!(
    #[allow(non_snake_case)]
    #[doc = #doc]
    #[no_mangle]
    #(#attribute)*
    #(#config)*
    unsafe fn #dispatcher_name() {
        /// The priority of this interrupt handler
        const PRIORITY: u8 = #level;
        rtic::export::run(PRIORITY, || {
            #(#stmts)*
        });
    }
));

其中 stmsts 是对当前优先级的所有软件任务执行语句.

for name in channel.tasks.iter() {
    let exec_name = util::internal_task_ident(name, "EXEC");
    let from_ptr_n_args =
        util::from_ptr_n_args_ident(app.software_tasks[name].inputs.len());
    stmts.push(quote!(
        let exec = rtic::export::executor::AsyncTaskExecutor::#from_ptr_n_args(#name, &#exec_name);
        exec.poll(|| {
            let exec = rtic::export::executor::AsyncTaskExecutor::#from_ptr_n_args(#name, &#exec_name);
            exec.set_pending();
            #pend_interrupt
        });
    ));
}

我们看到 Dispatcher 执行是在 AsyncTaskExecutor::poll 上的一个 wrapper, 这个 wrapper 定义了唤醒行为, 这个行为包括

设置 AsyncExecutor::pending 值, 使得执行器被唤醒时继续执行
触发当前 Dispatcher 中断源的中断, 达到重新执行这个 Dispatcher 的效果

由于唤醒时会触发中断, 会使得 Dispatcher 再次被调用, 直到任务结束. 如果软件任务是一个无限循环, 那么 Dispatcher 永远不会退出, 如果软件任务只需要被运行一次, 在它结束之后如果再次被唤醒, 因为 AsyncTaskExecutor::poll 执行时的检查条件 self.is_running() && self.check_and_clear_pending(), 它将不会被执行.

let pend_interrupt = if level > 0 {
    let int_mod = interrupt_mod(app);
    quote!(rtic::export::pend(#int_mod::#dispatcher_name);)
} else {
    // For 0 priority tasks we don't need to pend anything
    quote!()
};

这里触发中断通过 cortex_m::periphral::NVIC 对应的中断 bit 写入实现

/// Sets the given `interrupt` as pending
///
/// This is a convenience function around
/// [`NVIC::pend`](../cortex_m/peripheral/struct.NVIC.html#method.pend)
pub fn pend<I>(interrupt: I)
where
    I: InterruptNumber,
{
    NVIC::pend(interrupt);
}

Dispatcher 的执行流程
Waker::wake -> HW Interrupt -> dispatcher ISR -> AsyncTaskExecutor::poll -> Future::poll -> ISR Done

5.3 `idle` 任务和 0-优先级任务

idle 作为一个 0-优先级任务, 在 main 函数完成初始化后一直运行. 因为 main 函数不能够退出, idle 任务也不能够退出. 并且 idle 任务和 0-优先级任务不能够同时存在, 因为 idle 任务永不退出, 不能与 Dispatcher 兼容. 在 rt-macro::analyze::app 中能够找到其逻辑

// Check 0-priority async software tasks and idle dependency
for (name, task) in &app.software_tasks {
    if task.args.priority == 0 {
        // If there is a 0-priority task, there must be no idle
        if app.idle.is_some() {
            error.push(syn::Error::new(
                name.span(),
                format!(
                    "Async task {:?} has priority 0, but `#[idle]` is defined. 0-priority async tasks are only allowed if there is no `#[idle]`.",
                    name.to_string(),
                )
            ));
        }
    }
}

在 main 函数中, call_idle 块 (最后部分) 被定义为如下

let call_idle = if let Some(idle) = &app.idle {
    let name = &idle.name;
    quote!(#name(#name::Context::new()))
} else if analysis.channels.get(&0).is_some() {
    let dispatcher = util::zero_prio_dispatcher_ident();
    quote!(#dispatcher();)
} else {
    quote!(loop {})
};

如果有 0-优先级软件任务, 就会调用 0-Priority Dispatcher. 它的工作是循环对 0-优先级任务进行 poll, 它与 idle 本质一样, 也不会返回.
它的代码可以在 rtic-macros::async_dispatchers::codegen 中找到

if level > 0 {
    // generate code for non-zero dispatcher
} else {
    items.push(quote!(
        #[allow(non_snake_case)]
        unsafe fn #dispatcher_name() -> ! {
            loop {
                #(#stmts)*
            }
        }
    ));
}

5.4 `init` 任务

init 任务被用户定义, 在 main 函数中被执行. 它初始化所有任务的本地资源 (local resources) 和共享资源 (shared resources), 并返回一个元组.
在整个过程中, 中断被关闭, i.e. 执行流不会被打断.

6. 资源

RTIC 的资源分为 "局部资源" 和 "共享资源". 他们使用 #[local] 和 #[shared] 修饰的结构体来标识

#[shared]
struct Shared {
    shared1: u32,
    shared2: u32,
}

#[local]
struct Local {
    foo_local_res_1: u32,
    bar_local_res_1: u32,
}

6.1 局部资源 (Local Resources)

局部资源只能够被一个任务访问, 通过 #[task(local = [...])] 声明. 这里有两种声明方式

在 app 范围使用 #[shared] 修饰的结构体定义, 如上
在任务范围使用 #[task(local = [foo: FooType = FooType{ ... }])]

因为局部资源可以在 init 任务 (处于临界区, 互斥访问) 中被初始化, 后交还给指定的任务, 局部资源需要实现 Send 接口, 因为在 init 和目标任务之间, 这个变量穿过了线程边界 (thread boundary)

[!info] Send and Sync

Send 是指类型能在线程之间传递, 如 Arc, Mutex 等.

Sync 是指类型能在线程之间共享, T impls Sync iff &T impls Send.

6.2 共享资源 (Shared Resources)

共享资源通过在 #[task(shared = [...])] 声明.

对于仅在同一优先级之间共享的资源, 因为为单核模型, 它们只能顺序执行, 互不抢占, 所以我们能够不使用 #[lock_free] 修饰这个共享变量. 它的互斥访问通过 Rust 的所属权语义来保障, i.e. 在一个时刻, 一个变量只可能存在以下两种的引用情况

多个非可变引用 (Immutable Reference) &T
一个可变引用 (Mutable Reference) &mut T

如果在不同优先级间共享的变量被 #[lock_free] 修饰将不能通过编译, 这会在 rtic-macros::syntax::analyze 中被检查

// Check that lock_free resources are correct
for lf_res in lock_free.iter() {
    for (task, tr, _, priority) in task_resources_list.iter() {
        for r in tr {
            // Get all uses of resources annotated lock_free
            if lf_res == r {
                // Check so async tasks do not use lock free resources
                if app.software_tasks.get(task).is_some() {
                    error.push(syn::Error::new(
                        r.span(),
                        format!(
                            "Lock free shared resource {:?} is used by an async tasks, which is forbidden",
                            r.to_string(),
                        ),
                    ));
                }
                // HashMap returns the previous existing object if old.key == new.key
                if let Some(lf_res) = lf_hash.insert(
                    r.to_string(), 
                    (task, r, priority)
                ) {
                    // Check if priority differ, if it does, append to
                    // list of resources which will be annotated with errors
                    if priority != lf_res.2 {
                        lf_res_with_error.push(lf_res.1);
                        lf_res_with_error.push(r);
                    }
                    // If the resource already violates lock free properties
                    if lf_res_with_error.contains(&r) {
                        lf_res_with_error.push(lf_res.1);
                        lf_res_with_error.push(r);
                    }
                }
            }
        }
    }
}

对于可能被抢占的共享变量的访问, 我们需要临界区保护. RTIC 使用了基于优先级的临界区(Priority-based Critical Sections) 保证了高效的无竞争内存共享(Data-race-free Memory Sharing)

传入每个任务的 Context 中的共享变量实现了 Mutex 接口, 我们通过 lock 调用传入闭包进行对共享变量的访问和修改. 闭包内形成了一个临界区. lock API 的实现采用了之前提到的 Priority Ceiling Protocol 进行同步, 并使用 SRP 进行调度.

我们能看到 rtic::cortex_basepri::lock 的实现, 通过资源在 lock 实现时的 ceiling, 将 BASEPRI 在临界区设置为访问当前资源的 ceiling. 如果希望在最高优先级执行, 使用 critical_section::with 方法关闭所有中断, 进入全局临界区.

#[inline(always)]
pub unsafe fn lock<T, R>(
    ptr: *mut T,
    ceiling: u8,
    nvic_prio_bits: u8,
    f: impl FnOnce(&mut T) -> R,
) -> R {
    if ceiling == (1 << nvic_prio_bits) {
        critical_section::with(|_| f(&mut *ptr))
    } else {
        let current = basepri::read();
        basepri_max::write(cortex_logical2hw(ceiling, nvic_prio_bits));
        let r = f(&mut *ptr);
        basepri::write(current);
        r
    }
}

这里并不是共享资源 lock 的实现, 仅是硬件资源提供的抽象. 对于共享资源的 lock 实现, 我们能够在 rtic-macros::codegen::bindings::cortex::inpl_mutex 中找到, 它将通过静态分析得到的资源 ceiling 作为常量 CEILING 保存在资源的 lock 函数实现里, 调用硬件提供的 lock 函数.

    /// Generates a `Mutex` implementation
    #[allow(clippy::too_many_arguments)]
    pub fn impl_mutex(
        app: &App,
        _analysis: &CodegenAnalysis,
        cfgs: &[Attribute],
        resources_prefix: bool,
        name: &Ident,
        ty: &TokenStream2,
        ceiling: u8,
        ptr: &TokenStream2,
    ) -> TokenStream2 {
        let path = if resources_prefix {
            quote!(shared_resources::#name)
        } else {
            quote!(#name)
        };

        let device = &app.args.device;
        quote!(
            #(#cfgs)*
            impl<'a> rtic::Mutex for #path<'a> {
                type T = #ty;

                #[inline(always)]
                fn lock<RTIC_INTERNAL_R>(&mut self, f: impl FnOnce(&mut #ty) -> RTIC_INTERNAL_R) -> RTIC_INTERNAL_R {
                    /// Priority ceiling
                    const CEILING: u8 = #ceiling;

                    unsafe {
                        rtic::export::lock(
                            #ptr,
                            CEILING,
                            #device::NVIC_PRIO_BITS,
                            f,
                        )
                    }
                }
            }
        )
    }

7. Rust Macros

Rust macro 分为声明性(Declarative) Macro 和步骤性(Procedural) Macro, 更多资讯请参考 The Little Book of Rust Macros

由于声明性 macro 的功能较弱, 与 C 中的 #define 类似 (但是工作在 AST 上, 而不是 pre-processor 的直接替换文本, 提高了安全性和可读性), RTIC 使用步骤性 macro 对代码进行分析.

编译器在词法分析 (Lexical Analysis) 后会生成 Token Stream, 步骤性 Macro 就是在这里进行的, 它通过截取词法分析的 Token Stream, 将其转化为新的 Token Stream 再交还给编译器, 对于后续分析是透明的. 当然, 我们并不需要完成从 Token Stream 到 AST 的词法分析 (Syntax Analysis) 过程, "there is a crate for that": syn 能够通过 syn::parse(input) 得到一个 Rust AST.

关于编译步骤, 你可以通过下图有一个高层次的了解 (From Geek for Geeks: Phases of a Compiler)

有关 RTIC 的静态分析代码可以在 rtic-macros 中找到, 我们先了解它的大致工作流程

#[proc_macro_attribute]
pub fn app(_args: TokenStream, _input: TokenStream) -> TokenStream {
    let (mut app, analysis) = match syntax::parse(_args, _input) {
        Err(e) => return e.to_compile_error().into(),
        Ok(x) => x,
    };
    // Modify app based on backend before continuing
    if let Err(e) = preprocess::app(&mut app, &analysis) {
        return e.to_compile_error().into();
    }
    let app = app;
    // App is not mutable after this point
    if let Err(e) = check::app(&app, &analysis) {
        return e.to_compile_error().into();
    }
    let analysis = analyze::app(analysis, &app);
    let ts = codegen::app(&app, &analysis);
    // write to disk ...
}

可以通过下图直观的了解 (From *Tjäder 2021 , Figure 3.6)

Rust syn 库能够将 Token 流转换成 AST (Abstract Syntax Tree), 我们将在 AST 层面探讨对 RTIC 代码的静态分析 .

8. Priority Ceiling 的计算方法

经过 parsing 后, 我们收集到下面的结构体

pub struct App {
    /// The arguments to the `#[app]` attribute
    pub args: AppArgs,
    /// The name of the `const` item on which the `#[app]` attribute has been placed
    pub name: Ident,
    /// The `#[init]` function
    pub init: Init,
    /// The `#[idle]` function
    pub idle: Option<Idle>,
    /// Resources shared between tasks defined in `#[shared]`
    pub shared_resources: Map<SharedResource>,
    pub shared_resources_vis: syn::Visibility,
    /// Task local resources defined in `#[local]`
    pub local_resources: Map<LocalResource>,
    pub local_resources_vis: syn::Visibility,
    /// User imports
    pub user_imports: Vec<ItemUse>,
    /// User code
    pub user_code: Vec<Item>,
    /// Hardware tasks: `#[task(binds = ..)]`s
    pub hardware_tasks: Map<HardwareTask>,
    /// Async software tasks: `#[task]`
    pub software_tasks: Map<SoftwareTask>,
}

要对每个资源进行分析, 我们需要首先收集任务-资源关系. 我们将所有的资源都收集到 task_resource_list 中. 我们将 app.init, app.idle, app.software_tasks 和 app.hardware_tasks 中所有的中的资源收集成一个 (Task Name, Shared Resources, Local Resources, Priority) 集合.

为得到每个共享资源的 priority ceiling, 我们现在分析资源占有的情况. 定义 Access 结构体, 保存独占访问 x 和不可变访问 &x.

pub enum Access {
    /// `[x]`, a mutable resource
    Exclusive,
    /// `[&x]`, a static non-mutable resource
    Shared,
}

我们能够通过下面的 parse 代码了解其定义, 其中:

Expr::Path(ExprPath) 是一个完整变量名, 如 std::mem::replace
Expr::Reference(ExprReference)] 是一个变量引用, 如 &a 或 &mut a
- 在代码中检查了 r.mutability, 不允许可变引用的变量, 因为它不可能被共享

let (access, path) = match e {
    Expr::Path(e) => (Access::Exclusive, e.path),
    Expr::Reference(ref r) if r.mutability.is_none() => match &*r.expr {
        Expr::Path(e) => (Access::Shared, e.path.clone()),
        _ => return err,
    },
    _ => return err,
};

我们定义资源的所属情况 Ownership

Ownership::Owned: 资源被一个任务独享, 我们保存这个任务的优先级
Ownership::CoOwned: 资源被多个 相同优先级 的任务共享, 我们保存这个优先级
Ownership::Contended: 资源可能被多个 不同优先级 任务抢占, 需要保存资源的 priority ceiling

pub enum Ownership {
    /// Owned by a single task
    Owned {
        /// Priority of the task that owns this resource
        priority: u8,
    },
    /// "Co-owned" by more than one task; all of them have the same priority
    CoOwned {
        /// Priority of the tasks that co-own this resource
        priority: u8,
    },
    /// Contended by more than one task; the tasks have different priorities
    Contended {
        /// Priority ceiling
        ceiling: u8,
    },
}

我们通过遍历所有任务的资源访问情况, 算出 PCP (Priority Ceiling Protocol) 中每个任务需要的 Priority Ceiling:

对于每个新发现的资源
- 认为它是被一个任务独占的, 初始化为 Owned 类型
- 设置 资源优先级 为该 任务优先级
对于重复发现的资源 (任何类型)
- 它一定不是被独占的的资源, 我们比较 资源优先级 与 (重复发现的) 任务优先级
- 不等, 认为是 Contended (不同优先级任务共享), 并更新 资源优先级.
- 相等, 认为是 CoOwned (相同优先级任务共享)
  - 但不能确定一定是仅同优先级共享, 下一回合可能发现其他优先级转为 Contended

let mut used_shared_resource = IndexSet::new();
let mut ownerships = Ownerships::new();
let mut sync_types = SyncTypes::new();
for (prio, name, access) in app.shared_resource_accesses() {
    let res = app.shared_resources.get(name).expect("UNREACHABLE");
    // This shared resource is used
    used_shared_resource.insert(name.clone());
    if let Some(priority) = prio {
        if let Some(ownership) = ownerships.get_mut(name) {
            match *ownership {
                Ownership::Owned { priority: ceiling }
                | Ownership::CoOwned { priority: ceiling }
                | Ownership::Contended { ceiling }
                    if priority != ceiling =>
                {
                    *ownership = Ownership::Contended {
                        ceiling: cmp::max(ceiling, priority),
                    };
                    if access.is_shared() {
                        sync_types.insert(res.ty.clone());
                    }
                }
                Ownership::Owned { priority: ceil } if ceil == priority => {
                    *ownership = Ownership::CoOwned { priority };
                }
                _ => {}
            }
        } else {
            ownerships.insert(name.clone(), Ownership::Owned { priority });
        }
    }
}

至此我们已经静态计算出每一个资源的 Priority Ceiling 了

9. RTIC 启动过程

RTIC 的入口函数为 main, 它的工作为初始化和执行后台任务. 这个函数永不退出, 我们将执行器分配在 main 函数的栈贞中.
main 函数的主要工作为

关闭中断, 进入临界区
设置中断源优先级, 启用中断源 (中断仍然关闭)
调用 init 初始化资源
开启中断, 离开临界区
执行后台任务 (0-优先级)

关闭中断的代码能够在 rtic-macros::codegen::pre_init::codegen 中找到, 使用 interrupt::disable() 将中断关闭.

启用中断源的代码能够在 rtic-macros::codegen::bindings::pre_init_enable_interrupts 中找到.
它使用 NVIC 设置外部中断 (外部中断被认为是特殊的异常), 使用 SBC 设置系统异常.

我们对 interrupt_ids 和 hardware_tasks 中的中断进行, 其中 interrupt_ids 保存了 软件任务 对应的 Dispatcher 的中断源.
因为(外部)中断默认关闭, 我们通过 NVIC 设置外部中断后, 需要通过 unmask 开启中断源.

for (&priority, name) in interrupt_ids.chain(app.hardware_tasks.values().filter_map(|task| {
       if is_exception(&task.args.binds) {
           // We do exceptions in another pass
           None
       } else {
           Some((&task.args.priority, &task.args.binds))
       }
   })) {
       stmts.push(quote!(
           core.NVIC.set_priority(
               #rt_err::#interrupt::#name,
               rtic::export::cortex_logical2hw(#priority, #nvic_prio_bits),
           );
       ));
       // NOTE unmask the interrupt *after* setting its priority: changing the priority of a pended
       // interrupt is implementation defined
       stmts.push(quote!(rtic::export::NVIC::unmask(#rt_err::#interrupt::#name);));
   }

这里的异常被认为是 能够定义优先级的系统异常, 它包含以下异常

MemoryManagement
BusFault
UsageFault
SecureFault
SVCall
DebugMonitor
PendSV
SysTick 因为这些异常被认为是系统异常, 他们通过 SCB (System Configuration Block) 进行设置, 并默认开启

// Set exception priorities
for (name, priority) in app.hardware_tasks.values().filter_map(|task| {
    if is_exception(&task.args.binds) {
        Some((&task.args.binds, task.args.priority))
    } else {
        None
    }
}) {
    stmts.push(quote!(core.SCB.set_priority(
        rtic::export::SystemHandler::#name,
        rtic::export::cortex_logical2hw(#priority, #nvic_prio_bits),
    );));
}

我们接下来分配软件任务的执行器. 我们提到, 我们为 每一个 软件任务分配一个执行器, 它的分配先通过在 main 栈上创建 AsyncTaskExecutor, 再将它的地址复值到全局指针 AsyncTaskExecutorPtr 中, 使得所有函数都能够通过这个变量得到执行器.

for (name, _) in app.software_tasks.iter() {
    let exec_name = util::internal_task_ident(name, "EXEC");
    let new_n_args = util::new_n_args_ident(app.software_tasks[name].inputs.len());
    executor_allocations.push(quote!(
        let executor = ::core::mem::ManuallyDrop::new(rtic::export::executor::AsyncTaskExecutor::#new_n_args(#name));
        executors_size += ::core::mem::size_of_val(&executor);
        #exec_name.set_in_main(&executor);
    ));
}

我们接下来调用 init 任务函数对资源进行初始化. 注意到这里我们并不再 main 的执行栈上创建资源, 而是将 init 初始化资源的值拷贝到资源的全局变量中.
这里使用闭包并且不允许内联, 这样使得编译器对 let (shared_resources, local_resources) 分配的栈空间能够回收, 减少 main 调用栈的空间占用.

#[inline(never)]
fn __rtic_init_resources<F>(f: F) where F: FnOnce() {
    f();
}
// Wrap late_init_stmts in a function to ensure that stack space is reclaimed.
__rtic_init_resources(||{
    let (shared_resources, local_resources) = #init_name(#init_name::Context::new(#init_args));
    #(#post_init_stmts)*
});

在获得了初始化的 shared_resources 和 local_resources 后, 通过拷贝的方式复制到对应资源的全局变量中. 注意这里可能对位置敏感类型产生影响.
完成拷贝后, 开启中断, 离开临界区

/// Generates code that runs after `#[init]` returns
pub fn codegen(app: &App, analysis: &Analysis) -> Vec<TokenStream2> {
    let mut stmts = vec![];

    // Initialize shared resources
    for (name, res) in &app.shared_resources {
        let mangled_name = util::static_shared_resource_ident(name);
        // If it's live
        let cfgs = res.cfgs.clone();
        if analysis.shared_resources.get(name).is_some() {
            stmts.push(quote!(
                // We include the cfgs
                #(#cfgs)*
                // Resource is a RacyCell<MaybeUninit<T>>
                // - `get_mut` to obtain a raw pointer to `MaybeUninit<T>`
                // - `write` the defined value for the late resource T
                #mangled_name.get_mut().write(core::mem::MaybeUninit::new(shared_resources.#name));
            ));
        }
    }

    // Initialize local resources
    for (name, res) in &app.local_resources {
        let mangled_name = util::static_local_resource_ident(name);
        // If it's live
        let cfgs = res.cfgs.clone();
        if analysis.local_resources.get(name).is_some() {
            stmts.push(quote!(
                // We include the cfgs
                #(#cfgs)*
                // Resource is a RacyCell<MaybeUninit<T>>
                // - `get_mut` to obtain a raw pointer to `MaybeUninit<T>`
                // - `write` the defined value for the late resource T
                #mangled_name.get_mut().write(core::mem::MaybeUninit::new(local_resources.#name));
            ));
        }
    }

    // Enable the interrupts -- this completes the `init`-ialization phase
    stmts.push(quote!(rtic::export::interrupt::enable();));

    stmts
}

现在初始化完成, 进入后台任务执行, 通过调用 idle 函数或 zero_prio_dispatcher.

10. 总结

RTIC 是一个 Rust 语言编写的使用硬件调度加速的实时框架, 支持优先级抢占式调度. 它能够进行硬件调度的多亏于在代码定义时对每个任务占有的局部和共享资源的声明和任务优先级的静态定义. 这些信息能被用来分析出每个资源临界区时需要组织执行的任务. 它通过 ARM 的 NVIC 机制实现硬件电路级别的优先级抢占, 通过 BASEPRIO 寄存器实现阻塞互斥访问的任务, 以满足 Priority Ceiling Protocol, 实现对资源无锁访问的调度顺序.

Under the Hook - The Cortex Runtime

Jens — Thu, 11 Apr 2024 04:43:14 +0000

Refer to the cortex-m-rt documentation and its source code for more information.

1. Memory Layout

To understand more about the memory layout on ARM Cortex-M devices, let's look at the link.x.in and memory.x file.

1.1 Linker Script

according to the developer notes in the linker.x.in file, we make a few clarifications

1.1.1 Naming Conventions of Linker Symbols

We need to clarify here, that,

symbols with the _ (single underscore) prefix are semi-public, in the way that:
- users can ONLY override them in the linker script
- users are NOT allowed to reference them in rust code as external symbols
symbols with the __ (double underscore) prefix are private, and
- users should NOT in any way use or modify it

1.1.2 Weak Aliasing at the Linker Script Level

Symbols using PROVIDE are "weak aliases at the linker level", so that "users can override any of these aliases by defining the corresponding symbol themselves" .

EXTERN forces the linker to keep a symbol in the final binary (even if it is not needed)
PROVIDE provides default values that can be overridden by a user linker script For example, the each exception vectors can be overridden with use defined exception! macros

EXTERN(__EXCEPTIONS); /* depends on all the these PROVIDED symbols */

EXTERN(DefaultHandler);

PROVIDE(NonMaskableInt = DefaultHandler);
EXTERN(HardFaultTrampoline);
PROVIDE(MemoryManagement = DefaultHandler);
PROVIDE(BusFault = DefaultHandler);
PROVIDE(UsageFault = DefaultHandler);
PROVIDE(SecureFault = DefaultHandler);
PROVIDE(SVCall = DefaultHandler);
PROVIDE(DebugMonitor = DefaultHandler);
PROVIDE(PendSV = DefaultHandler);
PROVIDE(SysTick = DefaultHandler);

PROVIDE(DefaultHandler = DefaultHandler_);
PROVIDE(HardFault = HardFault_);

1.1.3 Virtual and Load Memory Addresses

The location counter ALWAYS tracks VMA, and
To use LMA, use LOADADDR(...)

Code Section

The .text section only needs to be stored in the FLASH memory because it is only a sequence of read-only executable code.

.text {
    *(.text)
} > FLASH

Since the .text section resides in the FLASH memory, there's no need of a write permission, we do not need to do anything special when booting.

Initialised Data Section

.data {
    *(.data)
} > RAM AT> FLASH

3:
    ldr r0, =__sdata
    ldr r1, =__edata
    ldr r2, =__sidata
4:
    cmp r1, r0
    beq 5f
    ldm r2!, {{r3}}
    stm r0!, {{r3}}
    b 4b
5:

Uninitialised Data Section

.bss {
    *(.bss)
} > RAM

1:
    ldr r0, =__sbss
    ldr r1, =__ebss
    movs r2, #0
2:
    cmp r1, r0
    beq 3f
    stm r0!, {{r2}}
    b 2b
3:

1.2 Embedonomicon Implementation

Here is another version of .data section in Embedonomicon

.rodata {
    *(.rodata .rodata.*);
} > FLASH

.data: AT(ADDR(.rodata) + SIZEOF(.rodata)) {
    *(.data .data.*)
} > RAM

where AT(/* ... */) specifies the LMA in FLASH: at the end of the .rodata section.
In this version, the initialisation step is performed in Rust code, before calling our user-defined entry function. ptr::write_bytes and ptr::copy_nonoverlapping are equivalent to the above assembly code.

#[no_mangle]
pub unsafe exterm "C" fn Reset() -> {
    extern "C" {
        static mut _sbss: u8;
        static mut _ebss: u8;
        static mut _sdata: u8;
        static mut _edata: u8;
        static _sidata: u8;    // LMA of the .data section_
    }

    let count = &_ebss as *const u8 as usize - &_sbss as *const u8 as usize;
    ptr::write_bytes(&mut _sbss as *mut u8, 0, count);

    let count = &_edata as *const u8 as usize - &_stada as *const u8 as usize;
    ptr::copy_nonoverlapping(&_sidata as *const u8, &mut _sdata as *mut u8, const);

    extern "Rust" {
        fn main() -> !;
    }

    main();
}

1.3 Customisable Layout

The user is allowed to customise the memory layout inside the memory.x

device memory
- i.e. the MEMORY section
start of the stack
- It is places at the end of RAM by default (if omitted)
- It grows downwards
start of the code (.text) section
- It is placed at the beginning of FLASH by default (if omitted) Here is an example of such file

/* Linker script for the STM32F303VCT6 */
MEMORY
{
    FLASH : ORIGIN = 0x08000000, LENGTH = 256K

    /* .bss, .data and the heap go in this region */
    RAM : ORIGIN = 0x20000000, LENGTH = 40K

    /* Core coupled (faster) RAM dedicated to hold the stack */
    CCRAM : ORIGIN = 0x10000000, LENGTH = 8K
}

_stack_start = ORIGIN(CCRAM) + LENGTH(CCRAM);

2. Exception and Interrupt Handling

[!info] Exception and Interrupt in ARM
In the ARM documentation, “interrupt” is used to describe a special type of “exception”

The first 0-15 interrupts are dedicated to system interrupts

The other 16-255 interrupts are referred to as a user or peripheral interrupts ### 2.2 Vector Table A vector table stores the address of the handler routines for its corresponding exceptions/interrupts.

The in-memory layout (FLASH memory) of the vector table is as follows.

/* ## Sections in FLASH */
/* ### Vector table */
.vector_table ORIGIN(FLASH) :
{
  __vector_table = .;
  /* Initial Stack Pointer (SP) value.
   * We mask the bottom three bits to force 8-byte alignment.
   * Despite having an assert for this later, it's possible that a separate
   * linker script could override _stack_start after the assert is checked.
   */
  LONG(_stack_start & 0xFFFFFFF8);
  /* Reset vector */
  KEEP(*(.vector_table.reset_vector)); /* this is the `__RESET_VECTOR` symbol */
  /* Exceptions */
  __exceptions = .; /* start of exceptions */
  KEEP(*(.vector_table.exceptions)); /* this is the `__EXCEPTIONS` symbol */
  __eexceptions = .; /* end of exceptions */
  /* Device specific interrupts */
  KEEP(*(.vector_table.interrupts)); /* this is the `__INTERRUPTS` symbol */
} > FLASH

In rust code, each vector is represented by the Vector struct. It is a Union type, can either be a handler pointer or reserved (as in reserved, or not used, by the ARM architecture)

#[repr(C)]
pub union Vector {
    handler: unsafe extern "C" fn(),
    reserved: usize,
}

[!Info] Initial Stack Pointer
the first entry of the index table holds the reset (initial) value of the stack pointer (8-bit aligned).
We can find it in the link.x.in file, where it uses LONG(_stack_start & 0xFFFFFFF8) at the start of the .vector_table section

[!info] The Reset Exception
The Reset routine is executed when a chip resets, it is places at the second entry of the vector table.

2.3 Activation of Vector Tables

The address of the memory-mapped register VTOR (Vector Table Offset Register) is 0xe000ed08.

To set its value, we simply write to the address of our vector table (provided by the linker symbol__vector_table) to the corresponding VTOR address.

ldr r0, = 0xe000ed08
ldr r1, =__vector_table
str r1, [r0]

2.4 Handlers

The user-defined handler is prefixed with __cortex_m_rt_ and the actual handler is a wrapper function post-fixed with _trampoline and exported as the original name.

let ident = f.sig.ident.clone();
let ident_s = ident.to_string();
// ...
f.sig.ident = Ident::new(&format!("__cortex_m_rt_{}", f.sig.ident), Span::call_site());
let tramp_ident = Ident::new(&format!("{}_trampoline", f.sig.ident), Span::call_site());
let (ref cfgs, ref attrs) = extract_cfgs(f.attrs.clone());

quote!(
    #(#cfgs)*
    #(#attrs)*
    #[doc(hidden)]
    #[export_name = #ident_s]
    // ...
)

The library provided default handler is simply an infinite loop

#[no_mangle]
pub unsafe extern "C" fn DefaultHandler_() -> ! {
    #[allow(clippy::empty_loop)]
    loop {}
}

But users can easily override it by providing their own DefaultHandler definitions, since PROVIDE is weak aliasing

PROVIDE(DefaultHandler = DefaultHandler_);

The default handler for HardFault is also an infinite loop

#[cfg_attr(cortex_m, link_section = ".HardFault.default")]
#[no_mangle]
pub unsafe extern "C" fn HardFault_() -> ! {
    #[allow(clippy::empty_loop)]
    loop {}
}

2.5 Built-in Exceptions

2.5.1 Exception Mechanisms

Refer to the Pre-emption and Exception Exit documentation for further information

Before entering ISR
- Push registers on selected stack (by EXC_RETURN)
- Read the corresponding vector table entry
- Update PC to the handler instruction
- Update LR (Link Register) to EXC_RETURN
Exiting ISR
- Pop Registers
- Load current active interrupt number. We can return to
  - another exception (nested), or
  - thread mode (no nested interrupt)
- Select stack pointer
  - Returning to an exception: SP <- SP_main
  - Returning to thread mode: SP <- SP_main or SP_process

2.5.2 Exception Handlers

For more information, please refer to the Exception Macro Documentation

Exception handlers can ONLY be called by hardware.

Exception handlers are divided into four categories, namely, the DefaultHandler, the HardFault handler, the NonMaskableInt-errupt exception handler , and Other exception handler.

#[derive(Debug, PartialEq)]
enum Exception {
    DefaultHandler,
    HardFault(HardFaultArgs),
    NonMaskableInt,
    Other,
}

The HardFault exception is the catch all exception for assorted system failures
- such as divide-by-zero exception, bad memory accesses etc.
- Finer granularity fault handlers: MemManage, BusFault etc.
- Its arguments (whether to use trampoline) are passed as macro arguments
The NonMaskableInt-errrupt exception is interrupt that cannot be disabled by setting PRIMASK or BASEPRIO.
- Besides the Reset exception, it has the highest priority of all other exceptions
- It is NOT generally safe to define handlers for non-maskable interrupt since it may break critical sections
- Its implementation should guarantee that: it does not access any data that is
  - protected by a critical section, and
  - shared with other interrupts that may be preempted by the NMI handler
Other exceptions are
- MemoryManagement
  - Memory accesses that violates MMU rules
- BusFault
  - Access that violates the system bus
- UsageFault
  - Such as divide-by-zero exceptions
- SecureFault
- SVCall: invoked when making a supervisor call (svc)
- DebugMonitor
- PendSV: raised to defer context switch to thread mode (user mode)
  - when multiple IRQ exceptions has been raised to minimise the IRQ delay
  - refer to [this](https://www.sciencedirect.com/topics/computer-science/software-interrupt#:~:text=A%20typical%20use%20of%20PendSV,be%20triggered%20by%20the%20following%3A&text=Calling%20an%20SVC%20function&text=The%20system%20timer%20(SYSTICK) paper
- SysTick: system timer

The parsing code makes sure that they are checked

let exn = match &*ident_s {
    "DefaultHandler" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::DefaultHandler
    }
    "HardFault" => Exception::HardFault(parse_macro_input!(args)),
    "NonMaskableInt" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::NonMaskableInt
    }
    // NOTE that at this point we don't check if the exception is available on the target (e.g.
    // MemoryManagement is not available on Cortex-M0)
    "MemoryManagement" | "BusFault" | "UsageFault" | "SecureFault" | "SVCall"
    | "DebugMonitor" | "PendSV" | "SysTick" => {
        if !args.is_empty() {
            return parse::Error::new(Span::call_site(), "This attribute accepts no arguments")
                .to_compile_error()
                .into();
        }
        Exception::Other
    }
    _ => {
        return parse::Error::new(ident.span(), "This is not a valid exception name")
            .to_compile_error()
            .into();
    }
};

The `DefaultHandler` for Exceptions

If the handler is an Exception::DefaultHandler, it extracts the irq number from the SCB_ICSR register (memory-mapped) and pass it as an argument to the user-defined handler.

Note that the user-defined DefaultHandler must has exactly one input argument, and can only have the "default", "empty tuple" not "never" return type. The constraints are checked by the macro.

f.sig.ident = Ident::new(&format!("__cortex_m_rt_{}", f.sig.ident), Span::call_site());
let tramp_ident = Ident::new(&format!("{}_trampoline", f.sig.ident), Span::call_site());
let ident = &f.sig.iden
let (ref cfgs, ref attrs) = extract_cfgs(f.attrs.clone()
quote!(
    #(#cfgs)*
    #(#attrs)*
    #[doc(hidden)]
    #[export_name = #ident_s]
    pub unsafe extern "C" fn #tramp_ident() {
        extern crate cor
        const SCB_ICSR: *const u32 = 0xE000_ED04 as *const u3
        let irqn = unsafe { (core::ptr::read_volatile(SCB_ICSR) & 0x1FF) as i16 - 16 }; 
        #ident(irqn)
    }
    #f
)

The `HardFault` Handler for Exceptions

We need to specify whether we need to use the trampoline mode. If using the trampoline mode, we should check the stack mode and use the corresponding stack pointers.

The way it works is

An assembly code marked HardFault which is a symbol used in the vector table
It passes the correct stack pointer and calls the trampoline code exported as _HardFault
The rust-written _HardFault calls the user-defined handler prefixed with __cirtex_m_rt_

The global HardFault function is defined as follows.

// HardFault exceptions are bounced through this trampoline which grabs the stack pointer at
// the time of the exception and passes it to the user's HardFault handler in r0.
// Depending on the stack mode in EXC_RETURN, fetches stack from either MSP or PSP.
core::arch::global_asm!(
    ".cfi_sections .debug_frame
    .section .HardFault.user, \"ax\"
    .global HardFault
    .type HardFault,%function
    .thumb_func
    .cfi_startproc
    HardFault:",
       "mov r0, lr
        movs r1, #4
        tst r0, r1
        bne 0f
        mrs r0, MSP
        b _HardFault
    0:
        mrs r0, PSP
        b _HardFault",
    ".cfi_endproc
    .size HardFault, . - HardFault",
);

The _HardFault function takes an ExcaptionFrame and calls the user-defined handler.

quote!(
    #(#cfgs)*
    #(#attrs)*
    #[doc(hidden)]
    #[export_name = "_HardFault"]
    unsafe extern "C" fn #tramp_ident(frame: &::cortex_m_rt::ExceptionFrame) {
        #ident(frame)
    }
    #f
    // ...
)

[!info] Preemptive Stack Framing
Refer to this documentation for further information

When the processor invokes an exception, it automatically pushes the following eight registers to the SP in the following order:

Program Counter (PC)

Processor Status Register (xPSR)

r0-r3

r12

Link Register (LR).

After the push, our stack pointer now points to the ExceptionFrame structure
![[stack-contents.svg]]
So passing the correct stack pointer to r0, is passing the frame argument to the handler function

The exception frame is defined as follows

/// Registers stacked (pushed onto the stack) during an exception.
#[derive(Clone, Copy)]
#[repr(C)]
pub struct ExceptionFrame {
    r0: u32,
    r1: u32,
    r2: u32,
    r3: u32,
    r12: u32,
    lr: u32,
    pc: u32,
    xpsr: u32,
}

If it is not using the trampoline mode, the handler invocation is simply a function call to the handler function.

quote!(
    #[export_name = "HardFault"]
    // Only emit link_section when building for embedded targets,
    // because some hosted platforms (used to check the build)
    // cannot handle the long link section names.
    #[cfg_attr(target_os = "none", link_section = ".HardFault.user")]
    #f
)

`NonMaskableInt`-errupts or `Other` interrupts

It is allowed to use static variables inside a handler. Every static variables are shared across each invocation of its handler.
It is achieved by converting static mut into mut &, and passing it as an argument to the interrupt handler (Its signature is extended to incorporate these extra arguments, and the original declarations are removed from the function).

We can use a code snipped of the interrupt macro to explain the process.

Firstly, we extract every static mut declaration in the block statements of the function

pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    let (statics, stmts) = match extract_static_muts(f.block.stmts.iter().cloned()) {
        Err(e) => return e.to_compile_error().into(),
        Ok(x) => x,
    };
    //...
}

/// Extracts `static mut` vars from the beginning of the given statements
fn extract_static_muts(
    stmts: impl IntoIterator<Item = Stmt>,
) -> Result<(Vec<ItemStatic>, Vec<Stmt>), parse::Error> {
    let mut istmts = stmts.into_iter();

    let mut seen = HashSet::new();
    let mut statics = vec![];
    let mut stmts = vec![];
    for stmt in istmts.by_ref() {
        match stmt {
            Stmt::Item(Item::Static(var)) => match var.mutability {
                syn::StaticMutability::Mut(_) => {
                    if seen.contains(&var.ident) {
                        return Err(parse::Error::new(
                            var.ident.span(),
                            format!("the name `{}` is defined multiple times", var.ident),
                        ));
                    }

                    seen.insert(var.ident.clone());
                    statics.push(var);
                }
                _ => stmts.push(Stmt::Item(Item::Static(var))),
            },
            _ => {
                stmts.push(stmt);
                break;
            }
        }
    }

    stmts.extend(istmts);

    Ok((statics, stmts))
}

/// An argument in a function signature: the `n: usize` in `fn f(n: usize)`.
pub enum FnArg {
    /// The `self` argument of an associated method.
    Receiver(Receiver),
    /// A function argument accepted by pattern and type.
    Typed(PatType),
}

pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    f.sig.inputs.extend(statics.iter().map(|statik| {
        let ident = &statik.ident;
        let ty = &statik.ty;
        let attrs = &statik.attrs;
        syn::parse::<FnArg>(quote!(#[allow(non_snake_case)] #(#attrs)* #ident: &mut #ty).into())
            .unwrap()
    }));
    //...
}

The arguments are constructed in a block which evaluates to the &mut value

pub fn interrupt(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    let resource_args = statics
        .iter()
        .map(|statik| {
            let (ref cfgs, ref attrs) = extract_cfgs(statik.attrs.clone());
            let ident = &statik.ident;
            let ty = &statik.ty;
            let expr = &statik.expr;
            quote! {
                #(#cfgs)*
                {
                    #(#attrs)*
                    static mut #ident: #ty = #expr;
                    &mut #ident
                }
            }
        })
        .collect::<Vec<_>>();

    // ...
}

The final layout of the code generated

pub fn exception(args: TokenStream, input: TokenStream) -> TokenStream {
    // ...
    quote!(
        #(#cfgs)*
        #(#attrs)*
        #[doc(hidden)]
        #[export_name = #ident_s]
        pub unsafe extern "C" fn #tramp_ident() {
            #ident(
                #(#resource_args),*
            )
        }

        #f
    )
    .into()
    // end of function
}

2.5.3 Exception Vector Table

To construct a vector table, we declare a slice with 14 entries of such Vectors, and place it in the .vector_table.exceptions section, which is defined in the linker script.

The entries to the exception vector tables are stored in__EXCEPTIONS (apart from the two above-mentioned entries)

#[cfg_attr(cortex_m, link_section = ".vector_table.exceptions")]
#[no_mangle]
pub static __EXCEPTIONS: [Vector; 14] = [
    // Exception 2: Non Maskable Interrupt.
    Vector {
        handler: NonMaskableInt,
    },
    // Exception 3: Hard Fault Interrupt.
    Vector { handler: HardFault },
    // Exception 4: Memory Management Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: MemoryManagement,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 5: Bus Fault Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector { handler: BusFault },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 6: Usage Fault Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: UsageFault,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // Exception 7: Secure Fault Interrupt [only on Armv8-M].
    #[cfg(armv8m)]
    Vector {
        handler: SecureFault,
    },
    #[cfg(not(armv8m))]
    Vector { reserved: 0 },
    // 8-10: Reserved
    Vector { reserved: 0 },
    Vector { reserved: 0 },
    Vector { reserved: 0 },
    // Exception 11: SV Call Interrupt.
    Vector { handler: SVCall },
    // Exception 12: Debug Monitor Interrupt [not on Cortex-M0 variants].
    #[cfg(not(armv6m))]
    Vector {
        handler: DebugMonitor,
    },
    #[cfg(armv6m)]
    Vector { reserved: 0 },
    // 13: Reserved
    Vector { reserved: 0 },
    // Exception 14: Pend SV Interrupt [not on Cortex-M0 variants].
    Vector { handler: PendSV },
    // Exception 15: System Tick Interrupt.
    Vector { handler: SysTick },
];

These handler symbols are by default the DefaultHandler, as declared in the linker script

PROVIDE(NonMaskableInt = DefaultHandler);
PROVIDE(MemoryManagement = DefaultHandler);
PROVIDE(BusFault = DefaultHandler);
PROVIDE(UsageFault = DefaultHandler);
PROVIDE(SecureFault = DefaultHandler);
PROVIDE(SVCall = DefaultHandler);
PROVIDE(DebugMonitor = DefaultHandler);
PROVIDE(PendSV = DefaultHandler);
PROVIDE(SysTick = DefaultHandler);

These are their signatures in rust

extern "C" {
    fn Reset() -> !;
    fn NonMaskableInt();
    fn HardFault();
    #[cfg(not(armv6m))]
    fn MemoryManagement();
    #[cfg(not(armv6m))]
    fn BusFault();
    #[cfg(not(armv6m))]
    fn UsageFault();
    #[cfg(armv8m)]
    fn SecureFault();
    fn SVCall();
    #[cfg(not(armv6m))]
    fn DebugMonitor();
    fn PendSV();
    fn SysTick();
}

2.6 External Interrupts

[!info] NVIC: Nested Vectored Interrupt Controller
All external interrupts are configured via the NCIV peripheral

![[Nested-vectored-interrupt-controller-NVIC-ARM-CortexM-microcontrollers.webp]]

2.6.1 External Interrupt Handlers

The codegen for external interrupt handlers are more or less the same for Other interrupts.
For more information, please refer to the Interrupt Macro Documentation

2.6.2 External Interrupt Vector Table

It is initialised all interrupt handlers to the DefaultHandler declared in src/lib.rs.

#[cfg(all(any(not(feature = "device"), test), not(armv6m)))]
#[cfg_attr(cortex_m, link_section = ".vector_table.interrupts")]
#[no_mangle]
pub static __INTERRUPTS: [unsafe extern "C" fn(); 240] = [{
    extern "C" {
        fn DefaultHandler();
    }

    DefaultHandler
}; 240];

RTIC 在 Blue Pill 上的点灯案例

Jens — Fri, 05 Apr 2024 14:03:41 +0000

前提条件可以参考这篇文章的第一章节

1. 代码解读

TODO

2. 写入启动

我们 clone RTIC Example 仓库，并进入 rtic_v1 目录下的 stm32f1_bluepill_blinky 目录

git clone https://github.com/rtic-rs/rtic-examples
cd rtic-exmaples/rtic_v1/stm32f1_bluepill_blinky/

我们进入 .embed.toml 文件，将 chip = “STM32F103" 改为更加具体的芯片版本，在这里我们使用的是 "STM32F103C8T6"，所以改为 chip = "STM32F103C8"，否则会出现 ambiguous match for specified chip name 错误

我们现在连接 Blue Pill，使用 cargo embed 编译项目并写入开发板

cargo embed --release

Debugging

出现 JtagNoDeviceConnected 怎么办？

我们尝试使用 st-info --descr 命令得到的结果是 unknown，这说明我们的开发板并没有被正确识别，经过以下尝试后设备得以识别并成功写入闪灯示例：

将 ST-Link 重新插入
使用 reset 按键重置安装板
使用 st-flash erase 命令格式化开发板：注意在重置状态下使用

现在点灯示例能够成功运行了！

Embassy 在 Blue Pill 上的点灯案例

Jens — Fri, 05 Apr 2024 07:38:59 +0000

这篇文章旨在尝试将 Embassy 的 blinky 案例在 Blue Pill (STM32F103C8T6）开发板上运行，它将记录所需要的依赖和常见问题的解决方法

本文参考了 Jonathan Klimt 的环境配置

系统环境: Ubuntu 22.04.4 (6.5.0-26-generic)

1. 前提

假设已经安装 rust-up 和 build-essential，有正常的 Rust 编译环境。当前使用的 Rust Toolchian 版本为 1.77.1（2024-03-27），如果出现问题可以尝试使用这个 Toolchain 版本看看问题是否消失。

1.1 依赖库安装

sudo apt install -y pkg-config libudev-dev libusb-1.0 libftdil-debv

1.2 `probe-rs` Toolkit

我们安装 probe-rs，其中包含了 probe-rs，cargo-flash，cargo-embed 等常用工具

cargo install probe-rs --features cli

1.3 ARM Cortex-m toolchain

这是进行交叉编译需要的库

sudo apt install binutils-arm-none-eabi

1.4 连接设备

我们需要安装 OpenOCD 来对设备进行快速烧录和调试

sudo apt-get install openocd

安装完成后，我们尝试使用 OpenOCD 对我们的 ST-Link 设备进行探测。我们先查看 ST-Link 连接器是否被时被识别，我们使用 lsusb | grep ST 命令对它进行查找

说明我们已经成功连接了，这时我们通过 OpenOCD 来探测设备是否工作正常

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg

我们注意到有错误信息，这是因为这个型号（STM32F103C8T6）的芯片是仿制版，其 CPU tap id 被修改，请见这个讨论。我们将 OpenOCD 安装目录（通常为 /usr/share/openocd）下 scripts/target 的 stm32f1x.cfg 中的 0x1ba01477 改为 0x2ba01477。请注意将原始文件保存，以免需要恢复。

我们现在能够成功连接并且识别开发板了

1.5 ST-Link Tools

我们安装 st-link tools 便于我们对开发板进行快速的格式化和烧录，这样能够使得我们绕开 cargo-embed 工具，能够更清楚地看到错误信息，并且更灵活。

我们下载 stlink-1.8.0_amd64.deb 或任何版本的 Debian 包。接下来在下载位置使用 sudo apt install ./{file-name.deb} 进行安装。这样不需要我们编译。

安装完成后使用 st-info --descr 进行检查是否正常

我们可以尝试使用 st-erase 对设备进行格式化（慎重），但是可能会出现 "Flash Memory is Write Protected" 提示，这是因为 STM32 芯片的写保护措施。如果我们使用 "ST-Link Tools" 直接使用 cargo embed 命令，只会在写入 Page 0 时报错，但是不会写出错误原因。

现在我们可以使用 Windows 下的 ST-Link Utility 软件对其进行解锁。

首先连接设备，在 ST-Link Utility 中找到 Target -> Connect

连接完成后选择 Target -> Option Bytes

在这里我们关闭 Read Out Protection （如果没有关闭）

我们反选所有的 Flash 扇区保护

最后点击右下角 Apply 应用设置，现在开发板的读写保护已经被关闭了

2. Embassy 案例

我们 clone Embassy 项目并进入 STM32F1x 的示例下

2.1 代码理解

使用 Embassy 框架使得写一个任务变得十分简单。我们使用异步关键词 async 修饰这个函数，并且使用 embassy_executor::main 来告诉编译器这个是主任务。
我们通过调用 embassy_stm32::init 函数初始化芯片和外围设备，该函数返回可用的外围设备对象（记为 p）

#[embassy_executor::main]
async fn main(_spawner: Spawner) {
    let p = embassy_stm32::init(Default::default());
}

接下来我们可以通过创建Output对象获得 PC13 这个引脚的控制，最后在一个循环中将这个引脚置高，等待一段时间再置低。
这里简单说明：Timer::after_millis 函数返回一个 Future 对象，我们在这里使用 .await 会放弃CPU使用权并交还给执行器。在时钟过期后，程序将从这里被恢复执行。

#[embassy_executor::main]
async fn main(_spawner: Spawner) {
    let p = embassy_stm32::init(Default::default());
    info!("Hello World!");

    let mut led = Output::new(p.PC13, Level::High, Speed::Low);

    loop {
        info!("high");
        led.set_high();
        Timer::after_millis(300).await;

        info!("low");
        led.set_low();
        Timer::after_millis(300).await;
    }
}

2.2 烧录运行

git clone https://github.com/embassy-rs/embassy.git
cd embassy/examples/stm32f1

现在使用 cargo run 进行编译和写入

cargo run --bin blinky --release

在写入完成后 Blue Pill 就能够闪灯了！

对于 Embassy 框架的探索

Jens — Fri, 05 Apr 2024 06:43:35 +0000

1. 什么是 Embassy

Embassy 使用 Rust 语言的 async / .await 元语实现，本质上来说是一个 Rust异步运行时（Runtime），通过实现 Rust 提供的接口加上硬件抽象层(HAL) 支持对嵌入式设备的的协助式多任务支持。

根据 Dion 对 FreeRTOS 和 Embassy 的比较，Embassy 在中断时间，中断延迟，程序大小等方面表现相当不错。

2. Rust 对 Zero-cost `async`/`.await` 的探索

因为 Embassy 基于 Rust 提供的异步抽象，我们先对 Rust 的异步抽象概念进行解释。内容参考了 OS-Blog 中 Async/Await 的理解

2.1 `Future` 对象

Future 表明了一个最终会完成计算的值，一个 Future 只定义了一个计算过程，但是不会开始计算，需要通过运行时不断通过 Future::poll 对它进行执行。

它的接口定义为

pub trait Future {
    type Output;

    // Required method
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

其中 poll 为其核心函数，我们将它理解为 “try to make some progress”。每一次对 Future::poll 的调用返回一个 Poll 作为结果，它被定义为

pub enum Poll<T> {
    Ready(T),
    Pending,
}

当返回结果为 Poll::Ready 时，其元组的内容为计算值，表示这个 Future 已经完成，当返回内容为 Poll::Pending 时，表示仍为进行完成，需要再次调用 Future::poll。至于在什么时候调用就是像 Embassy 这样的运行时决定了。

我们需要注意到 Future::poll 的函数定义，其中第一个参数为 Pin<&mut Self>，第二个参数为 &mut Context 的执行上下文。我们下面对它们进行一一分析。

self: Pin<&mut Self> 为一个 self 对象，这里使用的 arbitrary self type 将 self 范化成一个 “可以通过一系列解引用得到 self 的对象“，例如

fn do_something(self: Rc<Self>);
fn do_something(self: Arc<Self>);
fn do_something(self: Box<Self>);
fn do_something(self: MutexGuard<Self>);

2.2 移动/地址不敏感类型

对于更详细的解释，可以参照 Rust 官方文档

我们需要注意到 Pin<Ptr> 这个对象，它能够保证对象内部的内容不会被移动，因为在异步Rust中很多状态会对自己的某个 field 或自己进行自引用 (self-reference)，因为编译器不能在编译时分辨出一个类型是否包含自引用，所以我们通过 Pin<Ptr> 来保证：它的指向对象 要么永远不会移动，要么实现 Unpin (i.e. 对移动不敏感）

我们接下来举例说明对移动敏感的类型：

对于一个类型，它有一个数组，并且有一个指向数组第一个元素的指针，定义如下

struct AddressSensitiveType {
    data: [u8; 1024],
    first_element: *const u8,
}

如果我们在栈上初始化（局部变量）后希望将它通过 Box 移动到堆空间 (recall: 对于 Copy trait 只会进行 bitwise copy，其 first_element 仍指向栈的空间的无效的 data，而不是移动后的堆空间的 data。就如下图展示的：

移动前

移动后

需要注意，Unpin 是一个自动接口 (auto trait)，在编译器眼中，一个类型的任意一个 field 如果实现 !Unpin，整个类型为 !Unpin（不能对其进行 Unpin, i.e. 对移动敏感）我们可以通过一个无大小的标记 field 对这个类型进行标记，这个标记实现了 !Unpin

struct AddressSensitiveType {
    data: [u8; 1024],
    first_element: *const u8,
    _pin: PhantomPinned
}

Pin<Ptr> 的实现十分简单，即对任何 Ptr: Deref 实现解引用，但仅对实现了 Unpin 的 Ptr:Target 进行可变解引用。

impl<Ptr: DerefMut<Ptr::Target: Unpin>> DerefMut for Pin<Ptr> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut *self.ptr
    }
}

我们仍然可以通过 unsafe 方法得到对类型的可变引用，但是我们需要保证不会对地址敏感内容进行修改和对这个类型进行移动

2.3 `Future` 执行上下文

当前的执行上下文仅用于保存 Waker 对象，我们通过 Waker 对象唤醒运行时，以免它进行忙等消耗资源。Waker 通过执行器 Executor 创建，这样我们才知道唤醒那一个 Executor (可以有多个执行器并行执行，这需要线程抽象)。Waker 实现了 Clone, Send 和 Sync 确保它能够在不同线程间传递。

当我们返回 Poll::Pending 时需要保证存在一个 Waker 在这个 Future 准备好被 poll again 时唤醒执行器。否则它将不会再被执行。

需要注意，每次我们执行一次 Feature::poll 后都需要更新执行上下文/Waker，因为一个 Future 可以在多个 Executor 间移动，我们需要保证后面 Waker 唤醒的是最新的一个 Executor 而不是移动之前的 Executor（我们不进行细节上更深入的讨论）。

pub struct Context<'a> {
    waker: &'a Waker,
    // Ensure we future-proof against variance changes by forcing
    // the lifetime to be invariant (argument-position lifetimes
    // are contravariant while return-position lifetimes are
    // covariant).
    _marker: PhantomData<fn(&'a ()) -> &'a ()>,
    // Ensure `Context` is `!Send` and `!Sync` in order to allow
    // for future `!Send` and / or `!Sync` fields.
    _marker2: PhantomData<*mut ()>,
}

其中 Waker 是对 RawWaker 的一个封装，RawWaker 内部实现机制为虚表(vtable)，对不同的操作调用函数进行保存。对 Waker 的唤醒被代理为对 RawWaker保存函数的调用。

pub struct Waker {
    waker: RawWaker,
}

impl Waker {
    pub fn wake(self) {
        // The actual wakeup call is delegated through a virtual function call
        // to the implementation which is defined by the executor.
        let wake = self.waker.vtable.wake;
        let data = self.waker.data;

        // Don't call `drop` -- the waker will be consumed by `wake`.
        crate::mem::forget(self);

        // SAFETY: This is safe because `Waker::from_raw` is the only way
        // to initialize `wake` and `data` requiring the user to acknowledge
        // that the contract of `RawWaker` is upheld.
        unsafe { (wake)(data) };
    }

    pub fn wake_by_ref(&self) {
        // The actual wakeup call is delegated through a virtual function call
        // to the implementation which is defined by the executor.

        // SAFETY: see `wake`
        unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
    }

    // ...
}

对于 RawWaker 的实现我们简单给出源码

pub struct RawWaker {
    /// A data pointer, which can be used to store arbitrary data as required
    /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
    /// that is associated with the task.
    /// The value of this field gets passed to all functions that are part of
    /// the vtable as the first parameter.
    data: *const (),
    /// Virtual function pointer table that customizes the behavior of this waker.
    vtable: &'static RawWakerVTable,
}

pub struct RawWakerVTable {
    /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
    /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
    ///
    /// The implementation of this function must retain all resources that are
    /// required for this additional instance of a [`RawWaker`] and associated
    /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
    /// of the same task that would have been awoken by the original [`RawWaker`].
    clone: unsafe fn(*const ()) -> RawWaker,

    /// This function will be called when `wake` is called on the [`Waker`].
    /// It must wake up the task associated with this [`RawWaker`].
    ///
    /// The implementation of this function must make sure to release any
    /// resources that are associated with this instance of a [`RawWaker`] and
    /// associated task.
    wake: unsafe fn(*const ()),

    /// This function will be called when `wake_by_ref` is called on the [`Waker`].
    /// It must wake up the task associated with this [`RawWaker`].
    ///
    /// This function is similar to `wake`, but must not consume the provided data
    /// pointer.
    wake_by_ref: unsafe fn(*const ()),

    /// This function gets called when a [`Waker`] gets dropped.
    ///
    /// The implementation of this function must make sure to release any
    /// resources that are associated with this instance of a [`RawWaker`] and
    /// associated task.
    drop: unsafe fn(*const ()),
}

2.4 `Future` 是一个状态机

我们并没有在执行上下文中保存寄存器内容，每个任务也没有独立的栈，这样虽然大大减少了分配任务和上下文切换需要的时间，但我们如何保存这些任务的执行状态，使得在每次放弃执行和继续执行时的状态相同呢？这需要 Rust 编译器的支持。

首先我们将探讨 Future 是如何可以被嵌套形成多种执行逻辑的。

因为对于执行器来说，每个 Future 都可以被调度执行，如果我们希望先执行 A 在执行 B 应该如何表示呢？我们仍然用一个新的 Future 表示，定义为 AndThen。我们将尝试用伪代码实现它，尽管其中有很多细节没有考虑

struct<F> AndThenState {
    WaittingOnFirstFut,
    WaittingOnSecondFut {
        first_fut_result: F 
    },
    Done,
}

struct<F, S> AndThen {
    first_fut: Future<F>,
    second_fut: Future<S>,
    state: AndThenState 
}

impl<F, S> Future for AndThen {
      type Output = S；
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        match self.state {
            AndThenState::WaittingOnFirstFut => {
                match self.first_fut.poll(...) {
                    Poll::Pending => {
                        do_something_with_the_waker();
                        return Poll::Pending,
                    }
                    Poll::Ready(reuslt) => {
                        self.state = AndThenState::WrittingOnSecondFut {
                            first_fut_result = result
                        };
                        do_something_with_the_waker();
                        return Poll::Pending;
                    }
                }
            },
            AndThenState::WaittingOnSecondFut => {
                match self.second_fut.poll(...) {
                    Poll::Pending => {
                        do_some_thing_with_the_waker();
                        return Poll::Pending,
                    }
                    Poll::Ready(result) => {
                        self.state = AndThenState::Done;
                        return Poll::Ready(result)
                    }
                }
            },
            AndThenState::Done => {
                panic!("Already Done!")
            }
        }
    }
}

我们其实创建了一个状态机，在每一个状态中保存了这个状态执行所需要的内容。对于 Rust 编译器来说，每一个 .await 就是一个状态的节点，我们将在这里保存当前状态并将执行权交还执行器。下面的例子来自于 OS Blog

async fn example(min_len: usize) -> String {
    let content = async_read_file("foo.txt").await;
    if content.len() < min_len {
        content + &async_read_file("bar.txt").await
    } else {
        content
    }
}

编译器将生成一个有限状态机对每个状态进行保存。至于这些状态依赖的变量怎么得到，怎么裁减掉对于这个状态无用的变量等问题超出了本文的范畴，这将由编译器决定。

状态转换图如下

我们可以生成以下四个状态。注意到 WaitingOnBarTxtState 对 min_len 并没有需要，它不会保存在这个状态中。但是因为会使用 constent + &async_read_file("bar.txt")，将 content保存下来。

这是可能的编译器生成的状态

// The compiler-generated state structs:

struct StartState {
    min_len: usize,
}

struct WaitingOnFooTxtState {
    min_len: usize,
    foo_txt_future: impl Future<Output = String>,
}

struct WaitingOnBarTxtState {
    content: String,
    bar_txt_future: impl Future<Output = String>,
}

struct EndState {}

于是我们可以创建状态机

enum ExampleStateMachine {
    Start(StartState),
    WaitingOnFooTxt(WaitingOnFooTxtState),
    WaitingOnBarTxt(WaitingOnBarTxtState),
    End(EndState),
}

我们需要对原代码分段加入不同的状态，并在执行完成这一段代码后改变状态并保存下一个状态依赖的内容。因为编译器生成条件语句时会将它转变为 goto, 这对于实现状态机十分友好。

impl Future for ExampleStateMachine {
    type Output = String; // return type of `example`

    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
        loop {
            match self { // TODO: handle pinning
                ExampleStateMachine::Start(state) => {
                    // from body of `example`
                    let foo_txt_future = async_read_file("foo.txt");
                    // `.await` operation
                    let state = WaitingOnFooTxtState {
                        min_len: state.min_len,
                        foo_txt_future,
                    };
                    *self = ExampleStateMachine::WaitingOnFooTxt(state);
                }
                ExampleStateMachine::WaitingOnFooTxt(state) => {
                    match state.foo_txt_future.poll(cx) {
                        Poll::Pending => return Poll::Pending,
                        Poll::Ready(content) => {
                            // from body of `example`
                            if content.len() < state.min_len {
                                let bar_txt_future = async_read_file("bar.txt");
                                // `.await` operation
                                let state = WaitingOnBarTxtState {
                                    content,
                                    bar_txt_future,
                                };
                                *self = ExampleStateMachine::WaitingOnBarTxt(state);
                            } else {
                                *self = ExampleStateMachine::End(EndState);
                                return Poll::Ready(content);
                            }
                        }
                    }
                }
                ExampleStateMachine::WaitingOnBarTxt(state) => {
                    match state.bar_txt_future.poll(cx) {
                        Poll::Pending => return Poll::Pending,
                        Poll::Ready(bar_txt) => {
                            *self = ExampleStateMachine::End(EndState);
                            // from body of `example`
                            return Poll::Ready(state.content + &bar_txt);
                        }
                    }
                }
                ExampleStateMachine::End(_) => {
                    panic!("poll called after Poll::Ready was returned");
                }
            }
        }
    }
}

2.5 执行器 `Executor`

执行器用来执行多个 Future 计算，我们将每一个 Future 计算的执行作为一个 Task 任务，执行器管理对每一个任务的调度执行。

需要清楚，执行器是非抢占性的，每个任务必须自觉的将执行权归还给执行器（返回 Poll::Pending），执行器才能进行它的工作，否则如果一个 Future 被阻塞或者一直循环，其他所有的任务都不能被继续执行（假设单个执行器）。故我们在使用系统调用时（如果操作系统）不要选择阻塞调用。

协助式多任务

Each future that is added to the executor is basically a cooperative task.

Instead of using an explicit yield operation, futures give up control of the CPU core by returning Poll::Pending (or Poll::Ready at the end).

There is nothing that forces futures to give up the CPU. If they want, they can never return from poll, e.g., by spinning endlessly in a loop.

Since each future can block the execution of the other futures in the executor, we need to trust them to not be malicious.

Futures internally store all the state they need to continue execution on the next poll call. With async/await, the compiler automatically detects all variables that are needed and stores them inside the generated state machine.

Only the minimum state required for continuation is saved.

Since the poll method gives up the call stack when it returns, the same stack can be used for polling other futures.

3. Embassy 的运行时（Runtime）实现

下面的解释参考了 Embassy Documentation 和 Embassy 源码

我们现在探讨 Embassy 对任务的抽象 (Rust aysnc API 之外)

3.1 `TaskStorage` 用来封装任务状态机和调度

embassy_executor::task macro 会静态分配一个 TaskStorage 数组，这个数组保存了未初始化的任务（TaskHeader::state = !STATE_SPAWNED)

pub struct TaskPool<F: Future + 'static, const N: usize> {
    pool: [TaskStorage<F>; N],
}

每一个 TaskStorage 保存了一个 TaskHeader 和 Future。

pub struct TaskStorage<F: Future + 'static> {
    raw: TaskHeader,
    future: UninitCell<F>, // Valid if STATE_SPAWNED
}

/// An uninitialized [`TaskStorage`].
pub struct AvailableTask<F: Future + 'static> {
    task: &'static TaskStorage<F>,
}

3.2 `TaskHeader` 用来封装任务调度

其中 TaskHeader 起到了一个保存执行调度状态和函数逻辑的功能

其中 State 为程序调度状态，分别有 spawned, run_queued, timer_queued，状态可以叠加。
run_queue_item 保存运行队列中的下一个任务，是运行队列的的一个节点

RunQueue → TaskHeader (pointer) → TaskRef (pointer, TaskHeader::run_queue_item) → TaskHeader (pointer) → …
executor 指向执行器
poll_fn 执行函数，这里保存任务的执行逻辑，这个函数会被调用并且完整执行（这个逻辑可以是一个对状态机的一次执行，我们将在后面对它进行解释)

/// Raw task header for use in task pointers.
pub(crate) struct TaskHeader {
    pub(crate) state: State,
    pub(crate) run_queue_item: RunQueueItem,
    pub(crate) executor: SyncUnsafeCell<Option<&'static SyncExecutor>>,
    poll_fn: SyncUnsafeCell<Option<unsafe fn(TaskRef)>>,

    #[cfg(feature = "integrated-timers")]
    pub(crate) expires_at: SyncUnsafeCell<u64>,
    #[cfg(feature = "integrated-timers")]
    pub(crate) timer_queue_item: timer_queue::TimerQueueItem,
}

TaskRef 是对 TaskHeader 的引用包裹，存有指向 TaskHeader 的非空指针

/// This is essentially a `&'static TaskStorage<F>` where the type of the future has been erased.
#[derive(Clone, Copy)]
pub struct TaskRef {
    ptr: NonNull<TaskHeader>,
}

3.3 `Executor`s

arch Executor

这里对每个支持的 CPU 架构都进行了 Executor 设计，常通过中断唤醒

// risc-v 32 executor
pub struct Executor {
    inner: raw::Executor,
    not_send: PhantomData<*mut ()>,
}

raw Executor

#[repr(transparent)]
pub struct Executor {
    pub(crate) inner: SyncExecutor,

    _not_sync: PhantomData<*mut ()>,
}

SyncExecutor

pub(crate) struct SyncExecutor {
    run_queue: RunQueue,
    pender: Pender,

    #[cfg(feature = "integrated-timers")]
    pub(crate) timer_queue: timer_queue::TimerQueue,
    #[cfg(feature = "integrated-timers")]
    alarm: AlarmHandle,
}

所有的poll 逻辑在 SyncExecutor 中被实现，其实现很简单，将运行队列中所有的任务出队（并在这时更新在 TaskHeader 中的任务状态为出队, i.e. run_queued 位置 0）并执行任务

注意到任务并不会被重新放回 RunQueue，如果开启时钟，我们可以将超时的任务重新放入 RunQueue，在 SyncExecutor::timer_queue::dequeue_expired 中执行 wake_task_no_pend 将这些任务在 SyncExecutor::poll 执行 SyncExecutor::run_queue::dequeue_all 前将这些任务放入运行队列 run_queue

pub fn wake_task_no_pend(task: TaskRef) {
    let header = task.header();
    if header.state.run_enqueue() {
        // We have just marked the task as scheduled, so enqueue it.
        unsafe {
            let executor = header.executor.get().unwrap_unchecked();
            executor.run_queue.enqueue(task);
        }
    }
}

在任务执行后，再将这个任务加入时钟队列 SyncExecutor::timer_queue （此时已经移出运行队列）

pub(crate) unsafe fn update(&self, p: TaskRef) {
    let task = p.header();
    if task.expires_at.get() != u64::MAX {
        if task.state.timer_enqueue() {
            task.timer_queue_item.next.set(self.head.get());
            self.head.set(Some(p));
        }
    }
}

下面是执行逻辑

impl SyncExecutor {
    /// # Safety
    ///
    /// Same as [`Executor::poll`], plus you must only call this on the thread this executor was created.
    pub(crate) unsafe fn poll(&'static self) {
        #[cfg(feature = "integrated-timers")]
        embassy_time_driver::set_alarm_callback(self.alarm, Self::alarm_callback, self as *const _ as *mut ());

        #[allow(clippy::never_loop)]
        loop {
            #[cfg(feature = "integrated-timers")]
            self.timer_queue
                .dequeue_expired(embassy_time_driver::now(), wake_task_no_pend);

            self.run_queue.dequeue_all(|p| {
                let task = p.header();

                #[cfg(feature = "integrated-timers")]
                task.expires_at.set(u64::MAX);

                if !task.state.run_dequeue() {
                    // If task is not running, ignore it. This can happen in the following scenario:
                    //   - Task gets dequeued, poll starts
                    //   - While task is being polled, it gets woken. It gets placed in the queue.
                    //   - Task poll finishes, returning done=true
                    //   - RUNNING bit is cleared, but the task is already in the queue.
                    return;
                }

                #[cfg(feature = "rtos-trace")]
                trace::task_exec_begin(p.as_ptr() as u32);

                // Run the task
                task.poll_fn.get().unwrap_unchecked()(p);

                #[cfg(feature = "rtos-trace")]
                trace::task_exec_end();

                // Enqueue or update into timer_queue
                #[cfg(feature = "integrated-timers")]
                self.timer_queue.update(p);
            });

            #[cfg(feature = "integrated-timers")]
            {
                // If this is already in the past, set_alarm might return false
                // In that case do another poll loop iteration.
                let next_expiration = self.timer_queue.next_expiration();
                if embassy_time_driver::set_alarm(self.alarm, next_expiration) {
                    break;
                }
            }

            #[cfg(not(feature = "integrated-timers"))]
            {
                break;
            }
        }

        #[cfg(feature = "rtos-trace")]
        trace::system_idle();
    }
}

其中 RunQueue::dequeue_all 是一个安全抽象，实现的一个 non-blocking 链表，其算法在这里不做讨论

impl RunQueue {
        /// Empty the queue, then call `on_task` for each task that was in the queue.
    /// NOTE: It is OK for `on_task` to enqueue more tasks. In this case they're left in the queue
    /// and will be processed by the *next* call to `dequeue_all`, *not* the current one.
    pub(crate) fn dequeue_all(&self, on_task: impl Fn(TaskRef)) {
        // Atomically empty the queue.
        let ptr = self.head.swap(ptr::null_mut(), Ordering::AcqRel);

        // safety: the pointer is either null or valid
        let mut next = unsafe { NonNull::new(ptr).map(|ptr| TaskRef::from_ptr(ptr.as_ptr())) };

        // Iterate the linked list of tasks that were previously in the queue.
        while let Some(task) = next {
            // If the task re-enqueues itself, the `next` pointer will get overwritten.
            // Therefore, first read the next pointer, and only then process the task.
            // safety: there are no concurrent accesses to `next`
            next = unsafe { task.header().run_queue_item.next.get() };

            on_task(task);
        }
    }
}

3.4 `Pender`

Pender 表示执行器在对每一个能够执行的任务执行 poll 过程中有其他任务能够继续被执行，如在这个过程中 I/O 设备已经准备好缓存了。
这样我们在执行完成一遍 poll 后不进行等待（如等待中断），直接再进行一遍 poll，因为已经有任务准备好了可以进一步执行。

Pender 是 arch specific 函数，在每一个 arch 下都有对 __pender 的实现，定义如下：

impl Pender {
    pub(crate) fn pend(self) {
        extern "Rust" {
            fn __pender(context: *mut ());
        }
        unsafe { __pender(self.0) };
    }
}

我们先了解一下 Pender 会在什么时候被调用
在开启时钟时，会在每次时钟超时后进行调用。我们在每次 SyncExecutor::poll 时会调用 set_alarm_callback，这里就会将 SyncExecutor::alarm_callback 函数传入作为回调函数，将当前 SyncExecutor指针传入作为上下文。

impl SyncExecutor {
        pub(crate) unsafe fn poll(&'static self) {
        #[cfg(feature = "integrated-timers")]
        embassy_time_driver::set_alarm_callback(self.alarm, Self::alarm_callback, self as *const _ as *mut ());
                // polling logic ...
        }
}

impl SyncExecutor {
        #[cfg(feature = "integrated-timers")]
    fn alarm_callback(ctx: *mut ()) {
        let this: &Self = unsafe { &*(ctx as *const Self) };
        this.pender.pend();
    }
}

我们查看 RISC-V 32 下的实现

/// global atomic used to keep track of whether there is work to do since sev() is not available on RISCV
static SIGNAL_WORK_THREAD_MODE: AtomicBool = AtomicBool::new(false);

#[export_name = "__pender"]
fn __pender(_context: *mut ()) {
    SIGNAL_WORK_THREAD_MODE.store(true, Ordering::SeqCst);
}

暂时不知道 embassy 对 RISC-V 时中中断是怎么实现的，可能这段代码会在中断程序中执行，然后会在 U-Mode 触发中断

下面是 RISC-V 32 CPU 的 Executor 的执行实现，通过 wfi (wait for interrupt) 指令等待中断，在中断发生后就会执行。我们现在能够更加理解 SIGNAL_WORK_THREAD_MODE 与 Pender 的含义：如果在执行 poll 时出现中断，这个中断记号会被保存，在处理结束后会继续重新执行 poll，如果没有中断产生，就会进入低耗能的等待模式

pub struct Executor {
    inner: raw::Executor,
    not_send: PhantomData<*mut ()>,
}
impl Executor {
    pub fn run(&'static mut self, init: impl FnOnce(Spawner)) -> ! {
        init(self.inner.spawner());

        loop {
            unsafe {
                self.inner.poll();
                // we do not care about race conditions between the load and store operations, interrupts
                // will only set this value to true.
                critical_section::with(|_| {
                    // if there is work to do, loop back to polling
                    // TODO can we relax this?
                    if SIGNAL_WORK_THREAD_MODE.load(Ordering::SeqCst) {
                        SIGNAL_WORK_THREAD_MODE.store(false, Ordering::SeqCst);
                    }
                    // if not, wait for interrupt
                    else {
                        core::arch::asm!("wfi");
                    }
                });
                // if an interrupt occurred while waiting, it will be serviced here
            }
        }
    }
}

Q: Future 状态机的特性在 Embassy 中怎么体现？

我们会注意到，Embassy 将我们创建的 Future 状态机保存在了 TaskStorage 中（它在一个静态数组内）

这样我们就可以将状态机和调度解耦，执行器在 Embassy 中仅负责调度，即执行那个任务，唤醒那个任务等；对每个任务，它都保存成了一个状态机，对这个状态机的执行是通过调用任务相对应的 TaskHeader::poll_fn 进行执行，这个 poll_fn 对每个任务来说都是相同的, i.e. 是状态机的执行函数，与我们之前看到的 Rust 状态机执行类似。

pub struct TaskStorage<F: Future + 'static> {
    raw: TaskHeader,
    future: UninitCell<F>, // Valid if STATE_SPAWNED
}

我们在调用 Embassy 的执行器执行时会调用 task.poll_fn.get().unwrap_unchecked()(p)，我们接下来分析这个函数

这里的 task 是一个 TaskRef，指向一个 TaskHeader

pub(crate) struct TaskHeader {
    pub(crate) state: State,
    pub(crate) run_queue_item: RunQueueItem,
    pub(crate) executor: SyncUnsafeCell<Option<&'static SyncExecutor>>,
    poll_fn: SyncUnsafeCell<Option<unsafe fn(TaskRef)>>,

    #[cfg(feature = "integrated-timers")]
    pub(crate) expires_at: SyncUnsafeCell<u64>,
    #[cfg(feature = "integrated-timers")]
    pub(crate) timer_queue_item: timer_queue::TimerQueueItem,
}

Task创建的初始化代码我们可以在 TaskPool 中找到，原因我们会在后面讲解。这里我们注意这个函数，它初始化了 TaskHeader::poll_fn 函数的执行逻辑

fn initialize_impl<S>(self, future: impl FnOnce() -> F) -> SpawnToken<S> {
    unsafe {
        self.task.raw.poll_fn.set(Some(TaskStorage::<F>::poll));
        self.task.future.write_in_place(future);

        let task = TaskRef::new(self.task);

        SpawnToken::new(task)
    }
}

我们现在查看 TaskStorage::poll 的逻辑：这就是正统的 Future 状态机的一次执行模型（这个函数会被调用多次）

unsafe fn poll(p: TaskRef) {
    let this = &*(p.as_ptr() as *const TaskStorage<F>);
    let future = Pin::new_unchecked(this.future.as_mut());
    let waker = waker::from_task(p);
    let mut cx = Context::from_waker(&waker);
    match future.poll(&mut cx) {
        Poll::Ready(_) => {
            this.future.drop_in_place();
            this.raw.state.despawn();
            #[cfg(feature = "integrated-timers")]
            this.raw.expires_at.set(u64::MAX);
        }
        Poll::Pending => {}
    }
    // the compiler is emitting a virtual call for waker drop, but we know
    // it's a noop for our waker.
    mem::forget(waker);
}

我们可以借此机会通过了解 Timer 的案例来了解以下自定义 Future 的实现

这里，我们在返回 Poll::Pending 时就通知了时间队列 time_queue，让它在一段时间后调用 waker 对执行器进行唤醒

/// A future that completes at a specified [Instant](struct.Instant.html).
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Timer {
    expires_at: Instant,
    yielded_once: bool,
}

impl Unpin for Timer {}

impl Future for Timer {
    type Output = ();
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        if self.yielded_once && self.expires_at <= Instant::now() {
            Poll::Ready(())
        } else {
            embassy_time_queue_driver::schedule_wake(self.expires_at.as_ticks(), cx.waker());
            self.yielded_once = true;
            Poll::Pending
        }
    }
}

对于 schedule_wake 的实现，我们现在给出

它将它 TaskHeader::expires_at 重新设置，使得我们在 TimerQueue 中能够在指定时间被唤醒

我们可以基于上述SyncExecutor执行器的设计得到下面的执行流程

时钟中断 → Executor::run 的循环中先将超时任务出队执行器→ 任务需要重新设置 Timer：调用 schedule_wake 更新其 TaskHeader::expires_at → 执行结束，调用 TimerQueue::update(task)，如果 expires_at 仍有更新，重新加入等待队列 → …e

#[cfg(feature = "integrated-timers")]
impl embassy_time_queue_driver::TimerQueue for TimerQueue {
    fn schedule_wake(&'static self, at: u64, waker: &core::task::Waker) {
        let task = waker::task_from_waker(waker);
        let task = task.header();
        unsafe {
            let expires_at = task.expires_at.get();
            task.expires_at.set(expires_at.min(at));
        }
    }
}

4. Embassy 如何执行

我们对 Embassy 的实现做一个 high-level 的了解，通过 blinky 案例

#[embassy_executor::main]
async fn main(_spawner: Spawner) {
    let p = embassy_stm32::init(Default::default());
    info!("Hello World!");

    let mut led = Output::new(p.PC13, Level::High, Speed::Low);

    loop {
        info!("high");
        led.set_high();
        Timer::after_millis(300).await;

        info!("low");
        led.set_low();
        Timer::after_millis(300).await;
    }
}

为了方便我们了解 Embassy 到底干了什么，我们展开这个 macro

// Recursive expansion of main_cortex_m macro
// ===========================================

#[doc(hidden)]
async fn ____embassy_main_task(_spawner: Spawner) {
    {
        let p = embassy_stm32::init(Default::default());
        info!("Hello World!");
        let mut led = Output::new(p.PC13, Level::High, Speed::Low);
        loop {
            info!("high");
            led.set_high();
            Timer::after_millis(300).await;
            info!("low");
            led.set_low();
            Timer::after_millis(300).await;
        }
    }
}
fn __embassy_main(_spawner: Spawner) -> ::embassy_executor::SpawnToken<impl Sized> {
    const POOL_SIZE: usize = 1;
    static POOL: ::embassy_executor::_export::TaskPoolRef = ::embassy_executor::_export::TaskPoolRef::new();
    unsafe {
        POOL.get::<_, POOL_SIZE>()
            ._spawn_async_fn(move || ____embassy_main_task(_spawner))
    }
}
unsafe fn __make_static<T>(t: &mut T) -> &'static mut T {
    ::core::mem::transmute(t)
}
#[doc(hidden)]
#[export_name = "main"]
pub unsafe extern "C" fn __cortex_m_rt_main_trampoline() {
    __cortex_m_rt_main()
}
fn __cortex_m_rt_main() -> ! {
    let mut executor = ::embassy_executor::Executor::new();
    let executor = unsafe { __make_static(&mut executor) };
    executor.run(|spawner| {
        spawner.must_spawn(__embassy_main(spawner));
    })
}

简单的说，当执行交给 __cortex_m_rt_main 后，我们

新建一个执行器，并初始化任务池，并

将 ____embassy_main_task 生成的 Future 传递任务池（注意到这个函数被 async 修饰，调用这个函数得到的是 Future，函数逻辑并不会被执行，这是一个 syntactic suger）

这个功能通过调用 TaskPool::spawn_impl 于是调用 AvailableTask::initialize_impl 实现

impl<F: Future + 'static, const N: usize> TaskPool<F, N> {
    fn spawn_impl<T>(&'static self, future: impl FnOnce() -> F) -> SpawnToken<T> {
        match self.pool.iter().find_map(AvailableTask::claim) {
            Some(task) => task.initialize_impl::<T>(future),
            None => SpawnToken::new_failed(),
        }
    }
}

impl<F: Future + 'static> AvailableTask<F> {
    fn initialize_impl<S>(self, future: impl FnOnce() -> F) -> SpawnToken<S> {
        unsafe {
            self.task.raw.poll_fn.set(Some(TaskStorage::<F>::poll));
            self.task.future.write_in_place(future);

            let task = TaskRef::new(self.task);

            SpawnToken::new(task)
        }
    }
}

注意到 AvailableTask 代表一个任务池中没有被初始化的任务

pub struct AvailableTask<F: Future + 'static> {
    task: &'static TaskStorage<F>,
}

pub struct TaskStorage<F: Future + 'static> {
    raw: TaskHeader,
    future: UninitCell<F>, // Valid if STATE_SPAWNED
}

我们先通过任务池找到一个位置，再通过 AvailableTask::claim 函数占有这个位置，最后对这个位置进行初始化

我们需要注意到初始化中，我们设置 self.task.raw (TaskHeader) 中的任务逻辑设置为 TaskStorage::poll，我们检查这个函数

unsafe fn poll(p: TaskRef) {
    let this = &*(p.as_ptr() as *const TaskStorage<F>);
    let future = Pin::new_unchecked(this.future.as_mut());
    let waker = waker::from_task(p);
    let mut cx = Context::from_waker(&waker);
    match future.poll(&mut cx) {
        Poll::Ready(_) => {
            this.future.drop_in_place();
            this.raw.state.despawn();
            #[cfg(feature = "integrated-timers")]
            this.raw.expires_at.set(u64::MAX);
        }
        Poll::Pending => {}
    }
    // the compiler is emitting a virtual call for waker drop, but we know
    // it's a noop for our waker.
    mem::forget(waker);
}

我们注意到在 TaskStorage 中保存了我们的 async 逻辑，即 LED 点灯逻辑（在这个案例中），因为我们的 TaskStorage 生命周期为 'static 并且生成后（除非被删除）不会被移动，当然可以直接使用 unsafe 函数 Pin::new_unchecked 创建 Feature::poll 需要的参数 self: Pin<&mut Self>

我们接下来对这个 Feature 进行 poll 操作，这里就是 Rust 的异步接口了

注意到当 poll 返回 Poll::Pending 的时候我们不做任何事情，因为我们可以靠着中断来唤醒 Executor

这里对waker 使用 mem::forget 进行优化，因为 Waker 是一个接口，调用其析构函数会增加 overhead，因为我们知道这个 Waker 什么都不会做，我们使用 mem::forget 不调用其析构函数

最后调用 Executor::run 来启动执行器，注意到 Spawner 是对执行器的安全抽象，我们将不安全的代码封装在闭包外，闭包内传递这个抽象 (init: impl FnOnce(Spawner))

/// Handle to spawn tasks into an executor.
///
/// This Spawner can spawn any task (Send and non-Send ones), but it can
/// only be used in the executor thread (it is not Send itself).
///
/// If you want to spawn tasks from another thread, use [SendSpawner].
#[derive(Copy, Clone)]
pub struct Spawner {
    executor: &'static raw::Executor,
    not_send: PhantomData<*mut ()>,
}

impl Executor {
    /// Get a spawner that spawns tasks in this executor.
    ///
    /// It is OK to call this method multiple times to obtain multiple
    /// `Spawner`s. You may also copy `Spawner`s.
    pub fn spawner(&'static self) -> super::Spawner {
        super::Spawner::new(self)
    }
}

impl Executor {
    pub fn run(&'static mut self, init: impl FnOnce(Spawner)) -> ! {
        init(self.inner.spawner());
        // do polling in a loop...
    }
}

这里的 init 逻辑就是为执行器增加任务

executor.run(|spawner| {
    spawner.must_spawn(__embassy_main(spawner));
})

这里的 Spawner 和 SpawnToken 是 Embassy 对执行器和任务的安全抽象

pub fn must_spawn<S>(&self, token: SpawnToken<S>) {
    unwrap!(self.spawn(token));
}
pub fn spawn<S>(&self, token: SpawnToken<S>) -> Result<(), SpawnError> {
    let task = token.raw_task;
    mem::forget(token);
    match task {
        Some(task) => {
            unsafe { self.executor.spawn(task) };
            Ok(())
        }
        None => Err(SpawnError::Busy),
    }
}

pub struct SpawnToken<S> {
    raw_task: Option<raw::TaskRef>,
    phantom: PhantomData<*mut S>,
}

到此为止，Embassy 就能开始执行任务了

5. 总结

Embassy 是一个 Rust 异步运行时框架，高度结合了 Rust 语言对异步语法的优点。它借助编译器生成的状态机保存任务执行状态。它不是一个ROTS，并且不支持抢占式调度和优先级调度。由于不要求抢占式调度，它的执行是同步的（任务主动使用 .await, yeild 让出CPU，此时由Rust编译器生成状态保存的代码），不使用操作系统中常用的方法（上下文切换，独立栈）的方法保存任务进度（因为没有必要）。这大大减少了保存和恢复上下文的损耗，使得性能的以提高。在 Dion 的测试中，STM32F446 微控制器在 Embassy 的平均中断时间较 FreeRTOS 减少 51.0%，平均中断延迟较 FreeRTOS 减少 24.8%，平均线程时间较 FreeRTOS 减少 28.1%。

但是经过目前的理解和探索，并没有找到 Embassy 对抢占式优先级调度的证据，暂且认为它不支持抢占式优先级调度，这可能使得在一些场景下不太适用。

DEV Community: Jens

Embassy 下使用温湿度传感器

1. 接线方法

3.演示

Under the Hook - The Cortex Runtime

1. Memory Layout

1.1 Linker Script

Naming Conventions of Linker Symbols

Weak Aliasing at the Linker Script Level

Virtual and Load Memory Addresses

Code Section

Initialised Data Section

Uninitialised Data Section

Customisable Layout

2. The Booting Process

2.1 Initialising the Stack Pointer

Exception and Interrupt Handling

Vector Table

Activation of Vector Tables

Built-in Exceptions

Exception Handlers

Exception Vector Table

External Interrupts

External Interrupt Handlers

External Interrupt Vector Table

Default Handlers

对 RTIC 框架的探索

1. RTIC 简介

2. SRP 规则

3. ARM Cortex-M 中断机制

3.1 NVIC 模块

3.2 中断向量表 (Vector Table)

4. Rust 异步状态机

5. 任务 (Tasks)

5.1 硬件任务 (Hardware Tasks)

5.2 软件任务 (Software Tasks)

5.2.1 Executor 执行器

5.2.2 Dispatcher 分发器

5.3 idle 任务 和 0-优先级任务

5.4 init 任务

6. 资源

6.1 局部资源 (Local Resources)

6.2 共享资源 (Shared Resources)

7. Rust Macros

8. Priority Ceiling 的计算方法

9. RTIC 启动过程

10. 总结

Under the Hook - The Cortex Runtime

1. Memory Layout

1.1 Linker Script

1.1.1 Naming Conventions of Linker Symbols

1.1.2 Weak Aliasing at the Linker Script Level

1.1.3 Virtual and Load Memory Addresses

Code Section

Initialised Data Section

Uninitialised Data Section

1.2 Embedonomicon Implementation

1.3 Customisable Layout

2. Exception and Interrupt Handling

2.3 Activation of Vector Tables

2.4 Handlers

2.5 Built-in Exceptions

2.5.1 Exception Mechanisms

2.5.2 Exception Handlers

The DefaultHandler for Exceptions

The HardFault Handler for Exceptions

NonMaskableInt-errupts or Other interrupts

2.5.3 Exception Vector Table

2.6 External Interrupts

2.6.1 External Interrupt Handlers

2.6.2 External Interrupt Vector Table

RTIC 在 Blue Pill 上的点灯案例

1. 代码解读

2. 写入启动

Debugging

Embassy 在 Blue Pill 上的点灯案例

1. 前提

1.1 依赖库安装

1.2 probe-rs Toolkit

1.3 ARM Cortex-m toolchain

5.2.1 `Executor` 执行器

5.2.2 `Dispatcher` 分发器

5.3 `idle` 任务和 0-优先级任务

5.4 `init` 任务

The `DefaultHandler` for Exceptions

The `HardFault` Handler for Exceptions

`NonMaskableInt`-errupts or `Other` interrupts

1.2 `probe-rs` Toolkit

2. Rust 对 Zero-cost `async`/`.await` 的探索

2.1 `Future` 对象

2.3 `Future` 执行上下文

2.4 `Future` 是一个状态机

2.5 执行器 `Executor`

3.1 `TaskStorage` 用来封装任务状态机和调度

3.2 `TaskHeader` 用来封装任务调度

3.3 `Executor`s

3.4 `Pender`