ESP-IoT-Solution XZ 解压组件实战指南从 xz_decompress 单次解压到 multi-call 流式 API【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solutionXZ 是一种高压缩比的数据压缩格式在嵌入式场景中常用于固件、资源文件与 OTA 数据的存储与传输。ESP-IoT-Solution 在components/utilities/xz目录下提供了基于 XZ Embedded 的 XZ 解压组件对外暴露统一的xz_decompress()接口并在 1.1.0 版本起将底层 multi-call 解压 API 公开供上层直接使用。阅读完本文你将掌握该组件的 API 语义、single-call 与 multi-call 两种模式的内部机制、内存友好的流式解压方法以及如何在 ESP-IDF 工程中集成并编写解压示例。组件定位与核心能力components/utilities/xz是一个轻量的 XZ 解压工具组件其官方描述为 xz decompression utility。组件以 XZ Embedded 库为内核由 Espressif 移植并封装成 ESP-IDF 组件espressif/xz托管于组件仓库idf_component.yml中声明版本为1.1.0要求idf: 4.1。从目录结构看组件由三部分组成include/xz_decompress.h对外公开的xz_decompress()解压入口src/xz_decompress.c对 XZ Embedded 原生 API 的封装实现port/include/xz_config.hXZ Embedded 在 ESP-IDF 环境下的移植配置内存宏、CRC、字节序工具等xz-embedded/XZ Embedded 原始代码树编译时只选用linux/lib/xz/下的xz_dec_bcj.c、xz_dec_lzma2.c、xz_dec_stream.c三个解码源文件。组件的 CMake 配置CMakeLists.txt将include与xz-embedded/linux/include/linux作为公开头文件目录把port/include与xz-embedded/linux/lib/xz设为私有头文件目录因此用户只需要#include xz_decompress.h即可使用无需关心 XZ Embedded 的内部细节。版本演进解读对应 CHANGELOG 主线组件 CHANGELOG.md 记录了三个版本的发展脉络理解这条演进主线有助于正确选用 APIv1.0.02023-2-10首次发布支持 xz_decompress首个版本确立了组件的核心形态对外只提供一个xz_decompress()函数内部自动在 single-call 与 multi-call 两种模式间选择用户无需感知底层解码器初始化、xz_dec_run()循环等细节。这一阶段的设计目标是开箱即用满足绝大多数给我一个压缩缓冲区还我一个解压缓冲区的诉求。v1.0.12025-2-20修复 error 回调原型错误该版本修复了一个关键 bugxz_decompress的error回调参数原型不正确。在 xz_decompress.h 中正确的声明为int xz_decompress(unsigned char *in, int in_size, int (*fill)(void *dest, unsigned int size), int (*flush)(void *src, unsigned int size), unsigned char *out, int *in_used, void (*error)(const char *x));即error是一个接收const char *错误信息、无返回值的回调用于向调用方输出可读的错误描述。修复前原型不匹配会导致启用该回调时产生编译警告或未定义行为升级到 v1.0.1 及以上版本即可规避。v1.1.02025-3-25公开 multi-call API1.1.0 是功能上的一次重要开放将 XZ Embedded 库的 multi-call 解压 APIxz_dec_init、xz_dec_run、xz_dec_end以及struct xz_buf等公开。这意味着高级用户不再受限于xz_decompress()的封装可以直接用底层 multi-call 接口自主控制输入/输出缓冲、分块处理和内存占用。在 示例程序 中新增的test_chunked_api()即演示了这一用法用xz_dec_init(XZ_PREALLOC, 1 16)指定 64 KB 字典配合xz_dec_run()循环按 4 KB 分块解压。xz_decompress API 详解xz_decompress()实现了 Linux 内核linux/decompress/generic.h所定义的通用解压接口语义其签名与参数含义如下完整注释见 xz_decompress.h参数类型含义inunsigned char *指向待解压的压缩数据缓冲区传入NULL时表示由fill回调按需提供数据in_sizeint输入缓冲区大小当in为NULL时该值被忽略fillint (*)(void *dest, unsigned int size)读取压缩数据的回调NULL表示压缩数据一次性存放在in中flushint (*)(void *src, unsigned int size)写出解压数据的回调NULL表示解压结果写入out缓冲区outunsigned char *存放解压结果的缓冲区传入NULL时表示由flush回调逐块消费输出in_usedint *输出参数返回实际消耗的压缩数据字节数可为NULLerrorvoid (*)(const char *x)错误信息输出回调返回值0表示解压成功-1表示发生错误。fill回调应返回实际读取的字节数返回负数表示读取失败flush回调应返回实际写出的字节数返回值不等于入参size会被视为缓冲错误。single-call 与 multi-call 的自动选择机制xz_decompress()的封装价值在于自动选择底层解码模式。在 xz_decompress.c 中可以看到判定逻辑if (fill NULL flush NULL) s xz_dec_init(XZ_SINGLE, 0); else s xz_dec_init(XZ_DYNALLOC, (uint32_t)-1);single-call 模式当fill与flush均为NULL时启用。要求输入、输出缓冲区都作为完整数据块一次性提供即调用方持有完整的压缩数据且out缓冲区足够容纳全部解压结果。这是最简单、最快的方式适合解压已知尺寸的小型资源如配置文件、小文本。multi-call 模式只要fill或flush任一非NULL即启用使用XZ_DYNALLOC动态分配字典内部以XZ_IOBUF_SIZE4096 字节见 xz_decompress.c为分块单位循环调用xz_dec_run()配合回调实现边读边解边写的流式处理。内存占用与输出尺寸解耦适合解压大文件或写入 flash 分区等场景。对应地out/in缓冲区的分配也有区分xz_decompress.cflush NULL时直接使用调用方传入的out且输出尺寸视为无限大flush ! NULL时内部vmalloc一块XZ_IOBUF_SIZE的临时输出缓冲填满即回调flush写走。in NULL时同样由内部申请一块 4096 字节缓冲每次填满后交给fill重新装载数据并通过*in_used累加统计已消耗的输入字节。四种回调组合的实战用法示例程序 用app_main依次演示了四种组合可视为 API 的完整使用范式1. buf → buffill NULL flush NULL压缩数据在in_buf解压结果写入out_buf。示例中先malloc(IO_BUFFER_LEN)申请输出缓冲并清零再一次性调用int ret xz_decompress((unsigned char *)xz_compressed_file_start, compressed_file_length, NULL, NULL, (unsigned char *)out_buf, decompressed_count, error);适用条件能预估解压后数据量且输出缓冲足够大。2. cb → cbin NULL out NULL压缩数据由fill从分区/内存按块读出解压结果由flush按块写出。这是内存最友好的方式因为读写都以 4096 字节分块进行不要求调用方持有完整数据static int fill(void *buf, unsigned int size) { uint32_t len (compressed_file_length - filled_length size) ? size : compressed_file_length - filled_length; if (len 0) { memcpy(buf, xz_compressed_file_start filled_length, len); filled_length len; } return len; } static int flush(void *buf, unsigned int size) { return fwrite(buf, 1, size, stdout); // 示例中直接打印到串口 }3. cb → bufflush NULLfill按块喂入压缩数据解压结果集中写入调用方提供的out_buf此时仍需保证out_buf容量足够。4. buf → cbfill NULL压缩数据一次性放入in解压结果通过flush逐块写出到目标位置如 flash 分区。适合压缩数据已完整拿到但输出目标不确定/过大的场景。底层实现要点CRC32、内存与格式支持组件在移植层面做了三处关键适配理解它们有助于排查问题CRC32 硬件加速xz_decompress.c 将 XZ Embedded 的 CRC32 计算重定向到 ROM 库esp_rom_crc32_le()避免引入额外的软件 CRC 表既省内存又提升速度并通过XZ_INTERNAL_CRC32宏启用内部 CRC 校验路径。若需要 CRC64默认关闭可取消 xz_config.h 中XZ_USE_CRC64的注释。内存宏映射xz_config.h 将内核风格的kmalloc/vmalloc/kfree/vfree直接映射为malloc/free使 XZ Embedded 的源码无需改动即可运行在 ESP-IDF 的堆分配器之上。这意味着解压大文件时的峰值内存主要由字典大小与缓冲尺寸决定可通过XZ_PREALLOC模式显式指定字典大小来控制。BCJ 过滤器可选xz_config.h 中默认未开启XZ_DEC_X86、XZ_DEC_ARM、XZ_DEC_ARMTHUMB等可执行代码转换过滤器。若解压对象是带 BCJ 过滤的 x86/ARM 固件镜像需要按需开启对应宏后重新编译组件。工程集成方式组件支持两种标准的 ESP-IDF 组件依赖方式详见 README.md方式一命令行添加依赖idf.py add-dependency xz1.1.0方式二在工程 main 组件的idf_component.yml中声明dependencies: espressif/xz: ^1.1.0本地开发时示例的依赖清单 展示了如何通过override_path指向仓库内的组件源码dependencies: xz: version: ~1.1.0 # 若通过 idf.py create-project-from-example 安装示例请注释下面一行 override_path: ../../../../components/utilities/xz也可以直接基于示例创建工程idf.py create-project-from-example espressif/xz^1.1.0:xz_decompress_file示例实战解压 hello.txt.xz示例工程 将test_file/hello.txt与其压缩版本hello.txt.xz通过EMBED_TXTFILES嵌入固件见 main/CMakeLists.txt运行时借助链接器生成的_binary_xxx_start/_binary_xxx_end符号定位数据。生成压缩文件示例使用 CRC32 校验并限定 LZMA2 字典为 8 KiB以保证 ESP32 等小内存设备可解压xz --checkcrc32 --lzma2dict8KiB -k test_file/hello.txt注意--lzma2dict8KiB会限制压缩端字典大小从而控制解压端的内存需求压缩时字典设置过大可能导致解压端内存不足。编译烧录idf.py -p PORT flash monitor退出串口监视器请按Ctrl-]。运行结果示例日志显示原始文件 393 字节被压缩到 93 字节buf→buf 模式解压后完整还原文本内容并返回ret 0, decompressed count is 92完整输出见 示例 READMEI (309) xz decompress: origin file size is 393, compressed file size is 93 bytes I (329) xz decompress: decompress data: Hello World!Hello Everyone! ... I (369) xz decompress: ret 0, decompressed count is 92示例末尾还新增了test_chunked_api()直接使用 1.1.0 公开的 multi-call API 以 4 KB 分块解压并统计输入/输出字节数展示了在无法预估输出大小时的显式控制流。使用注意事项输出缓冲必须足够大buf→buf / cb→buf 模式要求调用方保证out容量示例中out_buf清零且注释强调 out_buf need to be large enough。容量不足时解压会失败并返回-1。错误回调不可省发生错误时组件会调用error回调输出具体原因内存不足、格式错误、数据损坏等见 xz_decompress.c建议始终提供并打印。CRC 校验方式要与压缩端一致默认仅启用 CRC32若压缩时使用--checkcrc64需在xz_config.h中启用XZ_USE_CRC64重新编译。字典大小决定内存上限解压大文件时优先考虑 multi-call 模式或XZ_PREALLOC显式指定字典如示例中的 64 KB避免XZ_DYNALLOC模式下默认字典过大导致内存申请失败。综上espressif/xz组件从 v1.0.0 的单一入口到 v1.1.0 的 API 开放覆盖了从小数据一次解压到大数据流式解压的全谱系需求是 ESP32 系列平台上处理 XZ 压缩资源的轻量可靠选择。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考