main.h

源文件路径：user/main.h 所属模块：user（主程序入口 / 全局 IPC 句柄声明） 代码行数：66

1. 文件职责

本文件是 user/main.c 的对外头文件，但它的实际内容与本工程的 main.c 关系很浅——它不声明任何函数，只做两件事：一是声明 8 个 uCOS-II 信号量句柄与 1 个事件标志组句柄（extern），把「谁创建事件对象」和「谁使用事件对象」解耦成"main.c 创建、其它模块引用"的全局单例模式；二是定义调试宏 DEBUG_OS_EVENT。它在数据流中扮演中断服务程序与任务之间同步通道的公共契约：所有串口 ISR（hardware/usart*/）、掉电 EXTI（hardware/exti/）、CT 采样中断（midware/meter/ct.c）以及云通信快速调度触发（net/server.c）都通过 include 本文件拿到这些句柄。它只 #include "ucos_ii.h"，因此是工程里少数几个"只暴露内核类型"的轻量头文件，被 20 个源文件引用，是 user/ 目录下被依赖面最广的头文件。

2. 关键数据结构与宏

本文件不定义任何结构体、枚举、联合体、位域、函数原型或全局变量实体，只声明 extern。OS_EVENT / OS_FLAG_GRP 两个内核类型来自 #include "ucos_ii.h"（main.h:42）。

3. 函数清单

本文件是纯声明文件，共 9 个 extern 对象 + 1 个配置宏。

4. 核心逻辑解析

4.1 声明的语义：IPC 句柄的"创建-使用"分离

本文件的可执行逻辑为零，其价值全在符号可见性契约上：

• 创建方唯一：9 个句柄的实体全部在 user/main.c:53-62 定义，创建动作全部在 main.c 的 event_init()（main.c:74-131）中完成，且该函数在 start_task 的临界区内被调用一次。
• 使用方分散：20 个文件通过 include 本文件取得这些句柄。若没有本文件，这些硬件驱动就必须 extern 到 main.c 或自行创建，会破坏"句柄单例"的约束。
• 初始化时序隐含契约：所有使用方（ISR 与任务）都假设"句柄在我第一次访问前已经非空"。这个前提由 main() 的顺序保证——Board_init()（board_init.c:217，其中初始化了 usart0/1/2/4/5、EXTI、CAN 等）在 OSInit() 与 start_task 之前执行。但关中断是在 start_task 内才做的（main.c:154），也就是说 Board_init() 期间中断已开（INTX_ENABLE() 是 main.c:350，在 Board_init() 之前），此时若某个串口中断到达并调用 OSSemPost(g_t_uartX_rcv_sem)，而该句柄还是 NULL——这是一个真实存在的启动窗口风险，见备注 3。

4.2 通信协议帧格式

本文件不涉及任何协议；但通过声明 g_t_uart1_rcv_sem … g_t_uart5_rcv_sem，它隐含地把 5 条通信通道的"接收完成"语义绑定到了 5 个信号量上：

超时重试机制不由本文件决定，而由消费者在 OSSemPend 里给出的超时值决定：hardware/usart*/ 的收帧函数统一用 500 tick（=500 ms）；midware/interface/interface.c:364 的 Modbus 任务用 100 tick，源码注释写明「调整阻塞时间，防止切换到充电桩时任务无法继续执行」。

4.3 定时 / uCOS-II 配合

本文件不声明任何任务、不定时、不持有状态，因此没有状态机、没有状态迁移。

4.4 关键全局变量如何被读写

本文件不含变量定义，只有声明。就可见性而言，这些句柄的读写分布为：

• 只写（且仅一次）：user/main.c 的 event_init()，8 次 OSSemCreate + 1 次 OSFlagCreate。
• 写（投递）：hardware/usart0/usart0.c:92、usart1.c:303、usart2.c:94、usart3.c:123、usart4.c:120、usart5.c:99、hardware/exti/exti.c:95、midware/meter/ct.c:834、net/server.c:838、logic/logic.c:2953、midware/inverter/inverter.c:1185——多数位于中断上下文。
• 写（清零）：usart0.c:151、usart1.c:196、usart2.c:152、usart3.c:200、usart4.c:245、usart5.c:159、elink_parse.c:227 的 OSSemSet(..., 0, &err)，用于丢弃上一次未消费的信号。
• 读（等待）：usart0.c:212、usart1.c:256、usart2.c:213、usart3.c:277、usart4.c:325、midware/interface/interface.c:364、midware/ethernt/wireless/elink_parse.c:108、midware/meter/ct.c:883（task_sampling）、data/data.c:263（task_system_data）、logic/logic.c:2912、midware/inverter/inverter.c:1054/1207。
• 读+写（标志位的置/清）：g_t_fast_dispatch_flag 由 OSFlagPost 置位、OSFlagPend(..., OS_FLAG_CONSUME) 自动清位，形成 4.4 节所述的流水线。

5. 对外接口

本文件导出（供外部使用）

本文件不导出任何函数、类型、typedef 或 static inline。

本文件引用（外部符号）：仅 OS_EVENT、OS_FLAG_GRP 两个 uCOS-II 内核类型（main.h:42 的 #include "ucos_ii.h"）。不引用任何应用层符号。

6. 依赖关系

依赖：

• #include "ucos_ii.h"（main.h:42）——这是本文件唯一的 include，提供 OS_EVENT、OS_FLAG_GRP、INT8U 等类型；os_cfg.h / app_cfg.h / os_cpu.h 由 ucos_ii.h 链式引入。
• 隐式依赖：本文件用 #include 名字是 "ucos_ii.h"，但没有 include includes.h 或 chip.h。这意味着 20 个包含者中若某个只依赖本文件而不先引入工程类型头，会拿不到 u8 等自定义类型（例如 hardware/dma/dma.h、hardware/spi/spi1.h 这类纯头文件）；实际能编译通过依赖各 .c 先包含 includes.h 的顺序约定。
• 头文件名 main.h 与 user/ 目录同名，在 Keil 的 include 搜索路径里存在同名冲突隐患（工程里如果将来新增另一个 main.h，#include "main.h" 会解析到先搜索到的那一个）。

被依赖（全部 20 个 include 点）：

注意 user/main.c 没有 include user/main.h——它在自己文件里直接定义这些变量，不依赖声明文件。这是它能编译通过的原因（否则会与 extern 声明一起出现，虽然合法但不必要）。

7. 备注与风险点

1. 头文件不自包含（not self-contained）：本文件只 include ucos_ii.h，不引入 includes.h/chip.h，所以拿不到 u8/u32/SET/TRUE 等工程自定义类型。若某个文件只想用信号量句柄而先 include 了本文件、之后才 include 类型头，编译顺序一换就会报错。当前靠"各 .c 先包含 includes.h"的隐式约定活着。
2. ST 模板残留样板：main.h:1-36 与 main.h:66 是 STMicroelectronics Templates/Inc/main.h V1.2.2（2015-05-25）的版权头与尾注释，共约 36 行，占文件一半以上篇幅，与本工程（AlphaESS EMS、GigaDevice GD32F407）没有任何关系。@file Templates/Inc/main.h、@author MCD Application Team 等元信息全部失真，会误导阅读者认为本文件源自 ST 工程模板。
3. 句柄结构体完全暴露，靠调用方自律：本文件声明了 9 个 OS_EVENT * / OS_FLAG_GRP * 的 extern。uCOS-II 的 OS_EVENT / OS_FLAG_GRP 是公开的透明结构体（定义在 ucos_ii.h 内，OS_EVENT 含 .OSEventType、.OSEventPtr、.OSEventCnt、.OSEventGrp、.OSEventName 等成员），不是不透明句柄。任何包含本文件的驱动都能在中断里直接读写其成员（例如直接改 .OSEventCnt）从而绕过内核的临界区保护——本工程实际未这样做（全部走 OSSemPost/OSSemPend API），但这层保护完全依赖调用方自律，头文件层面无从约束。
4. 启动窗口内的空句柄风险：INTX_ENABLE()（main.c:350）在 Board_init()（main.c:353）之前执行，而 9 个内核对象直到 start_task 内的 event_init()（main.c:334，位于 OS_ENTER_CRITICAL 之内）才被创建。若 Board_init() 之中或之后、event_init() 之前有串口中断到达并执行 OSSemPost(g_t_uartX_rcv_sem)，传入的是全局变量初始值 NULL（BSS 清零），OSSemPost 会因 OS_ARG_CHK_EN = 0（os_cfg.h:31）不做参数检查而直接解引用空指针。这属于低概率但有理论依据的启动竞态。稳妥做法是在 Board_init() 里先关闭相关外设中断，或在 OSInit() 之前集中创建这些内核对象。
5. DEBUG_OS_EVENT 语义单一：它只控制 main.c 中 9 行指针打印，不控制任何行为。把它放在 main.h 而不是 main.c 顶部，会让所有 20 个包含者都看到这个宏，存在宏名污染的可能（虽然名字足够特异）。
6. include guard 命名不规范：__MAIN_H__（main.h:39）同时存在两个问题：(a) 以双下划线开头是 C 标准保留给实现的标识符；(b) 该宏名过于通用，极易与第三方库或其他 ST 模板的 main.h 冲突——而本工程正是从 ST 模板派生的，若再引入第二个 ST 模板文件，两个 __MAIN_H__ 会互相屏蔽，导致其中一个头文件的 extern 声明静默消失，编译器不报错但在链接期才暴露未定义符号。
7. 未声明 SYSTEM_TASK_CNT_T g_t_task_run_status 的 extern：g_t_task_run_status 同样定义在 user/main.c:31，但它的 extern 声明不在本文件，而在 UCOSII/uCOS-CONFIG/includes.h:49（连同类型定义 includes.h:29-47）。结果是同一批"main.c 定义的全局对象"被拆到两个头文件里声明，维护时需要同时看两处才能拼出 main.c 的对外契约，属于接口分散。
8. 注释与版权声明不一致：文件头 @file Templates/Inc/main.h、@date 25-May-2015 与文件实际最后修改时间（工程内为 2025-10-09）差距十年，且无任何 AlphaESS 的修改记录说明。虽不影响功能，但对版本追溯是负面因素。