MoonBit 微控制器硬件抽象层接口规范 (`moonbit-mcu-hal`)

moonbit-mcu-hal 是专为 MoonBit 语言 打造的高性能、工业级微控制器硬件抽象层（MCU HAL）接口规范与无硬件内存仿真套件。本项目旨在为嵌入式 MoonBit 生态提供统一的外设抽象、完备的资源并发锁、无硬件单元测试驱动的内存仿真后端，以及多芯片厂商（STM32、RP2040 Pico、ESP32）适配层。

🎯 项目立项背景与核心优势

在嵌入式开发中，不同微控制器厂商（如 STMicroelectronics, Raspberry Pi Trading, Espressif）的硬件外设寄存器布局与驱动接口往往高度碎片化。传统 C/C++ HAL 库绑定具体芯片，无法轻松实现跨平台软件复用与无硬件单元测试。

moonbit-mcu-hal 充分利用 MoonBit 语言的高效类型系统、模式匹配与现代包管理机制，设计了独立于芯片架构的统一外设 HAL 规范：

统一外设抽象: 提供 GPIO, UART, SPI, I²C, PWM, ADC, Timer, RTC, DMA, Concurrency Mutex 10大嵌入式外设抽象接口。
零硬件依赖仿真 (In-Memory Virtual HAL): 内置基于 RAM 的虚拟 MMIO 寄存器空间、虚拟 IO 导线总线，以及 AT24C02 EEPROM、W25Q64 SPI Flash 虚拟外设，支持在本地与 CI/CD 环境中零硬件运行 63+ 组单元测试。
多厂商芯片适配层: 内置 STM32F4 (BSRR/RCC/USART), RP2040 Pico (SIO/PL011 UART), ESP32 (GPIO Matrix/LEDC PWM) 3 大主流芯片适配驱动。
嵌入式 RTOS 与并发锁定机制: 提供 CriticalSection 原子关中断保护、PeripheralMutex[T] 跨任务外设互斥锁，以及轻量级嵌入式 RTOS 任务调度器与信号量。
设备树 (Device Tree AST): 支持解析与构造设备树节点与属性，实现外设资源的静态声明与配置生成。

🏗️ 系统架构图

flowchart TD
    A[应用层 / 用户嵌入式代码] -->|调用抽象接口| B[BSP & Sensor 驱动层]
    B -->|Mpu6050 / Ssd1306 / EEPROM| C[HAL 核心外设接口层]
    
    C -->|GPIO / UART / SPI / I2C / PWM / ADC / Timer / RTC / DMA| D[并发与资源锁定机制]
    D -->|CriticalSection / PeripheralMutex| E[后端驱动适配与仿真层]
    
    E -->|芯片适配 1| F[STM32 Adaptation Layer]
    E -->|芯片适配 2| G[RP2040 Pico Adaptation Layer]
    E -->|芯片适配 3| H[ESP32 Adaptation Layer]
    E -->|无硬件测试| I[In-Memory Virtual MCU Simulator]

📦 模块目录结构

moonbit-mcu-hal/
├── moon.mod               # MoonBit 模块配置文件 (sbqrre/moonbit-mcu-hal)
├── README.md              # 项目中文说明文档
├── LICENSE                # Apache License 2.0 许可证
├── OSC2026_Hackathon_Proposal.md # 8月黑客松申报书
├── .github/
│   └── workflows/
│       └── ci.yml         # 多平台 CI/CD 工作流 (Linux/macOS/Windows)
└── src/
    ├── types/             # 基础硬件类型 (PinSpec, PinState, Hertz, DeviceCapability)
    ├── errors/            # 统一 HAL 硬件错误枚举 (HalError)
    ├── clock_delay/       # HalClock 时钟树控制器 & HalDelay 延时定时器
    ├── gpio/              # GPIO 模式、拉电阻、中断与引脚控制
    ├── uart/              # UART 串口配置、RingBuffer FIFO 与事务处理
    ├── spi/               # SPI 模式0-3、位序与全双工事务
    ├── i2c/               # I2C 7b/10b 寻址、主机读写与 SMBus 协议辅助
    ├── pwm/               # PWM 多通道占空比、频率与死区控制
    ├── adc/               # ADC 8-16b 分辨率、电压转换与多通道序列扫描
    ├── timer/             # 硬件定时器单次/周期模式与预分频器
    ├── rtc/               # 实时时钟 DateTime 日历计算与闹钟触发器
    ├── dma/               # DMA 内存/外设传输通道与缓冲区引擎
    ├── lock/              # CriticalSection 原子关中断与 PeripheralMutex 互斥锁
    ├── sim/               # In-Memory Virtual HAL 仿真器 (AT24C02 EEPROM, W25Q64 Flash)
    ├── stm32/             # STM32 芯片适配层 (RCC, BSRR GPIO, USART)
    ├── rp2040/            # RP2040 芯片适配层 (SIO IO, PL011 UART)
    ├── esp32/             # ESP32 芯片适配层 (GPIO Matrix, LEDC PWM)
    ├── dts/               # Device Tree 设备树 AST 与解析器
    ├── rtos/              # 嵌入式 RTOS 任务调度器与计数信号量
    ├── bsp/               # 板级支持包 (Pico, STM32F4-Discovery, ESP32-DevKitC)
    └── main/              # 整合测试与可执行主入口 demo

⚡ 快速开始与使用示例

1. 环境准备

使用最新版 MoonBit 工具链 (0.10.3 / 0.1.20260713):

# 检查 MoonBit 版本
moon version

2. 编译与检查

本项目零警告通过 MoonBit 官方链检查：

# 1. 检查代码类型与语法
moon check

# 2. 格式化代码规范
moon fmt

# 3. 生成接口定义文件
moon info

# 4. 运行全量单元测试 (63 组)
moon test

3. 运行完整示例

moon run src/main

4. 代码使用示例

// 示例：GPIO 引脚与 I2C EEPROM 仿真读写
fn demo() {
  // 1. 初始化 72MHz 系统时钟与 100ms 延时
  let clk = @clock_delay.HalClock::default_clock()
  let delay = @clock_delay.HalDelay::new(clk)
  delay.delay_ms(100)

  // 2. 配置 PA5 引脚为 High
  let pin_spec = @types.PinSpec::new(@types.PortId::PortA, 5, 0)
  let gpio_cfg = @gpio.GpioConfig::default_output(pin_spec)
  let pin = @gpio.GpioPin::new(gpio_cfg)
  let _ = pin.set_high()

  // 3. 无硬件 I2C AT24C02 EEPROM 模拟
  let i2c_cfg = @i2c.I2cConfig::default_config()
  let i2c = @i2c.I2cMaster::new(i2c_cfg)
  let addr = @i2c.I2cAddress::Addr7Bit(0x50)
  let eeprom = @sim.At24c02Eeprom::attach(i2c, addr)

  let _ = eeprom.write_byte(0x10, (0x77 : Byte))
  let val = eeprom.read_byte(0x10).unwrap()
  println("EEPROM byte at 0x10: " + val.to_int().to_string())
}