平台配置与固件打包工具

AC79NN（WL82 平台）SDK 中用于固件打包、平台配置与升级文件生成的批处理工具集，涵盖 cpu/wl82/tools/ 下的升级固件生成脚本、tools/ 目录下的交叉编译辅助工具，以及配套的资源打包、Flash 写入、镜像分析等工具。

Purpose and Scope

本文档介绍 AC79 系列芯片平台（cpu/wl82）SDK 中与平台配置与固件打包相关的工具链，包括：

• 升级固件生成流程（SD/U 盘升级、OTA 升级两种模式）及产物命名规范
• cpu/wl82/tools/ 目录下的打包脚本（生成升级固件.bat、loader_tools/upgrade.bat、packres/packres.bat 等）
• tools/ 根目录与 tools/utils/ 下的通用工具（make.exe、merge-archives.exe、override-seg.exe、do_merge_libs.bat 等）
• 平台配置入口（脚本引用的 note.txt、download.bat 等）

本页边界：本文只覆盖"工具本身"——脚本的调用方式、执行流程、产物与失败模式。SDK 的编译构建系统（Makefile / 链接脚本）、烧录器（JTAG）底层驱动、OTA 升级的固件内协议实现均属于其他目录页范畴，这里仅在必要时交叉引用。

Overview

嵌入式 SDK 的交付物通常不是单个可执行文件，而是一组面向不同升级通道的固件镜像。在 AC79NN SDK 中，编译链接后主要产生两类关键产物：

• jl_isd.ufw：完整固件包，用于 SD 卡 / U 盘本地升级（支持双备份，即 A/B 双镜像）。
• db_update_files_data.bin：差分/增量数据文件，用于 HTTP OTA / FTP 远程升级（仅支持单备份）。

由于 Bootloader 和升级程序（loader）对升级文件有严格的命名约定，直接拷贝产物无法被识别。因此平台提供了一批 Windows 批处理脚本，将这些产物重命名并归档到约定的 upgrade\ 目录，形成最终可发布的升级包：

除打包脚本外，平台还提供一组配套工具：交叉编译辅助（make.exe、do_merge_libs.bat）、资源打包（packres.bat）、Flash 写入（write_file_to_flash.bat）、ELF 体积分析（report_elf_sizes.bat）与异常地址定位（定位异常地址.bat）等，构成完整的平台工具生态。

Architecture

flowchart TD
    subgraph sg_Build["构建阶段（编译链接）"]
        ELF["链接产物 .elf / .bin"]
        UFW["jl_isd.ufw"]
        BIN["db_update_files_data.bin"]
    end

    subgraph sg_Tools["平台打包工具（cpu/wl82/tools）"]
        GEN["生成升级固件.bat"]
        UP["loader_tools/upgrade.bat"]
        UPF["loader_tools/升级文件.bat / 升级文件-OTA.bat"]
        PACK["packres/packres.bat"]
        WTF["write_file_to_flash.bat"]
    end

    subgraph sg_Output["发布产物（upgrade/ 目录）"]
        U1["update.ufw"]
        U2["update-ota.ufw"]
        RES["资源包 res"]
        FLASH["烧写镜像"]
    end

    subgraph sg_Utils["通用工具（tools/ 与 tools/utils/）"]
        MAKE["make.exe"]
        MERGE["merge-archives.exe"]
        OV["override-seg.exe"]
        DML["do_merge_libs.bat"]
    end

    ELF --> UFW
    ELF --> BIN
    UFW --> GEN
    BIN --> GEN
    UFW --> UP
    BIN --> UP
    GEN -->|"菜单选择 1/2"| U1
    GEN -->|"菜单选择 2"| U2
    UP -->|"参数 OTA"| U2
    UP -->|"参数 SD"| U1
    UPF --> U1
    UPF --> U2
    PACK --> RES
    WTF --> FLASH
    MERGE --> DML
    OV --> DML
    MAKE -.->|"构建辅助"| ELF

架构说明：

• 构建阶段产生 jl_isd.ufw 与 db_update_files_data.bin，这两个文件是打包脚本的输入。
• 打包工具层是核心：生成升级固件.bat 提供交互式菜单（1=SD/U 盘双备份，2=HTTP OTA/FTP 单备份，q=取消），loader_tools/upgrade.bat 提供命令行参数（OTA / SD）驱动的非交互式打包，二者共用相同的复制-重命名逻辑。
• 发布产物层统一落在 upgrade\ 目录，update.ufw 与 update-ota.ufw 是 loader 约定的标准文件名。
• 通用工具层服务于构建与库合并，merge-archives.exe 与 override-seg.exe 被 do_merge_libs.bat 串联使用。

固件打包主流程

交互式打包：生成升级固件.bat

cpu/wl82/tools/生成升级固件.bat 是平台最核心的打包入口，面向产线/测试人员提供交互式选择。其执行流程如下：

@echo off

call .\download.bat
cls

if exist upgrade\*.ufw del upgrade\*.ufw
if not exist upgrade md upgrade

start "" "note.txt"

Source: 生成升级固件.bat

脚本首先调用 download.bat（构建下载/拉取最新镜像），随后清空并重建 upgrade\ 目录——这一步保证每次打包都是干净的，避免残留旧固件被误发布。start "" "note.txt" 弹出操作说明文档，强制操作者先阅读注意事项。

随后进入菜单分支：

echo [ 升级方式选择 ]
echo 1: SD卡升级/U盘升级方式：[支持双备份]
echo 2: HTTP OTA、FTP升级方式：[只支持单备份]
echo q: 取消

set /p var=请先仔细阅读note.txt, 再选择升级方式：

if %var% EQU 1 (
	copy jl_isd.ufw upgrade\update.ufw
	...
) else if %var% EQU 2 (
	copy db_update_files_data.bin upgrade\update-ota.ufw
	...
) else if %var% EQU q (
    exit
)

Source: 生成升级固件.bat

设计意图：双备份（A/B）模式允许 SD/U 盘升级时保留一个可回退的旧镜像，安全性更高，因此只支持本地介质；OTA 因带宽与存储限制只做单备份。菜单用 set /p 读取用户输入并逐项 if/else if 匹配，复制完成后用 exist 校验目标文件是否生成，输出 [OK]/[ERR] 提示，保证操作者能立即感知失败。

命令行打包：loader_tools/upgrade.bat

cpu/wl82/tools/loader_tools/upgrade.bat 是同一逻辑的参数化版本，便于集成到自动化流水线（CI/产测脚本）中。它通过第一个参数 %1 选择模式：

if /i %1 == OTA (
	echo "当前打包模式：OTA"
	copy db_update_files_data.bin upgrade\update-ota.ufw
	...
)else (

if /i %1 == SD (
	echo "当前打包模式：SD"
	copy jl_isd.ufw upgrade\update.ufw
	...
) else (
	echo "当前打包模式：ERROR"
)
)

Source: upgrade.bat

要点：

• if /i 使参数匹配大小写不敏感（ota、Ota 均有效）。
• 脚本先要求用户确认已读 note.txt（set /p var=...y/n），未确认（非 y）则直接失败退出——这是文档驱动的操作规范在脚本层面的强制化。
• 成功打包后 choice /t 2 /d y /n >nul 让窗口停留 2 秒后自动关闭，适配双击运行场景。
• 非 OTA/SD 参数会落入 ERROR 分支，提示调用方参数错误。

打包产物校验

两种脚本都使用 if exist 校验复制结果：复制成功才打印 [OK] 并给出最终文件名与放置路径；失败则打印 [ERR] 并提示"请仔细阅读 note.txt"。这一设计把"文件系统操作可能静默失败"（磁盘满、权限不足、源文件缺失）这一风险显性化。

平台工具目录结构

flowchart LR
    subgraph sg_Root["SDK 根目录"]
        T["tools/"]
    end

    subgraph sg_Utils["tools/utils/"]
        MAKE["make.exe"]
        MERGE["merge-archives.exe"]
        OV["override-seg.exe"]
        DML["do_merge_libs.bat"]
    end

    subgraph sg_CPU["cpu/wl82/tools/"]
        GEN["生成升级固件.bat"]
        LT["loader_tools/"]
        PR["packres/packres.bat"]
        WTF["write_file_to_flash.bat"]
        REP["report_elf_sizes.bat"]
        LOC["定位异常地址.bat"]
        JTAG["jtag/download_jtag.bat"]
    end

    T --> sg_Utils
    GEN --> LT
    LT --> UFW["update.ufw / update-ota.ufw"]

说明：除 生成升级固件.bat 与 upgrade.bat 外，上表其余工具的职责根据文件名与目录约定归纳；未逐一读取脚本内容，具体参数请以各脚本内注释为准。

使用示例

场景一：产线生成 SD/U 盘升级包（交互式）

在 cpu/wl82/tools/ 目录下双击 生成升级固件.bat，或命令行执行：

:: 进入打包工具目录（假设 SDK 根目录为当前目录）
cd cpu/wl82/tools

:: 运行打包脚本：脚本先执行 download.bat 拉取最新镜像
:: 然后在提示符输入 1 并按回车
生成升级固件.bat
:: 输入: 1
:: 结果: upgrade\update.ufw 生成（源: jl_isd.ufw）

Source: 生成升级固件.bat

场景二：CI 流水线生成 OTA 升级包（参数化）

cd cpu/wl82/tools/loader_tools

:: 以 OTA 模式打包：参数大小写不敏感（if /i 匹配）
upgrade.bat OTA
:: 结果: upgrade\update-ota.ufw 生成（源: db_update_files_data.bin）
:: 注：脚本会先要求确认已读 note.txt，输入 y 继续

:: 以 SD 模式打包
upgrade.bat SD
:: 结果: upgrade\update.ufw 生成（源: jl_isd.ufw）

Source: upgrade.bat

场景三：失败路径

:: 源文件缺失或未确认文档阅读时，脚本输出 [ERR] 而非 [OK]
upgrade.bat
:: 提示: 是否已经仔细阅读note.txt？确认开始升级文件？y/n：
:: 输入 n → 输出 "生成升级文件失败" 并退出

Source: upgrade.bat

配置选项

打包工具是零配置的批处理脚本，所有"配置"均通过文件约定与环境约定实现：

配置设计意图：批处理工具刻意避免配置文件，把"该打包什么"固化为两个源文件名、把"该生成什么"固化为两个目标文件名。这降低了产线误配置的风险，但代价是灵活性低——若构建产物改名，需同步修改脚本。

失败模式、边界情况与并发

已知失败模式

边界情况

• 空输入：set /p 直接回车时 %var% 为空，if %var% EQU 1 这类比较在 cmd 中可能产生语法错误或落入非预期分支——脚本未对空输入做防护，属于已知边界，操作上依赖用户输入正确。
• 文件名编码：脚本以 GBK/ANSI 编码保存（如 升级文件.bat、定位异常地址.bat 等中文文件名），在非中文区域设置的 Windows 上可能显示乱码，但不影响 copy 等核心命令执行。
• 路径假设：脚本基于"当前工作目录即工具目录"的假设执行相对路径复制，从其他目录调用时需先 cd。

并发与一致性

打包脚本不支持并发执行：

• 多个实例同时写入 upgrade\ 会互相覆盖（del + copy 非原子）。
• 产线若需并行打包，应通过流水线串行化或为每个任务分配独立的工作目录。
• 由于每次打包前都会 del 旧文件，并发场景下可能出现"A 实例清理了 B 实例刚生成的包"的竞态，最终产物不确定。推荐做法：单实例串行执行，或在脚本外层加锁（如锁文件/任务系统互斥）。

性能与运维要点

• 执行成本：打包本质是文件复制，耗时由产物体积与磁盘速度决定（通常秒级）；download.bat 若涉及网络拉取镜像，才是时间大头。
• 产物校验建议：脚本仅校验"文件存在"，不校验内容完整性。发布前建议对 update.ufw / update-ota.ufw 计算哈希（如 certutil -hashfile）并与构建产物比对，防止复制损坏。
• 日志与追溯：脚本不写日志。产线建议在调用层（CI）捕获输出，记录时间戳、模式参数与产物哈希，便于回溯问题固件批次。
• 清理策略：upgrade\ 每次打包自动清空，发布服务器应另行归档历史包，避免仅剩最新包导致无法回退。

扩展点

• 新增升级通道：在 生成升级固件.bat 的 if/else if 链中追加分支，并约定新的目标文件名（如 update-wifi.ufw），同时在 loader 侧注册对应文件头识别逻辑。
• 前置/后置钩子：call .\download.bat 是天然的前置钩子位置——替换为自己的镜像拉取/版本检查脚本即可接入现有 CI，无需改动打包主体。
• 自动化集成：loader_tools/upgrade.bat OTA|SD 的无交互入口专为流水线设计；if /i 大小写容错降低了脚本语言层面的集成摩擦。
• 库合并流水线：tools/utils/do_merge_libs.bat 串联 merge-archives.exe 与 override-seg.exe，新增静态库或需要段级修补时，在此脚本中追加工具调用即可。
• 中文环境适配：脚本文件名为中文（GBK），如需国际化部署，可复制为 ASCII 文件名并保持内部逻辑不变（if /i 与 copy 逻辑与文件名无关）。

Related Links

• 构建系统与链接脚本（平台编译入口） —— 编译如何产出 jl_isd.ufw 与 db_update_files_data.bin
• 升级与 OTA 机制（loader 侧文件识别） —— update.ufw / update-ota.ufw 在设备端如何被解析
• JTAG 调试与烧录 —— jtag/download_jtag.bat 与 write_file_to_flash.bat 的底层实现
• 关键源文件：
  • 生成升级固件.bat
  • loader_tools/upgrade.bat
  • tools/utils/do_merge_libs.bat
  • tools/make_prompt.bat