eZIP工具¶

1. 简介¶

eZIP是思澈开发硬件级无损压缩加速模块，直接集成在 SoC 架构中。通过eZIP硬件，将有效的降低数据传输带宽、减少存储空间占用、提高系统帧率。
eZIP软件工具是为了适配eZIP硬件而开发的一个图片（png、gif、bmp）转换（压缩）工具，同时也提供了其他类型图形（jpg、mp4）的格式转换功能。版本2.6.9开始支持bmp。

2. 主命令¶

完整命令	主参数	功能描述
`eZIP -convert xxx`	`[-binfile 1]`	转换一个图片为像素bin文件，开头包含4个字节（v9是12个字节）的`lv_img_header_t`头
`eZIP -convert xxx`	`[-binfile 2]`	转换一个图片为eZIP压缩后的bin文件，开头包含4个字节（v9是12个字节）`lv_img_header_t`头
`eZIP -convert xxx`	`[-cfile 1]`	转换一个图片为像素c文件，使用`lv_img_dsc_t`数据结构
`eZIP -convert xxx`	`[-cfile 2]`	转换一个图片为eZIP压缩的c文件，使用`lv_img_dsc_t`数据结构
`eZIP -dir xxx`	`[-binfile 1 [wxh]]`	转换一个目录下对应分辨率的图片为像素bin文件
`eZIP -dir xxx`	`[-binfile 2 [wxh]]`	转换一个目录下对应分辨率的图片为eZIP压缩后的bin文件
`eZIP -dir xxx`	`[-cfile 1 [wxh]]`	转换一个目录下对应分辨率的图片为像素c文件
`eZIP -dir xxx`	`[-cfile 2 [wxh]]`	转换一个目录下对应分辨率的图片为eZIP压缩的c文件
`eZIP -lz4 xxx`		使用lz4压缩xxx文件
`eZIP -unlz4 xxx`		解压-lz4压缩的文件
`eZIP -gzip xxx`		使用gzip压缩xxx文件
`eZIP -ungzip xxx`		解压-gzip压缩的文件
`eZIP -img2jpg xxx`	`[-cfile 2]` `[-binfile 2]` `[-quality xx]`	显式转换png或bmp图片为jpg；jpg不支持alpha，带alpha图片会丢失透明信息或被合成。

3. 命令参数¶

3.1 -convert xxx¶

作用
- 转换一张图片（.png、.bmp、.gif、.jpg、 .mp4、.c）或一个freetype（.ttf）文件。其中，
  - .png：将转换为芯片硬件支持的eZIP格式
  - .bmp：版本2.6.9开始支持。带alpha的bmp将转换为带alpha的eZIP格式，不带alpha的bmp将转换为普通eZIP格式
  - .gif：将转换为芯片硬件支持的agif格式
  - .c：支持lvgl的像素格式的c文件转换为eZIP格式
  - .jpg：保持jpg格式，根据参数-cfile或-binfile转换为c或jpg格式
  - .mp4：保持mp4格式，根据参数-cfile或-binfile转换为c或mp4格式
  - .ttf: 保持ttf数据，根据参数-cfile或-binfile转换为c或ttf/bin格式

可选参数

转换类型（默认是binfile 2)

参数类型	功能描述
`-binfile 1`	转换为像素bin文件，开头包含`lv_img_header_t`头
`-binfile 2`	转换为eZIP压缩后的bin文件，开头包含`lv_img_header_t`头
`-cfile 1`	转换为像素c文件，使用`lv_img_dsc_t`数据结构
`-cfile 2`	转换为eZIP压缩的c文件，使用`lv_img_dsc_t`数据结构

芯片类型（默认是sf55x)

参数类型

功能描述

-chip xxx

default: sf55x
-chip sf55x
-chip sf58x
-chip sf56x
-chip sf52x
-chip sf57x
-chip sf…x [注：将来芯片命名]
输出颜色（默认是-rgb565）

参数类型

功能描述

-rgb565

输出565格式。如果原图是带alpha的，则输出是带alpha的

-rgb888

输出888格式。如果原图是带alpha的，则输出是带alpha的
lvgl版本（默认是-lvgl_version 8）

参数类型

功能描述

-lvgl_version 9

生成lvgl v9格式的数据
是否需要dither（默认是-dither 1）

参数类型

功能描述

-dither 0

888转换为565的时候不做dither

-dither 1

888转换为565的时候做dither
生成C文件时数据结构变量的段名（默认是ROM3_IMG）

参数类型

功能描述

-section XXX

定义生成C文件时数据结构变量的段名。其中lv_img_dsc_t的头段名为XXX_HEADER
生成bin文件时扩展名（默认是.bin）

参数类型

功能描述

-binext .xxx

生成bin文件时，文件的扩展名为.xxx
提取alpha，生成mask

参数类型

功能描述

-mask

从带alpha的png中提取alpha
生成文件的输出目录（默认输出目录是output）

参数类型

功能描述

-outdir xxx

生成文件的输出到xxx目录

参数类型	功能描述
`-chip xxx`	default: sf55x -chip sf55x -chip sf58x -chip sf56x -chip sf52x -chip sf57x -chip sf…x [注：将来芯片命名]

参数类型	功能描述
`-rgb565`	输出565格式。如果原图是带alpha的，则输出是带alpha的
`-rgb888`	输出888格式。如果原图是带alpha的，则输出是带alpha的

参数类型	功能描述
`-lvgl_version 9`	生成lvgl v9格式的数据

参数类型	功能描述
`-section XXX`	定义生成C文件时数据结构变量的段名。其中lv_img_dsc_t的头段名为XXX_HEADER

参数类型	功能描述
`-binext .xxx`	生成bin文件时，文件的扩展名为`.xxx`

参数类型	功能描述
`-mask`	从带alpha的png中提取alpha

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

3.2 -dir xxx¶

作用

转换一个目录（包括子目录）。采用-dir时，目录下的资源有两种组织方式：

Solution下要求的资源放置方式，需要严格按照图片资源的位置。此种方式下，命令行必须带分辨率[wxh]，例如ezip -dir images -cfile 2 410x494。eZIP只处理common和命令行指定分辨率目录下的资源，其他分辨率目录会跳过。

目录要求如下：
  +- images/
    +- app_name/               # 每个应用单独一个目录
      +- common/               # 所有分辨率共用资源
        +- ezip/
        +- ezip_dither/
        +- no_ezip/
        +- gif/
        +- mp4/
        +- mask/
        +- jpg/
      +- 410x494/              # 指定分辨率资源，目录名必须为 宽x高
        +- ezip/
        +- ezip_dither/
        +- no_ezip/
        +- gif/
        +- mp4/
        +- mask/
        +- jpg/

分辨率目录要求：
- `common`：所有分辨率共用的图片资源。
- `[wxh]`：某个分辨率专用的图片资源，例如`410x494`；命令行带`410x494`时，只处理`common`和`410x494`。

资源类型子目录要求：
- `ezip_dither`： `-dither 3`时，且输出rgb565时，存放需要非旋转但有渐进色的图片
- `ezip`： 存放非旋转的png/bmp图片。 eZIP在`-binfile 2`或`-cfile 2`的时候，会进行压缩处理，否则转换为像素的c文件或bin文件。版本2.6.9开始支持bmp：带alpha的bmp输出带alpha的eZIP，不带alpha的bmp输出不带alpha的eZIP
- `no_ezip`： 存放需要旋转的png/bmp图片。eZIP不做压缩处理，直接转换为像素的c文件或bin文件
- `gif`： 存放gif图片。 eZIP在`-binfile 2`或`-cfile 2`的时候，会进行压缩处理；否则，直接转换为c文件或bin文件
- `mp4`： 存放h264的视频。eZIP不做压缩处理，直接转换为c文件或bin文件
- `mask`： 存放作为mask的图片。eZIP会抽取该图片所有像素的alpha
- `jpg`： 存放jpg图片。支持Baseline jpg、渐进式或非YUV420的jpg，eZIP会先规范化为硬件支持的Baseline YUV420 jpg，再转换为c文件或bin文件

如果命令行包含`-img2jpg`，则`ezip`目录下无alpha的png/bmp图片会先按eZIP路径编码，再生成jpg候选并比较实际输出大小；只有jpg候选小于eZIP结果时才输出jpg。带alpha的png/bmp不会转jpg，仍按eZIP路径输出。

图片资源在xxx目录下随意放置（命令行不带分辨率）此种方式下，eZIP会根据会直接根据-binfile/-cfile后面跟的数字1或2决定怎么转换。如果是1，则是转换为像素；如果是2，则是进行压缩处理。

注意：使用-dir命令，如果使用-cfile，会自动生成一个头文件（通常按输入目录命名，形如 xxx_header.h），其中包括所有图片结构变量的声明。

  /*---------------------alarm_common_ezip begin--------------------*/
  LV_IMG_DECLARE(img_alarm_add_icon);
  LV_IMG_DECLARE(img_alarm_check);
  LV_IMG_DECLARE(img_alarm_delete_icon);
  LV_IMG_DECLARE(img_alarm_fail_icon);
  LV_IMG_DECLARE(img_alarm_selected);
  LV_IMG_DECLARE(img_alarm_success_icon);
  LV_IMG_DECLARE(img_gif_alarm);

  /*---------------------alarm_common_ezip  end--------------------*/

可选参数

2.1中的可选参数对-dir依然有效，另外还有以下一些扩展。

是否需要dither（默认是-dither 1）

参数类型	功能描述
`-dither 0`	888转换为565的时候不做dither
`-dither 1`	888转换为565的时候做dither
`-dither 3`	默认只有放在`ezip_dither`目录下的才做dither，其他图片不做dither

生成文件是否分目录存放（仅配合-dir使用）

参数类型	功能描述
`-separate_dir`	仅配合`-dir`使用。按输入资源路径拆分输出目录，生成文件存放在对应的资源类型/应用子目录下，用于避免不同目录下同名资源互相覆盖。
`-separate_dir header`	仅配合`-dir`使用。在分目录输出的基础上，生成的资源名/头文件声明也按应用目录做区分，用于减少头文件声明中的同名冲突。

-cfile时生成c文件的结构变量是否添加增加LV_ATTRIBUTE_USED_XXX

参数类型

功能描述

-attr_used

添加该宏以后，可以映射该宏为__attribute__((used))，用于Solution的builtin_res

参数类型	功能描述
`-attr_used`	添加该宏以后，可以映射该宏为`__attribute__((used))`，用于Solution的`builtin_res`

3.3 -gzip xxx¶

作用
- 使用gzip压缩xxx文件
可选参数
- 是否包括header（gzip标准的头，默认是包括的）
  
  参数类型
  
  功能描述
  
  -noheader
  
  disable gzip的头。生成的不带gzip头的压缩文件（.gz）
- 头上是否包括length（默认不包括）
  
  参数类型
  
  功能描述
  
  -length
  
  压缩文件起始是否是4个字节length（整个文件长度）
- 生成文件的输出目录（默认输出目录是output）
  
  参数类型
  
  功能描述
  
  -outdir xxx
  
  生成文件的输出到xxx目录

参数类型	功能描述
`-noheader`	disable gzip的头。生成的不带gzip头的压缩文件（.gz）

参数类型	功能描述
`-length`	压缩文件起始是否是4个字节length（整个文件长度）

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

3.4 -ungzip xxx¶

作用
- 解压-gzip压缩的文件
可选参数
- 与2.3节的参数一样。

3.5 -lz4 xxx¶

作用
- 使用lz4压缩xxx文件
可选参数
- 头上是否包括length（默认不包括）
  
  参数类型
  
  功能描述
  
  -length
  
  压缩文件起始是否是4个字节length（整个文件长度）
- 生成文件的输出目录（默认输出目录是output）
  
  参数类型
  
  功能描述
  
  -outdir xxx
  
  生成文件的输出到xxx目录

参数类型	功能描述
`-length`	压缩文件起始是否是4个字节length（整个文件长度）

参数类型	功能描述
`-outdir xxx`	生成文件的输出到xxx目录

3.6 -unlz4 xxx¶

作用解压-lz4压缩的文件
可选参数
- 与2.5节的参数一样。

3.7 -img2jpg xxx¶

作用转换png或bmp为jpg。默认生成的图片质量为85%，输出.jpg文件。该命令只支持png/bmp输入；原生jpg请使用-jpg或-convert xxx.jpg。

输出jpg必须满足Baseline YUV420采样，且文件中只有一个FF D8 SOI标记。如果生成结果不满足该约束，则转换失败。

可选参数

参数类型	功能描述
`-quality xx`	输出jpg的图片质量，默认为85%。图片质量越高，则生成的图片尺寸越大
`-binfile 2`	转换为jpg的bin文件，开头包含`lv_img_header_t`头
`-cfile 2`	转换为jpg的c文件，使用`lv_img_dsc_t`数据结构

4. 使用例程¶

4.1 eZIP C 文件生成¶

ezip -convert png\min_hand.png -rgb888 -cfile 1 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个 rgb888格式的像素（非压缩） C 文件，生成文件放在当前目录下的png_out子目录下。

LV_ATTRIBUTE_MEM_ALIGN_EZIP const uint8_t min_hand_map[] SECTION(".ROM3_IMG_PIXEL.min_hand") = { 
    0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,...,
};

#ifndef LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER
#define LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER ALIGN(4)
#endif
LV_ATTRIBUTE_MEM_ALIGN_PIXEL_HEADER const eZIP_RGBARGB888A LV_ATTRIBUTE_USED_PIXEL lv_img_dsc_t min_hand SECTION(".ROM3_IMG_PIXEL_HEADER.min_hand") = { 
  .header.cf = LV_IMG_CF_TRUE_COLOR_ALPHA,
  .header.always_zero = 0,
  .header.w = 11,
  .header.h = 180,
  .data_size  = 7920,
  .data = min_hand_map
};

ezip -convert png\menu_bg.png -cfile 2 -section ROM1_IMG -attr_used

用途：转换当前目录下png\menu_bg.png的文件，生成一个格式为rgb565格式的 eZIP （压缩） C 文件，段名为ROM1_IMG，且包含LV_ATTRIBUTE_USED_，输出目录为output。

LV_ATTRIBUTE_MEM_ALIGN_EZIP const LV_ATTRIBUTE_USED_EZIP uint8_t menu_bg_map[] SECTION(".ROM1_IMG_EZIP.menu_bg") = { 
    0x00,0x00,0x00,0x81,0x43,0x04,0x20,0x00,0x00,0x30,0x00,0x30,0x00,0x05,0x00,0x00,0x00,0x00,0x00,0x00,...,
};

#ifndef LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER
#define LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER ALIGN(4)
#endif
LV_ATTRIBUTE_MEM_ALIGN_EZIP_HEADER const eZIP_RGBARGB_PAL LV_ATTRIBUTE_USED_EZIP lv_img_dsc_t menu_bg SECTION(".ROM1_IMG_EZIP_HEADER.menu_bg") = { 
  .header.cf = LV_IMG_CF_RAW_ALPHA,
  .header.always_zero = 0,
  .header.w = 48,
  .header.h = 48,
  .data_size  = 129,
  .data = menu_bg_map
};

ezip -dir png -rgb888 -cfile 1 -chip sf55x -outdir png_out

用途：解码目录 png 及其子目录下的所有图片，并批量生成像素格式的c文件。

ezip -dir png -rgb888 -cfile 2 -chip sf52x 410x494 -outdir png_out

用途：解码目录 png 及其子目录下分辨率为410x494的所有图片（common子以及410x494子目录），并批量生成 eZIP 格式的文件。

ezip -gif gif_stress.gif -cfile 1 -outdir png_out 或 ezip -convert gif_stress.gif -cfile 1 -outdir png_out

用途： gif转换为c格式（原样转换）。

ezip -convert gif_stress.gif -cfile 2 -chip sf52x -outdir png_out

用途： gif转换为eZIP格式的c文件。（注意： -chip sf55x不会使用eZIP转换，会输出gif格式的c文件）

ezip -convert beauty.jpg -cfile 1 -outdir png_out

用途：jpg转换为lv_img_dsc_t结构的c文件

ezip -convert beauty.mp4 -cfile 1 -outdir png_out

用途： mp4转换为lv_img_dsc_t结构的c文件

ezip -convert _tiny55_full.ttf -cfile 2 -outdir png_out

用途：将ttf文件转换为转换为lv_font_freetype_lib_dsc_t结构的c文件

const lv_font_freetype_lib_dsc_t SECTION(".SECTION_TTF_HEADER._tiny55_full") _tiny55_full_lib = { 
  .font_lib_size = 0x1098ac,
  .font_lib_data = (const char *) ttf_map,
  .font_lib_name = name,
}

ezip -convert beauty.c -cfile 2 -chip sf52x -outdir png_out

用途：转换lvgl的像素格式的c文件为eZIP的c文件格式。该命令可用于转换第三方UI工具生成的c格式图片为eZIP格式。

4.2 eZIP bin 文件生成¶

ezip -convert png\min_hand.png -rgb888 -binfile 1 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个 rgb888格式的像素（非压缩） bin 文件，生成文件放在当前目录下的png_out子目录下。

ezip -convert png\menu_bg.png -binfile 2 -binext .ezip

用途：转换当前目录下png\menu_bg.png的文件，生成一个rgb565格式的 eZIP （压缩）扩展名为.ezip 的bin文件，输出目录为output。

ezip -dir png -rgb888 -binfile 1 410x494 -chip sf52x -outdir png_out

用途：解码目录 png 及其子目录下的分辨率为410x494的所有图片（common子以及410x494子目录），并批量生成像素格式的bin文件。

ezip -dir png -binfile 2 -chip sf58x -outdir png_out

用途：解码目录 png 及其子目录下的所有图片，并批量生成 rgb565 格式的 eZIP 文件。如果图片是palette格式，则使用palette压缩。

ezip -convert gif_stress.gif -binfile 1 -outdir png_out

用途：gif转换为bin格式（原样转换）。

ezip -convert gif_stress.gif -binfile 2 -chip sf56x -outdir png_out

用途：gif转换为eZIP格式的bin文件

ezip -convert beauty.c -binfile 2 -chip sf56x -outdir png_out

用途：转换lvgl的像素格式的c文件为eZIP的bin文件格式。该命令可用于转换第三方UI工具生成的c格式图片为eZIP格式。

4.3 gzip压缩和解压¶

ezip -gzip sample.txt -outdir gzip_out

用途：使用gzip标准格式进行压缩，压缩文件为sample.txt.gz，放在gzip_out。

ezip -ungzip sample.txt.gz -outdir gzip_out

用途：使用gzip对sample.txt.gz进行解压，解压文件放在gzip_out。

ezip -gzip sample.txt -noheader -length -outdir gzip_out

用途：使用gzip对sample.txt进行压缩，压缩文件为sample.txt.gz，压缩时不加标准的头，前面加4个字节放长度，输出放在gzip_out。

ezip -ungzip sample.txt.gz -noheader -length -outdir gzip_out

用途：使用gzip对sample.txt.gz进行解压，解压文件放在gzip_out。（注意ungzip需要和gzip的参数-noheader -length配对）。

4.4 使用 eZIP 硬件解码 gzip 数据¶

本节说明固件端如何通过 eZIP 硬件将 gzip 压缩数据解压到 AHB 可访问的内存；解压后的数据可由应用继续写入 Flash、文件系统或用于其他业务处理。此方式使用 eZIP 的 HAL_EZIP_OUTPUT_AHB 输出模式。

压缩数据可通过以下两种途径生成：

PC 端命令行：使用 eZIP gzip 命令及 SDK 目录 sdk/tools/png2ezip/eZIP.exe 执行压缩；硬件解码场景推荐使用下方的 -length -noheader 参数组合。
手机端 APK/SDK 接口：由 APK 调用 eZIP SDK 接口的gzip生成数据。支持的平台及接入文档请参见 eZIPSDK 移动端文档

Android 接口定义
iOS 接口定义
Harmony 接口定义。手机端输出的数据封装必须与固件端约定一致。

重要

无论通过 PC 端命令行还是手机端 APK/SDK 接口压缩，手机端、PC 端和固件端必须使用相同的数据封装格式。PC 端推荐使用 SDK 的 sdk/tools/png2ezip/eZIP.exe 生成无 gzip 标准头且带原始长度前缀的数据：

eZIP.exe -gzip file.bin -length -noheader

生成的 file.bin.gz 的格式如下，其中长度字段为小端序 uint32_t，不传给硬件；其后的原始 deflate 压缩数据才是 eZIP 的输入。

+--------------------------+--------------------------------+
| 4 字节原始数据长度        | gzip / deflate 压缩数据         |
+--------------------------+--------------------------------+
^                          ^
|                          |
读取并校验，不传给 eZIP      作为 HAL_EZIP_Decode() 的输入

标准 gzip 文件含有 gzip 头、尾等封装信息，不能直接按本节示例送入硬件。若数据由手机 SDK 或其他工具生成，应在协议中约定其输出与上述格式一致。

4.4.1 固件端解压步骤¶

从压缩文件或传输数据的前 4 字节读取原始数据长度，并按该长度分配或准备输出缓冲区。
将第 5 字节开始的压缩数据复制到 4 字节对齐的输入缓冲区；输入、输出缓冲区均须为 4 字节对齐。
若缓冲区位于 Cacheable 内存（例如 PSRAM），在启动硬件前执行 Cache 维护操作。
填充 EZIP_DecodeConfigTypeDef，设置 work_mode 为 HAL_EZIP_MODE_GZIP，并设置 output_mode 为 HAL_EZIP_OUTPUT_AHB。
初始化 EZIP_HandleTypeDef 后调用 HAL_EZIP_Decode()。该调用使用轮询等待硬件完成。
硬件完成后再次进行 Cache 维护；此时输出缓冲区中的前 original_size 字节即为原始数据。

下面示例与 SDK 中 DFU 的硬件解压流程一致。调用方只需传入完整的 -length -noheader 格式数据，以及容量不小于原始长度的输出缓冲区。

#include "rtthread.h"
#include "bf0_hal.h"

#ifdef BSP_USING_EPIC
#include "drv_epic.h"
#endif

#ifndef hwp_ezip
#define hwp_ezip hwp_ezip1
#endif

static rt_err_t ezip_gzip_decode_ahb(const uint8_t *gzip_file,
                                     uint32_t gzip_file_size,
                                     uint8_t *output,
                                     uint32_t output_capacity)
{
    EZIP_DecodeConfigTypeDef config = {0};
    EZIP_HandleTypeDef ezip_handle = {0};
    HAL_StatusTypeDef status;
    uint8_t *input;
    uint32_t original_size;
    rt_base_t level;

    if ((gzip_file == RT_NULL) || (output == RT_NULL) ||
            (gzip_file_size <= sizeof(original_size)))
    {
        return -RT_EINVAL;
    }

    /* 前 4 字节为 eZIP.exe -length 写入的原始数据长度。 */
    memcpy(&original_size, gzip_file, sizeof(original_size));
    if (original_size > output_capacity)
    {
        return -RT_EFULL;
    }

    /* rt_malloc() 返回的地址满足对齐要求；复制后跳过长度字段。 */
    /* 注：Solution也可以使用app_malloc()、app_cache_alloc() 获取对齐内存。 */
    input = rt_malloc(gzip_file_size - sizeof(original_size));
    if (input == RT_NULL)
    {
        return -RT_ENOMEM;
    }
    memcpy(input, gzip_file + sizeof(original_size),
           gzip_file_size - sizeof(original_size));

#ifdef BSP_USING_EPIC
    /* eZIP 与 EPIC 共用硬件资源，使用前先获取互斥锁。 */
    if (drv_epic_take(RT_WAITING_FOREVER) != RT_EOK)
    {
        rt_free(input);
        return -RT_ERROR;
    }
#endif

    /* Cacheable 内存（如 PSRAM）必须在硬件访问前维护 Cache。 */
    SCB_InvalidateDCache_by_Addr(input,
                                 gzip_file_size - sizeof(original_size));
    SCB_InvalidateDCache_by_Addr(output, original_size);

    config.input = input;
    config.output = output;
    config.work_mode = HAL_EZIP_MODE_GZIP;
    config.output_mode = HAL_EZIP_OUTPUT_AHB;

    ezip_handle.Instance = hwp_ezip;
    status = HAL_EZIP_Init(&ezip_handle);
    if (status == HAL_OK)
    {
        /* AHB 轮询模式下为避免解压过程被中断打断，暂时关闭中断。 */
        level = rt_hw_interrupt_disable();
        status = HAL_EZIP_Decode(&ezip_handle, &config);
        rt_hw_interrupt_enable(level);
    }

    /* 确保 CPU 读取到硬件写入后的最新数据。 */
    SCB_InvalidateDCache_by_Addr(output, original_size);

#ifdef BSP_USING_EPIC
    drv_epic_release();
#endif
    rt_free(input);

    return (status == HAL_OK) ? RT_EOK : -RT_ERROR;
}

备注

示例采用一次性解压，压缩数据和解压结果都必须能完整放入内存。大文件不能将同一条 gzip/deflate 数据流拆成多次独立解压；应在发送端先按业务数据分块，再分别执行 eZIP.exe -gzip ... -length -noheader。每个分块都保存自己的 4 字节原始长度，设备端按顺序解压并写入 Flash、文件系统或其他目标位置。
HAL_EZIP_Decode() 要求输入和 AHB 输出地址均为 4 字节对齐。静态缓冲区建议使用 ALIGN(4)；rt_malloc() 返回的缓冲区可满足该要求。
在 SF32LB55X 上，AHB 输出地址不能位于 ITCM 或 RETM 区域。
示例为了保证 AHB 轮询解压不被中断打断，在调用前关闭中断。解压数据较大时会延长关中断时间，应通过分块压缩控制单次数据量。
如果工程中 EPIC 或其他模块也会使用 eZIP，必须成对调用 drv_epic_take() 和 drv_epic_release()，避免并发访问硬件。

4.5 lz4压缩和解压¶

ezip -lz4 sample.txt -outdir lz4_out

用途：使用lz4格式进行压缩，压缩文件为sample.txt.lz4，放在lz4_out。

ezip -unlz4 sample.txt.lz4 -outdir lz4_out

用途：使用lz4对sample.txt.lz4进行解压，解压文件放在lz4_out。

ezip -lz4 sample.txt -length -outdir lz4_out

用途：使用lz4对sample.txt进行压缩，压缩文件为sample.txt.lz4，压缩后文件前面加4个字节放长度，输出放在lz4_out。

ezip -unlz4 sample.txt.lz4 -length -outdir lz4_out

用途：使用lz4对sample.txt.lz4进行解压，解压文件放在lz4_out。（注意unlz4需要和lz4的参数-length配对）。

4.6 eZIP文件反解为png文件¶

ezip -convert png\min_hand.bin -spt 1 -dpt 0 -outdir png_out

用途：解码eZIP的压缩文件png\min_hand.bin为png的图片。

ezip -convert psram.bin -spt 1 -dpt 0 -dec_off 0x1234 -outdir png_out

用途：解码psram.bin中偏移地址为0x1234处的eZIP bin，反解为png的图片。

ezip -dir png -spt 1 -dpt 0 -outdir png_out

用途：批量解码png目录下所有的eZIP压缩文件，反解为png图片。

4.7 图片转为jpg文件¶

-img2jpg直接作为主命令使用时，表示用户显式要求将png/bmp转换为jpg；即使源图带alpha，也会继续生成jpg，透明信息会丢失或被合成。与此不同，-dir中附带-img2jpg属于自动择优模式，只会对无alpha的png/bmp生成jpg候选，带alpha图片仍按eZIP路径输出。

ezip -img2jpg png\min_hand.png -outdir png_out

用途：显式转换当前目录下png\min_hand.png的文件，生成一个图片质量为85%的jpg格式文件，生成文件放在当前目录下的png_out子目录下。注意： jpg不带透明色，因此对于带alpha的图片会丢失透明信息或被合成。

ezip -img2jpg png\min_hand.png -binfile 2 -quality 90 -outdir png_out

用途：转换当前目录下png\min_hand.png的文件，生成一个图片质量为90%的jpg格式bin文件，生成文件放在当前目录下的png_out子目录下。注意，bin文件包括lv_img_header_t + jpg文件。

ezip -img2jpg bmp\min_hand.bmp -cfile 2 -quality 95 -outdir png_out

用途：转换当前目录下bmp\min_hand.bmp的文件，生成一个图片质量为95%的jpg格式c文件，生成文件放在当前目录下的png_out子目录下。