1. 代码开发工具不止编辑器:为什么我先裁剪 mbedTLS 再谈编译
代码开发工具这个词,很多人第一反应是编辑器、调试器、版本控制。但我吃过一次亏之后,更愿意把它理解成整条构建链路:源码怎么组织、编译开关怎么设、产物体积怎么验。那次是一个 Cortex-M 项目,Flash 只剩不到 64KB,我把 mbedTLS 默认配置直接拉进工程,编译出来接近 250KB,链接器当场报 overflow。后来把 mbedTLS 裁剪到只留 AES-GCM、SHA256、PBKDF2 和 CTR_DRBG,同样的 ARM GCC -Os 选项,产物压到约 45KB。这一篇就按这个实操过程,讲清楚源码怎么裁、宏怎么配、体积怎么验、坑在哪。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 用代码开发工具管理源码:third_party 目录与最小文件集
第三方库进工程,第一步不是改代码,而是决定“放哪里、放哪些”。目录结构没定好,后面裁剪和升级都会变成体力活。
2.1 为什么单独放 third_party/mbedtls
我一般把第三方源码统一放到工程根目录的 third_party 下,每个库一个子目录。这样做的好处很直接:业务代码和第三方代码物理隔离,编译文件列表可以按目录通配,升级时也只需要替换一个目录,不会跟自己的 app/、bsp/ 混在一起。
mbedTLS 的源码分 library 和 include/mbedtls 两块,我保留同样的相对结构,只把需要的文件拷进去。先建目录:
bash复制# 在工程根目录下创建第三方库目录
mkdir -p third_party/mbedtls/library
mkdir -p third_party/mbedtls/include/mbedtls
这里不直接把整个 mbedTLS 仓库拖进来,是因为完整仓库里包含大量测试代码、示例程序和不需要的算法模块。编译文件列表一旦用通配符扫整个目录,这些文件都会被拉进构建,裁剪宏就失去意义了。目录建好之后,下一步是决定哪些 .c 文件值得留。
2.2 七个源文件的职责与依赖
只做 AES-GCM 加密、SHA256 哈希和 PBKDF2 密钥派生,需要的文件并不多。我把它们的作用和依赖关系整理成一张表,方便每次换版本时逐项核对:
| 文件 | 作用 | 依赖/备注 |
|---|---|---|
aes.c |
AES 分组加密 | GCM 和 CTR_DRBG 的底层 |
gcm.c |
GCM 认证加密模式 | 依赖 aes.c |
sha256.c |
SHA-256 哈希 | PBKDF2 的底层 |
pkcs5.c |
PBKDF2 密钥派生 | 依赖 sha256.c |
ctr_drbg.c |
确定性随机比特生成器 | 依赖 aes.c |
entropy.c |
熵池 | 需要熵源实现 |
platform.c |
平台适配(可选) | 提供平台相关函数 |
拷贝命令可以写成这样,源路径用占位符,按实际解压位置替换:
bash复制# 只拷贝最小文件集,platform.c 按需保留
cp /path/to/mbedtls/library/aes.c \
/path/to/mbedtls/library/gcm.c \
/path/to/mbedtls/library/sha256.c \
/path/to/mbedtls/library/pkcs5.c \
/path/to/mbedtls/library/ctr_drbg.c \
/path/to/mbedtls/library/entropy.c \
third_party/mbedtls/library/
# platform.c 在裸机上通常可选,先不拷贝
# cp /path/to/mbedtls/library/platform.c third_party/mbedtls/library/
# 头文件按需拷贝,保持 include/mbedtls 结构
cp /path/to/mbedtls/include/mbedtls/*.h third_party/mbedtls/include/mbedtls/
这段命令的关键点不在 cp 本身,而在“只拷贝这些”。aes.c 和 gcm.c 是加密路径,sha256.c 和 pkcs5.c 是密钥派生路径,ctr_drbg.c 和 entropy.c 是随机数路径。四条路径之外的文件,哪怕编译能过,也会增加 Flash 占用。platform.c 我一般先不拷,等链接报错说缺平台函数时再补,避免一开始就把可选依赖带进来。
头文件全拷看起来有点浪费,但 mbedTLS 的头文件之间互相包含关系比较密,手工删头文件容易在编译阶段报“找不到定义”。头文件本身不占 Flash,只影响编译时间,所以这一步可以先粗放,等源文件稳定后再考虑精简。
2.3 不走完整 CMake 构建的取舍
mbedTLS 官方提供 CMake 构建,能直接编出静态库。但在嵌入式工程里,我通常不用这个静态库,而是把源码拉进工程一起编译。原因有三个。
第一,编译选项要统一。工程自己的 -Os、-ffunction-sections、-fdata-sections 需要作用到 mbedTLS 的每个源文件上,如果先用 CMake 编成 .a,选项不一致时容易出现体积反弹或链接告警。第二,裁剪要彻底。CMake 构建默认会带上不少模块,即使 config 里关了,构建系统仍可能把相关源文件编进去,最后靠链接器回收,但中间产物体积和编译时间都上去了。第三,调试要能进源码。加密握手出问题时,能单步进 gcm.c 比对着静态库反汇编要省时间。
代价也要说清楚:源码内嵌意味着升级 mbedTLS 时不能只替换一个 .a 文件,而要重新核对文件列表和 config 宏。我的做法是维护一份 mbedtls_files.txt 和一份 mbedtls_macros.txt,升级时逐项比对,缺什么补什么。这个习惯后面第 6 章会展开。
3. 编译期开关也是代码开发工具:mbedtls_config.h 的宏取舍
源码放进工程只是第一步,真正决定体积的是 config 头文件。mbedTLS 把功能开关集中在这里,宏开得越少,编译进去的代码路径越短。
3.1 最小宏集合:AES、GCM、SHA256、PKCS5
只保留 AES-GCM、SHA256、PBKDF2 和 CTR_DRBG 时,mbedtls_config.h 里我一般这样配:
c复制// mbedtls_config.h(旧版本叫 config.h)
// 只保留需要的算法
#define MBEDTLS_AES_C
#define MBEDTLS_GCM_C
#define MBEDTLS_SHA256_C
#define MBEDTLS_PKCS5_C
// CTR_DRBG 需要 AES 作为底层
#define MBEDTLS_CTR_DRBG_C
#define MBEDTLS_ENTROPY_C
// 去掉不再需要的模块
// #undef MBEDTLS_RSA_C
// #undef MBEDTLS_ECDSA_C
// #undef MBEDTLS_SSL_TLS_C
这段配置里,前四个宏是算法能力:MBEDTLS_AES_C 打开 AES 分组算法,MBEDTLS_GCM_C 打开 GCM 模式,MBEDTLS_SHA256_C 打开 SHA-256,MBEDTLS_PKCS5_C 打开 PBKDF2。后两个宏是随机数能力:MBEDTLS_CTR_DRBG_C 提供确定性随机比特生成器,MBEDTLS_ENTROPY_C 提供熵池。
下面三行被注释掉的 #undef 是关闭大模块。注意写法:不是简单删掉 #define,而是用 #undef 覆盖掉默认配置里可能已经打开的宏。不同版本的默认 config 不一样,有的版本默认开 RSA,有的默认开 TLS,直接注释 #define 不一定能关干净,用 #undef 更稳妥。
改完宏之后,编译文件列表要和宏保持一致。比如关了 MBEDTLS_SSL_TLS_C,就不要把 ssl_tls.c 拷进 library 目录;否则源文件还在编译列表里,宏关了也会编出一堆空函数或直接报错。
3.2 CTR_DRBG 与 ENTROPY 的依赖链
随机数这条链路最容易裁出问题。MBEDTLS_CTR_DRBG_C 不是孤立工作的,它需要三样东西同时成立:
- 底层分组算法,通常是
MBEDTLS_AES_C; - 熵池
MBEDTLS_ENTROPY_C,负责收集初始种子; - 一个可用的熵源,裸机上通过
MBEDTLS_ENTROPY_HARDWARE_ALT指向硬件 TRNG。
这三者的关系可以这样理解:CTR_DRBG 是“产生随机数的机器”,AES 是机器里的核心部件,ENTROPY 是给机器加第一次油的管道,硬件熵源是油本身。只开 MBEDTLS_CTR_DRBG_C 而不开 MBEDTLS_ENTROPY_C,编译可能过,但运行时会因为拿不到种子而初始化失败;开了 ENTROPY 却没有 MBEDTLS_ENTROPY_HARDWARE_ALT,裸机上就没有熵源实现,链接阶段会报未定义符号。
我在 config 里通常会把这两个宏显式写出来,不依赖默认值:
c复制// 裸机工程必须打开硬件熵源,否则 entropy_poll 没有实现
#define MBEDTLS_ENTROPY_HARDWARE_ALT
#define MBEDTLS_CTR_DRBG_C
#define MBEDTLS_ENTROPY_C
MBEDTLS_ENTROPY_HARDWARE_ALT 的含义是“熵源由用户自己提供”,也就是后面第 4 章要写的 mbedtls_platform_entropy_poll。如果只做 Linux 用户态程序,这个宏可以不开,因为默认实现会读 /dev/urandom;但裸机上没有文件系统,必须自己接 TRNG。
3.3 关掉 RSA、ECDSA、TLS 之后失去什么
裁剪不是没有代价的。关掉 MBEDTLS_RSA_C、MBEDTLS_ECDSA_C、MBEDTLS_SSL_TLS_C 之后,这个 mbedTLS 实例就不能做 TLS 握手、不能验证 X.509 证书、不能做 RSA 或 ECDSA 签名验签。
如果你的场景只是“本地用 AES-GCM 加密一段数据,用 PBKDF2 从口令派生密钥”,那这些能力本来就用不上,关掉是合理的。但如果后续要加 TLS 通信,就得把 ssl_tls.c、x509 相关文件、对应的算法宏再加回来,体积会明显回升。我一般会在工程文档里写清楚“当前裁剪范围”,避免下一个人以为这是完整版 mbedTLS 直接拿去调 TLS。
还有一个边界:关掉 MBEDTLS_PKCS5_C 只影响 PBKDF2,不影响 AES-GCM 本身。所以如果项目不需要口令派生,pkcs5.c 和 MBEDTLS_PKCS5_C 可以一起去掉,又能省一点。但去掉之前要确认没有别的地方调用 mbedtls_pkcs5_pbkdf2_hmac,否则链接会报错。
4. 编译工具链配置:-Os、体积验证与裸机熵源对接
宏配好之后,体积不会自动降下来,还要看编译选项和链接回收。这一章把编译配置和验证方法串起来。
4.1 -Os 与裁剪宏的配合
材料里给出的参照是“ARM GCC -Os 优化下,默认配置约 250KB;裁剪后约 45KB”。这个数字说明两件事:裁剪宏决定“编不编”,-Os 决定“编出来多紧”。两者缺一不可。
我一般会在工程 Makefile 或 CMake 里给 mbedTLS 源文件单独加编译选项,至少包含:
bash复制# 体积优先的编译选项,按工程实际工具链调整
CFLAGS += -Os
CFLAGS += -ffunction-sections -fdata-sections
LDFLAGS += -Wl,--gc-sections
-Os 是体积优化,-ffunction-sections 和 -fdata-sections 让每个函数、每个数据对象单独成段,链接时 --gc-sections 可以把没有被引用的段回收掉。裁剪宏关掉的是“源码级”的功能,链接回收处理的是“目标文件级”的冗余,两层叠加才能接近 45KB。
要注意的是,-Os 不是越小越好。某些加密算法在 -Os 下会展开成更保守的循环,反而比 -O2 大一点;但材料里的参照是 -Os,我一般先按 -Os 跑,如果体积还差一点,再用 map 文件看具体是哪个符号占得最多,而不是盲目换优化等级。
4.2 用 size 和 map 文件确认 45KB 目标
编译完之后,先用 size 看整体:
bash复制# 查看 text/data/bss 体积,text+data 基本对应 Flash 占用
arm-none-eabi-size build/firmware.elf
# 按符号大小排序,找出占用最大的前 20 个符号
arm-none-eabi-nm --size-sort -S build/firmware.elf | tail -20
size 输出里,text 是代码段,data 是初始化数据段,这两个加起来接近 Flash 占用;bss 是未初始化数据段,主要占 RAM。裁剪 mbedTLS 主要影响 text,如果 text 没降,说明宏没生效或者源文件还在编译列表里。
nm --size-sort 用来定位“谁在占空间”。如果裁剪后 text 仍然偏大,先看排在前面的符号是不是 mbedtls_ssl_*、mbedtls_x509_* 这类本不该出现的函数。如果有,回头检查两处:config 里的 #undef 是否真的覆盖了默认值,编译文件列表里是否还带着 ssl_tls.c、x509*.c。map 文件也能做同样的事,链接时加 -Wl,-Map=build/firmware.map,然后在 map 里搜 mbedtls,看哪些目标文件被链接进来。
材料里 250KB 到 45KB 的差距,主要来自关掉 TLS、X.509、RSA、ECDSA 这些大模块。如果只关了一部分,体积落在中间值是正常的;要对照自己的宏清单和文件清单,而不是只看一个总数。
4.3 裸机熵源:mbedtls_platform_entropy_poll 怎么写
裸机工程打开 MBEDTLS_ENTROPY_HARDWARE_ALT 之后,必须提供 mbedtls_platform_entropy_poll 的实现。材料里只给了函数名和“从 TRNG 获取数据”这个方向,具体骨架我一般写成这样:
c复制#include "mbedtls/entropy_poll.h"
/*
* 裸机熵源:从芯片 TRNG 读取 len 字节。
* 返回值:0 表示成功,非 0 表示错误。
* olen 必须填写实际写入的字节数。
*/
int mbedtls_platform_entropy_poll(void *data,
unsigned char *output,
size_t len,
size_t *olen)
{
(void)data;
/* TRNG 未就绪时返回错误,不要返回 0 长度却报成功 */
if (trng_is_ready() != 0) {
return MBEDTLS_ERR_ENTROPY_SOURCE_FAILED;
}
/* 按芯片 TRNG 接口填充 output,这里用占位函数表示 */
if (trng_read(output, len) != 0) {
return MBEDTLS_ERR_ENTROPY_SOURCE_FAILED;
}
*olen = len;
return 0;
}
这段代码的关键不是 trng_read 的具体实现,而是三个约定:第一,返回值必须是 0 或 mbedTLS 的错误码,不能随便返回负数;第二,olen 必须填写实际读取的字节数,熵池靠它判断拿到多少种子;第三,TRNG 没就绪时要返回错误,不能“假装成功”给全 0 数据,否则 CTR_DRBG 会用固定种子初始化,随机数就变成可预测的。
函数签名以所用版本的 entropy_poll.h 声明为准,不同版本参数顺序可能略有差异。Linux 用户态程序不需要写这个函数,默认实现会读 /dev/urandom,这也是为什么同一套 config 在 PC 上能跑、搬到裸机就链接报错的原因。
5. 裁剪实战的避坑排查:宏依赖、熵源与体积反弹
裁剪过程里的问题大多不是“代码写错”,而是“配置和文件列表对不上”。下面几条是我实际踩过的,按现象、原因、解决整理。
5.1 链接报 undefined reference to mbedtls_platform_entropy_poll
现象:编译通过,链接阶段报 undefined reference to 'mbedtls_platform_entropy_poll'。
原因:config 里打开了 MBEDTLS_ENTROPY_HARDWARE_ALT,但工程里没有提供这个函数的实现;或者只打开了 MBEDTLS_ENTROPY_C,没有打开硬件熵源宏,裸机下默认实现不可用。
解决:在工程里新增一个 entropy_hardware.c,按上一节的骨架实现该函数,并把它加入编译文件列表。如果暂时不想接 TRNG,可以先关掉 MBEDTLS_ENTROPY_HARDWARE_ALT,改用其他熵源方案,但不要留着宏不实现。
5.2 CTR_DRBG 初始化失败,随机数不可用
现象:mbedtls_ctr_drbg_seed 返回非 0,或者程序运行后生成的“随机数”每次一致。
原因:熵源函数返回了成功,但 olen 没有赋值,熵池实际拿到的种子长度为 0;或者 TRNG 初始化在熵源调用之后才执行,第一次取种子时硬件还没就绪。
解决:检查 mbedtls_platform_entropy_poll 里 *olen = len 是否执行到;把 TRNG 初始化提前到 mbedtls_ctr_drbg_seed 之前。如果 TRNG 需要启动时间,在熵源函数里轮询就绪标志,超时后返回 MBEDTLS_ERR_ENTROPY_SOURCE_FAILED,让上层感知失败,而不是静默返回全 0。
5.3 裁剪后体积只降了一点
现象:config 里已经 #undef 了 TLS 和 RSA,但 size 显示 text 只降了十几 KB,离 45KB 还很远。
原因:编译文件列表里仍然带着 ssl_tls.c、x509*.c、rsa.c 这些源文件;或者 #undef 写在了默认 #define 之前,被后面的默认配置重新打开;再或者没有开 --gc-sections,未引用函数还在。
解决:先核对 library 目录和编译文件列表,只保留最小文件集;再检查 config 里 #undef 的位置,确保它在所有默认 #define 之后;最后用 nm --size-sort 看大符号,确认没有 mbedtls_ssl_* 残留。
5.4 升级 mbedTLS 后找不到 config.h
现象:换了一个新版本源码,编译报 fatal error: config.h: No such file or directory。
原因:新版本把配置文件从 config.h 改名为 mbedtls_config.h,工程里的包含路径还指向旧文件名。
解决:在 third_party/mbedtls/include/mbedtls/ 下保留正确的文件名,并修改工程里引用 config 的地方。如果工程里有多处 #include "mbedtls/config.h",统一改成 #include "mbedtls/mbedtls_config.h",或者加一个兼容头文件做转发。升级时把旧 config 里的自定义宏逐项迁移到新文件,不要直接覆盖。
5.5 关掉 TLS 宏后,某些源文件编译报错
现象:#undef MBEDTLS_SSL_TLS_C 之后,编译 ssl_tls.c 报大量类型未定义。
原因:宏关了,但 ssl_tls.c 还在编译文件列表里;这个文件内部依赖 MBEDTLS_SSL_TLS_C 打开的类型和函数,宏关掉后条件编译不成立,自然报错。
解决:把 ssl_tls.c 及相关 x509 文件从编译列表里移除,而不是靠宏关掉后继续编译。mbedTLS 的源文件和宏配置要成对维护:文件在,宏就得开;宏关了,文件就不该进编译。
6. 把裁剪清单固化成脚本:换版本也能复现的检查习惯
手工核对宏和文件列表,第一次能记住,第三次换版本就会漏。我现在把裁剪配置做成一个可执行的检查脚本,放在工程 tools/ 下,每次拉新版本源码先跑一遍。
bash复制#!/usr/bin/env bash
# check_mbedtls_trim.sh
# 检查裁剪后的 mbedtls_config.h 是否包含必要宏、是否误开大模块
CONFIG="third_party/mbedtls/include/mbedtls/mbedtls_config.h"
required=(
MBEDTLS_AES_C
MBEDTLS_GCM_C
MBEDTLS_SHA256_C
MBEDTLS_PKCS5_C
MBEDTLS_CTR_DRBG_C
MBEDTLS_ENTROPY_C
MBEDTLS_ENTROPY_HARDWARE_ALT
)
for macro in "${required[@]}"; do
if ! grep -qE "^#define[[:space:]]+$macro" "$CONFIG"; then
echo "缺少必要宏: $macro"
fi
done
# 这些大模块不应该出现在裁剪配置里
disabled=(
MBEDTLS_RSA_C
MBEDTLS_ECDSA_C
MBEDTLS_SSL_TLS_C
)
for macro in "${disabled[@]}"; do
if grep -qE "^#define[[:space:]]+$macro" "$CONFIG"; then
echo "大模块未关闭: $macro"
fi
done
# 检查 library 目录是否混入不该有的源文件
for src in ssl_tls.c x509.c rsa.c ecdsa.c; do
if [ -f "third_party/mbedtls/library/$src" ]; then
echo "文件列表可能过宽: $src"
fi
done
脚本的逻辑很直白:必要宏逐个 grep,缺了就打印;大模块宏如果还被 #define,也打印;最后检查 library 目录里有没有混进 ssl_tls.c、x509.c 这类文件。它不修改任何东西,只做“清单对账”,输出为空才说明配置和文件列表一致。
参数上唯一需要按工程调整的是 CONFIG 路径和 library 路径。如果工程把 mbedTLS 放在别的位置,改这两处即可。grep 用了 ^#define[[:space:]]+ 来避免匹配到注释里的宏名;如果你的 config 里有 #define MBEDTLS_AES_C /* 注释 */ 这种写法,这个正则仍然能命中。
我还会把文件清单单独存一份 tools/mbedtls_files.txt,每次升级时用 diff 对比新旧文件列表,确认没有多拷或少拷。宏清单和文件清单分开维护,好处是排查问题时能快速判断是“宏没开”还是“文件没进编译”。
从那以后我每次把第三方库拉进工程,都先列文件清单和宏清单,再动编译选项;换版本时先跑检查脚本,不再靠记忆。希望帮到你。
