编译环境与快速开始

本文档介绍 gitee-repos-Other 仓库中 JL（杰理）系列定制 Bootloader（fw-Bootloader）与 OTA Loader（ac791n-ota-loader / ac792n-ota-loader）的编译环境搭建方法与快速开始流程，帮助开发者从拿到仓库代码到生成 uboot.boot 并进入硬件调试的全过程。

Purpose and Scope

本页面向首次接触该仓库的嵌入式开发者，覆盖以下内容：

仓库整体结构与各子项目的定位
工具链要求（与 JL 标准 SDK 一致）及常见工具链错误的处理方法
SDK 芯片型号与 BootLoader 编译入口的对应关系
使用 Codeblock 与 Make 两种方式编译工程的步骤
生成的 uboot.boot 如何进入原 SDK 下载目录进行硬件调试

以下主题属于兄弟页面，不在本页展开：

uboot 升级使用说明：见 fw-Bootloader/doc/uboot升级使用说明v1.1.2.md
uboot 升级协议流程：见 fw-Bootloader/doc/uboot升级协议流程v1.1.2.md
OTA Loader 具体实现：ac791n-ota-loader / ac792n-ota-loader 子项目为独立的 ota_loader 固件，其 README 仅给出项目定位，无更多编译细节（见 ac792n-ota-loader/README.md、ac791n-ota-loader/README.md）

Overview

gitee-repos-Other 是杰理（Jieli）仓库整理集合中"其他"分类的聚合仓库，根 README 明确指出其包含两个子项目：

目录	说明
fw-Bootloader	JL 系列定制 Bootloader（user boot）
ac792n-ota-loader	JL AC792N 系列定制 ota-loader

其中 fw-Bootloader 是编译与快速开始的主要对象。它包含 user boot release 版本代码，线上/线下支持同步发布，支持用户自定义串口升级和 usb_hid 升级两种方式。其 README 特别强调：

本工程提供的例子，需要结合对应命名规则的库文件（lib.a）和对应的子仓库进行编译。

也就是说，fw-Bootloader 仓库本身并不包含全部编译依赖——必须搭配芯片 SDK 中按命名规则提供的静态库（lib.a）以及对应子仓库才能完成编译。这是理解整个编译流程的关键前提：仓库代码只是工程的源码部分，编译环境与库文件来自 JL 标准 SDK。

ac791n-ota-loader 定位为 AC79 系列的定制 ota_loader，ac792n-ota-loader 定位为 AC792N 芯片的 OTA LOADER；二者 README 信息量极少，本页仅将其作为仓库结构的一部分介绍，不深入其编译细节。

Architecture

下图展示仓库结构、编译依赖关系与产物流转：

flowchart TD
    subgraph sg_Repo["gitee-repos-Other 仓库"]
        subgraph sg_Boot["fw-Bootloader（JL 系列 user boot）"]
            Boot["user boot 固件工程<br/>user_boot/cpu/&lt;系列&gt;/&lt;系列&gt;_uboot.cbp"]
            Docs["doc/ 升级说明与协议文档"]
            Tools["update_tools/ 串口升级工具"]
        end
        subgraph sg_Ota["OTA Loader 子项目"]
            Ota792["ac792n-ota-loader（AC792N）"]
            Ota791["ac791n-ota-loader（AC79 系列）"]
        end
    end
    Toolchain["JL 标准 SDK 工具链<br/>Codeblock / Make"]
    Libs["按命名规则的库文件 lib.a<br/>+ 对应子仓库"]

    Boot --> Toolchain
    Boot --> Libs
    Toolchain --> Bin["uboot.boot"]
    Docs --> Boot
    Tools --> Boot
    Ota792 --> Toolchain
    Ota791 --> Toolchain

架构说明：

fw-Bootloader 是编译的主工程，其源码按芯片系列组织在 user_boot/cpu/<系列>/ 目录下，每个系列对应一个 *_uboot.cbp 工程文件（Codeblock 工程）。
工具链与 JL 标准 SDK 完全一致，不引入额外编译器；编译方式支持 Codeblock 与 Make 两种。
库文件依赖：示例工程依赖按命名规则提供的 lib.a 与对应子仓库，这是 README 中唯一明确声明的外部依赖。
产物：编译最终生成 uboot.boot，需要复制到原 SDK 的下载目录中进行调试。
OTA Loader 子项目独立维护，作为同一仓库体系下的兄弟固件存在。

工具链与编译环境

fw-Bootloader/README.md 的"工具链"一节明确说明：

使用的工具链与标准SDK一致。

这意味着开发者不需要为 Bootloader 单独安装编译器，只要已搭建好对应芯片 SDK 的编译环境即可直接编译本工程。README 同时给出了一个典型的工具链问题及其处理方式：当编译时出现如下错误时，说明本地工具版本过旧，需要更新到最新工具：

《"错误: uboot.boot数据的CRC校验错误"错误:生成失败，无效的F文件，请重新选择系统找不到指定的文件。》

此类错误的根因是工具链与固件格式不匹配：uboot.boot 的 CRC 校验逻辑由工具链生成，旧工具无法正确生成新格式的 F 文件（中间文件），从而导致校验失败。官方修复途径为更新工具：

https://doc.zh-jieli.com/Tools/zh-cn/other_info/index.html

Source: fw-Bootloader/README.md

环境搭建要点归纳：

项	要求
编译器	与 JL 标准 SDK 一致，无需额外安装
编译方式	Codeblock 或 Make，二选一
外部依赖	按命名规则的库文件 `lib.a` + 对应子仓库
工具版本	出现 CRC 校验错误时须更新至官方最新工具

SDK 与 BootLoader 系列对应关系

由于不同芯片 SDK 对应不同的 BootLoader 工程，快速开始的第一步就是根据 SDK 型号找到正确的编译入口。README 提供了完整的对应表：

| SDK型号    | BootLoader对应  |
|  ----      | ----        |
| AC693N/AC693X  | bd19 |
| AC635N/AC695X/AC695N  | br23 |
| AC636N/AC696X/AC696N  | br25 |
| AC697N/AC897N  | br30 |
| AC638N/AD698N  | br34 |
| AD14N/AD104N   | sh54 |
| AD15N/AD105N   | sh55 |
| AC791N         | wl82 |
| AC701N         | br28 |

Source: fw-Bootloader/README.md

README 给出的示例说明了如何使用该表：

例如: SDK型号使用的是AC701N, 使用user_boot\cpu\br28\br28_uboot.cbp作为工程入口。

Source: fw-Bootloader/README.md

设计意图： 将 SDK 型号与 BootLoader 编译入口解耦——同一个 fw-Bootloader 仓库容纳了多代芯片（AC63 系列起，涵盖 AC69/AC69X、AC63/AC696X、AC79、AD 系列等）的 user boot 源码，通过 user_boot/cpu/<系列>/ 目录隔离各芯片的差异。开发者只需确认 SDK 型号，即可按表定位到唯一正确的 .cbp 工程文件，避免在多个工程间误选。wl82（AC791N）的存在也印证了根 README 中"fw-Bootloader"与 AC79 系列 OTA loader 在仓库中的并列关系。

编译工程

README 的"编译工程"一节说明了两种编译方式：

SDK 同时支持Codeblock 和 Make 编译环境，请确保编译前已经搭建好编译环境，
Codeblock 编译 : 进入对应的工程目录并找到后缀为 .cbp 的文件, 双击打开便可进行编译.

Source: fw-Bootloader/README.md

Codeblock 方式是最直接的路径：定位到对应系列的工程目录（如 user_boot/cpu/br28/），双击 br28_uboot.cbp，在 Codeblock 中即可完成编译。Make 方式适用于习惯命令行/脚本化构建的流水线场景，但 README 未给出具体 Make 命令，仅声明其受支持——这与标准 SDK 的构建体系保持一致。

编译前置条件（按 README 顺序核对）：

已安装与标准 SDK 一致的工具链
已获取按命名规则匹配的库文件 lib.a 与对应子仓库
已根据 SDK 型号确认正确的 .cbp 工程入口
工具链版本足够新（否则出现 uboot.boot数据的CRC校验错误）

核心流程：从源码到硬件调试

将 README 中的信息整合为一条完整的端到端流程。下图展示了从确认芯片型号到完成硬件调试的决策路径：

flowchart TD
    Start([开始]) --> Step1["确认 SDK 芯片型号<br/>例如 AC701N"]
    Step1 --> Step2["查表定位 BootLoader 系列<br/>AC701N → br28"]
    Step2 --> Step3["进入对应工程目录<br/>user_boot/cpu/br28/br28_uboot.cbp"]
    Step3 --> Step4{"选择编译方式"}
    Step4 -->|"Codeblock"| CB["双击 .cbp 打开工程<br/>在 Codeblock 中编译"]
    Step4 -->|"Make"| MK["使用 Make 环境编译"]
    CB --> Check{"出现 CRC 校验错误?<br/>（uboot.boot数据的CRC校验错误）"}
    MK --> Check
    Check -->|"是"| Update["更新最新工具链<br/>doc.zh-jieli.com/Tools/zh-cn/other_info"]
    Update --> Step3
    Check -->|"否"| Out["生成 uboot.boot"]
    Out --> HW["添加到原 SDK 下载目录"]
    HW --> End([硬件调试])

逐步说明：

确认型号：编译入口完全由 SDK 芯片型号决定，必须先明确目标芯片（如 AC701N）。
查表定位：使用"SDK与BootLoader系列对应说明"表，将型号映射到唯一的系列代号（br28 等）。
选择工程：进入 user_boot/cpu/<系列>/，打开 <系列>_uboot.cbp。README 以 br28_uboot.cbp 为例。
编译：Codeblock 或 Make 二选一；两者共享同一套工具链。
错误处理：若出现 uboot.boot数据的CRC校验错误 或 生成失败，无效的F文件，说明工具链过旧，需更新官方工具后重新编译——这是 README 中唯一显式给出的故障分支。
烧录调试：将生成的 uboot.boot 添加到原 SDK 下载目录中，调试流程详见 uboot 升级使用说明。

硬件环境与下载调试

README 的"硬件环境"一节指出：

与标准SDK一致，生成的uboot.boot要添加到原SDK下载目录调试，流程见 uboot升级使用说明

Source: fw-Bootloader/README.md

要点解读：

硬件环境与标准 SDK 一致：不需要为 Bootloader 准备单独的下载器或串口工具链，复用 SDK 已有的下载环境即可。
产物集成方式：uboot.boot 不是独立烧录的镜像，而是作为原 SDK 下载目录中的一部分参与整体下载流程。也就是说，Bootloader 升级发生在 SDK 的下载/升级框架内，这解释了为什么需要"结合对应命名规则的库文件（lib.a）和对应的子仓库进行编译"——Bootloader 与 SDK 侧代码是同一套构建体系的两半。
升级方式：本工程支持串口升级与 usb_hid 升级两种自定义升级路径；串口侧配套工具位于 fw-Bootloader/update_tools/win-uart/（Windows UART 工具）。

使用示例

以下示例全部提取自仓库实际源码（Markdown 文档），展示快速开始中的关键操作。

示例 1：定位编译入口（查表 → 打开工程）

这是 README 提供的标准快速开始示例——先按 SDK 型号查表，再进入对应工程目录：

| SDK型号    | BootLoader对应  |
|  ----      | ----        |
| AC693N/AC693X  | bd19 |
| AC635N/AC695X/AC695N  | br23 |
| AC636N/AC696X/AC696N  | br25 |
| AC697N/AC897N  | br30 |
| AC638N/AD698N  | br34 |
| AD14N/AD104N   | sh54 |
| AD15N/AD105N   | sh55 |
| AC791N         | wl82 |
| AC701N         | br28 |

例如: SDK型号使用的是AC701N, 使用user_boot\cpu\br28\br28_uboot.cbp作为工程入口。

Sources:
fw-Bootloader/README.md

示例 2：工具链故障的判定与修复

当编译报错时，README 给出的判定依据与修复动作如下（错误消息为原文，路径为官方工具文档）：

使用的工具链与标准SDK一致。如遇到《"错误: uboot.boot数据的CRC校验错误"错误:生成失败，
无效的F文件，请重新选择系统找不到指定的文件。》这样的错误，需要更新最新的工具：
https://doc.zh-jieli.com/Tools/zh-cn/other_info/index.html

Source: fw-Bootloader/README.md

示例 3：编译方式选择

README 声明的两种编译方式（注意需先搭建好编译环境）：

SDK 同时支持Codeblock 和 Make 编译环境，请确保编译前已经搭建好编译环境，

* Codeblock 编译 : 进入对应的工程目录并找到后缀为 `.cbp` 的文件, 双击打开便可进行编译.

Source: fw-Bootloader/README.md

示例 4：仓库整体结构

根 README 定义了本仓库的边界——它只是杰理"其他"分类的聚合仓库，具体内容在子目录中：

| 目录 | 说明 |
|------|------|
| fw-Bootloader | JL 系列定制 Bootloader |
| ac792n-ota-loader | JL AC792N系列定制 ota-loader |

Source: README.md

配置选项

本仓库的"配置"主要体现在芯片系列与工程入口的映射上，这是快速开始前必须确定的核心参数：

配置项	取值（系列代号）	说明
bd19	AC693N / AC693X	BootLoader 工程目录 `user_boot/cpu/bd19/`
br23	AC635N / AC695X / AC695N	BootLoader 工程目录 `user_boot/cpu/br23/`
br25	AC636N / AC696X / AC696N	BootLoader 工程目录 `user_boot/cpu/br25/`
br30	AC697N / AC897N	BootLoader 工程目录 `user_boot/cpu/br30/`
br34	AC638N / AD698N	BootLoader 工程目录 `user_boot/cpu/br34/`
sh54	AD14N / AD104N	BootLoader 工程目录 `user_boot/cpu/sh54/`
sh55	AD15N / AD105N	BootLoader 工程目录 `user_boot/cpu/sh55/`
wl82	AC791N	BootLoader 工程目录 `user_boot/cpu/wl82/`
br28	AC701N	BootLoader 工程目录 `user_boot/cpu/br28/`（README 示例）

其余环境类配置（工具链、编译方式、外部依赖）已在"工具链与编译环境"一节列出，此处不重复。

故障模式、边界情况与并发注意

以下内容全部来自 README 的显式声明或合理推断（推断处已标注）：

已知故障：工具链过旧导致的 CRC 校验失败

现象：编译时提示 uboot.boot数据的CRC校验错误、生成失败，无效的F文件 或 系统找不到指定的文件。
根因：工具链版本与固件格式不匹配（工具链负责生成含 CRC 校验的 F 中间文件）。
处置：更新至官方最新工具（https://doc.zh-jieli.com/Tools/zh-cn/other_info/index.html），重新编译。
判定要点：README 将这三条错误消息捆绑出现作为"工具过旧"的判别特征，不建议通过修改源码绕过。

边界情况：缺失库文件无法编译

README 明确"需要结合对应命名规则的库文件（lib.a）和对应的子仓库进行编译"。推断：若未配置与芯片系列匹配的 lib.a，链接阶段会失败；这不是工具链问题，而是依赖缺失，应先补齐库与子仓库再排查工具链（推断依据：README 将二者分别声明为前置条件与故障修复手段）。

边界情况：多系列共仓库带来的选择风险

同一仓库容纳 bd19/br23/br25/br30/br34/sh54/sh55/wl82/br28 九个系列工程，选错 .cbp 会导致链接或下载失败。README 用对应表消除歧义——必须按 SDK 型号查表选入口，不能按芯片外观或型号近似猜测。

并发与一致性（推断性说明）

README 未提及并行编译或并发烧录。推断：Make 环境支持多线程构建，但 Codeblock 默认串行；uboot.boot 的 CRC 校验表明产物具有完整性校验机制，可防止烧录过程中因中断/并发导致的损坏镜像进入设备。此类校验由工具链完成，开发者无需额外处理。

免责声明（官方提醒）

README 结尾特别提醒：

user boot 支持多系列芯片开发，鉴于boot的特殊性，请务必进行充分测试。

Source: fw-Bootloader/README.md

这说明该 Bootloader 面向多系列芯片，且 boot 固件一旦出错将直接影响设备启动，生产发布前必须针对目标芯片进行充分的升级与回退测试。

性能与运维注意

仓库源码中与"性能/运维"直接相关的证据有限，但结合 README 可归纳出以下运维要点：

工具链更新是运维常态：CRC 校验错误直接指向工具过旧，意味着 Bootloader 的构建产物与官方工具链存在版本耦合。线上/线下同步发布的节奏（"线上线下支持同步发布"）要求维护者保持工具链与固件版本同步更新。
构建产物可复用：uboot.boot 作为单一产物集成进原 SDK 下载目录，说明发布流程中无需单独的烧录流水线，降低运维复杂度。
批量验证：鉴于 boot 固件的特殊性（免责声明），建议在发布流程中增加针对目标芯片的自动化冒烟测试（升级 → 启动 → 回退），而不只是单次编译成功。

扩展点

从 README 可以识别出两个明确的扩展维度：

新增芯片系列支持：在 user_boot/cpu/ 下新增目录（如新的系列代号），并在 SDK 型号对应表中登记新条目。工程结构按系列隔离，新增系列不影响既有工程——这是该仓库设计的核心扩展模式（证据：README 同时列出 bd19 至 br28 共九个系列，且 AC791N 对应 wl82，说明该结构随芯片迭代持续扩展）。
自定义升级方式：README 声明支持"自定义串口升级和 usb_hid 升级"。串口侧已有配套工具 fw-Bootloader/update_tools/win-uart/，开发者可在该路径下扩展或定制 Windows 串口升级工具；usb_hid 升级链路则需结合对应 SDK 的 HID 协议实现（细节未在 README 中展开，需查阅 SDK 侧文档）。

Source: fw-Bootloader/README.md