led_dev.c

源文件路径：hmi/led/led_dev.c 所属模块：hmi/led（人机界面 - WS2812 灯带编码/驱动层） 代码行数：197

1. 文件职责

本文件是 WS2812 灯带编码/驱动层的实现，负责把"第几颗灯珠、什么颜色"翻译成定时器比较值序列（bit 流），并启动一次 DMA 发送。它不直接写寄存器之外的业务逻辑：定时器 PWM 初始化在 hardware/timer/timer4.c、DMA 通道初始化在 hardware/dma/dma.c，本文件只做数据编码 + 发送触发 + 互斥标志维护。

数据流位置：上游由 hmi/led/app_led.c:156-207 的 led_build_full_buffer() 逐颗调用 ws2812_set_color_hex() 填缓冲、最后调用 ws2812_update() 启动发送；下游是 DMA0 通道 0（源地址 g_u16_ws2812_data、目标 TIMER_CH3CV(TIMER4)）与 DMA0_Channel0_IRQHandler（hardware/dma/dma.c:266-283）。

被谁驱动：ws2812_init() 由 system/board_init/board_init.c:242 在上电初始化阶段调用一次；ws2812_update() 与各写函数只可能由 led_display_task() 的调用链驱动（当前该链未接线，详见第 7 节）。

编码缓冲 g_u16_ws2812_data 被 __attribute__((at(SDRAM_WS2812_DATA_ADDR))) 固定到 SDRAM，因此本文件隐含依赖"SDRAM_Init() 必须先于任何写操作"的初始化顺序。

2. 关键数据结构与宏

3. 函数清单

本文件共 6 个函数（1 个未在头文件声明），已全部列出。文件内无 static 函数。

4. 核心逻辑解析

4.1 帧结构与位编码

WS2812（灯珠型号 FL3512SRGBICK-8MA-3T）的时序规范在文件头注释中给出（hmi/led/led_dev.c:9-41）：每位固定周期 1.20 µs（实际实现 1.25 µs），位"0"高 0.32 µs、位"1"高 0.67 µs，帧尾 >200 µs 低电平作为 Reset。

本文件的编码策略是"每位一个定时器比较值"：

u32 *pdata = &g_u16_ws2812_data[led_idx * LED_BITS];   // 每颗灯珠占 24 个 u32
for (int i = 0; i < LED_BITS; i++)
    *pdata++ = (grb_color & (0x800000 >> i)) ? T1_PULSE : T0_PULSE;

• MSB 先出（0x800000 >> i 从 bit23 走到 bit0）。
• 缓冲区元素是送给 TIMER_CH3CV(TIMER4) 的比较寄存器值，不是电平宽度本身。DMA 在 TIMER4 的更新事件（TIMER_DMA_UPD）上逐个搬运，配合 hardware/timer/timer4.c:49 的 period = 209（210 计数 @168 MHz = 1.25 µs）产生 800 kHz 的位流。
• 一个灯珠 24 表项 = 30 µs，121 颗 = 2904 表项 ≈ 3.63 ms；再加数组末尾 3 个表项（ws2812_init() 中 memset 为 0）。
• hardware/dma/dma.c:55 用 sizeof(g_u16_ws2812_data) / 4 作为传输个数（= 2907），因此数组的 +3 会被一并发送，形成帧尾的额外低电平时间；真正 >200 µs 的 Reset 由 DMA 完成中断把 PA3 拉低并保持实现（hardware/dma/dma.c:278-280）。

4.2 颜色字节序转换

ws2812_set_color_hex()（hmi/led/led_dev.c:118-145）内部有 #if 1（GRB）与 #else（RGB）两套：

u8 r = (u32_color >> 16) & 0xFF;
u8 g = (u32_color >> 8)  & 0xFF;
u8 b =  u32_color        & 0xFF;
u32 grb_color = (g << 16) | (r << 8) | b;     // 生效：GRB

WS2812 系列灯珠的 24 bit 顺序为 G7..G0/R7..R0/B7..B0，所以对外统一使用 0xRRGGBB 的调用者（hmi/led/app_led_cfg.c）无需关心字节序。ws2812_set_color_rgb()（hmi/led/led_dev.c:106）则不做转换，直接 rgb = r<<16 | g<<8 | b，两者行为不一致（该函数当前无调用点）。

4.3 发送流程与互斥标志

ws2812_update()（hmi/led/led_dev.c:86-98）：

while (g_u_ws2812_flag.bit.read_flag == TRUE)      // 1) 等待"没人在改缓冲"
    OSTimeDlyHMSM(0, 0, 0, 1);                     //    1 ms 粒度让出 CPU
g_u_ws2812_flag.bit.write_flag = TRUE;             // 2) 宣告"DMA 占用中"
gpio_mode_set(GPIOA, GPIO_MODE_AF, GPIO_PUPD_NONE, GPIO_PIN_3);  // 3) PA3 复用为 TIMER4_CH3
delay_us(1);
dma_channel_enable(DMA0, DMA_CH0);                 // 4) 使能 DMA 通道
timer_enable(TIMER4);                              // 5) 启动定时器 → 产生位流

ws2812_init()（hmi/led/led_dev.c:72-78）：

timer4_fl3512_init();                    // TIMER4 CH3 PWM，800 kHz，极性 LOW
led_timer4_pwm_dma0_channel0_init();     // DMA0 CH0：内存 g_u16_ws2812_data → TIMER_CH3CV(TIMER4)，32 bit
memset(g_u16_ws2812_data, 0, sizeof(g_u16_ws2812_data));
printf("ws2812初始化成功\n");             // USMART 调试串口输出

DMA 完成中断（hardware/dma/dma.c:266-283）负责收尾：清 FTF 标志 → timer_disable(TIMER4) → dma_channel_disable(DMA0, DMA_CH0) → 把 PA3 改成下拉输出并拉低（提供 Reset 低电平）→ g_u_ws2812_flag.bit.write_flag = FALSE。

因此一次完整的"改缓冲 → 发送 → 允许再改"闭环为：

所有写函数开头都有 if (g_u_ws2812_flag.bit.write_flag == TRUE) return;（led_dev.c:103、121、155、174），即DMA 发送期间写入被静默丢弃（不返回错误码）。

4.4 ws2812_set_color_buffer_clear() 与 ws2812_set_on_off_color_light()

void ws2812_set_color_buffer_clear(void)      // led_dev.c:153
{
    if (g_u_ws2812_flag.bit.write_flag == TRUE) return;
    for (int i = 0; i < RKP_LED_NUM; i++)
        ws2812_set_color_hex(i, 0);           // 内部又各自检查一次 write_flag
}

• 双层检查：外层一次 + 内层 121 次；每次 ws2812_set_color_hex 还会独立地置位/清零 read_flag 121 次（led_dev.c:131/144），使每次清屏产生 242 次对同一字节的读-改-写，是效率与竞态面的双重放大。
• ws2812_set_on_off_color_light(u8 u8_flag, u32 u32_color)（led_dev.c:170-192）：先清屏，u8_flag == FALSE 时用黑色 0，否则用 u32_color，然后把 121 颗全部设成同一颜色。语义是"整条灯带单色点亮/熄灭"，未在 led_dev.h 声明（编译器会告警"无前导原型"），且全工程无调用点。

4.5 时间与调度

• 本文件只有一处阻塞调用：ws2812_update() 中的 OSTimeDlyHMSM(0, 0, 0, 1)（led_dev.c:90）。由于 OS_TICKS_PER_SEC = 1000u（UCOSII/uCOS-CONFIG/os_cfg.h:51），即每次让出 1 个 tick。若调用时调度器未启动或该任务优先级最高且无其他任务就绪，则可能长期空转但不死锁（有延时调用）。
• 一帧发送约 3.63 ms，是纯硬件（DMA + TIMER）行为，不占用 CPU 时间；调用者在 ws2812_update() 返回后即可继续执行，不能立即改写缓冲（会被 write_flag 拦住）。
• 与 uCOS-II 的其它配合：无信号量、无消息邮箱；唯一的跨上下文变量是 g_u_ws2812_flag。

4.6 关键全局变量的读写

5. 对外接口

本文件导出

本文件调用的外部函数/变量

6. 依赖关系

依赖（本文件 include）：led_dev.h(45)、includes.h(46)、timer4.h(47)、timer2.h(48)、dma.h(49)、delay.h(50)、app_led.h(51)、sdram.h(52)。

timer2.h、app_led.h 在本文件正文中没有任何符号被使用（app_led.h 反向依赖 led_dev.h，构成循环 include），属多余依赖。

被依赖：

• hmi/led/app_led.c（唯一业务调用方）
• hardware/dma/dma.c（通过 dma.h:17 → led_dev.h 访问缓冲与标志）
• system/board_init/board_init.c（ws2812_init()）

7. 备注与风险点

• 缓冲越界无保护：ws2812_set_color_rgb()/ws2812_set_color_hex() 对 led_idx 不做任何范围检查（hmi/led/led_dev.c:107、130）。led_idx = 120 时写入 2880~2903 项，尚在 2907 项缓冲内；但 led_idx ≥ 122 会越界写 SDRAM，破坏紧随其后的 SDRAM_BAT_INFO_ADDR 数据区（hardware/sdram/sdram.h:65），且不会立即崩溃，属静默数据损坏。get_bms_soc() 的返回值只被用作循环上限（hmi/led/app_led.c:188），所以目前不会触发。
• g_u_ws2812_flag 的位操作竞态：volatile 不等于原子。任务侧 bit.read_flag = TRUE/FALSE（led_dev.c:109/114/131/144）与中断侧 bit.write_flag = FALSE（hardware/dma/dma.c:280）都是对同一字节 u8_all 的读-改-写；若中断落在任务侧 RMW 之间，write_flag 的清零会被覆盖 → 后续所有写函数永久 return，灯带冻结在最后一帧。建议改为独立的 volatile u8 变量或使用 OS 临界区。
• ws2812_update() 只等 read_flag，不等 write_flag（hmi/led/led_dev.c:88）：若上一帧尚未发完就再次调用，函数会重复置位 write_flag、重新配置 GPIO、再次 dma_channel_enable + timer_enable，可能造成 DMA 重装计数/半个帧中断，出现灯带乱码。当前调用链（1 s 周期）不会触发，但不属于安全设计。
• 写入被静默丢弃：DMA 期间的写操作直接 return，没有返回值也没有重试机制（led_dev.c:103/121/155/174）。ws2812_set_color_buffer_clear() 若恰逢发送中被丢弃，随后 led_build_full_buffer() 的逐颗设置也会被丢弃，但末尾的 ws2812_update() 仍会重发旧内容，表现为"这一秒灯带没变"，属难排查的偶发现象。
• ws2812_set_on_off_color_light() 未在头文件声明（hmi/led/led_dev.c:170），既无法被其他模块正常调用，也会在 Keil 中产生 "no previous prototype" 告警。
• ws2812_set_color_rgb() 与 ws2812_set_color_hex() 字节序不一致：前者 RGB、后者 GRB。若将来启用 ws2812_set_color_rgb()，红蓝会互换。
• printf("ws2812初始化成功\n")（led_dev.c:77）：初始化阶段经由串口输出中文，依赖 USMART/串口已初始化且 printf 已重定向；若 board_init 中串口初始化顺序变化会导致无输出或阻塞（usart0_init 在 board_init.c:225 先于 board_init.c:242 的 ws2812_init，目前安全）。
• g_u16_ws2812_data 命名与类型不符（u32[] 却叫 u16_），且 hardware/dma/dma.c:55 用 sizeof(...) / 4 硬编码元素宽度，两处一旦不同步就会静默改变传输长度与越界范围。
• #if 0 分支清理不彻底：hmi/led/led_dev.c:123/136-143 保留了 RGB 版本代码；hmi/led/app_led.c:161-181 保留了另一套 SOC 点亮规则，均靠编译开关切换。
• soc_color_flag/net_color_flag/sys_run_color_flag 三个位（led_dev.h:60-62）在本文件及全工程均未使用，是设计未落地的痕迹。
• 文件头注释（hmi/led/led_dev.c:2）写的是 File Name: app_led_cfg.c，与真实文件名不符。