chrg/docs/程序流程与函数说明.md

# 程序流程与函数说明

## 1. 文档范围

本文按当前源码（2026-07-19）说明 `apps/chrg/applications/` 的自研函数、运行流程和函数级调用关系，并补充 `apps/boot/` 的启动主链。`rt-thread/`、`libs/`、CubeMX 生成代码、HAL 中断模板以及调试 shell 命令的内部库调用不展开。调用关系由源码静态分析得到；通过 `INIT_*_EXPORT`、线程入口、回调和函数指针发生的调用会单独标明。

## 2. 上电与初始化流程

```mermaid
flowchart TD
    R["芯片复位"] --> B["Boot main()"]
    B --> SI["System_Init()"]
    SI --> AI["APP_Init()"]
    AI --> AR["APP_Running()"]
    AR --> CK["boot_CheckAndHandle()"]
    CK -->|APP 有效| JA["boot_JumpToAPP()"]
    CK -->|需要升级| RX["recvDataHandler()"]
    RX --> YH["ymodemHandler()"]
    YH --> BP["boot_ProtocolDataHandle()"]
    BP --> FM["FM_* 擦写/校验函数"]
    FM --> JA
    JA --> RTT["RT-Thread 启动"]
    RTT --> INIT["INIT_PREV/DEVICE/ENV/APP_EXPORT"]
    INIT --> TI["chrg_thread_init()"]
    TI --> TC["chrg_thread_create() x 6"]
    TC --> MAIN["main() 空闲循环"]
```

`main()` 不是业务入口。GPIO、FAL、定时器、串口、继电器和看门狗由 RT-Thread 自动初始化段调用；`chrg_thread_init()` 再创建六个常驻线程。初始化失败目前不会阻止后续线程继续创建，排障时必须查看启动日志。

## 3. 运行期线程与数据流

| 线程入口 | 职责 | 主要输入 | 主要输出 |
|---|---|---|---|
| `chrg_north_thread_entry` | 接收协议板/Sink/Source 北向帧 | 北向 UART ringbuffer | 更新 `chrgnorth.sw[]`，投递帧 |
| `chrg_south_thread_entry` | 接收功率板 Modbus 响应 | 南向 UART ringbuffer | 投递响应到轮询/通信模块 |
| `chrg_comm_thread_entry` | 上位机 Modbus、寄存器映射和业务命令 | mailbox、Modbus 回调 | 修改目标状态，生成南北向命令 |
| `chrg_lcd_thread_entry` | HMI 报文解析和状态显示 | LCD 串口 | 修改配置、刷新页面 |
| `chrg_roll_nor_thread_entry` | 分时驱动四路 Sink/Source 协议板 | event、通道状态 | 查询/设置协议板，运行 Sink 状态机 |
| `chrg_roll_sou_thread_entry` | 串行执行功率板寄存器读写 | event、批命令队列 | Modbus RTU 请求与完成状态 |

```mermaid
flowchart LR
    PC["上位机"] --> MB["Modbus 回调 func* / mb_reg_*_cb"]
    LCD["HMI"] --> LP["chrg_lcd_parse()"]
    MB --> CM["chrg_comm_parse_msg()"]
    LP --> ST["chrgnorth.sw[] 目标状态"]
    CM --> ST
    RN["chrg_roll_nor_thread_entry()"] --> SET["chrg_roll_nor_set()"]
    ST --> SET
    SET --> SK["sink/source 设置函数"]
    SK --> NTX["chrg_north_send()"]
    DEV["协议板"] --> NRX["chrg_north_thread_entry()"]
    NRX --> FD["chrg_north_frame_dispatch()"]
    FD --> SP["chrg_sink_parse() / Source 解析"]
    SP --> SW["chrg_sink_work()"]
    SW --> SR["chrg_set_sou_reg()"]
    CM --> SR
    SR --> RS["chrg_roll_sou_thread_entry()"]
    RS --> STX["chrg_south_send()"]
    PWR["功率板"] --> SRX["chrg_south_thread_entry()"]
    SRX --> SD["chrg_south_frame_dispatch()"]
    SD --> RS
```

## 4. Sink 工作状态机

```mermaid
stateDiagram-v2
    [*] --> INIT
    INIT --> WAIT: 下发停止/安全继电器状态
    WAIT --> RUNING: 电压正常且接近目标
    RUNING --> WAIT: 电压正常但电流连续偏低
    RUNING --> LOW: 电压连续低于 WORK_MIN_VOLT
    WAIT --> LOW: 电压连续过低
    LOW --> WAIT: 电压恢复并重新准备
    RUNING --> OFF: 停止工作
    WAIT --> OFF: 停止工作
```

函数级主链：`chrg_roll_nor_thread_entry()` → `chrg_roll_nor_set()` → `sink_get_vc()` → 北向响应 → `chrg_north_frame_dispatch()` → `chrg_sink_parse()` → `chrg_sink_work()` → `chrg_sink_work_init()` / `chrg_sink_work_volt_runing()` / `chrg_sink_nor_work_low()` / `chrg_sink_nor_work_off()`。继电器动作由 `chrg_sink_change_ON()`、`chrg_sink_SHOUT_ON()`、`chrg_nor_sw_rel()` 完成，功率板命令最终经 `chrg_set_sou_reg()` 交给南向轮询线程。

## 5. 函数说明：入口与线程基础设施

### `main.c`

| 函数 | 说明 |
|---|---|
| `show_app_version()` | 打印 RT-Thread 版本和固件编译时间，无输入和返回值。 |
| `main()` | 设置 shell 提示符后进入 1 秒延时循环；业务线程由自动初始化段提前创建。 |

### `thread/chrg_thread.c`

| 函数 | 说明 |
|---|---|
| `chrg_thread_evt_send()` | 向指定线程发送事件位；线程或事件对象无效时返回错误。 |
| `chrg_thread_mb_free()` | 释放邮箱消息及其 `payload`，仅供本文件失败路径使用。 |
| `chrg_thread_mb_send()` | 向指定线程邮箱转移消息所有权；发送失败时自动释放消息。 |
| `chrg_thread_mq_send()` | 向指定线程消息队列复制定长消息。 |
| `chrg_thread_create()` | 按 `chrgthr[]` 配置创建 IPC 对象、线程并启动线程。 |
| `chrg_thread_init()` | 遍历六个线程配置并创建；由 `INIT_APP_EXPORT` 隐式调用。 |

## 6. 函数说明：通信线程

### `thread/chrg_north.c`

| 函数 | 说明 |
|---|---|
| `chrg_compare()` | 计算两个有符号量的绝对差值。 |
| `chrg_source_stop()` | 按步骤停止 Source 输出并处理继电器/状态复位。 |
| `chrg_source_standard_output()` | 执行 Source 标准输出控制流程。 |
| `chrg_source_fast_output()` | 执行 Source 快充协议输出流程。 |
| `chrg_source_setting()` | 根据 Source 当前配置选择和推进设置过程。 |
| `chrg_sink_parse()` | 解析 Sink 电压、电流及状态，做低压/无流判定并调用 `chrg_sink_work()`。 |
| `chrg_north_handle_Seting_Volt()` | 解析北向设置电压类响应并更新通道状态。 |
| `chrg_north_switch()` | 选择当前北向物理通道。 |
| `chrg_north_send()` | 通过北向 TTY 发送一帧数据。 |
| `chrg_north_frame_head()` | 从 ringbuffer 搜索合法帧头。 |
| `chrg_north_frame_reset()` | 重置组帧上下文，并按参数决定是否释放缓存。 |
| `chrg_north_frame_append()` | 将接收字节追加到当前帧缓存。 |
| `chrg_north_frame_dispatch()` | 校验完整帧并分派到 Source/Sink 业务解析。 |
| `chrg_north_pickup_frame()` | 驱动“找帧头—收帧体—分派”状态机。 |
| `chrg_north_thread_entry()` | 北向接收线程主循环，从 UART ringbuffer 持续提取帧。 |
| `north_ch()` / `north_diag()` | FinSH 调试命令：切换通道、查看诊断计数。 |

### `thread/chrg_south.c`

| 函数 | 说明 |
|---|---|
| `chrg_south_switch_lv1()` / `chrg_south_switch_lv2_1()` / `chrg_south_switch_lv2_2()` | 控制级联选择线，完成南向通道硬件选通。 |
| `chrg_south_switch()` | 校验通道并组合调用三级选择函数。 |
| `chrg_south_send()` | 通过南向 TTY 发送 Modbus RTU 帧。 |
| `chrg_south_frame_head()` | 从 ringbuffer 识别目标地址和功能码。 |
| `chrg_south_frame_reset()` | 清理南向组帧状态和动态缓存。 |
| `chrg_south_frame_append()` | 追加南向接收字节。 |
| `chrg_south_frame_dispatch()` | 校验 CRC 后将响应投递给消费者。 |
| `chrg_south_pickup_frame()` | 推进南向组帧状态机。 |
| `chrg_south_thread_entry()` | 南向接收线程主循环。 |
| `south_ch()` | FinSH 南向通道调试命令。 |

### `thread/chrg_roll_nor.c`

| 函数 | 说明 |
|---|---|
| `sink_fill_pd_buf()` | 按协议类型把组号、电压、电流编码为 Sink 参数字节。 |
| `chrg_nor_source_stop()` | 分步骤停止 Source，关闭继电器并清理切换标志。 |
| `chrg_roll_nor_sw_uart()` | 在指定通道选择 Sink 或 Source UART。 |
| `chrg_roll_nor_sink_pro_set()` | 组装并发送 Sink 快充协议设置。 |
| `chrg_roll_nor_source_pro_set()` | 按设置来源选择 Source 协议下发函数。 |
| `chrg_roll_nor_parse()` | 根据角色和子命令生成一次北向查询/设置动作。 |
| `chrg_roll_nor_cmd()` | 北向命令参数检查接口；当前仅做空指针检查。 |
| `chrg_roll_nor_set()` | 北向轮询核心状态机，推进每通道 Source/Sink 子步骤。 |
| `chrg_roll_nor_thread_entry()` | 轮询四个北向通道，等待响应并控制超时/重试。 |
| `sink()` / `source()` | FinSH 手工配置 Sink/Source 的调试入口。 |
| `chrg_trim_crc()` | 计算校准数据 CRC。 |
| `chrg_trim_set_volt()` / `chrg_trim_set_curr()` / `chrg_trim_set_source_curr()` | 写入电压、电流及 Source 电流校准值。 |
| `chrg_trim_set_zero()` | 执行零点校准设置。 |
| `chrg_roll_trim_set()` | 按校准类型分派具体校准函数。 |

### `thread/chrg_roll_sou.c`

| 函数 | 说明 |
|---|---|
| `chrg_sou_com_batch_submit()` | 提交一批南向连续写寄存器命令。 |
| `chrg_sou_com_batch_add_reg()` | 向当前批次追加通道、寄存器和值。 |
| `chrg_set_sou_reg()` | 提交单个异步寄存器写命令。 |
| `chrg_set_sou_reg_com()` | 将寄存器写入合并批次。 |
| `sou_com_batch_next()` | 在锁保护下取下一条批命令。 |
| `sou_com_batch_complete()` | 标记批命令完成并推进队列。 |
| `sou_com_batch_cancel()` | 取消指定通道批命令。 |
| `sou_com_batch_pending_locked()` | 判断锁内是否还有待处理批命令。 |
| `sou_single_command_finish()` | 结束单命令，恢复期望运行状态。 |
| `sou_com_response_matches()` | 判断响应是否匹配当前请求。 |
| `sou_msg_free()` | 释放南向邮箱消息。 |
| `sou_com_command_failed()` | 统一处理超时/协议错误和批次回滚。 |
| `chrg_roll_sou_thread_entry()` | 串行发送南向命令、等待响应并处理重试。 |
| `south_send()` / `south_run()` | FinSH 发送寄存器和启停调试命令。 |

## 7. 函数说明：业务与协议

### `utils/chrg_sink.c`

| 函数 | 说明 |
|---|---|
| `sink_get_vc()` / `sink_get_pd()` | 生成 Sink 电压电流/协议查询帧。 |
| `sink_set_cc_line()` / `sink_set_cc_lvl()` | 设置 CC 线选择和电平。 |
| `sink_set_pd()` | 编码并发送 Sink 快充协议参数。 |
| `chrg_sink_work_init()` | 初始化工作步骤并下发停止/安全继电器命令。 |
| `chrg_sink_work_volt_runing()` | 在电压满足条件时推进 RUNING 动作。 |
| `chrg_sink_nor_work_low()` | 处理持续低压状态并复位运行条件。 |
| `chrg_sink_nor_work_off()` | 执行 Sink 停机收尾。 |
| `chrg_sink_change_ON()` / `chrg_sink_SHOUT_ON()` | 控制换向和短接相关继电器步骤。 |
| `chrg_sink_work()` | 根据 `work_mode` 分派 Sink 工作状态。 |

### `utils/chrg_source.c`

| 函数组 | 说明 |
|---|---|
| `source_get_vc()` / `source_get_pd()` | 生成 Source 电参/协议查询帧。 |
| `source_set_cc_lvl()` / `source_set_cc_choose()` | 配置 Source CC 电平和选择方式。 |
| `parse_mulit_gear_One()` / `parse_power_single_gear()` | 解析单组固定档快充能力。 |
| `parse_pd_11group_pdo()` / `parse_power_pdo_gear()` | 解析 PDO/PPS 多档能力。 |
| `parse_mulit_gear_more()` / `parse_multi_gear_more()` | 解析多组多档协议能力。 |
| `parse_ufcs_gear_more()` / `parse_power_ufcs()` | 解析 UFCS 档位。 |
| `pd_fill_single_group()` | 通用单组协议参数编码。 |
| `source_set_pd()` | 按协议、电压和电流生成 Source 设置帧。 |
| `pd_fill_single_group_com()` | 按通信寄存器档位编码单组参数。 |
| `pd_fill_single_group_need_src_com()` / `pd_fill_single_group_no_src_com()` | 分别编码需要/不需要 Source 参数的协议。 |
| `pd_fill_single_group_FCP_AFC()` / `pd_fill_single_group_UFCS()` | 编码 FCP/AFC 和 UFCS 专用参数。 |
| `source_set_pd_com()` / `source_set_pd_new_com()` | 根据寄存器配置或完整通道状态下发 Source 协议。 |

### `utils/chrg_eload.c`

| 函数组 | 说明 |
|---|---|
| `chrg_eload_set_ymodem_resp()` / `chrg_eload_get_ymodem_resp()` / `chrg_eload_clear_ymodem_resp()` | 设置、读取和清除电子负载升级响应标志。 |
| `memcmp_8bytes()` | 比较固定 8 字节标识。 |
| `chrg_eload_read_regs()` / `chrg_eload_write_reg()` / `chrg_eload_write_More_reg()` | 生成电子负载 Modbus 读、单写和多写请求。 |
| `chrg_eload_send_ymodem_data()` | 转发 YModem 升级数据。 |
| `chrg_write_cv()` | 写入电子负载 CV 参数。 |
| `chrg_eload_send_relay()` | 下发电子负载继电器动作。 |
| `chrg_eload_refresh()` | 刷新电子负载测量状态。 |
| `chrg_eload_parse()` | 解析电子负载响应并更新通道数据。 |
| `snp_ch()` | 选择电子负载通道。 |
| `Show_Volt()` / `Show_Curr()` / `Show_Ripple()` / `Show_DZF()` | 计算或刷新对应测量显示项。 |
| `Sta_compute()` | 汇总测量状态。 |
| `LCD_SHOW()` | 将电子负载测量结果推送到 LCD。 |

### `utils/chrg_north_pkg.c` 与 `utils/chrg_utils.c`

| 函数 | 说明 |
|---|---|
| `chrg_north_pkg_encode()` / `chrg_north_pkg_decode()` | 编码和解码北向协议包，并校验长度/校验值。 |
| `mb_crc16()` | 计算 Modbus CRC16。 |
| `_crc8()` / `calc_crc8()` | 单字节推进及整段 CRC8 计算。 |
| `u16_to_u8v()` / `u16_to_u8v_com()` / `u8v_to_u16()` | 16 位整数与字节序列互转。 |
| `u32_to_u8v()` / `u8v_to_u32()` | 32 位整数与字节序列互转。 |
| `swap_u16()` / `swap_u32()` | 交换 16/32 位整数端序。 |

## 8. 函数说明：上位机、LCD 与板级封装

### `thread/chrg_comm.c`

| 函数组 | 说明 |
|---|---|
| `chrg_shadow_sync()` / `chrg_shadow_init()` | 同步/初始化 Modbus 寄存器影子数据。 |
| `mb_set_bits()` / `mb_get_bits()` | 在 Modbus 位缓冲区写入/读取指定位段。 |
| `mb_reg_input_cb()` / `mb_reg_holding_cb()` / `mb_reg_test_cb()` | 输入、保持和测试寄存器回调。 |
| `mb_ymodem_updata_cb()` | 处理升级寄存器数据。 |
| `mb_reg_coils_cb()` / `mb_reg_discrete_cb()` | 线圈与离散输入回调。 |
| `funcReadCoils()` / `funcReadDiscreteInputs()` / `funcReadHoldingRegister()` / `funcReadInputRegister()` | 实现对应 Modbus 读功能。 |
| `funcWriteCoil()` / `funcWriteHoldingRegister()` / `funcWriteMultipleCoils()` / `funcWriteMultipleHoldingRegister()` | 校验并执行对应写功能。 |
| `sink_proto_lookup()` / `src_proto_lookup()` / `src_type_lookup()` | 将寄存器枚举映射为内部协议/Source 类型。 |
| `parse_load_no_group()` / `parse_load_with_group()` | 解析无组号/带组号的负载协议参数。 |
| `chrg_com_source_on()` | 根据通信配置启动 Source 流程。 |
| `funcWriteProtoCal()` / `funcSinkTest()` / `funcTrimELoad()` | 处理协议校准、Sink 测试和电子负载校准命令。 |
| `funYmodemUpadata()` | 推进固件升级命令。 |
| `chrg_comm_parse_msg()` | 解析通信线程邮箱消息并分派功能码。 |
| `chrg_comm_updata_north()` | 将实时北向状态同步到寄存器区。 |
| `chrg_comm_thread_entry()` | 初始化 Modbus 从站并循环处理消息/状态同步。 |
| `chrg_mb_write_sink()` / `chrg_mb_write_src()` / `chrg_mb_write_sys()` | 将保持寄存器变化写入 Sink、Source 和系统状态。 |
| `chrg_sink_get_proto_diff()` | 比较目标与实际 Sink 协议参数。 |
| `chrg_sink_diff_send_reg()` | 仅发送存在差异的 Sink 寄存器。 |
| `set_ymodem_update_channel()` / `mb_error()` / `rs485snd()` | 分别设置升级通道、转换错误码和提供 RS485 调试命令。 |

### `thread/chrg_lcd.c`

| 函数组 | 说明 |
|---|---|
| `chrg_sou_work()` / `chrg_sou_stop()` | 启动/停止指定功率通道。 |
| `chrg_pro_set()` | 应用 LCD 输入的快充协议配置。 |
| `chrg_set_eload_sink()` / `chrg_set_eload_source()` | 配置电子负载的 Sink/Source 角色。 |
| `chrg_set_CV()` / `chrg_set_CC()` / `chrg_roll_set_cv()` | 设置 CV、CC 及轮询相关目标值。 |
| `chrg_lcd_parse()` | 解析 HMI 命令并修改对应通道配置。 |
| `chrg_lcd_send()` | 向 HMI 发送数据。 |
| `chrg_lcd_thread_entry()` | LCD 串口收发与周期刷新主循环。 |
| `lcdsend()` | FinSH LCD 原始发送调试命令。 |

### `bsp/`

| 模块 | 函数说明 |
|---|---|
| `chrg_fal.c` | `chrg_fal_read()`、`chrg_fal_write()`、`chrg_fal_erase()`、`chrg_fal_erase_all()` 封装分区访问；`chrg_fal_init()` 初始化 FAL。 |
| `chrg_gpio.c` | `chrg_gpio_mode_set()`、`chrg_gpio_get()`、`chrg_gpio_set()` 封装 GPIO；`chrg_gpios_init()` 初始化引脚。 |
| `chrg_rel.c` | `chrg_nor_sw_rel()` 控制北向继电器；`chrg_nor_rel_init()` 初始化；`rel_test()` 用于 shell 测试。 |
| `chrg_switch.c` | `chrg_switch_ch()` 驱动通道译码选择线。 |
| `chrg_vcom.c` | `chrg_vcom_init()` 初始化 USB 虚拟串口；`chrg_vcom_console_init()` 注册控制台。 |
| `chrg_wdt.c` | `chrg_wdt_feed()` 喂狗；`chrg_wdt_init()` 初始化并启动看门狗。 |
| `chrg_tmr.c` | `chrg_tmr_get_count()`、`chrg_tmr_start()`、`chrg_tmr_stop()`、`chrg_tmr_release()`、`chrg_tmr_open()` 管理软件秒定时器；`chrg_tmr_1s_callback()` 计时；`chrg_tmrs_init()` 初始化；`uptime()`、`sec_tmr()` 为 shell 命令。 |
| `chrg_led.c` | `chrg_led_get()`、`chrg_led_set()`、`chrg_led_toggle()`、`chrg_led_pulsing()`、`chrg_led_flashing()` 控制 LED；`chrg_led_timer_set_on()`、`chrg_led_timer_set_off()`、`chrg_led_timer_start()`、`chrg_led_timer_delete()`、`chrg_led_timer_timeout_callback()`、`chrg_led_show()` 管理闪烁时序；`chrg_leds_init()` 初始化。 |
| `chrg_tty.c` | `chrg_tty_send_comp_hook()`、`chrg_tty_recv_ind_hook()` 为驱动回调；`chrg_tty_cal_byte_tmo()`、`chrg_tty_mode_set()`、`chrg_tty_dev_open()`、`chrg_tty_config()` 配置串口；`chrg_tty_connect()`、`chrg_tty_disconn()`、`chrg_tty_destory()` 管理连接；`chrg_tty_set_recv_tmo()`、`chrg_tty_set_byte_tmo()` 设置超时；`chrg_tty_recv()`、`chrg_tty_send()`、`chrg_tty_break_recv()`、`chrg_tty_send_then_recv()` 完成阻塞式收发。 |

## 9. Bootloader 函数级主链

```mermaid
flowchart TD
    M["main()"] --> SI["System_Init()"]
    M --> GPIO["MX_GPIO_Init() / MX_DMA_Init() / MX_USART_Init()"]
    M --> AI["APP_Init()"]
    AI --> DTI["DT_Init()"]
    AI --> YI["ymodem_init()"]
    AI --> FI["FM_Init()"]
    M --> AR["APP_Running()"]
    AR --> RD["recvDataHandler()"]
    RD --> DPR["DT_PollingReceive()"]
    RD --> YH["ymodemHandler()"]
    YH --> BPD["boot_ProtocolDataHandle()"]
    AR --> BCH["boot_CheckAndHandle()"]
    BCH --> BCF["boot_CheckFirmware()"]
    BCH --> BAU["boot_AutoUpdate()"]
    BAU --> FMR["FM_ReadFirmwareHead()"]
    BAU --> FMV["FM_VerifyFirmware()"]
    BAU --> FMU["FM_UpdateToAPP()"]
    BCH --> J["boot_JumpToAPP()"]
```

Boot 辅助模块职责：`firmware.c` 的 `FM_*` 函数负责分区头、擦写、CRC 校验、版本和搬运；`ymodem.c` 的 `ymodemHandler()`、`ymodemConfig()` 负责升级协议状态机；`transfer.c` 的 `DT_Init()`、`DT_Send()`、`DT_PollingReceive()` 负责串口帧传输；`drv_timer.c` 提供启动、重启、暂停、注销、处理和用户数据绑定；`bsp_uart.c`/`bsp_uart_port.c` 提供 UART、DMA、中断及接收完成回调。

## 10. 阅读与调试顺序

1. 启动异常先看 `chrg_thread_init()` 和各 `INIT_*_EXPORT` 初始化返回值。
2. 北向无数据依次跟踪 `chrg_north_thread_entry()`、`chrg_north_frame_head()`、`chrg_north_pickup_frame()`、`chrg_north_frame_dispatch()`。
3. Sink 不启动依次检查 `chrg_sink_parse()` 的电压/电流判定、`work_mode`、`chrg_sink_work()` 和 `chrg_set_sou_reg()`。
4. 功率板命令未生效依次检查 `chrg_set_sou_reg()`、`chrg_roll_sou_thread_entry()`、`chrg_south_send()` 和南向响应匹配。
5. 上位机写入未生效依次检查 Modbus `funcWrite*()`、`chrg_mb_write_*()`、共享状态和两个轮询线程。