Bootloader 架构与芯片适配

本文介绍杰理（JL）系列芯片的 user boot 固件（uboot）整体架构、SDK 与 BootLoader 的对应关系、跨芯片适配机制、升级协议与参数传递设计，帮助开发者理解 boot 引导与升级链路的端到端工作方式。

Purpose and Scope

本页面覆盖以下内容：

• fw-Bootloader：JL 系列（AC63 等）user boot 固件的仓库结构、芯片系列与 BootLoader 工程映射、编译入口与产物（uboot.boot）。
• 升级协议：uboot 与上位机（PC 工具）之间的数据包格式、操作指令、回复状态（v1.1.2）。
• 参数传递机制：SDK 与 uboot 之间通过保留 RAM 传递的 UPDATA_PARM、boot_info_t、SYS_CFG 等结构体（定义于 boot.h）。
• OTA Loader 变体：ac791n-ota-loader 与 ac792n-ota-loader 的多种升级通道（USB、SD、UART、USB-HID）。

以下主题属于其他页面范围，本文仅作指引：具体的上位机工具使用方法请参见「uboot 升级使用说明」；具体芯片 SDK 的驱动细节属于各芯片 SDK 文档；fw-ota_loader 系列各通道的详细实现属于 OTA 页面。

Overview

杰理芯片的固件体系分为 app（应用）、uboot（user boot） 与 ota_loader（OTA 加载器） 三层。uboot 是上电后最先执行的用户引导程序，负责引导 app、并在需要时接管升级流程（串口 / USB-HID / USB / SD 卡等通道），把新的固件写入 Flash 对应区域。

本仓库中的 boot 工程按芯片系列拆分（bd19、br23、br25、br30、br34、sh54、sh55、wl82、br28 等），每个系列有独立的工程入口（.cbp）、链接脚本（.ld）与后处理打包脚本（post_build），最终产出一个统一的 uboot.boot 文件，由 SDK 下载工具烧录到 Flash 的 boot 分区。

升级协议采用「小端 + CRC-CCITT(XModem)」的帧格式，上位机与设备之间通过一组 JL_SU_CMD_* 指令完成设备初始化、鉴权、擦写与校验。uboot 与 SDK 之间则通过一段保留 RAM（0x1C000-0x80）交换升级类型、结果与私有参数，做到升级请求的「零耦合传递」。

Architecture

flowchart TD
    subgraph sg_Host["上位机 / 工具层"]
        PC["PC 升级工具<br/>(UART / USB-HID)"]
    end

    subgraph sg_Device["设备侧"]
        subgraph sg_Boot["uboot (user boot)"]
            UART["串口升级通道"]
            USBHID["USB-HID 升级通道"]
            PROTO["升级协议解析<br/>JL_SU_CMD_*"]
            FLASHOP["Flash 擦写 / 校验"]
        end

        subgraph sg_OTA["ota_loader (AC79)"]
            OTA_USB["usb_ota_update"]
            OTA_SD["sd_ota_update"]
            OTA_UART["uart_user_update"]
            OTA_HID["usb_hid_ota_update"]
        end

        RAM["保留 RAM<br/>0x1C000-0x80 参数区"]
        APP["app 固件 (SDK)"]
        FLASH[("SPI Flash<br/>boot 区 / app 区 / 升级区")]
    end

    PC -->|"0xAA 0x55 帧"| UART
    PC -->|"0xAA 0x55 帧"| USBHID
    UART --> PROTO
    USBHID --> PROTO
    PROTO --> FLASHOP
    FLASHOP --> FLASH
    APP -->|"写 UPDATA_PARM"| RAM
    RAM -->|"读升级参数"| UART
    RAM -->|"读升级参数"| USBHID
    OTA_USB --> FLASH
    OTA_SD --> FLASH
    OTA_UART --> FLASH
    OTA_HID --> FLASH
    FLASH --> APP

架构说明：

• 上位机工具通过 UART 或 USB-HID 与设备通信，帧头固定为 0xAA 0x55，所有多字节数据按小端排列，帧尾带 CRC16（CRC-CCITT/XModem）。
• uboot 内部按「通道 → 协议解析 → Flash 操作」分层：UART/USB-HID 通道负责收发字节流，协议层解析 JL_SU_CMD_* 指令并回复 rsp_status，Flash 层负责擦除、写入与 CRC 校验。
• SDK（app）与 uboot 的解耦通过保留 RAM 完成：SDK 在预留的 0x1C000-0x80 处写入 UPDATA_PARM（含 parm_type 升级类型、file_patch 文件路径、ota_addr 升级地址等），uboot 启动后读取该结构体判断是否进入升级模式、走哪条升级通道。
• AC79 系列的 ac792n-ota-loader 在 uboot 之上进一步拆分为多个独立通道工程（usb_ota_update、sd_ota_update、uart_user_update、usb_hid_ota_update、usb_sec_ota_update、sd_sec_ota_update），每个工程独立产出 uboot_lz4.exe / uboot_package.exe 镜像，体现了「同一协议、多通道复用」的架构意图。

芯片系列与 BootLoader 对应关系

fw-Bootloader 面向多系列芯片，仓库 README 给出了 SDK 型号与 BootLoader 工程名的权威映射表：

来源：fw-Bootloader/README.md

设计意图： 不同芯片系列在 Flash 控制器（SFC）、时钟/振荡器配置、引脚复用和硬件加密能力上存在差异，因此 boot 无法「一套代码走天下」。杰理的做法是每颗芯片系列维护一份 boot 工程（cpu/<chip>/<chip>_uboot.cbp），共享同一套协议与上层逻辑，仅在芯片相关层（Flash、时钟、引脚、密钥）做替换，这正是「芯片适配」这一主题的核心。

工程入口与编译

README 明确说明：例如 SDK 型号为 AC701N 时，使用 user_boot/cpu/br28/br28_uboot.cbp 作为工程入口。编译环境与标准 SDK 一致，支持 Codeblocks 与 Make：

• Codeblocks 编译：进入对应工程目录，找到后缀为 .cbp 的文件，双击打开即可编译。
• 产物：生成 uboot.boot，需添加到原 SDK 下载目录中调试（具体流程见 uboot升级使用说明）。

来源：fw-Bootloader/README.md

post_build 与链接脚本（以 AC791N/wl82 为例）

ac791n-ota-loader 的 uboot/apps/post_build/wl82/ 目录展示了 boot 产物的后处理产物链：

• uboot.ld：常规链接脚本；
• uboot_uart_update.ld：串口升级专用链接脚本（分区/地址布局不同）；
• uboot_package.exe / uboot.exe：打包与原始镜像。

这些文件的存在说明同一颗芯片会按升级通道产生不同的布局变体，链接脚本是芯片 Flash 分区布局适配的最直接载体。

来源：ac791n-ota-loader/uboot/apps/post_build/wl82/

SDK ↔ uboot 参数传递机制

升级标志与保留 RAM

//updata_flag
#define UPDATA_FLAG_ADDR		((void *)(0x1C000-0x80))		/* (0x1C000-0x80)-0x1C000:		reserved_ram for updata */
#define UPDATE_PRIV_PARAM_LEN	32
#define UPDATA_MAGIC			(0x5A00)		//防止CRC == 0 的情况

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

UPDATA_FLAG_ADDR 指向 0x1C000-0x80 到 0x1C000 的保留 RAM 段，SDK 把升级请求写入此处，uboot 复位后从这里读取。UPDATA_MAGIC = 0x5A00 的设计意图是防止 CRC 恰好为 0——用魔数区分「无升级请求」与「有效请求」，避免校验字段全零时误判。

升级结果枚举

typedef enum {
    UPDATA_NON = UPDATA_MAGIC,
    UPDATA_READY,
    UPDATA_SUCCESSFULLY,
    UPDATA_PARM_ERR,
    UPDATA_DEV_ERR,
    UPDATA_KEY_ERR,
} UPDATA_RESULT_TO_SDK;

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

该枚举是 uboot 回写 SDK 的结果通道：UPDATA_READY 表示已就绪、UPDATA_SUCCESSFULLY 表示升级成功、UPDATA_PARM_ERR/UPDATA_DEV_ERR/UPDATA_KEY_ERR 分别表示参数错误、设备错误、密钥错误。SDK 侧在 app 重启后读取该值即可得知上次升级结果。

升级类型枚举

typedef enum {
    USB_UPDATA = UPDATA_MAGIC,		//0x5A00
    SD0_UPDATA,						//0x5A01
    SD1_UPDATA,
    PC_UPDATA,
    UART_UPDATA,
    BT_UPDATA,
    BLE_APP_UPDATA,
    SPP_APP_UPDATA,
    DUAL_BANK_UPDATA,
    BLE_TEST_UPDATA,
    NORFLASH_UPDATA,
    // BLE_UPDATA,
    USER_NORFLASH_UFW_UPDATA,
    USER_LC_FLASH_UFW_UPDATA,
    USB_HID_UPDATA,
    DEV_NORFLASH_UFW_UPDATA,
    NET_UFW_UPDATA,

    NON_DEV_UPDATA = 0xFFFF,
} UPDATA_TYPE;

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

UPDATA_TYPE 覆盖了 USB、SD 卡、PC、UART、蓝牙（BT/SPP/BLE）、双 Bank、NOR Flash、USB-HID、网络（NET）等全部升级来源。枚举值从 0x5A00 起递增，与 UPDATA_MAGIC 同源，保证「非 0xFFFF 即为有效类型」，NON_DEV_UPDATA = 0xFFFF 用于表示无效/非设备升级。

核心结构体：UPDATA_PARM、SYS_CFG 与 boot_info_t

UPDATA_PARM（升级参数，V2 版本）

#if FLASH_FRAMEWORK_VERSION_V2_EN
#define UPDATE_PARAM_MAGIC		0x5441
typedef struct _UPDATA_PARM {
    u16 parm_crc;
    u16 parm_type;				//UPDATA_TYPE:sdk pass parm to uboot
    u16 parm_result;			//UPDATA_TYPE:uboot return result to sdk
    u16 magic;
    u8 	file_patch[32];
    u8 	parm_priv[32];
    u32 ota_addr;
    u16	ext_arg_len;
    u16 ext_arg_crc;
} UPDATA_PARM;

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

字段语义与设计意图：

该结构体的双向性（parm_type 由 SDK 写入、parm_result 由 uboot 回写）是 SDK 与 boot 解耦的关键：双方只依赖一块固定 RAM 地址和固定布局，不依赖函数调用或中断，天然跨二进制边界兼容。V1 版本（FLASH_FRAMEWORK_VERSION_V1_EN）没有 ota_addr 与扩展参数字段，反映了框架从「按文件名升级」演进到「可指定地址升级」的能力扩展。

SYS_CFG（系统配置）

struct SYS_CFG {
    u32 sdtap: 8;
    u32 osc_type: 4;
    u32 osc_hc_en: 1;
    u32 osc_1pin_en: 1;
    u32 lsb_div: 4;
    u32 res: 4;

    u32 osc_freq;
    u32 sys_clk;

    char uttx[8];
    char utrx[8];
    u32 utbaud;

    char port_output[8];
    char port_input[8];

    char reset_pin[4];
};

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

SYS_CFG 是芯片适配的核心载体：位域段（sdtap/osc_type/osc_hc_en/osc_1pin_en/lsb_div）描述晶振类型与时钟树；osc_freq/sys_clk 描述频率；uttx/utrx/utbaud 是 UART 升级通道的引脚与波特率；port_output/port_input/reset_pin 描述 IO 与复位引脚。uboot 通过该结构体即可在不改代码的情况下适配不同芯片的硬件差异——这也是「芯片适配」在数据结构层面的落点。

boot_info_t（引导信息）

struct boot_info_t {
    u32 entry_addr;
    u32 sfc_base_addr;

    struct SYS_CFG *sys_cfg;

    u16 chip_key;
    u16 res;//同步结构体和uboot一致
    u32 version;
    void *arch_info;
};

来源：ac791n-ota-loader/uboot/include_lib/logic/boot.h

boot_info_t 是 uboot 引导 app 时交给 SDK 的「交接单」：entry_addr 为 app 入口地址，sfc_base_addr 为 SPI Flash 控制器基地址，sys_cfg 指向系统配置，chip_key 为芯片密钥（升级鉴权用），version 为 boot 版本，arch_info 为架构相关扩展信息。res 字段注释「同步结构体和uboot一致」强调该结构体布局必须与 uboot 侧严格同步——任何字段顺序调整都会破坏跨二进制兼容。

OTA Loader 变体与多通道布局

仓库中的 AC79 系列 OTA 通道工程（ac792n-ota-loader）展示了同一协议在多个通道上的落地形态：

来源：ac792n-ota-loader

每个通道工程独立产出 uboot_lz4.exe（LZ4 压缩镜像）与 uboot_package.exe（打包镜像），位于 cpu/wl83/output/。sec 变体的存在说明安全升级（带密钥校验的镜像）与普通升级共用同一协议框架，仅在镜像鉴权环节叠加密钥检查（对应 UPDATA_KEY_ERR 与 chip_key）。

升级协议（v1.1.2）

数据包格式

协议文档定义的帧结构如下（多字节小端，CRC16 采用 CRC-CCITT/XModem，回复使用相同指令）：

• syncdata0/syncdata1：固定同步头 0xAA 0x55；
• cmd_len：cmd + rsp_status + 数据 的长度；
• cmd：操作指令；
• rsp_status：回复状态；
• crc16：整包（除 CRC 自身外）的 CRC-CCITT(XModem) 校验。

来源：uboot升级协议流程v1.1.2.md

回复状态

来源：uboot升级协议流程v1.1.2.md

操作指令

JL_SU_CMD_DEVICE_INIT (0xC0)——设备初始化，获取指定区域的地址、长度等信息。

• 上位机 → 设备参数：file_name[16]（区域名）+ mode（读取模式，app_dir_head 与 uboot_zone 均置 0）；
• 设备 → 上位机回复参数：upgrade_addr（区域地址）、upgrade_len（区域长度）、upgrade_eoffset（设备偏移）、flash_alignsize（Flash 对齐长度）。

struct {
    u8 file_name[16];
    u8 mode;
} init;

struct {
    u32 upgrade_addr;
    u32 upgrade_len;
    u32 upgrade_eoffset;
    u32 flash_alignsize;
} init;

来源：uboot升级协议流程v1.1.2.md

JL_SU_CMD_DEVICE_CHECK (0xC1)——获取设备的 PID/VID/sdkID。

• 上位机 → 设备参数：sdk_id（上位机 SDK ID）；
• 设备校验后回复设备侧 sdk_id 等身份信息，用于防止跨 SDK 版本误刷（对应 JL_SU_CMD_SDK_ID_ERROR）。

来源：uboot升级协议流程v1.1.2.md

协议设计意图：DEVICE_INIT 让上位机在写任何数据之前先拿到 Flash 区域布局与对齐要求（flash_alignsize），从而正确构造擦写命令；DEVICE_CHECK 则在上位机与设备之间建立身份互认，避免把 A SDK 的固件刷进 B SDK 的设备。

Core Flow：一次升级的端到端流程

sequenceDiagram
    participant SDK as app (SDK)
    participant RAM as 保留RAM 0x1C000-0x80
    participant UBOOT as uboot (user boot)
    participant PC as PC 升级工具
    participant FLASH as SPI Flash

    SDK->>RAM: 写 UPDATA_PARM (parm_type/parm_result/file_patch)
    SDK->>UBOOT: 复位/跳转 boot
    UBOOT->>RAM: 读 UPDATA_PARM + 校验 magic/CRC
    alt 校验通过 (进入升级模式)
        UBOOT->>PC: 等待 0xAA 0x55 帧
        PC->>UBOOT: JL_SU_CMD_DEVICE_INIT (0xC0)
        UBOOT->>FLASH: 读取区域布局 (addr/len/align)
        UBOOT-->>PC: 回复 upgrade_addr/len/eoffset/alignsize
        PC->>UBOOT: JL_SU_CMD_DEVICE_CHECK (0xC1, sdk_id)
        UBOOT-->>PC: 回复身份信息 (rsp_status)
        PC->>UBOOT: 数据下发 (分帧 + CRC16)
        UBOOT->>FLASH: 擦除/写入/回读校验
        UBOOT-->>PC: JL_SU_CMD_SUSS 或错误状态
        UBOOT->>RAM: 写 parm_result = UPDATA_SUCCESSFULLY / ERROR
        UBOOT->>FLASH: 引导 app
    else 校验失败 (无升级请求)
        UBOOT->>FLASH: 直接引导 app (entry_addr)
    end
    FLASH->>SDK: app 启动, 读 parm_result 上报升级结果

流程要点：

1. 请求注入：app 在复位前把 UPDATA_PARM 写入保留 RAM，parm_type 决定升级通道，file_patch/ota_addr 决定目标位置。
2. 模式仲裁：uboot 启动时校验 magic 与 parm_crc，只有校验通过才进入升级模式，否则走正常引导路径——该设计保证升级请求丢失或损坏时系统仍能正常启动。
3. 协议握手：上位机先 DEVICE_INIT 拿布局，再 DEVICE_CHECK 验身份，之后才进入数据下发；每帧带 CRC16，设备以 rsp_status 反馈，实现「发一帧、验一帧、回一帧」的可靠传输。
4. 结果回写：升级结束后 uboot 把 parm_result 写回保留 RAM，app 重启后可读取并上报，形成完整的闭环追踪。

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

失败模式

边界情况

• Flash 对齐：DEVICE_INIT 回复中的 flash_alignsize 要求上位机按对齐长度构造擦写单元，否则可能出现跨页写坏。协议把对齐信息显式交给上位机，而非在设备端猜测。
• 多字节序：协议统一小端（低字节在前），跨工具/固件版本都必须遵守，避免大小端不一致导致 upgrade_addr/upgrade_len 解析错误。
• 结构体布局同步：boot_info_t 的 res 字段注释强调「同步结构体和uboot一致」——SDK 与 uboot 由不同仓库/版本维护，布局漂移会直接导致引导崩溃，因此该结构体是兼容性红线。

并发与一致性

boot 阶段为单线程裸机环境，不存在多线程竞争；真正的并发风险在升级中断电：擦写中途掉电会导致半写状态。协议通过「先回读校验、成功后回写 parm_result」的次序保证一致性——parm_result 只有在整包数据落盘并校验通过后才置为 UPDATA_SUCCESSFULLY，掉电后 app 读到的是旧值（未成功），可触发重试机制。OTA 布局（upgrade_eoffset 设备偏移）通常将升级数据写到独立区域，避免与运行中的 app 重叠。

性能与运维注意事项

• UART 波特率：SYS_CFG.utbaud 决定串口升级速率；uttx/utrx 引脚按芯片复用配置，更换芯片时需同步修改 SYS_CFG，这是「芯片适配」最常见的运维动作。
• 镜像压缩：AC79 系列产出 uboot_lz4.exe（LZ4 压缩），压缩镜像可显著缩短串口/低速通道的传输时间；上位机需先解压再按协议下发。
• 升级耗时：主要瓶颈在 Flash 擦写与传输，flash_alignsize 越大，单次擦除的浪费越多，协议要求上位机按对齐值规划数据块以降低无效擦写。
• 工具链一致性：README 特别提示——如遇「uboot.boot 数据的 CRC 校验错误 / 生成失败，无效的 F 文件」类错误，需要更新最新工具（杰理工具链下载），说明 boot 产物与打包工具存在版本耦合。
• 充分测试：README 免责声明强调「user boot 支持多系列芯片开发，鉴于 boot 的特殊性，请务必进行充分测试」——boot 处于上电首条路径，任何缺陷都会直接导致设备变砖。

扩展点

1. 新增芯片系列：在 user_boot/cpu/ 下新增 <chip>/<chip>_uboot.cbp 工程，参照现有系列（如 br28）复制结构，主要改动点为链接脚本（Flash 布局）、SYS_CFG 默认值（时钟/引脚/波特率）与 Flash 驱动。
2. 新增升级通道：在 UPDATA_TYPE 枚举中追加类型值，同时在 uboot 的通道分发处挂接新的收发实现；parm_type 的值域由 SDK 与 uboot 双方约定，属于二进制协议的一部分，新增枚举需同步两边。
3. 私有参数扩展：parm_priv[32] 与 V2 的 ext_arg_len/ext_arg_crc 提供扩展参数挂载点，可在不改动主结构体的情况下携带自定义升级元数据（如加密盐、固件版本号）。
4. 安全升级：usb_sec_ota_update/sd_sec_ota_update 展示了在既有协议上叠加密钥校验（对应 chip_key 与 UPDATA_KEY_ERR）的模式，普通通道可向安全通道演进而无需更换协议帧。

配置选项汇总

芯片适配配置（SYS_CFG 字段）

升级参数配置（UPDATA_PARM 字段）

编译与工具配置

API Reference（boot.h 关键类型）

UPDATA_PARM

SDK 与 uboot 之间的升级参数结构体（V2 见上）。parm_type（SDK→uboot 输入）与 parm_result（uboot→SDK 输出）构成双向接口。

字段约束：

• parm_crc：须覆盖整个结构体的 CRC16，防止 RAM 内容损坏触发误升级；
• magic：V2 为 0x5441，与 UPDATA_MAGIC (0x5A00) 不同，用于区分参数区版本。

UPDATA_RESULT_TO_SDK（enum）

UPDATA_NON / UPDATA_READY / UPDATA_SUCCESSFULLY / UPDATA_PARM_ERR / UPDATA_DEV_ERR / UPDATA_KEY_ERR——app 重启后通过 parm_result 读取。

UPDATA_TYPE（enum）

从 0x5A00（USB_UPDATA）到 NET_UFW_UPDATA 的 16 种升级来源，NON_DEV_UPDATA = 0xFFFF 表示无效。

SYS_CFG

芯片系统配置（时钟、晶振、串口引脚/波特率、IO、复位引脚），由 uboot 与 SDK 共享，见上表。

boot_info_t

uboot 引导 app 时的交接结构：entry_addr（app 入口）、sfc_base_addr（Flash 控制器基址）、sys_cfg（系统配置指针）、chip_key（芯片密钥）、version（boot 版本）、arch_info（架构扩展信息）。布局必须与 uboot 严格同步。

Related Links

• fw-Bootloader README（SDK 与 BootLoader 对应表、编译说明）
• uboot 升级使用说明 v1.1.2（上位机操作流程）
• uboot 升级协议流程 v1.1.2（数据包格式与指令定义）
• boot.h（UPDATA_PARM / SYS_CFG / boot_info_t 定义）
• ac791n-ota-loader（AC791N/wl82 OTA 工程与链接脚本）
• ac792n-ota-loader（AC792N 多通道 OTA 工程）
• 仓库根 README：README.md / README.en.md