第 15 章：生态全景与库推荐

use embassy_stm32::StaticCell;

// 声明一个静态存储位置（此时内容为空）
static I2C_BUS: StaticCell<embassy_stm32::i2c::I2c<'static>> = StaticCell::new();

#[embassy_executor::main]
async fn main(spawner: Spawner) {
    let p = embassy_stm32::init(Default::default());
    
    // 在运行时初始化，并获得 'static 引用
    let i2c = I2C_BUS.init(
        embassy_stm32::i2c::I2c::new(
            p.I2C1, p.PB8, p.PB9,
            Irqs, p.DMA1_CH6, p.DMA1_CH7,
            100_000,  // 100 kHz
        )
    );
    
    // i2c 的类型是 &'static mut I2c<'static>
    // 可以安全地传递给任何任务
    spawner.spawn(sensor_task(i2c)).unwrap();
}

use heapless::{Vec, String, Queue, HistoryBuf};

// 固定容量的 Vec（类比 C 的固定数组 + 长度计数器）
let mut buf: Vec<u8, 256> = Vec::new();  // 最多 256 字节，在栈上分配
buf.push(0xAA).unwrap();
buf.extend_from_slice(&[0x01, 0x02, 0x03]).unwrap();
assert_eq!(buf.len(), 4);
// buf.push() 在满时返回 Err，不会 panic

// 固定容量的 String
let mut msg: String<64> = String::new();
msg.push_str("T:25.3 H:65.2").unwrap();

// 固定容量的队列（SPSC：单生产者单消费者）
use heapless::spsc::Queue;
static UART_QUEUE: Queue<u8, 128> = Queue::new();
// 生产者（中断中）：UART_QUEUE.split().0.enqueue(byte)
// 消费者（任务中）：UART_QUEUE.split().1.dequeue()

// 环形缓冲区
let mut history: HistoryBuf<u16, 100> = HistoryBuf::new();
history.write(1024);
history.write(2048);
// 保留最近 100 个采样值

#![feature(alloc_error_handler)]

use embedded_alloc::LlffHeap as Heap;

#[global_allocator]
static HEAP: Heap = Heap::empty();

#[alloc_error_handler]
fn alloc_error(layout: core::alloc::Layout) -> ! {
    defmt::error!("alloc error: size={=usize}", layout.size());
    panic!();
}

#[embassy_executor::main]
async fn main(_spawner: Spawner) {
    // 初始化堆：使用 RAM 中的一段区域
    static mut HEAP_MEM: [u8; 4096] = [0u8; 4096];
    unsafe { HEAP.init(HEAP_MEM.as_ptr() as usize, HEAP_MEM.len()); }
    
    // 现在可以使用 Vec、String、Box 了
    let mut data: alloc::vec::Vec<u8> = alloc::vec::Vec::new();
    data.push(0x01);
}

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  # === 第一阶段：快速检查（< 1 分钟）===
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: thumbv7em-none-eabihf
      - run: cargo check --target thumbv7em-none-eabihf
      - run: cargo clippy --target thumbv7em-none-eabihf -- -D warnings
      - run: cargo fmt --check

  # === 第二阶段：主机测试（< 3 分钟）===
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo test  # 纯逻辑单元测试
      - run: cargo test --doc  # 文档测试

  # === 第三阶段：交叉编译（< 5 分钟）===
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        target:
          - thumbv7em-none-eabihf   # STM32F4
          - thumbv8m.main-none-eabihf  # nRF52840
          - riscv32imc-unknown-none-elf  # ESP32-C3
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
      - run: cargo build --release --target ${{ matrix.target }}
      - run: cargo size --release --target ${{ matrix.target }}

  # === 第四阶段：HIL 测试（需要物理硬件）===
  hil:
    runs-on: [self-hosted, hil-rig]  # 自托管 runner，连接了开发板
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - run: cargo build --release --target thumbv7em-none-eabihf
      - run: probe-rs run --chip STM32F407VGTx target/thumbv7em-none-eabihf/release/firmware
      - run: python3 tests/hil_verify.py  # 验证硬件行为

# deny.toml
[licenses]
unlicensed = "deny"
allow = ["MIT", "Apache-2.0", "BSD-3-Clause"]
copyleft = "warn"  # GPL 等 copyleft 许可证发出警告

[bans]
multiple-versions = "warn"  # 同一 crate 的多个版本发出警告
deny = [
    { name = "openssl" },  # 嵌入式中不应该依赖 OpenSSL
]

[sources]
unknown-registry = "deny"
unknown-git = "deny"
allow-registry = ["https://github.com/rust-lang/crates.io-index"]

阶段 1：新项目用 Rust
┌─────────────────────────────────┐
│  新产品线（Rust + Embassy）       │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│  旧产品线（C，继续维护）          │
└─────────────────────────────────┘

阶段 2：新模块用 Rust，通过 FFI 集成到 C 项目
┌─────────────────────────────────┐
│  C 主程序                        │
│  ├── 旧模块 A（C）              │
│  ├── 旧模块 B（C）              │
│  └── 新模块 C（Rust，通过 FFI）  │  ← 新写的
└─────────────────────────────────┘

阶段 3：逐步替换旧模块
┌─────────────────────────────────┐
│  C 主程序（逐渐缩小）            │
│  ├── 旧模块 A（C）→ 计划替换    │
│  └── 模块 B（Rust）             │  ← 已替换
│  └── 模块 C（Rust）             │
│  └── 模块 D（Rust）             │  ← 新写的
└─────────────────────────────────┘

阶段 4：C 只剩薄壳
┌─────────────────────────────────┐
│  Rust 主程序                     │
│  ├── 模块 A（Rust）             │  ← 已替换
│  ├── 模块 B（Rust）             │
│  ├── 模块 C（Rust）             │
│  └── 启动代码（C，极少量）       │
└─────────────────────────────────┘

// 编译为静态库：crate-type = ["staticlib"]

/// C 兼容的接口
#[no_mangle]
pub extern "C" fn modbus_encode_frame(
    cmd: u8,
    payload: *const u8,
    payload_len: usize,
    output: *mut u8,
    output_cap: usize,
) -> i32 {
    // 安全检查
    if payload.is_null() || output.is_null() {
        return -1;
    }
    if payload_len > 250 || output_cap < payload_len + 5 {
        return -2;
    }
    
    let payload_slice = unsafe { core::slice::from_raw_parts(payload, payload_len) };
    let output_slice = unsafe { core::slice::from_raw_parts_mut(output, output_cap) };
    
    // 使用 Rust 的类型安全逻辑
    let frame = encode_frame(cmd, payload_slice);
    output_slice[..frame.len()].copy_from_slice(&frame);
    
    frame.len() as i32  // 返回帧长度
}

#[no_mangle]
pub extern "C" fn modbus_decode_frame(
    data: *const u8,
    data_len: usize,
    cmd_out: *mut u8,
    payload_out: *mut u8,
    payload_cap: usize,
) -> i32 {
    // ... 类似的安全检查 + 解码逻辑
    todo!()
}

// protocol.h（由 Rust 侧生成，或手写）
#include <stdint.h>

int32_t modbus_encode_frame(
    uint8_t cmd,
    const uint8_t* payload,
    size_t payload_len,
    uint8_t* output,
    size_t output_cap
);

int32_t modbus_decode_frame(
    const uint8_t* data,
    size_t data_len,
    uint8_t* cmd_out,
    uint8_t* payload_out,
    size_t payload_cap
);

// 在 C 代码中调用
void send_modbus_response(uint8_t cmd, uint8_t* data, uint8_t len) {
    uint8_t frame[256];
    int32_t frame_len = modbus_encode_frame(cmd, data, len, frame, sizeof(frame));
    if (frame_len > 0) {
        uart_send(frame, frame_len);
    }
}

// 声明 C 函数
extern "C" {
    fn HAL_I2C_Master_Transmit(
        hi2c: *mut I2C_HandleTypeDef,
        dev_addr: u16,
        data: *mut u8,
        size: u16,
        timeout: u32,
    ) -> i32;
}

// 安全封装
pub struct I2cDriver {
    handle: *mut I2C_HandleTypeDef,
}

impl I2cDriver {
    pub fn transmit(&mut self, addr: u8, data: &mut [u8]) -> Result<(), I2cError> {
        let ret = unsafe {
            HAL_I2C_Master_Transmit(
                self.handle,
                (addr as u16) << 1,
                data.as_mut_ptr(),
                data.len() as u16,
                100,
            )
        };
        match ret {
            0 => Ok(()),  // HAL_OK
            _ => Err(I2cError::TransferFailed),
        }
    }
}

// 危险：谁负责释放这块内存？
#[no_mangle]
pub extern "C" fn create_buffer(size: usize) -> *mut u8 {
    let mut buf = vec![0u8; size];
    buf.as_mut_ptr()  // buf 在这里被 drop！返回悬垂指针！
}

// 正确：明确所有权转移
#[no_mangle]
pub extern "C" fn create_buffer(size: usize) -> *mut u8 {
    let mut buf = vec![0u8; size].into_boxed_slice();
    Box::into_raw(buf) as *mut u8  // 所有权转移给调用者
}

#[no_mangle]
pub extern "C" fn free_buffer(ptr: *mut u8, size: usize) {
    unsafe {
        let slice = core::slice::from_raw_parts_mut(ptr, size);
        drop(Box::from_raw(slice as *mut [u8]));
    }
}

你的项目是什么类型？
│
├── 消费电子产品（无认证要求）
│   ├── 需要 WiFi/BLE？
│   │   ├── 是 → ESP32 + esp-hal + Embassy
│   │   └── 否 → STM32 + Embassy（或 nRF52 + Embassy）
│   └── 需要 USB？
│       ├── 是 → STM32 + embassy-usb
│       └── 否 → 任何支持的 MCU + Embassy
│
├── 工业控制（SIL 1-2）
│   ├── 需要实时性 < 10μs？
│   │   ├── 是 → RTIC（中断驱动）或裸机
│   │   └── 否 → Embassy（协作式足够）
│   └── 需要长期维护（10+ 年）？
│       ├── 是 → 标准 Rust + 最小依赖
│       └── 否 → Embassy + 完整生态
│
├── 汽车电子（ASIL A-D）
│   ├── ASIL A-B → 标准 Rust + 严格测试
│   ├── ASIL C-D → Ferrocene + 工具鉴定包
│   └── 需要 AUTOSAR？→ 关注 Eclipse S-CORE 进展
│
├── 医疗器械（IEC 62304）
│   ├── Class A-B → 标准 Rust + 完整测试
│   └── Class C → Ferrocene（已获认证）
│
└── 原型 / 教育 / 爱好者
    └── RP2040/RP2350 + Embassy（最便宜的入门方式）

你的团队现状？
│
├── 纯 C 团队，无 Rust 经验
│   ├── 时间充裕（6+ 个月）？
│   │   ├── 是 → 从新项目开始，逐步学习
│   │   └── 否 → 先用 C 完成项目，业余时间学习 Rust
│   └── 团队规模？
│       ├── 1-3 人 → 直接上手 Embassy（学习曲线可接受）
│       └── 5+ 人 → 先派 1-2 人试点，再推广
│
├── 有 Rust 经验，无嵌入式经验
│   └── 从 RP2040 开始（社区资源丰富，便宜）
│       → 掌握 Embassy 后迁移到目标平台
│
├── 有嵌入式经验，有 Rust 基础
│   └── 直接上目标平台 + Embassy
│       → 参考本书第 8-11 章
│
└── 混合团队（部分 C，部分 Rust）
    └── 使用 FFI 集成（第 15.5 节）
        → 新模块用 Rust，旧模块保持 C

你的硬件约束？
│
├── Flash < 64 KB
│   ├── 是 → 裸机 PAC（无 HAL）或 embassy + opt-level="z"
│   └── 否 → 继续
│
├── RAM < 8 KB
│   ├── 是 → 裸机（Embassy 最小开销 ~400B，但 HAL 需要更多）
│   └── 否 → Embassy 可行
│
├── 需要 5V 容忍 GPIO？
│   ├── 是 → STM32F4/F7（部分引脚 FT）
│   └── 否 → 任何平台
│
├── 需要双核？
│   ├── 是 → RP2040/RP2350 或 ESP32
│   └── 否 → 任何平台
│
├── 需要 RISC-V？
│   ├── 是 → ESP32-C3/C6 或 GD32VF103
│   └── 否 → ARM Cortex-M 系列
│
└── 需要低功耗（< 10μA 睡眠）？
    ├── 是 → nRF52840（System OFF: 0.4μA）或 STM32L4
    └── 否 → 任何平台

第 1 个月：Rust 语言基础
├── 读完本书 Part 1（第 1-6 章）
├── 在 PC 上写几个小项目（CLI 工具、文件处理）
└── 重点掌握：所有权、trait、枚举、Result

第 2 个月：嵌入式 Rust 入门
├── 买一块 STM32F4 Discovery 或 RP2040 Pico
├── 读完本书 Part 2（第 7-11 章）
├── 完成：LED 闪烁 → UART 回显 → I2C 传感器 → 多任务
└── 重点掌握：Embassy 任务模型、async/await、Channel

第 3 个月：工程实践
├── 读完本书 Part 3（第 12-15 章）
├── 用 Embassy 重写一个你熟悉的 C 项目
├── 配置完整的 CI/CD 流水线
└── 重点掌握：调试、测试、优化、工程架构

第 4-6 个月：深入与拓展
├── 阅读 Embassy 源码（特别是 executor 和 HAL）
├── 尝试写一个 embedded-hal 驱动并发布到 crates.io
├── 探索 USB / 网络 / BLE 等高级功能
└── 参与社区（Matrix 聊天室、GitHub Issues）

Part 1：为什么？是什么？
├── 第 1 章：为什么 Rust 适合嵌入式（动机）
├── 第 2 章：Rust 语法速成（工具）
├── 第 3 章：第一个裸机工程（起步）
├── 第 4 章：零成本抽象（信心）
├── 第 5 章：并发基础（概念）
└── 第 6 章：生态层次（地图）

Part 2：怎么用？
├── 第 7 章：Embassy 思想（理念）
├── 第 8 章：第一个 Embassy 工程（实践）
├── 第 9 章：运行时原理（理解）
├── 第 10 章：任务间通信（协作）
└── 第 11 章：生态组件（拓展）

Part 3：怎么做好？
├── 第 12 章：工具链深度（底层）
├── 第 13 章：调试、测试与架构（方法论）
├── 第 14 章：性能与体积优化（精进）
└── 第 15 章：生态全景与迁移（全局）