首页 / knowledge/代码解析/common

convert.h

本页目录1. 文件职责 2. 关键数据结构与宏 3. 函数清单 4. 核心逻辑解析 4.1 两个函数的参数与返回值约定（依据 convert.c 实现）4.2 调用方约定的长度关系 4.3 通信协议 / 定时 / uCOS-II 配合 5. 对外接口 6. 依赖关系 7. 备注与风险点

源文件路径：common/convert.h 所属模块：common（通用工具库）代码行数：21

1. 文件职责

本文件是 common/convert.c 的对外接口头文件，声明两个 ASCII 十六进制转换函数：ascii_to_hex（单个字符转 4 位半字节）与 hex_ascii_to_bin（整串 ASCII 十六进制转二进制）。它在数据流中处于「字符串→二进制」的解码入口，目前有两个真实使用场景：云端/服务器下发的固件 MD5 校验串还原（midware/inverter/alphaess/alphaess_upgrade.c 需要把 32 字符的 MD5 十六进制串还原成 16 字节再与本地文件摘要比对），以及服务器 JSON 里携带的固件数据报文还原（net/server.c 把 Base 字段的十六进制串转成固件二进制）。文件本身不含逻辑与状态，只暴露函数原型。

2. 关键数据结构与宏

名称	类型	说明
`__CONVERT_H__`	宏	include guard
`ascii_to_hex`	函数原型	`u8 ascii_to_hex(char c)`，单字符转 0~15，定义于 `convert.c:27`
`hex_ascii_to_bin`	函数原型	`int hex_ascii_to_bin(u8 in_buf, u32 len, u8 ou_buf)`，整串转换，定义于 `convert.c:54`

本文件不定义结构体、枚举、联合体、位域，也没有除 include guard 外的宏常量。u8 / u32 来自第 13 行 #include <includes.h>（注意是尖括号形式，指向 UCOSII/uCOS-CONFIG/includes.h）。

3. 函数清单

函数名	作用域	说明
`ascii_to_hex`	全局（原型声明）	单个 ASCII 字符转 4 位数值，定义于 `convert.c:27`
`hex_ascii_to_bin`	全局（原型声明）	把长度为偶数的 ASCII 十六进制串按字节打包进输出缓冲，定义于 `convert.c:54`

共 2 个原型声明，均对应 convert.c 中的全局定义；无 static 函数、无函数指针、无回调。

4. 核心逻辑解析

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

4.1 两个函数的参数与返回值约定（依据 `convert.c` 实现）

ascii_to_hex(char c)：输入 '0'~'9' / 'a'~'f' / 'A'~'F' 返回 0~15；其它字符一律返回 0，不报错。这是本接口最重要的契约：非法输入不会让调用方察觉（详见 convert.c.md 备注 1）。
hex_ascii_to_bin(in_buf, len, ou_buf)：len 是输入 ASCII 字符个数，必须为偶数；返回值为 len/2（成功写出的字节数），奇数长度返回 -2。输出缓冲需要由调用方保证不少于 len/2 字节，接口不做长度校验。

4.2 调用方约定的长度关系

调用点	传入 `len`	输出字节数	语义
`midware/inverter/alphaess/alphaess_upgrade.c:105`/`:107`	`32`	16	本地固件 MD5 十六进制串 → 16 字节摘要
`midware/inverter/alphaess/alphaess_upgrade.c:109`/`:111`	`32`	16	服务器下发 MD5 串 → 16 字节摘要
`net/server.c:3743`	`2 * lenPck`	`lenPck`	JSON 字段中的固件十六进制正文 → 固件二进制

三处都依赖「ASCII 串长度是字节数的 2 倍」这一关系，因此 len 为偶数是硬性前提。

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

无。本文件不涉及帧格式、校验、超时重试、定时调度，不声明信号量或消息邮箱，不引用 uCOS-II API。转换是纯 CPU 运算，在调用它的升级任务上下文中同步完成。

5. 对外接口

导出（供外部使用）：

名称	使用方
`ascii_to_hex`	工程内没有外部调用点；仅被同文件的 `hex_ascii_to_bin`（`convert.c:64`）使用（`common/json.c` 里同名标识符只出现在注释中，是复制粘贴的注释残留）
`hex_ascii_to_bin`	`midware/inverter/alphaess/alphaess_upgrade.c:105`、`:107`、`:109`、`:111`；`net/server.c:3743`

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

名称	来源
`includes.h`	`UCOSII/uCOS-CONFIG/includes.h`（第 13 行 include），提供 `u8` / `u32`，并间接引入 `chip.h`、`ucos_ii.h`

本文件不导出任何全局变量。

6. 依赖关系

依赖：

UCOSII/uCOS-CONFIG/includes.h——唯一 include，且用的是 <...> 尖括号形式（其它同类头文件多写 "..."）。它会连带引入 uclib、ucos_ii.h、gd32f4xx.h、chip.h 等，编译开销比 #include "chip.h" 大；
不依赖 crc.h、s19.h、hex_file_parse.h。

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

common/convert.c:14
midware/inverter/alphaess/alphaess_upgrade.c
net/server.c

7. 备注与风险点

头文件注释与文件内容不匹配：@brief 为空，没有说明两个函数「非法字符返回 0」「奇数长度返回 -2」这两个关键契约，调用方只能去读 .c。
hex_ascii_to_bin 的第二个参数类型是 u32 而返回类型是 int：返回值 -2 表示错误，但返回类型是有符号 int，而长度参数是无符号 u32。调用方若写成 if (hex_ascii_to_bin(...)) 会把 -2 与正数都当作"合法"，必须先判断 < 0 或 != len/2（当前 6 个调用点全部没有检查返回值，见 convert.c.md 备注 3）。
扩展性强但语义弱：hex_ascii_to_bin 同时支持大小写十六进制（因为 ascii_to_hex 三种分支都覆盖），但没有「跳过空白/0x 前缀」的能力；如果将来服务器下发带分隔符的十六进制串（如 "AA BB"），本接口会把非法字符静默当 0 处理，产生错误结果而不报错。
ascii_to_hex 被导出却无外部使用者：它更适合写成 static 或收进 convert.c 内部；当前作为全局符号存在，理论上与其他模块的同名符号有链接期重名风险（工程内 common/json.c 的注释里就残留了同名标注，说明历史上确实出现过重名混淆）。