简介针对STM32及国产单片机平台RAM小的痛点这份移植Zlib实现数据压缩的源码资源为嵌入式开发者和电子工程师提供了完整可用的解决方案。资源将Zlib默认的MAX_WBITS由15调低至8压缩等级设为3并借鉴网友思路重写了deflate_compress同时集成正点原子malloc使压缩功能能在单片机端稳定运行后续还参考libharu实现了PDF FlateDecode经PDFStreamDumper验证压缩率可达10倍以上并且压缩后的数据可直接传入加密函数仅需注意传入数据长度。压缩包共149个文件以79个h头文件和49个c源文件为主体另有少量工程配置、脚本、说明文档及辅助工具整体大小4.77MB目录结构清晰方便直接导入Keil或STM32CubeMX工程使用。已有2208人学习下载适合具备一定单片机基础、希望在资源受限设备上实现数据压缩与加密的开发者参考也可用于IAP固件升级、日志存储等场景无论是通信数据压缩还是文件传输处理均有实际参考价值。 去年调远程数据上云的项目时设备端每包发512字节传感器原始帧后端链路速率限制得很死一个采集点轮询一圈要十几分钟现场根本没法用。我把Zlib移植到STM32设备里做数据压缩后再上传同样的帧压掉一半以上整个采集轮询周期才回到“能正常交付”的状态。这篇把Zlib在STM32和国产单片机上的移植过程、裁剪方案、内存代价和实测数据一次讲透。如果你正在纠结要不要在MCU里做数据压缩或者已经把源码加到工程但一编译就炸这篇应该能帮你少折腾两个星期。1. “把压缩做进设备端”什么时候值得什么时候纯属找罪受先说结论不是所有项目都适合在单片机上压缩数据。我见过不少团队一看到传输带宽不够、存储容量吃紧第一反应就是上Zlib结果压了个寂寞——某些数据模型压缩率不到10%白白增加几十KB Flash和CPU负担。判断该不该上压缩核心看三个问题。数据有没有“可压性”。传感器数值、日志文本、JSON/CSV配置这种含有大量重复模式和固定字段的数据适合压缩但已经加密的数据、白噪声信号、随机化处理的固件升级包压缩率很差甚至会出现越压越大的情况。我测试过加密后的数据流Zlib压完比原始数据还大3%~5%这种情况就别做无用功。瓶颈究竟在哪。如果瓶颈是UART或者无线模块的带宽压缩传输链路能直接见效如果瓶颈是MCU本身的算力那压缩反而会把上报周期拖得更长得不偿失。我接触过一些项目明明换一颗更高主频的芯片就能解决结果花了两周在压缩算法上最后性能还是不够这就本末倒置了。有没有比压缩更省事的替代方案。增量上报、事件触发上报、降采样、换更高带宽的无线模块、外扩存储芯片这些方案在某些场景下比压缩更简单可靠。我把几种方案放在一起比对过方案实现成本对现有硬件改动典型收益设备端Zlib压缩中无传输量降50%~70%增量上报低-中无有效数据占比大幅提升降采样/事件上报低无上报频率下降换高带宽模块低更换硬件带宽翻倍以上外扩存储低更换硬件存储量提升但传输瓶颈仍在我的建议是当“不能改硬件”和“带宽/存储是硬瓶颈”同时成立并且数据类型有较明显冗余时Zlib压缩才值得做。设备端压缩不是炫技它是被物理条件逼出来的方案。2. 动手前先算好Flash、RAM、CPU的账否则必返工Zlib的核心算法是Deflate它由LZ77字典压缩和Huffman编码两级组成。LZ77需要维护一张哈希表和一个滑窗缓冲区这是它内存消耗大的根源。很多人移植失败不是因为代码写错而是RAM不够deflateInit2_直接返回Z_MEM_ERROR。先看默认参数下的内存账。Zlib在MCU上首次初始化时需要分配几块连续内存窗口缓冲大小取决于MAX_WBITS默认15是 115 32KBprev数组用于LZ77回链一个字节的窗口位置需要2字节存储所以是64KBhead哈希表大小取决于HASH_BITSmemLevel越高哈希表越大deflate_state状态结构体约2KB左右默认配置算下来大约需要130KB以上的RAM。这还没算输出缓冲和调用者的业务缓冲。放到只有20KB SRAM的STM32F103上想都别想。放到192KB RAM的STM32F407上也得掂量一下因为你的业务程序、协议栈、RTOS任务栈还在里面占用。那是不是F103这种小内存MCU就完全不能跑也不是。Zlib的所有关键参数都可以在配置阶段调整。我把两套常用配置对比一下配置项默认配置MCU裁剪配置MAX_WBITS1532KB窗口124KB窗口memLevel84窗口prevhead估算128KB约15KBdeflate_state结构约2KB约1KB实测总内存占用130KB约16KB~18KB压缩率文本数据约45%体积约55%体积适用芯片F407/H7、部分AT32F103、GD32E103等注意MAX_WBITS降下来之后压缩率一定下降因为字典窗口变小了。但MCU场景下没人关心极限压缩率大家关心的是“在可用资源内把数据压到一个能省流量的程度”这就够了。再算Flash和CPU。实测在ARMCC -O2优化下只编译deflate压缩方向裁剪后代码体积在28KB左右如果同时要解压比如做OTA升级包解压还需要加上inflate相关文件总Flash占用约50KB。主频168MHz的MCU上压缩速率大约是level 1时20~30KB/slevel 9时2~4KB/s。理解这个量级很重要你要压缩100KB的日志文件用level 9压一次可能要几十秒这个延迟很多业务接受不了。所以动手移植之前先给项目画一条清晰的资源线当前还剩多少Flash、多少RAM、CPU余量多少再决定用什么参数组合。这一步省了后面会省大量调试时间。3. 从官方源码到单片机工程一步步裁剪落地3.1 源码版本选择和文件清单Zlib官方源码在官网直接下载稳定版比如1.2.13解压后不要整个文件夹往Keil工程里拖。Zlib包里有很多跟gzip文件操作、测试程序相关的文件在单片机工程里都用不上反而会引入对文件系统的依赖导致编译报错。我实际添加的文件只有这些文件名用途是否需要adler32.cAdler-32校验需要compress.ccompress/uncompress辅助API可选crc32.cCRC32校验可选deflate.c压缩核心必须trees.cHuffman树构建必须zutil.c内存/错误工具函数必须inflate.c解压核心按需inffast.c解压快速路径按需inftrees.cHuffman表构建按需gzclose.c/gzread.c/gzwrite.c等gzip文件操作不需要minigzip.c命令行Demo不需要example.c示例不需要只做设备端压缩上报的场景我建议连inflate方向都不编进去省下来的Flash可以给业务逻辑用。只有当设备需要做OTA固件解压或者接收上位机下发的压缩配置时才需要把inflate编进来。3.2 zconf.h配置调整zconf.h是Zlib的关键配置头文件。在MCU工程里我最常改的是两处开启Z_SOLO宏。这个宏会让Zlib去掉所有跟gzFile、文件系统相关的代码对裸机工程非常重要。不改也行但编译时很可能报找不到unistd.h、fcntl.h这类头文件的错误因为嵌入式交叉编译工具链不像Linux那样有完整的POSIX环境。处理off_t类型。ARMCC环境下zconf.h里的z_off_t可能会映射到off_t而off_t在MCU标准库里定义各不相同容易出问题。稳妥的做法是直接强制typedef long z_off_t;还有一个常见问题是某些编译器对__attribute__((unused))支持不好会在zutil.h里报警告。这种不影响功能直接忽略或者在编译选项里关掉对应警告即可。3.3 Keil/STM32CubeIDE工程落地配置在MDK Keil里我习惯这样组织源文件在项目目录下建一个Middleware/Zlib文件夹把上面选好的.c文件放进去头文件放同级方便管理进入Options for Target - C/C - Define加上Z_SOLOC99 Mode建议打开虽然Zlib本身是C90兼容的但你的调用代码和后续维护更省心不使用MicroLib直接用标准C库的malloc配合启动文件中的Heap_Size配置内存行为更可控在GCC环境下比如STM32CubeIDE、CLion arm-none-eabi-gcc操作类似只是把宏写在CMakeLists.txt或者Makefile的编译选项里-DZ_SOLO3.4 第一轮编译常见的坑即便配置正确第一次编译也大概率会出点小问题我把踩过的几类列出来unknown type name off_t这是zconf.h类型映射问题按上面说的typedef long z_off_t解决implicit declaration of function memcpy说明工程缺少字符串头文件在zutil.c里显式加上#include string.h即可链接时提示deflate相关符号重复定义多半是源文件重复添加或者整个文件夹误拖入优化等级建议先用-O0跑通功能再用-O2验证性能和正确性。zlib对优化等级不敏感但-O2下速度提升明显实测在F407上-O2比-O0快约40%4. 核心API使用逻辑和最容易被内存坑到的地方4.1 一次性压缩一个缓冲区的完整示例Zlib的使用比很多人想象中简单核心就是deflateInit2_、deflate、deflateEnd三个函数的组合。下面这个函数是我在F407上验证过的用来压缩一小块数据比如一帧传感器报文、一段日志static voidpf user_zalloc(voidpf opaque, uInt items, uInt size) { (void)opaque; return malloc(items * size); } static void user_zfree(voidpf opaque, voidpf address) { (void)opaque; free(address); } int zlib_compress_block(uint8_t *dst, uint32_t dst_cap, uint32_t *dst_len, const uint8_t *src, uint32_t src_len) { z_stream stream; int ret; memset(stream, 0, sizeof(stream)); stream.zalloc user_zalloc; stream.zfree user_zfree; ret deflateInit2_(stream, Z_BEST_SPEED, Z_DEFLATED, MAX_WBITS, 4, Z_DEFAULT_STRATEGY, ZLIB_VERSION, sizeof(z_stream)); if (ret ! Z_OK) { return ret; } stream.next_in (Bytef *)src; stream.avail_in src_len; stream.next_out dst; stream.avail_out dst_cap; ret deflate(stream, Z_FINISH); if (ret Z_STREAM_END) { *dst_len stream.total_out; deflateEnd(stream); return Z_OK; } deflateEnd(stream); return ret; }注意deflateInit2_的第二个参数是压缩级别第三个参数是压缩算法固定为Z_DEFLATED第四个是窗口大小第五个是memLevel。上面代码里memLevel写的是4而不是默认8这是刻意为之的。memLevel越大需要分配的内存越多压缩率越好但对应的是140KB级内存MCU上根据前面算的账我一般用4~5之间。4.2 deflateInit2_分配内存的逻辑与对策deflateInit2_内部会一次性调用zalloc分配窗口、prev数组、head数组等多块内存。如果你直接使用默认配置在RAM紧张的芯片上这里就会挂掉返回Z_MEM_ERROR。对策有三个方向第一降低memLevel和MAX_WBITS让单次内存需求降下来。我上面的代码就是用这个思路。第二扩大系统的堆空间。在MDK里修改启动文件startup_stm32f407xx.s中的Heap_Size从默认的0x200改成更大值比如0x2000。在GCC环境下则是修改链接脚本中的堆配置。第三不依赖系统malloc自己写zalloc/zfree。这个方案在实时性要求高、内存碎片多的RTOS环境下最稳妥。4.3 自定义zalloc/free与静态内存池方案在MCU上长期运行的项目我强烈建议不要裸奔系统malloc来给Zlib分配内存因为压缩任务反复初始化销毁会加剧堆碎片。可以给Zlib单独划一块静态内存池压缩函数开始时从池子里切块函数结束后整池复用static uint8_t zlib_pool[192 * 1024] __attribute__((aligned(8))); static size_t zlib_pool_pos 0; static int zlib_pool_inited 0; static voidpf user_zalloc(voidpf opaque, uInt items, uInt size) { size_t need (size_t)items * size; voidpf ptr; (void)opaque; if (!zlib_pool_inited) { zlib_pool_pos 0; zlib_pool_inited 1; } if (zlib_pool_pos need sizeof(zlib_pool)) { return Z_NULL; } ptr (voidpf)zlib_pool[zlib_pool_pos]; zlib_pool_pos need; return ptr; } static void user_zfree(voidpf opaque, voidpf address) { (void)opaque; (void)address; /* 不回收靠zlib_pool_pos在每次压缩前重置复用 */ }这个方案看起来“作弊”但在纯裸机或者单任务RTOS场景里非常实用一次只用一份z_stream压缩前重置池指针压缩结束直接丢弃内部状态。用之前仔细评估你的并发场景如果多个任务同时会调用压缩就不能这么简单粗暴得加互斥锁。4.4 流式分块压缩为什么更合适MCU上面示例是每次调用把整个输入缓冲压完这对几KB的帧没问题。但如果要压缩几十KB的批量日志一次性传入一个大缓冲区输出缓冲和内部缓冲不够时deflate会返回Z_OK但没压完代码必须循环处理同时还要防止输出缓冲溢出。更工程化的做法是分块流式压缩。把源数据按4KB切成小块循环调用deflate每块数据通过avail_in/avail_out控制进度最后以Z_FINISH结束。这样输入缓冲、输出缓冲都可以做得比较小内存占用更可控也更适合MCU的分包发送逻辑。细节上记得每次循环后都要更新next_in和next_out指针以及用total_out累计输出长度这个环节最容易写错。5. 实测数据三种最具代表性的数据模型我在一块STM32F407开发板168MHz内部RAM-O2优化上做了一组实测用来回答两个问题Zlib在MCU上到底能把数据压多少要花多长时间测试数据选了三种最具代表性的模型数据模型原始大小Level 1压缩后Level 9压缩后Level 1耗时Level 9耗时CAN总线报文大量0x00填充和重复ID4096B620B15%410B10%约120ms约900msCSV日志文本重复时间戳和字段名8192B2850B35%1990B24%约280ms约2sJSON配置键名重复度高2048B880B43%700B34%约60ms约400ms看数据你会发现Level 1和Level 9的压缩率差距并没有想象中大但耗时差距可能达到5倍以上。在MCU这种算力受限场景我还是一贯推荐用Level 1~3把节省下来的CPU时间留给业务逻辑。另一个结论是数据模型的“规律性”远比压缩等级重要。CAN报文因为大量重复填充Level 1就能压到15%JSON配置虽然文本结构整齐但有效字符占比高压到43%已经到了这个级别的天花板。所以选择压缩场景时优先挑数据冗余度高的而不是指望压缩算法“化腐朽为神奇”。实测下来F407上Zlib的压缩速率大约是Level 1时20~30KB/sLevel 9时2~4KB/s。如果你要压缩的数据达到几十KB一定要算一下这个耗时能不能被业务容忍。我见过有人想压缩一张100KB的截图用Level 9压一次要半分钟产品根本没法用后来改成Level 1加先缩放再压缩才勉强合格。5.1 压缩和解压的不对称性还有一个容易被忽略的点deflate慢、inflate快。解压速度通常是压缩的3~5倍RAM占用也小很多。所以在“设备压缩、上位机解压”的架构里设备端的负担其实只有压缩只有在设备端做OTA解压或解压下发配置时才需要评估inflate的性能。这个不对称性决定了哪怕压缩慢一点只要上传频率不高整个产品体验依然可以接受。6. 国产单片机移植的差异点与一份落地检查清单6.1 不同国产MCU的Zlib移植体验国产单片机核心就是ARM Cortex-M系列Zlib是纯C标准库代码不依赖任何芯片外设所以“能不能跑”不是问题“资源够不够”才是。我最近半年先后在GD32F303、AT32F413、APM32F407上做过同类移植GD32F303系列主频可以跑120MHz但部分型号的SRAM只有40KB出头用裁剪配置MAX_WBITS12、memLevel4很轻松Flash剩余也足够。程序基本可以直接从STM32F103迁移Zlib源码一行不用改主要是启动文件和时钟配置按GD32的库来。AT32F413系列主频可以到200MHzSRAM配置也比较大方跑Zlib压缩时性能甚至比F407还顺200MHz主频对deflate这类密集计算提升是实打实的。需要注意的是AT32的外设库跟STM32标准库不通用但Zlib只关心C库跟外设库没什么关系所以移植难度反而更低。APM32系列号称“硬件兼容”实测STM32工程直接烧录大多数场景能跑Zlib也不例外。不过部分型号在启动文件、Flash容量标识、USB和ADC这类模拟外设上还是有细节差异下载调试时会遇到一些奇怪问题。6.2 下载调试中遇到过的问题做这套开发时好几次在Keil里下载程序报“no stm32 target found”。排查下来最常见的原因是代码初始化把SWD引脚复用成GPIO了。Zlib移植工程往往会调整main函数里的初始化顺序如果GPIO初始化提前执行正好把JTAG/SWD引脚配置成普通IO调试器就抓不到芯片了。遇到这个报错先按住复位键再点下载同时检查目标板供电、复位电路和调试线连接别一上来就怀疑芯片烧了。代码里也可以加一段延时让MCU上电后给调试器一点时间握手。6.3 移植落地检查清单最后整理一份我每次都会对照的检查清单RAM预算算好压缩任务需要的窗口prevhead输出缓冲减去后确认剩余RAM够业务使用压缩等级选择先测Level 3再根据现场负载微调内存分配策略优先静态内存池其次是扩大Heap_Size禁止多任务环境下共享同一份z_stream编译宏必须加Z_SOLO确认z_off_t类型被正确typedef输出缓冲估算建议预留原始数据的60%~100%避免deflate返回Z_BUF_ERROR测试数据要用真实业务数据不要用“hello world”式的Demo文本压缩特征完全不同不要在中断服务函数里调用deflate压缩耗时太长会直接拖垮实时性确认RTOS任务栈足够默认2KB栈跑压缩任务不够建议调到4KB以上我自己在项目里的体会是Zlib移植的技术门槛其实不高真正考验人的是资源预算和场景判断。每次新项目要做压缩我都会先拿真实数据在目标板上跑一轮记录压缩率和耗时再做最终决定。最后再分享一个小技巧把压缩等级和“触发压缩的数据量阈值”做成可以通过配置项修改的参数不要写死在代码里。我之前把等级写死成Z_BEST_COMPRESSION现场一批旧设备CPU余量不足上报周期反而被拖累改成运行时读取配置后问题立刻解决。设备端做压缩要永远先考虑最坏情况再考虑平均情况最后才轮到那份性能好看的测试报告。本文还有配套的精品资源点击获取
