烧写与量产工具

本文档介绍 fw-AC63_GP_MCU SDK 中与固件烧写、产测与量产相关的工具链及其使用流程，覆盖 sdk/bsp/<芯片型号>/tools/ 目录下的下载脚本、配置文件与产物生成链路，以及量产烧写器（一拖二 / 一拖八 / 蓝牙测试盒）的固件兼容性约束。

Purpose and Scope

本文档面向需要使用 AC63 系列芯片（AC632N / AC635N / AC636N / AC638N）进行固件下载、裸片烧写或量产交付的开发与产线工程人员，说明：

• SDK 内置的烧写工具链组成（isd_download.exe、fw_add.exe、ufw_maker.exe 及配套 loader / uboot / 脚本文件）；
• download.bat 从 ELF 编译产物到可烧写镜像（app.bin → .fw → .ufw）的完整流水线；
• isd_config.ini 中影响下载行为、flash 分区、uboot 配置与量产工具版本校验的关键配置项；
• 量产工具（一拖二烧写器、一拖八烧写器、蓝牙测试盒）与固件的版本匹配机制。

烧录后运行时的设备行为（uboot 启动、OTA 升级、VM 分区读写）属于运行时固件范畴，不在本文档展开；如需了解 OTA 升级流程，请参见 SDK 开发文档中"升级"相关章节。生产烧写工具硬件的申请入口见 README.md。

Overview

AC63 系列通用 MCU 的固件烧写采用"上位机工具 + 芯片内置引导"的模式：PC 端通过 isd_download.exe 与芯片建立通信，将 uboot 引导程序和应用程序（app.bin）写入片外 SPI NOR Flash，再生成可被量产工具识别的固件包（.fw）与升级包（.ufw）。

整个烧写体系围绕 tools/ 目录组织，每个芯片型号（AC632N、AC635N 等）都有独立的一套工具文件，其中最关键的是两个入口：

• download.bat — 一键式下载脚本，开发者编译出 sdk.elf 后双击即可完成"切段 → 合并 → 下载 → 打版本 → 生成升级包"的完整流程；
• isd_config.ini — 下载工具的配置文件，声明芯片型号、程序入口地址、PID/VID、下载通道（USB/串口）、uboot 的 SPI flash 参数、flash 空间分区策略以及量产工具最低版本要求。

设计意图上，这种"脚本 + 配置文件"分离的结构让开发者无需修改工具本身，即可通过编辑 .ini 适配不同方案（不同 flash、不同 IO、不同波特率），同时通过 TOOL_CONFIG 段强制产线工具版本与固件特性对齐，避免旧版烧写器因不认识新版分区/选项而产生坏片。

Architecture

下图展示烧写工具链的整体架构：左侧为 SDK 编译产物，中间为 tools/ 目录中的工具与配置，右侧为输出的固件产物及其消费方（量产烧写器 / OTA 升级）。

flowchart TD
    subgraph sg_Build["编译产物 (../output)"]
        ELF["sdk.elf"]
    end

    subgraph sg_Tools["tools 目录 (sdk/bsp/AC63xx/tools)"]
        OBJCOPY["llvm-objcopy.exe"]
        ISD["isd_download.exe"]
        FWADD["fw_add.exe"]
        UFWMAKER["ufw_maker.exe"]
        CFG["isd_config.ini"]
        UBOOT["uboot.boot / uboot_no_ota.boot"]
        LOADER["bd19loader.bin / br23loader.bin"]
        VER["script.ver"]
    end

    subgraph sg_Out["烧写产物"]
        APPBIN["app.bin"]
        FW["jl_isd.fw"]
        UFW["update.ufw"]
    end

    subgraph sg_Prod["产线工具"]
        T2["一拖二烧写器 (>= 2.25.8)"]
        T8["一拖八烧写器 (>= 3.1.7)"]
        BTBOX["蓝牙测试盒 (>= 1.2.7)"]
    end

    ELF -->|"objcopy 按段切出"| OBJCOPY
    OBJCOPY -->|"text/data/data_code 合并"| APPBIN
    ISD -->|"读取烧写参数"| CFG
    ISD -->|"加载引导/uboot"| LOADER
    ISD -->|"加载 uboot 镜像"| UBOOT
    ISD -->|"写入"| APPBIN
    ISD -->|"生成"| FW
    FWADD -->|"注入 script.ver"| FW
    UFWMAKER -->|"fw_to_ufw 转换"| FW
    UFWMAKER -->|"生成"| UFW
    FW -->|"量产烧写固件"| T2
    FW -->|"量产烧写固件"| T8
    UFW -->|"产测/升级"| BTBOX

各环节职责如下：

说明：download.bat 与 isd_config.ini 在 AC632N 与 AC635N 的 tools/ 目录下各有一份，二者流程一致，仅芯片型号、loader 与启动参数（-boot）不同。本文以 AC635N 为例详细讲解，AC632N 的差异在相应小节说明。

烧写流水线详解

1. ELF 段切分与 app.bin 合成

download.bat 的第一步是检查工具链与编译产物是否存在，然后调用 llvm-objcopy 将 sdk.elf 中的三个关键段分别导出为独立二进制：

if not exist %OBJCOPY% goto download
if not exist %ELFFILE% goto download

%OBJCOPY% -O binary -j .text %ELFFILE% ../output/text.bin
%OBJCOPY% -O binary -j .data %ELFFILE% ../output/data.bin
%OBJCOPY% -O binary -j .data_code %ELFFILE% ../output/data_code.bin


%OBJDUMP% -section-headers -address-mask=0x1ffffff %ELFFILE%
%OBJSIZEDUMP% -skip-zero -lite  -enable-dbg-info %ELFFILE%  >symbol_tbl.txt

copy /b ..\output\text.bin+..\output\data.bin+..\output\data_code.bin  ..\output\app.bin
copy ..\output\app.bin app.bin

Source: download.bat

设计意图：

• 按段切分再合并 而不是直接 objcopy -O binary sdk.elf app.bin，是为了精确控制三个段的链接顺序与边界，保证 .text（代码）、.data（已初始化数据）、.data_code（可放 RAM 执行的代码）在 flash 中的布局与链接脚本一致；
• -address-mask=0x1ffffff 使 llvm-objdump 输出 25 位地址掩码下的段头信息，配合 symbol_tbl.txt 符号表用于异常地址定位（对应 tools 目录中的 定位异常地址.bat）；
• if not exist 守卫让脚本在缺少工具链或未编译时跳过切段，直接进入下载分支，避免报错中断。

2. isd_download 下载与 .fw 生成

第二步调用 isd_download.exe 完成实际烧写，并生成固件包：

set output_base_name=jl_isd

isd_download.exe isd_config.ini -tonorflash -dev br23 -boot 0x12000 -div8 -wait 300 -output %output_base_name% -uboot uboot.boot -app app.bin -uboot_compress

Source: download.bat

命令行关键参数含义：

download.bat 中还注释了常用的扩展烧写命令，例如 -format vm（擦除 VM 区域）与 -format 0x3f0-2（从第 0x3f0 个 sector 起连续擦除 2 个 sector），用于产线定制化擦除。

3. 版本注入与升级包生成

@rem 添加配置脚本的版本信息到 FW 文件中
fw_add.exe -noenc -fw %output_base_name%.fw -add script.ver -out %output_base_name%.fw


ufw_maker.exe -fw_to_ufw %output_base_name%.fw
copy %output_base_name%.ufw update.ufw
del %output_base_name%.ufw

Source: download.bat

• fw_add.exe -noenc 将 script.ver 中的版本信息以明文方式追加进 .fw 文件（-noenc 表示不加密），产线工具/测试盒据此识别固件版本；
• ufw_maker.exe -fw_to_ufw 把 .fw 转换为 update.ufw 升级文件，并复制为 update.ufw 供 OTA 升级或产测使用；
• 使用 copy + del 而非 rename，保证工作目录中始终存在名为 update.ufw 的标准升级包。

isd_config.ini 配置解析

isd_config.ini 是下载工具的配置中心，按 [段] 组织，采用 KEY=VALUE; 语法（// 或 # 为注释）。文件头部注释明确说明：配置数据按照"长度 + 配置名字 + 数据"的方式存储，即工具解析时按固定格式读取，因此段内键的顺序不可随意调整（尤其 [SYS_CFG_PARAM] 段注释有"请勿随意调整顺序"的警告）。

[EXTRA_CFG_PARAM] — 芯片与产品标识

[EXTRA_CFG_PARAM]
NEW_FLASH_FS=YES;
FORCE_VM_ALIGN=YES;
CHIP_NAME=AC635N;//芯片型号
ENTRY=0x1E00100;//程序入口地址
PID=AC635N_GP;//长度16byte,示例：芯片封装_应用方向_方案名称
VID=0.01;
SDK_VERSION=AC635N_GP_V1.1.0;

Source: isd_config.ini

• ENTRY 是程序入口地址，与链接脚本一致，下载器据此校验镜像合法性；
• PID（产品标识，16 字节）与 VID（版本）用于产线区分不同方案固件，PID 命名规范为"芯片封装_应用方向_方案名称"（如 AC635N_GP）；
• NEW_FLASH_FS / FORCE_VM_ALIGN 控制新版 flash 文件系统与 VM 对齐策略，二者开启后要求烧写器与固件配套，这也是 TOOL_CONFIG 中版本门槛存在的原因之一。

[SYS_CFG_PARAM] — uboot 与硬件参数

[SYS_CFG_PARAM]
SPI=2_3_0_1;	#width_clk_mode_port;
RESET=PB01_00_0;	//port口_长按时间_有效电平
UPDATE_JUMP=0;      //是否支持升级过程中维持IO电平
VLVD=4;//VDDIO_LVD挡位
FLASH_BIN_CNT=6;
EOFFSET=1;//n*4k

Source: isd_config.ini

• SPI=width_clk_mode_port：uboot 识别片外 flash 的四元组，3 表示 data width 为 3 时 uboot 自动识别 2/4 线；port 决定片选/时钟/数据线端口组（A 口或 B 口），注释中给出了 A/B 端口的引脚映射；
• RESET：复位引脚与长按时间、有效电平配置（长按时间可选 00/01/02/04/08 秒，00 关闭长按复位）；
• UPDATE_JUMP：升级过程中是否维持 IO 电平，用于依赖 IO 口供电的方案；
• VLVD：VDDIO 低压检测挡位（0~7 对应 1.9V~2.6V）；
• FLASH_BIN_CNT、EOFFSET：flash 分区粒度（4K 对齐）相关的镜像计数与偏移。

[RESERVED_CONFIG] — flash 空间分区

[RESERVED_CONFIG]
PRCT_ADR=0;
PRCT_LEN=CODE_LEN;
PRCT_OPT=2;

VM_ADR=0;
VM_LEN=8K;
VM_OPT=1;

Source: isd_config.ini

每个区域由 XXX_ADR（起始地址，AUTO 表示由工具自动分配）、XXX_LEN（长度，CODE_LEN 表示等于代码长度）、XXX_OPT（操作属性）三个键描述。OPT 取值：0 = 下载代码时擦除该区域，1 = 下载时不操作该区域，2 = 下载时给该区域加上保护。上例中：

• PRCT（产品码区域）长度为代码长度且加保护（OPT=2），保证产品标识不被下载覆盖；
• VM（虚拟机参数区）固定 8K 且下载时不操作（OPT=1），避免重烧时丢失用户参数。

[TOOL_CONFIG] — 量产工具版本门槛

[TOOL_CONFIG]
1TO2_MIN_VER  = 2.25.8    # 一拖二烧写器最低版本
1TO8_MIN_VER  = 3.1.7    # 一拖八烧写器最低版本
BTBOX_MIN_VER = 1.2.7     # 蓝牙测试盒最低版本

Source: isd_config.ini

该段定义了支持本固件的产线工具最低版本，注释标明"请勿修改"。这是固件与工具之间的兼容性契约：当固件引入了新的 flash 分区选项、uboot 参数或加密方式时，通过提高门槛强制产线升级烧写器，防止旧工具烧出功能缺失或损坏的固件。[BURNER_CONFIG] SIZE=32 则定义了烧写器相关容量参数。

[CHIP_VERSION] 与下载通道

[CHIP_VERSION]
SUPPORTED_LIST=A,B,D

#DOWNLOAD_MODEL=SERIAL;//usb
DOWNLOAD_MODEL=usb;
SERIAL_DEVICE_NAME=JlVirtualJtagSerial;
SERIAL_BARD_RATE=1000000;

Source: isd_config.ini

• SUPPORTED_LIST 声明匹配的芯片版本，注释明确"请勿随意修改"；
• DOWNLOAD_MODEL=usb 选择 USB 下载通道（可切换为 SERIAL）；串口通道下还需配置虚拟串口设备名 JlVirtualJtagSerial、波特率（SERIAL_BARD_RATE / SERIAL_INIT_BAUD_RATE 9600 / LOADER_BAUD_RATE）、命令选项 SERIAL_CMD_OPT 及 BEFORE_LOADER_WAIT_TIME 等参数，用于兼容不同 JTAG/串口桥接硬件。

Core Flow — 从编译到可烧写产物的完整流程

flowchart TD
    Start([编译工程]) --> ELF["生成 sdk.elf"]
    ELF --> CHECK{"objcopy/elf 存在?"}
    CHECK -->|"否"| SKIP["跳过切段, 直接下载"]
    CHECK -->|"是"| SPLIT["objcopy 切出 text.bin / data.bin / data_code.bin"]
    SPLIT --> SYM["objdump/objsizedump 输出符号表 symbol_tbl.txt"]
    SYM --> MERGE["copy /b 合并三段 -> app.bin"]
    MERGE --> ISD["isd_download.exe 读取 isd_config.ini"]
    ISD --> LOAD["加载 loader 与芯片握手 (USB/串口)"]
    LOAD --> UBOOT_W["写入 uboot.boot (压缩)"]
    UBOOT_W --> APP_W["写入 app.bin 至片外 NOR Flash"]
    APP_W --> FW["生成 jl_isd.fw"]
    FW --> VER["fw_add.exe 注入 script.ver 版本"]
    VER --> UFW["ufw_maker.exe 转 update.ufw"]
    UFW --> PROD["量产烧写器/测试盒消费 .fw / .ufw"]
    SKIP --> ISD

各步骤说明（按调试/扩展时的排查顺序）：

1. 编译：工程编译产出 ../output/sdk.elf，是后续一切产物的唯一来源；
2. 守卫检查：download.bat 通过 if not exist 判断 llvm-objcopy 与 sdk.elf 是否存在，缺失时跳过切段直接进入 :download 标签，保证脚本在未编译或工具链未安装时也能给出明确的下载尝试而非中断；
3. 段切分与符号表：.text / .data / .data_code 分别导出，同时生成 symbol_tbl.txt 符号表，供 定位异常地址.bat 在产线异常时反查崩溃地址对应的函数；
4. 合并：copy /b 按二进制模式按 .text + .data + .data_code 顺序拼接成 app.bin，顺序必须与链接脚本的内存布局一致；
5. 下载：isd_download.exe 依据 isd_config.ini 先通过 loader（bd19loader.bin / br23loader.bin）与芯片建立通信，再写入压缩后的 uboot 与应用镜像；
6. 固件打包：jl_isd.fw 是量产烧写器直接使用的固件包，fw_add.exe 将 script.ver 版本信息附加进 .fw，使产线工具能校验/展示版本；
7. 升级包：ufw_maker.exe 将 .fw 转成 update.ufw，供 OTA 与蓝牙测试盒产测使用。

Usage Examples

示例 1：AC635N 一键烧写脚本（完整）

实际项目中，开发者编译完成后直接运行 sdk/bsp/AC635N/tools/download.bat 即可完成全部烧写与打包：

@echo off
Setlocal enabledelayedexpansion
@echo ********************************************************************************
@echo           SDK AC635N
@echo ********************************************************************************
@echo %date%

cd /d %~dp0

set OBJDUMP=C:\JL\pi32\bin\llvm-objdump.exe
set OBJCOPY=C:\JL\pi32\bin\llvm-objcopy.exe
set ELFFILE=../output/sdk.elf

set OBJSIZEDUMP=C:\JL\pi32\bin\llvm-objsizedump.exe

if not exist %OBJCOPY% goto download
if not exist %ELFFILE% goto download

%OBJCOPY% -O binary -j .text %ELFFILE% ../output/text.bin
%OBJCOPY% -O binary -j .data %ELFFILE% ../output/data.bin
%OBJCOPY% -O binary -j .data_code %ELFFILE% ../output/data_code.bin

%OBJDUMP% -section-headers -address-mask=0x1ffffff %ELFFILE%
%OBJSIZEDUMP% -skip-zero -lite  -enable-dbg-info %ELFFILE%  >symbol_tbl.txt

copy /b ..\output\text.bin+..\output\data.bin+..\output\data_code.bin  ..\output\app.bin
copy ..\output\app.bin app.bin

:download
set output_base_name=jl_isd
isd_download.exe isd_config.ini -tonorflash -dev br23 -boot 0x12000 -div8 -wait 300 -output %output_base_name% -uboot uboot.boot -app app.bin -uboot_compress

@rem 常用命令说明
@rem -format vm        //擦除VM 区域
@rem -format 0x3f0-2   //表示从第 0x3f0 个 sector 开始连续擦除 2 个 sector

fw_add.exe -noenc -fw %output_base_name%.fw -add script.ver -out %output_base_name%.fw

ufw_maker.exe -fw_to_ufw %output_base_name%.fw
copy %output_base_name%.ufw update.ufw
del %output_base_name%.ufw

Source: download.bat

示例 2：AC632N 与 AC635N 的芯片差异

对比两个型号的下载命令，可看出工具链如何通过命令行参数适配不同芯片：

:: AC632N —— loader 型号 bd19，boot 地址 0x2000，附加资源 p11_code.bin，下载后延时复位
isd_download.exe isd_config.ini -tonorflash -dev bd19 -boot 0x2000 -div8 -wait 300 -output %output_base_name% -uboot uboot.boot -app app.bin -res p11_code.bin -uboot_compress -reboot 500

:: AC635N —— loader 型号 br23，boot 地址 0x12000，无附加资源参数
isd_download.exe isd_config.ini -tonorflash -dev br23 -boot 0x12000 -div8 -wait 300 -output %output_base_name% -uboot uboot.boot -app app.bin -uboot_compress

Sources:

• AC632N download.bat
• AC635N download.bat

为什么存在差异？ -dev 决定使用哪个 loader（bd19loader.bin 对应 AC632N，br23loader.bin 对应 AC635N），-boot 是 uboot 在 flash 中的链接地址，-res 是 AC632N 特有的附加资源段。这些参数与各芯片的 isd_config.ini 中 CHIP_NAME、ENTRY 一一对应，修改芯片型号时必须同步修改脚本与配置文件，否则下载器握手或地址校验会失败。

示例 3：产线定制擦除

download.bat 中注释给出了产线常用的扩展命令，可直接追加在 isd_download.exe 命令行后：

@rem 擦除 VM 区域（保留用户参数区，用于返工重烧）
isd_download.exe isd_config.ini ... -format vm

@rem 从第 0x3f0 个 sector 开始连续擦除 2 个 sector
@rem 第一个参数支持 16 进制或 10 进制，第二个参数必须是 10 进制
isd_download.exe isd_config.ini ... -format 0x3f0-2

Source: download.bat

Configuration Options

下表汇总 isd_config.ini 中影响烧写行为的关键配置项（以 AC635N 为例，AC632N 仅芯片相关键不同）：

[EXTRA_CFG_PARAM]

[CHIP_VERSION] / 下载通道

[SYS_CFG_PARAM]（uboot 硬件参数，键顺序不可调整）

[RESERVED_CONFIG]（flash 分区，每组由 ADR/LEN/OPT 三元组构成）

OPT 取值：0 下载时擦除、1 下载时不操作、2 下载时加保护。

[TOOL_CONFIG]（量产工具版本门槛，勿修改）

Failure Modes, Edge Cases & Concurrency

以下故障与边界情况均能从仓库中的脚本与配置得到印证：

1. 工具链缺失 / 未编译

download.bat 对 %OBJCOPY% 与 %ELFFILE% 做了 if not exist 守卫。若 C:\JL\pi32\bin 工具链未安装或 sdk.elf 未生成，脚本会跳过切段直接进入 :download 分支——此时 app.bin 可能是旧文件或不存在，isd_download.exe 会因找不到 -app 指定的镜像而报错。排查顺序：先确认编译成功，再确认 JL pi32 工具链已安装。

2. 芯片型号不匹配

isd_config.ini 中 CHIP_NAME / SUPPORTED_LIST 与 download.bat 中 -dev（bd19/br23）、-boot 地址必须一致。误用会导致 loader 握手失败或入口地址校验失败。两个芯片的 tools/ 目录互相独立（AC632N/tools 与 AC635N/tools），不要跨目录混用脚本与配置文件。

3. 产线工具版本过旧

固件若启用了 NEW_FLASH_FS=YES、FORCE_VM_ALIGN=YES 等新特性，但产线烧写器版本低于 [TOOL_CONFIG] 中对应门槛，工具会拒绝烧写（或烧出非预期布局）。这是"固件 ↔ 工具"的强制契约，升级固件时须同步升级产线工具。

4. 分区保护与返工烧写

PRCT_OPT=2（产品码区加保护）与 VM_OPT=1（VM 区不操作）意味着普通下载不会覆盖产品码与用户参数。若返工需要彻底擦除，必须显式使用 -format vm 或 -format 0x3f0-2 等命令——直接重烧可能保留旧数据，导致"烧写成功但行为异常"的隐性故障。

5. 并发/多机烧写

量产场景由一拖二、一拖八烧写器并行烧写多片，BURNER_CONFIG SIZE 与版本门槛保证多路烧写的一致性；脚本本身是单机工具，不涉及并发控制。多片并行时的差异仅来自 flash 个体差异，由 uboot 的 SPI 自动识别（width=3 时自动识别 2/4 线）兜底。

6. 串口通道稳定性

切到 SERIAL 下载通道时，需保证 SERIAL_INIT_BAUD_RATE（9600）→ LOADER_BAUD_RATE（1M）的波特率切换时序与 BEFORE_LOADER_WAIT_TIME 匹配；虚拟串口名 JlVirtualJtagSerial 必须与驱动安装一致，否则握手失败。

Performance & Operational Notes

• 下载速率：-div8 分频与 -wait 300 超时是速度与兼容性的平衡点；对低规格 flash 或长走线产线，可适当降低时钟（保持 -div8）换取稳定性；
• 镜像压缩：-uboot_compress 压缩 uboot 镜像，减少下载数据量，缩短产线节拍；
• 符号表留档：symbol_tbl.txt 每次下载都会重新生成，配合 定位异常地址.bat（tools 目录内）可把产线异常死机 PC 值反查为函数名，是量产问题分析的关键一手资料；
• 产物规范：update.ufw 固定命名，供测试盒与 OTA 升级统一引用；.fw 文件名由 -output 基名决定（默认 jl_isd），产线脚本中可通过修改基名区分不同方案固件。

Extension Points

• 新增芯片型号：复制某型号的 tools/ 目录，修改 isd_config.ini 的 CHIP_NAME/ENTRY/PID 与 download.bat 的 -dev/-boot/loader 文件名，即可生成新的烧写套件；
• 自定义分区：在 [RESERVED_CONFIG] 按 XXX_ADR/_LEN/_OPT 三元组追加区域（如序列号区、校准数据区），OPT 决定下载时的擦除/保护行为；
• 定制下载动作：在 isd_download.exe 命令行追加 -format 参数实现产线擦除策略，无需改动工具本体；
• 版本契约管理：固件引入新烧写特性时，通过提高 [TOOL_CONFIG] 中对应工具的最低版本，强制产线工具链同步升级。

Related Links

• README.md — 生产烧写工具申请入口
• AC635N tools 目录
• AC632N tools 目录
• AC635N download.bat
• AC635N isd_config.ini
• AC632N download.bat
• 固件运行期行为（uboot 启动、OTA、VM 分区）：参见 SDK 开发文档 https://doc.zh-jieli.com/GPMCU/zh-cn/master/index.html