domain-embedded

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Context (Auto-Injected)

项目上下文（自动注入）

Target configuration: !

cat .cargo/config.toml 2>/dev/null || echo "No .cargo/config.toml found"

目标配置： !

cat .cargo/config.toml 2>/dev/null || echo "No .cargo/config.toml found"

Embedded Domain

嵌入式领域

Layer 3: Domain Constraints

第三层：领域约束

Domain Constraints → Design Implications

领域约束 → 设计影响

Domain Rule	Design Constraint	Rust Implication
No heap	Stack allocation	heapless, no Box/Vec
No std	Core only	#![no_std]
Real-time	Predictable timing	No dynamic alloc
Resource limited	Minimal memory	Static buffers
Hardware safety	Safe peripheral access	HAL + ownership
Interrupt safe	No blocking in ISR	Atomic, critical sections

领域规则	设计约束	Rust 实现要求
无堆内存	栈分配	heapless、禁止使用Box/Vec
无标准库	仅使用Core库	#![no_std]
实时性	可预测时序	禁止动态分配
资源受限	最小化内存占用	静态缓冲区
硬件安全性	安全的外设访问	HAL + 所有权机制
中断安全	中断服务程序（ISR）中禁止阻塞	原子操作、临界区

Critical Constraints

关键约束

No Dynamic Allocation

禁止动态分配

RULE: Cannot use heap (no allocator)
WHY: Deterministic memory, no OOM
RUST: heapless::Vec<T, N>, arrays

RULE: 不能使用堆内存（无分配器）
WHY: 内存使用可确定，避免内存不足（OOM）
RUST: heapless::Vec<T, N>、数组

Interrupt Safety

中断安全

RULE: Shared state must be interrupt-safe
WHY: ISR can preempt at any time
RUST: Mutex<RefCell<T>> + critical section

RULE: 共享状态必须保证中断安全
WHY: ISR可随时抢占主线程
RUST: Mutex<RefCell<T>> + 临界区

Hardware Ownership

硬件所有权

RULE: Peripherals must have clear ownership
WHY: Prevent conflicting access
RUST: HAL takes ownership, singletons

RULE: 外设必须有明确的所有权
WHY: 防止冲突访问
RUST: HAL获取所有权、单例模式

Trace Down ↓

向下追溯 ↓

From constraints to design (Layer 2):

"Need no_std compatible data structures"
    ↓ m02-resource: heapless collections
    ↓ Static sizing: heapless::Vec<T, N>

"Need interrupt-safe state"
    ↓ m03-mutability: Mutex<RefCell<Option<T>>>
    ↓ m07-concurrency: Critical sections

"Need peripheral ownership"
    ↓ m01-ownership: Singleton pattern
    ↓ m12-lifecycle: RAII for hardware

从约束到设计（第二层）：

"需要兼容no_std的数据结构"
    ↓ m02-resource: heapless集合
    ↓ 静态大小：heapless::Vec<T, N>

"需要中断安全的状态管理"
    ↓ m03-mutability: Mutex<RefCell<Option<T>>>
    ↓ m07-concurrency: 临界区

"需要外设所有权管理"
    ↓ m01-ownership: 单例模式
    ↓ m12-lifecycle: 硬件的RAII机制

Layer Stack

层级栈

Layer	Examples	Purpose
PAC	stm32f4, esp32c3	Register access
HAL	stm32f4xx-hal	Hardware abstraction
Framework	RTIC, Embassy	Concurrency
Traits	embedded-hal	Portable drivers

层级	示例	用途
PAC	stm32f4、esp32c3	寄存器访问
HAL	stm32f4xx-hal	硬件抽象
框架	RTIC、Embassy	并发处理
特征	embedded-hal	可移植驱动

Framework Comparison

框架对比

Framework	Style	Best For
RTIC	Priority-based	Interrupt-driven apps
Embassy	Async	Complex state machines
Bare metal	Manual	Simple apps

框架	风格	最佳适用场景
RTIC	基于优先级	中断驱动型应用
Embassy	异步式	复杂状态机
裸机	手动控制	简单应用

Key Crates

核心依赖库

Purpose	Crate
Runtime (ARM)	cortex-m-rt
Panic handler	panic-halt, panic-probe
Collections	heapless
HAL traits	embedded-hal
Logging	defmt
Flash/debug	probe-run

用途	依赖库
运行时（ARM）	cortex-m-rt
Panic处理程序	panic-halt、panic-probe
集合类型	heapless
HAL特征	embedded-hal
日志	defmt
闪存/调试	probe-run

Design Patterns

设计模式

Pattern	Purpose	Implementation
no_std setup	Bare metal	`#![no_std]` + `#![no_main]`
Entry point	Startup	`#[entry]` or embassy
Static state	ISR access	`Mutex<RefCell<Option<T>>>`
Fixed buffers	No heap	`heapless::Vec<T, N>`

模式	用途	实现方式
no_std环境搭建	裸机开发	`#![no_std]` + `#![no_main]`
入口点	启动程序	`#[entry]` 或 Embassy
静态状态	ISR访问	`Mutex<RefCell<Option<T>>>`
固定缓冲区	无堆内存	`heapless::Vec<T, N>`

Code Pattern: Static Peripheral

代码模式：静态外设

rust

#![no_std]
#![no_main]

use cortex_m::interrupt::{self, Mutex};
use core::cell::RefCell;

static LED: Mutex<RefCell<Option<Led>>> = Mutex::new(RefCell::new(None));

#[entry]
fn main() -> ! {
    let dp = pac::Peripherals::take().unwrap();
    let led = Led::new(dp.GPIOA);

    interrupt::free(|cs| {
        LED.borrow(cs).replace(Some(led));
    });

    loop {
        interrupt::free(|cs| {
            if let Some(led) = LED.borrow(cs).borrow_mut().as_mut() {
                led.toggle();
            }
        });
    }
}

rust

#![no_std]
#![no_main]

use cortex_m::interrupt::{self, Mutex};
use core::cell::RefCell;

static LED: Mutex<RefCell<Option<Led>>> = Mutex::new(RefCell::new(None));

#[entry]
fn main() -> ! {
    let dp = pac::Peripherals::take().unwrap();
    let led = Led::new(dp.GPIOA);

    interrupt::free(|cs| {
        LED.borrow(cs).replace(Some(led));
    });

    loop {
        interrupt::free(|cs| {
            if let Some(led) = LED.borrow(cs).borrow_mut().as_mut() {
                led.toggle();
            }
        });
    }
}

Common Mistakes

常见错误

Mistake	Domain Violation	Fix
Using Vec	Heap allocation	heapless::Vec
No critical section	Race with ISR	Mutex + interrupt::free
Blocking in ISR	Missed interrupts	Defer to main loop
Unsafe peripheral	Hardware conflict	HAL ownership

错误	违反的领域规则	修复方案
使用Vec	堆内存分配	改用heapless::Vec
未使用临界区	与ISR竞争	Mutex + interrupt::free
ISR中阻塞	错过中断	延迟到主循环处理
不安全的外设访问	硬件冲突	使用HAL的所有权机制

Trace to Layer 1

追溯至第一层

Constraint	Layer 2 Pattern	Layer 1 Implementation
No heap	Static collections	heapless::Vec<T, N>
ISR safety	Critical sections	Mutex<RefCell<T>>
Hardware ownership	Singleton	take().unwrap()
no_std	Core-only	#![no_std], #![no_main]

约束	第二层模式	第一层实现
无堆内存	静态集合	heapless::Vec<T, N>
ISR安全	临界区	Mutex<RefCell<T>>
硬件所有权	单例模式	take().unwrap()
no_std	仅使用Core库	#![no_std]、#![no_main]

When	See
Static memory	m02-resource
Interior mutability	m03-mutability
Interrupt patterns	m07-concurrency
Unsafe for hardware	unsafe-checker

场景	参考
静态内存	m02-resource
内部可变性	m03-mutability
中断模式	m07-concurrency
硬件相关不安全代码	unsafe-checker

domain-embedded

Original

Translation

Project Context (Auto-Injected)

项目上下文（自动注入）

Embedded Domain

嵌入式领域

Domain Constraints → Design Implications

领域约束 → 设计影响

Critical Constraints

关键约束

No Dynamic Allocation

禁止动态分配

Interrupt Safety

中断安全

Hardware Ownership

硬件所有权

Trace Down ↓

向下追溯 ↓

Layer Stack

层级栈

Framework Comparison

框架对比

Key Crates

核心依赖库

Design Patterns

设计模式

Code Pattern: Static Peripheral

代码模式：静态外设

Common Mistakes

常见错误

Trace to Layer 1

追溯至第一层

Related Skills

相关技能