第 2 篇：硬件抽象与 SPI 总线共享

第 2 篇硬件抽象与 SPI 总线共享用 Rust 构建ESP32-C3 电子墨水屏阅读器 · 系列文章https://github.com/longxiangam/epd-reader引言操作硬件是嵌入式开发里最容易出错的地方两个模块同时驱动同一条 SPI 总线、寄存器配置冲突、GPIO 被两边同时拉高拉低——这些问题往往要等到运行时才暴露调试困难。esp-hal 用 Rust 的类型系统和所有权把其中一部分变成了编译期错误。本文讲本项目的硬件抽象重点是最典型的场景一条 SPI 总线怎么在电子墨水屏和 SD 卡之间安全共享。1. esp-hal v1.x 的硬件抽象设计1.1 外设获取所有权的第一步在 PC 上你可能通过系统调用来操作硬件。但在裸机嵌入式环境中硬件外设是直接映射到内存地址的寄存器。esp-hal 封装了这些底层细节提供一个类型安全的接口。一切始于hal_init// src/main.rs:83-84letconfigHalConfig::default().with_cpu_clock(CpuClock::max());letperipheralshal_init(config);hal_init返回一个Peripherals结构体它包含了 ESP32-C3 的所有硬件外设。关键在于每个外设只能被获取一次。hal_init内部使用了 Rust 的take()模式——第二次调用会 panic。这意味着全局只有一个Peripherals实例而它的字段通过移动语义确保每个外设只有唯一的所有者。1.2 GPIO从 Peripherals 到可用的引脚esp-hal v1.x 中GPIO 引脚直接从Peripherals获取// src/main.rs:106-112letepd_busyperipherals.GPIO6;// 输入引脚直接拿letepd_rstperipherals.GPIO7;// 输出引脚稍后配置letepd_csOutput::new(// 输出引脚立即配置peripherals.GPIO3,Level::High,// 初始电平高不选中OutputConfig::default(),// 默认输出配置);这里体现了 Rust 的所有权转移peripherals.GPIO6被移动给epd_busy变量后peripherals中就不再持有 GPIO6 了。如果后续代码试图再访问peripherals.GPIO6编译器会报错。Output::new是 esp-hal v1.x 的新 API需要三个参数pinGPIO 引脚所有权转入initial_level初始电平OutputConfig输出配置开漏、上拉等其中OutputConfig是 v1.x 新增的旧版只需两个参数。这种 Builder 模式的配置结构体在 esp-hal v1.x 中非常普遍。1.3 Input带配置的输入引脚// src/event.rs:99-100letmutkey1Input::new(key1,esp_hal::gpio::InputConfig::default().with_pull(Pull::Up)// 上拉输入);按钮引脚配置为上拉输入——未按下时读到高电平按下时读到低电平。InputConfig::default().with_pull(Pull::Up)是 esp-hal v1.x 的配置方式比旧版直接传Pull::Up更具扩展性。1.4 SPI总线配置SPI 是本项目最关键的总线电子墨水屏和 SD 卡都挂在上面// src/main.rs:129-137letspiSpi::new(peripherals.SPI2,SpiConfig::default().with_frequency(Rate::from_mhz(32))// 32MHz 时钟.with_mode(Mode::_0),// SPI Mode 0 (CPOL0, CPHA0)).unwrap().with_sck(epd_sclk)// GPIO8 时钟线.with_miso(epd_miso)// GPIO10 数据输入.with_mosi(epd_mosi);// GPIO0 数据输出esp-hal v1.x 的 SPI 配置使用SpiConfigBuilder 模式with_frequency(Rate::from_mhz(32))32MHz 是 SPI2 支持的较高速率with_mode(Mode::_0)注意枚举变体用了 PascalCase_0这是 Edition 2024 的规范.with_sck/miso/mosi()链式调用分配引脚注意创建 SPI 实例后peripherals.SPI2的所有权已经转移不能再次创建。同时epd_sclk、epd_miso、epd_mosi这三个引脚也被消费掉了。2. SPI 总线共享问题的本质本项目一条 SPI 总线上挂了两个设备EPD 和 SD 卡各自有自己的片选CS信号。直觉做法是操作 SD 卡前拉低CS_SD、传完拉高操作屏幕前拉低CS_EPD、传完拉高。问题在于并发如果两个任务几乎同时操作MOSI/SCK 线会被两个设备同时驱动数据错乱。在 Embassy 的异步环境里尤其要注意——一个任务.await让出执行权时另一个任务可能正好插进来操作 SPI一次传输若中途被打断CS 还拉着、总线却被别人占用就更糟。2.1 解决方案CsMutex CriticalSectionDevice本项目使用critical_section::Mutex配合embedded_hal_bus::spi::CriticalSectionDevice来解决这个问题// src/main.rs:161-168usecritical_section::MutexasCsMutex;// 1. 用 CsMutex 包裹 SPI 总线letshared_spiCsMutex::new(RefCell::new(spi));letshared_spi_staticstatic_cell::make_static!(shared_spi);// 2. 为每个设备创建独立的 CS-gated SPI 设备letspi_bus_sdCriticalSectionDevice::new_no_delay(shared_spi_static,sdcard_cs).unwrap();letspi_bus_epdCriticalSectionDevice::new_no_delay(shared_spi_static,epd_cs).unwrap();// 3. 提升为 static 生命周期letspi_bus_sdstatic_cell::make_static!(spi_bus_sd);letspi_bus_epdstatic_cell::make_static!(spi_bus_epd);工作原理如下图SPI2 (32MHz, Mode 0) │ CsMutexRefCellSpi (临界区互斥锁) ╱ ╲ CriticalSectionDevice CriticalSectionDevice (CS GPIO5, SD 卡) (CS GPIO3, 屏幕) │ │ sd_mount 模块 display 模块CsMutex是基于临界区的互斥锁。当任意一个设备要进行 SPI 操作时关闭中断进入临界区获取RefCell的可变引用拉低自己的 CS 引脚进行 SPI 数据传输拉高 CS 引脚释放引用恢复中断CriticalSectionDevice将这个流程封装成一个标准的embedded_hal::SpiDevicetrait 实现——对调用者来说它就是一个普通的 SPI 设备不需要关心互斥细节。2.2 为什么用 CsMutex 而不是 Embassy Mutex这里有一个微妙的设计选择锁类型实现方式适用场景CriticalSectionRawMutex关中断短时间持有微秒级 SPI 操作embassy::sync::Mutex异步等待可能长时间持有网络操作等SPI 操作非常快几微秒到几十微秒关中断的开销远小于异步锁的上下文切换开销。而且 SPI 操作本身不能被.await打断它不是异步的所以用临界区锁是最合适的。2.3new_no_delay是什么CriticalSectionDevice::new_no_delay(shared_spi_static,sdcard_cs).unwrap();new_no_delay表示不需要延迟对象。旧版CriticalSectionDevice::new()需要传入一个Delay参数用于 CS 拉低后等待设备就绪。但本项目的 EPD 和 SD 卡都不需要 CS 到数据之间的延迟所以使用new_no_delay简化接口。这也是embedded-hal-bus0.3 版本的改进。3. 全局静态状态管理在嵌入式 Rust 中硬件资源通常是全局唯一的——一个 SPI 总线、一个显示控制器、一个 WiFi 接口。但 Rust 的所有权模型要求每个值有唯一的所有者这与全局共享的需求冲突。本项目使用了四种模式来解决这个矛盾3.1 模式一Embassy Mutex Option这是最常用的模式用于需要在多个异步任务间共享的数据// src/wifi.rs 中的示例pubstaticWIFI_INFO:MutexCriticalSectionRawMutex,OptionWifiStorageMutex::new(None);// 使用时ifletSome(wifi)WIFI_INFO.lock().await.as_ref(){println!(wifi_ssid:{:?},wifi.wifi_ssid);}// 写入时WIFI_INFO.lock().await.replace(wifi_storage);为什么用Option包装因为全局变量在声明时还没有数据硬件还没初始化所以初始值是None。初始化后通过replace()填入实际值。Embassy 的Mutex是异步的——lock().await会在锁被占用时让出执行权不会阻塞其他任务。3.2 模式二core::ptr 安全访问 static mut用于性能敏感的单写多读场景如帧缓冲区// src/display.rs:60staticmutDISPLAY:OptionEpdDisplayNone;// 写入仅在初始化时调用一次unsafe{core::ptr::addr_of_mut!(DISPLAY).write(Some(display));}// 读取在渲染时频繁调用pubfndisplay_mut()-OptionstaticmutEpdDisplay{unsafe{(*core::ptr::addr_of_mut!(DISPLAY)).as_mut()}}为什么不用 Mutex因为帧缓冲区的访问模式非常明确写入仅在初始化时一次读取每次渲染时从页面代码调用而且渲染是整个系统最频繁的操作异步 Mutex 的开销不可接受。使用core::ptr::addr_of_mut!是 Rust 对static mut访问的安全要求——直接解引用*mut在新版编译器中会产生警告甚至错误。3.3 模式三StaticCell make_static!用于将局部变量提升为static生命周期// src/main.rs:162-163letshared_spiCsMutex::new(RefCell::new(spi));letshared_spi_staticstatic_cell::make_static!(shared_spi);make_static!宏将值分配到一个全局静态存储区域返回static mut T。这在 Embassy 任务中很常见——任务的参数通常要求static生命周期但很多值是在main()中动态创建的。static_cellcrate 内部使用一个全局的OnceCell来确保每个值只被初始化一次。3.4 模式四RTC 快速内存用于深度睡眠后需要保持的变量// src/display.rs:47-48#[ram(unstable(rtc_fast))]staticmutRENDER_TIMES:u320;ESP32-C3 的 RTC 快速内存是一块特殊的 SRAM 区域在深度睡眠期间保持供电。放在这里的变量在唤醒后仍然保留上次的值。#[ram(unstable(rtc_fast))]是 esp-hal v1.x 的写法旧版是#[ram(rtc_fast)]需要启用unstablefeature。本项目中有多个 RTC 变量渲染次数RENDER_TIMES、电池电量LAST_BATTERY_PERCENT、睡眠时间戳WHEN_SLEEP_RTC_MS等——它们都需要在唤醒后恢复状态。四种模式对比模式安全性性能适用场景Embassy Mutex Option安全编译期运行时较低异步锁多任务共享数据core::ptr static mutunsafe最高单写多读、高频访问StaticCell安全一次性局部变量提升为staticRTC 内存unsafe最高深度睡眠保持4. ADC模拟输入与多按键检测本项目的三个按键中按键 2 和按键 3 通过 ADC 分压电路共用一个 GPIO// src/main.rs:143-148letmutadc1_configAdcConfig::new();letadc_pinunsafe{peripherals.GPIO2.clone_unchecked()};letadc1_pinadc1_config.enable_pin_with_cal::_,AdcCalCurveesp_hal::peripherals::ADC1(adc_pin,Attenuation::_11dB);硬件上按键 2 和按键 3 通过不同的电阻分压接到 GPIO2。按下不同的键时ADC 读到不同的电压值。软件通过采样 ADC 来判断按下的是哪个键// src/event.rs:202-235asyncfnjudge_adc_num()-usize{// 采样 20 次 ADC 值取平均letavgadc_valute_sum/20;ifavg200{2// 按键 2低电压}else{3// 按键 3较高电压}}esp-hal v1.x 中 ADC 的类型系统更加严格// src/event.rs:119-120pubstaticADC_PIN:MutexCriticalSectionRawMutex,OptionAdcPinesp_hal::peripherals::GPIO2static,esp_hal::peripherals::ADC1,AdcCalCurveesp_hal::peripherals::ADC1Mutex::new(None);pubstaticADC_PER:MutexCriticalSectionRawMutex,OptionAdcstatic,esp_hal::peripherals::ADC1,esp_hal::BlockingMutex::new(None);泛型参数精确到了具体的引脚类型 (GPIO2static) 和 ADC 控制器类型 (ADC1)以及校准方式 (AdcCurve)。这种精度在旧版中是没有的它带来了更好的编译期类型安全。5. RTC实时时钟与睡眠控制// src/main.rs:92-93letrtcesp_hal::rtc_cntl::Rtc::new(peripherals.LPWR);crate::sleep::RTC_MANGE.lock().await.replace(rtc);RTCReal-Time Clock是 ESP32-C3 的低功耗外设它独立于 CPU 运行即使在深度睡眠期间也能保持计时。本项目中RTC 的作用包括记录进入睡眠的时间唤醒后通过差值恢复系统时间配置唤醒源定时器、GPIO控制深度睡眠LPWRLow Power外设在 esp-hal v1.x 中直接从Peripherals获取取代了旧版的RTC_CNTL。小结本文深入了 esp-hal v1.x 的硬件抽象设计技术点要点外设所有权Peripherals的每个字段只能被移动一次GPIO 新 APIOutput::new(pin, level, OutputConfig)增加配置结构体SPI 配置SpiConfigBuilder 模式Rate::from_mhz()频率设置SPI 共享CsMutexCriticalSectionDevice临界区互斥全局状态四种模式Embassy Mutex / core::ptr / StaticCell / RTCADC严格泛型参数曲线校准模拟按键检测RTCLPWR外设低功耗计时深度睡眠控制核心思想是用 Rust 的类型系统在编译期保证硬件访问的安全性用运行时锁在必要时协调并发访问。在下一篇文章中我们将进入电子墨水屏的世界看看显示渲染架构是如何设计的。