首页 / knowledge/代码解析/net

evc_download.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 返回值约定 4.2 接口覆盖范围（只有“下载”这一侧）4.3 通信协议 / 定时 / uCOS-II 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：net/evc_download.h 所属模块：net（网络应用层 / 设备固件升级下载）代码行数：30

1. 文件职责

本文件是 net/evc_download.c 的对外接口头文件，声明 EVC（充电桩）固件升级流程对外的 3 个查询接口（EVC 硬件版本、是否正在从云端下载、下载百分比），并额外保留了一个无实现的旧接口 calculate_evc_flash_md5 与一个未使用的调试开关 DEBUG_EVC_DOWNLOAD。

它在数据流中处于「EVC 升级状态与硬件版本的只读出口」位置：net/ems.c 通过 get_evc_hard_version() 把 EVC 硬件版本上报云端做文件匹配；hmi/ui/ui_main.c 通过 is_download_evc() / get_percent_download_evc() 显示下载进度。

本文件不含逻辑与状态，只含 include guard、一个 include、一个调试宏与 4 个函数原型。

2. 关键数据结构与宏

名称	类型	说明
`__EVC_DOWNLOAD_H__`	宏	include guard（第 9-10 行）
`DEBUG_EVC_DOWNLOAD`	宏	第 17 行，值 `(0)`。全工程无第二次引用，是未接线的调试开关（`evc_download.c` 内没有任何由此宏控制的打印）
`get_evc_hard_version`	函数原型	`char *get_evc_hard_version(void)`，定义于 `evc_download.c:37`
`calculate_evc_flash_md5`	函数原型	`void calculate_evc_flash_md5(void)`，全工程无定义、无调用点
`is_download_evc`	函数原型	`u8 is_download_evc(void)`，定义于 `evc_download.c:49`
`get_percent_download_evc`	函数原型	`u8 get_percent_download_evc(void)`，定义于 `evc_download.c:61`

本文件不定义结构体、枚举、联合体或位域。第 14 行额外 #include "upd_download.h"，但本头文件的 4 个原型都没有用到 upd_download.h 提供的类型，属于转发式冗余 include。基础类型 u8 来自第 13 行 #include <includes.h>。

3. 函数清单

函数名	作用域	说明
`get_evc_hard_version`	全局（原型声明）	返回 EVC 硬件版本常量 `"V1.02"`（`midware/evc/evc.h:17` `VERSION_EVC_HARD`），定义于 `evc_download.c:37`
`calculate_evc_flash_md5`	全局（原型声明）	语义应为“计算 EVC 固件 MD5”，全工程无定义、无调用点，已被通用接口 `calculate_dev_FW_Flash_MD5(UPDT_EVC, ...)` 取代
`is_download_evc`	全局（原型声明）	查询云端是否下发过 EVC 强制下载标志，定义于 `evc_download.c:49`
`get_percent_download_evc`	全局（原型声明）	查询 EVC 固件下载百分比（0~100），定义于 `evc_download.c:61`

共 4 个原型声明：3 个有实现、1 个无实现。无 static 函数、无函数指针、无回调、无宏函数。

4. 核心逻辑解析

本文件是纯声明文件，不含可执行逻辑。接口契约要点：

4.1 返回值约定

get_evc_hard_version()：返回指向常量字符串的 char*，调用方只读、不得释放。该串会进入云端 checkUpdate 请求的 Hard_Version 字段（net/ems.c:2984）。
is_download_evc()：返回 u8，实际取值仅 0 / 1（底层 BOOLEAN 提升）。
get_percent_download_evc()：返回 u8，语义 0~100；分母可能为 0（文件长度尚未从服务器取得时），详见 evc_download.c.md 备注 2。

4.2 接口覆盖范围（只有“下载”这一侧）

本头文件只导出“下载中”的查询，没有“下载已完成”的接口。EVC 的状态由两段构成：

阶段	状态来源	本头文件覆盖
云端下载固件到 SDRAM	`stUpt[UPDT_EVC].bIsUpdateForce`	是（`is_download_evc()`）
本地刷写 EVC	`midware/evc` 的 `is_upgrade_evc()` / `get_percent_upgrade_evc()`	否

stUpt[UPDT_EVC].bIsUpdatedFromServer（由 net/upd_download.c:412 置位）虽然没有专用接口，但可通过通用的 Get_Status_Is_Updated_From_Server(UPDT_EVC) 读取，net/ems_download.c:282 就是这么用的。

4.3 通信协议 / 定时 / uCOS-II

均不涉及。本文件不定义帧格式、起始码、长度、校验方式或超时重试参数，不声明信号量、消息邮箱或任务，也不引用 uCOS-II API。所声明的函数由调用方在自己的任务上下文同步调用。

5. 对外接口

导出（供外部使用）：

名称	使用方
`get_evc_hard_version`	`net/ems.c:2984`（组织 `checkUpdate` 请求的 `Hard_Version` 字段）。`net/server.c:3301-3310` 的 EVC 分支用的是 `get_evc_type()` / `get_evc_ii_type()`，不调用本函数
`is_download_evc`	`hmi/ui/ui_main.c:880`、`net/ems_download.c:260`
`get_percent_download_evc`	`hmi/ui/ui_main.c:886`
`calculate_evc_flash_md5`	无（无定义、无调用）
`DEBUG_EVC_DOWNLOAD`	无（无第二次引用）

被调用（本文件引用的外部符号）：

名称	来源
`includes.h`	第 13 行 `#include <includes.h>`，提供 `u8` 等基础类型，并间接引入 uCOS-II 与 GD32 头文件
`upd_download.h`	第 14 行 include，但本文件的原型未使用其中任何符号（冗余）

本文件不导出全局变量，也不引用外部全局变量。

6. 依赖关系

依赖：

UCOSII/uCOS-CONFIG/includes.h（第 13 行，尖括号形式）——提供基础类型；
net/upd_download.h（第 14 行）——冗余，本文件原型未使用其类型或宏。移除后对调用方无影响（调用方各自 include 真实需要的头文件）。

被依赖（include 本头文件的文件）：

net/evc_download.c:14、net/ems.c:46、net/server.c:50、net/ems_download.c:21
hmi/ui/ui_main.c:29
midware/evc/evc.c:14、midware/evc/evc_ii.c:15、midware/evc/evc_upgrade.c:15、midware/interface/interface.c:23

后 4 个 midware 文件属于纯冗余 include：get_evc_hard_version / is_download_evc / get_percent_download_evc / calculate_evc_flash_md5 在这 4 个文件中均无引用（已逐个 grep 确认）。

7. 备注与风险点

calculate_evc_flash_md5 声明无实现：全工程（.c / .h）中该标识符只出现于本文件第 26 行，既无定义也无调用。EVC 固件的整卷摘要校验当前由通用接口 calculate_dev_FW_Flash_MD5(UPDT_EVC, g_u8_fw_sdram1, EVC_FIRM_DOWNLOAD)（net/upd_download.c:391）完成，调用点在 net/server.c:3809。任何未来调用 calculate_evc_flash_md5() 的代码都会在链接期报未解析符号，应删除该声明。
DEBUG_EVC_DOWNLOAD 是死宏：evc_download.c 中不存在任何由它控制的调试输出，函数体内连一个 printf 都没有。若期望它控制日志，需要先在 evc_download.c 中接线；否则保留只会误导维护者。
文件头 @file 与真实文件名不符：第 2 行写 evc_download.h 的 @file 为 evc_download.h（此处一致），但 @author 是 Alpha g_stEMSInfo Team，与 evc_download.c 的 Alpha EMS Team 不一致，是批量替换注释的遗留；@date 为 2017/05/18，与 bms/inv/meter 三个 download 文件同源。
u8 / BOOLEAN 类型风格不统一：本文件对外用 u8 表示布尔（与 bms_download.h 一致），而底层 upd_download.h 用 BOOLEAN。虽然数值等价（u8 接受 0/1 提升后的 BOOLEAN），但混用不利于类型自解释。
冗余 include：本头文件第 14 行的 upd_download.h 未被使用；midware/evc/evc*.c、midware/interface/interface.c 4 处 include 也是纯冗余。这些都会扩大编译依赖面（upd_download.h 又 include ems.h）。
接口与同族文件不统一：bms_download.h 提供“已完成”查询（IsUpgradeBMS），afci_download.h 提供（is_afci_firm_download_finished），inv_download.h 提供（is_inverter_firm_download_finished），而本文件缺失对应接口，EVC 完成状态只能走通用接口，增加了调用方的心智负担。