stm32ral

本项目为所有 STM32 微控制器提供 Rust RAL（寄存器访问层）。

底层数据是通过在 stm32-rs 中的打补丁 SVD 文件生成的。

文档 · 仓库 · 支持的设备 · 示例项目

这是什么？

stm32ral 是一个轻量级寄存器访问层的实验。它提供了对每个寄存器的访问，并提供了一些常量，这些常量定义了寄存器中的字段和可能的字段值。从这个意义上说，它类似于 C 设备头文件。然而，它还提供了一些简单的宏，允许非常容易地访问寄存器，生成的代码非常简单，即使没有启用优化也非常高效。

主要目标是简单性、紧凑性和完整性。您会得到一个模块结构，它包含一个结构体，该结构体按顺序包含每个外设的寄存器，并为您提供大量用于字段宽度、位置和可能值的常量。除此之外没有其他内容，因此它占用的磁盘空间很少，构建速度非常快。它涵盖了所有 STM32 设备的所有寄存器，包括核心 Cortex-M 外设，并旨在尽快包含每个字段的完整枚举值。

请考虑试用它，并做出贡献或留下反馈！

快速示例

use stm32ral::{read_reg, write_reg, modify_reg, reset_reg};
use stm32ral::{rcc, gpio};

// For safe access we have to first `take()` the peripheral instance.
// This only returns Some(Instance) if that instance is not already
// taken; otherwise it returns None. This ensures that no other code can be
// simultaneously accessing the peripheral, which could lead to a race
// condition. There's `release()` to return it. See below for unsafe use.
let gpioa = gpio::GPIOA::take().unwrap();
let rcc = rcc::RCC::take().unwrap();

// Field-level read/modify/write, with either named values or just literals.
// Most of your code will look like this.
modify_reg!(rcc, rcc, AHB1ENR, GPIOAEN: Enabled);
modify_reg!(gpio, gpioa, MODER, MODER1: Input, MODER2: Output, MODER3: Input);
while read_reg!(gpio, gpioa, IDR, IDR3 == High) {
    let pa1 = read_reg!(gpio, gpioa, IDR, IDR1);
    modify_reg!(gpio, gpioa, ODR, ODR2: pa1);
}

// You can also reset whole registers or specific fields
reset_reg!(gpio, gpioa, GPIOA, MODER, MODER13, MODER14, MODER15);
reset_reg!(gpio, gpioa, GPIOA, MODER);

// Whole-register read/modify/write.
// Rarely used but nice to have the option.
let port = read_reg!(gpio, gpioa, IDR);
write_reg!(gpio, gpioa, ODR, 0x12345678);
modify_reg!(gpio, gpioa, MODER, |r| r | (0b10 << 4));

// Or forego the macros and just use the constants yourself.
// The macros above just expand to these forms for you, bringing
// the relevant constants into scope. Nothing else is going on.
let pa1 = (gpioa.IDR.read() & gpio::IDR::IDR1::mask) >> gpio::IDR::IDR1::offset;
gpioa.ODR.write(gpio::ODR::ODR2::RW::Output << gpio::ODR::ODR2::offset);

// Once you're done with a peripheral, you can release it so it is available
// to `take()` again. You can't use `gpioa` after this line.
gpio::GPIOA::release(gpioa);

// For unsafe access, you don't need to first call `take()`, just use `GPIOA`:
unsafe { modify_reg!(gpio, GPIOA, MODER, MODER1: Output) };
// With the `nosync` feature set, this is the only way to access registers.

请参阅 示例项目，以获取一个更完整的示例，该示例应该可以直接构建。

为什么使用 stm32ral？

• 小巧轻量（总文件大小约为 30MB，压缩后约为 2MB）
• 简单（仅 4 个宏和大量常量）
• 编译速度快（构建时间约为 2 秒）
• 在一个包中涵盖 所有 STM32 设备
• 通过 cortex-m-rt 的 rt 功能支持，包括中断
• 通过 cortex-m-rtic 的 rtic 功能支持，暴露一个包含所有外设的 device
• 不会妨碍您
• 有点类似于您从 C 头文件中习惯的东西

为什么不使用 stm32ral？

• 仍然是实验性的，API 设计可能会有破坏性更改
• 不会让您烧毁 CPU 时间
• 有点类似于您从 C 头文件中习惯的东西

相反，请考虑使用...

• svd2rust 是从 SVD 文件生成 Cortex-M 设备 crates 的明显选择，并为本项目提供了灵感。
• stm32-rs 为本 crate 支持的所有 STM32 设备提供了 svd2rust crates，并使用相同的底层修补过的 SVD 文件。
• TockOS 使用他们的 svd2regs 工具提供了一个用于寄存器访问的不错的 API。
• Bobbin 对于寄存器访问也有一些很好的想法（见 bobbin-dsl）。

在您自己的 crates 中使用

在您的 Cargo.toml 中

[dependencies.stm32ral]
version = "0.4.0"
features = ["stm32f405"]

将 stm32f405 替换为所需的芯片名称。有关完整列表，请参阅 支持设备。

然后，在您的代码中

#[macro_use]
extern crate stm32ral;

let gpioa = stm32ral::gpio::GPIOA::take().unwrap();
modify_reg!(stm32ral::gpio, gpioa, MODER, MODER1: Input, MODER2: Output, MODER3: Input);

crate 功能

• inline-asm：在 cortex_m 依赖项上启用 inline-asm。如果您使用的是支持它的 nightly 编译器，则建议使用。
• rt：在 cortex_m_rt 依赖项上启用 device，并提供相关的中断链接脚本。大多数用户推荐使用，但如果您想自己处理中断，则可以禁用。
• doc：在顶级不使用任何设备的情况下使所有设备可见。理想用于生成文档。实际上构建代码时无实际用途。
• nosync：禁用了所有同步访问（take()/release() 函数）。访问寄存器的唯一方法是使用直接的 unsafe 访问，例如 write_reg!(stm32ral::gpio, GPIOA, MODER, MODER1: Input)。移除所有相关的同步开销，但用户必须确保不会引起竞争条件。“C”模式。如果通过 HAL crate 启用，特别有用，HAL crate 将执行自己的同步，但仍允许用户通过不安全的方式直接访问外设（这也是为什么这是一个“负”功能的原因）。
• rtfm：为每个设备模块添加一个包含每个设备外设的 Instance 的 Peripherals 结构，并提供一个 steal() 方法以不安全地创建它并获取所有外设；此功能增加了将 stm32ral 作为 cortex-m-rtfm 设备 crate 使用时的兼容性。如果也启用了 nosync，则 Peripherals 结构将为空，并且具有空的 steal() 方法，保持兼容性（但只能直接不安全访问外设）。
• CPU 特性如 armv7em：从 CPU 核心本身引入外设，相关的一个会自动由设备特性包含。
• 设备特性：每个支持设备一个，例如，stm32f405。您应精确启用其中一个。

// Equivalent to stm32ral crate root with `--features stm32f405`
pub mod stm32f4 {
    pub mod stm32f405 {
        pub mod gpio {
            pub mod MODER {
                pub mod MODER15 {
                    pub const offset: u32 = 30;
                    pub const mask: u32 = 0b11 << offset;
                    pub mod R {}
                    pub mod W {}
                    pub mod RW {
                        pub const Input: u32 = 0b00;
                        pub const Output: u32 = 0b01;
                        pub const Alternate: u32 = 0b10;
                        pub const Analog: u32 = 0b11;
                    }
                }
            }
        }
    }
}
pub use stm32f4::stm32f405::*;

// Inside a peripheral module such as `stm32ral::stm32f4::stm32f405::gpio`

pub struct RegisterBlock {
    pub MODER: RWRegister<u32>,
    pub OTYPER: RWRegister<u32>,
    // ...
}

// In reality, you'd use reset_reg!(gpio, gpioa, GPIOA, MODER);
gpioa.MODER.write(stm32ral::gpio::GPIOA::reset.MODER);

// Inside a peripheral module such as `stm32ral::stm32f4::stm32f405::gpio`

pub struct Instance {
    addr: u32,
}
impl Deref for Instance {
    type Target = RegisterBlock;
    fn deref(&self) -> &RegisterBlock { ... }
}

// Inside a peripheral module such as `stm32ral::stm32f4::stm32f405::gpio`

pub mod GPIOA {
    pub const reset: ResetValues = ResetValues { ... };
    const INSTANCE: Instance = Instance { ... };
    pub fn take() -> Option<Instance> { ... };
    pub fn release(Instance) { ... };
}

pub mod GPIOB { ... }
pub mod GPIOC { ... }
// and so on

// In reality, you'd use write_reg!(gpio, gpioa, MODER, 0x1234)
// and read_reg!(gpio, gpioa, MODER)
let gpioa = gpio::GPIOA::take().unwrap();
gpioa.MODER.write(0x1234);
let _ = gpioa.MODER.read();

pub const GPIOA: *const RegisterBlock = ...;

// Set PA3 high (and all other GPIOA pins low).
write_reg!(stm32ral::gpio, gpioa, ODR, 1<<3);

// Set PA3 to Output, PA4 to Analog, PA5 to 0b01 (also Output), everything
// else gets set to 0 (Input).
// (In reality, be careful, as this operation will change the state of the
//  JTAG/SWD pins PA13-15, possibly breaking debugger access.
//  Use modify_reg!() instead.)
write_reg!(stm32ral::gpio, gpioa, MODER, MODER3: Output, MODER4: Analog, MODER5: 0b01);

// Get the value of the whole register IDR
let val = read_reg!(stm32ral::gpio, gpioa, IDR);

// Get the value of IDR2 (masked and shifted down to the LSbits)
let idr2 = read_reg!(stm32ral::gpio, gpioa, IDR, IDR2);

// Get the value of IDR2 and IDR3
let (idr2, idr3) = read_reg!(stm32ral::gpio, gpioa, IDR, IDR2, IDR3);

// Busy wait while PA2 is high
while read_reg!(stm32ral::gpio, gpioa, IDR, IDR2 == High) {}

// Set PA3 high without affecting any other bits
// (in reality, use the BSRR register for this).
modify_reg!(stm32ral::gpio, gpioa, ODR, |reg| reg | (1<<3));

// Set PA3 to Output and PA4 to Analog, but without affecting any other pins.
modify_reg!(stm32ral::gpio, gpioa, MODER, MODER3: Output, MODER4: Analog);

// Reset GPIOA back to reset state, with JTAG/SWD pins on PA13, PA14, PA15.
reset_reg!(stm32ral::gpio, gpioa, GPIOA, MODER);

// Reset PA13, PA14, PA15 to their reset state.
reset_reg!(stm32ral::gpio, gpioa, GPIOA, MODER, MODER13, MODER14, MODER15);

// Unsafely and directly access GPIOE.
unsafe { write_reg!(stm32ral::gpio, GPIOE, 0x01010101) };

// The macro is effectively doing this:
unsafe { (*stm32ral::gpio::GPIOE).MODER.write( 0x01010101 ) };

#[interrupt]
fn TIM2() {
    write_reg!(stm32ral::tim2, TIM2, SR, UIF: 0);
}

peripherals.NVIC.enable(stm32ral::Interrupt::TIM2);

$ git submodule update --init

$ make