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

程序流程与函数说明

1. 文档范围

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

2. 上电与初始化流程

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 请求与完成状态

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 工作状态机

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 函数级主链

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_*()、共享状态和两个轮询线程。