编译与烧录指南

本页介绍 fw-AC82N_GP-MCU_SDK 的完整编译与烧录流程：从环境搭建、杰理编译工具链安装、三种编译方式（Code::Blocks / Makefile / VS Code）、编译命令速查，到 USB 升级工具烧录与 OTA 升级，以及常见编译错误的排查方法。

Purpose and Scope

本页覆盖 AC82N SDK 从源码到目标板固件的完整工具链路径：

开发环境前提条件与杰理编译工具链（JL Toolchain）安装
三种编译方式的使用方法（Code::Blocks、Makefile 命令行、VS Code Tasks）
编译命令速查表（make all / make clean / make all VERBOSE=1）
编译产物的生成位置（cpu/cd09/tools/sdk.elf）
首次烧录与 OTA 升级流程
常见编译错误诊断与修复

以下内容不属于本页范围，请参阅对应页面：应用与示例（apps/gp_mcu/ 与 cpu/demo/ 外设示例）、配置说明（引脚映射、外设使能、时钟配置、功能裁剪）、以及 UBOOT/UI 独立工程的构建细节（仓库内 UBOOT工程/、UI工程/ 目录）。

Overview

fw-AC82N_GP-MCU_SDK 是杰理科技为 AC82N 系列（cd09 平台，含 AC822B / AC823B / AC825A / AC826B）提供的通用 MCU SDK。该 SDK 使用基于 clang 的杰理交叉编译工具链（pi32 架构），配合对应命名规则的预编译静态库（lib.a）进行编译，最终生成可烧录的固件镜像。

编译系统的关键设计意图：

统一入口：顶层 Makefile 是唯一编译入口，Code::Blocks 工程（AC82N_gp_mcu.cbp）与 VS Code 任务（.vscode/tasks.json）都最终驱动同一套 Makefile 规则，避免多套构建逻辑漂移。
库文件与源码分离：芯片平台底层（如 cpu/cd09/liba/）以预编译 .a 静态库形式提供，SDK Release 代码必须配套命名规则一致的库文件才能链接成功——这是 cannot find -lxxx 类错误的根源。
烧录脚本自动衔接：编译完成后生成 cpu/cd09/tools/sdk.elf，烧录脚本会自动调用该产物，减少手动配置环节。

整个编译-烧录路径可概括为：源码 + 静态库 → clang 工具链编译链接 → sdk.elf/固件 → USB 升级工具 → 目标板。

Architecture

下图展示了从源码到目标板的完整构建与烧录链路：

flowchart TD
    subgraph sg_Source["源码与工程"]
        S1["apps/gp_mcu（主应用入口）"]
        S2["cpu/demo（外设示例）"]
        S3["include_lib（头文件）"]
        S4["cpu/cd09/liba（预编译 .a 静态库）"]
    end

    subgraph sg_Build["编译层"]
        B1["顶层 Makefile（统一入口）"]
        B2["Code::Blocks（AC82N_gp_mcu.cbp）"]
        B3["VS Code（.vscode/tasks.json）"]
        B4["杰理编译工具链（clang / pi32）"]
    end

    subgraph sg_Output["编译产物"]
        O1["cpu/cd09/tools/sdk.elf"]
        O2["固件升级镜像"]
    end

    subgraph sg_Flash["烧录层"]
        F1["USB 升级工具（isd_download.exe）"]
        F2["生产烧写工具（量产/裸片）"]
    end

    T["AC82N 目标板（cd09 SoC）"]

    S1 --> B1
    S2 --> B1
    S3 --> B1
    S4 --> B4
    B2 --> B1
    B3 --> B1
    B1 --> B4
    B4 --> O1
    O1 --> O2
    O2 --> F1
    O1 --> F2
    F1 --> T
    F2 --> T

架构说明：

源码与工程：apps/gp_mcu/ 是 GP MCU 主应用入口（应用主函数、配置入口）；cpu/demo/ 提供 HADC/UART/SPI/IIC/MCPWM/RTC 等外设示例；include_lib/ 集中存放驱动、系统、UI、升级模块的头文件；cpu/cd09/liba/ 存放 cd09 平台的预编译静态库。
编译层：三种前端（Code::Blocks、Makefile、VS Code）都汇聚到顶层 Makefile。tools/make_prompt.bat 是 Windows 下预配置好环境变量的命令行入口；tools/utils/ 提供 make、rm 等工具集。
编译产物：链接结果落在 cpu/cd09/tools/ 目录（sdk.elf），烧录脚本自动引用；固件升级镜像由此生成。
烧录层：开发阶段使用 USB 升级工具（isd_download.exe），量产阶段使用生产烧写工具（由代理商提供），两者都将固件写入 AC82N 目标板。

环境搭建

前提条件

系统	说明
Windows	✅ 推荐使用 Code::Blocks IDE 编译
Linux	✅ 支持 Makefile 命令行编译
macOS	⚠️ 需自行配置交叉编译工具链

设计意图：SDK 官方主推 Windows + Code::Blocks 与 Linux + Makefile 两条路径，macOS 由于工具链生态差异需要开发者自行处理交叉编译环境，README 因此明确标注为"需自行配置"。

安装杰理编译工具链

# 验证工具链是否安装成功
clang --version

来源：README.md

安装步骤（对应 README.md 环境搭建章节）：

从杰理官方文档中心下载并安装杰理编译工具链；
Linux 用户可从 pkgman.jieliapp.com 下载：
- 解压到 /opt/jieli 目录；
- 确保 /opt/jieli/pi32/bin/clang 存在；
安装完成后执行 clang --version 验证。

/opt/jieli/pi32/bin/clang 这一路径是 Linux 环境的关键约束——Makefile 依赖该路径定位交叉编译器，路径缺失或环境变量未配置会直接导致 clang: command not found 错误。

安装烧录工具

工具	用途	获取方式
USB 升级工具	将固件烧录到目标板	申请链接 · 使用文档
生产烧写工具	量产/裸片烧写	代理商处 · 使用文档

来源：README.md

两种工具分工明确：开发调试阶段用 USB 升级工具（即 isd_download.exe），量产阶段走生产烧写工具（支持一拖二批量烧录）。生产烧写工具需通过代理商渠道获取，不在公开仓库中。

编译方式

方式一：Code::Blocks（推荐 Windows 用户）

双击打开 AC82N_gp_mcu.cbp 工程文件；
点击 Build → Build（Ctrl+F9）；
编译成功后，使用 USB 升级工具烧录生成的固件文件。

来源：README.md 快速开始

AC82N_gp_mcu.cbp 位于 SDK 根目录，是 Code::Blocks 工程入口文件，内部已经配置好编译器参数与源文件集合，Windows 用户无需手动设置工具链路径。

方式二：Makefile 命令行

# Windows 用户
双击 tools/make_prompt.bat 打开命令行环境

# Linux/macOS 用户
cd sdk 根目录
make all -j`nproc`

来源：README.md 快速开始

Windows 关键点：tools/make_prompt.bat 是预配置的编译命令行入口，脚本已设置好所有环境变量和 make 的路径。若在普通 CMD 中直接执行 make 报"不是有效命令"，必须通过该脚本进入环境——这是 Windows 下最常见的入门错误。

Linux 关键点：-jnproc`` 启用与 CPU 核数一致的并行编译，大幅缩短编译时间；但链接阶段需要打开大量文件，需配合 ulimit -n 8096 提高文件描述符限制（见下文常见错误）。

方式三：VS Code 编译

仓库已预配置 VS Code 任务（.vscode/tasks.json），按 Ctrl+Shift+B 即可选择 all / clean 编译目标。

来源：README.md 快速开始

三种方式共享同一套 Makefile 规则：Code::Blocks 工程与 VS Code 任务只是对 make all / make clean 的图形化封装，因此编译行为与命令行完全一致。

编译命令速查表

以下命令在 SDK 根目录下执行（对应 README.md 编译指南）：

目标	芯片	说明	命令
全部	cd09	编译并下载	`make all`
清理	cd09	清理编译产物	`make clean`
详细编译	cd09	显示详细编译过程	`make all VERBOSE=1`

要点解析：

make all 是"编译并下载"的合并目标——编译完成后烧录脚本会自动调用生成的 cpu/cd09/tools/sdk.elf；
make clean 用于清理中间产物，在切换配置或遇到诡异链接错误时可先清理再重建；
VERBOSE=1 输出完整编译命令行，适合定位头文件路径、编译选项等问题。

编译产物

编译完成后生成的产物位于 cpu/cd09/tools/ 目录，核心产物为 sdk.elf。README 明确指出：

提示：编译完成后会生成 cpu/cd09/tools/sdk.elf，烧录脚本会自动调用。

来源：README.md 快速开始

该目录同时存放链接脚本与下载脚本（cpu/*/tools/ 在工程结构说明中被归类为"烧录/链接工具"），即链接、下载两个环节的工具都由芯片平台目录统一管理，这是 SDK 按芯片平台（如 cpu/cd09/）划分构建资源的设计体现。

另外，仓库中 UBOOT工程/ 与 UI工程/ 为独立编译的工程，不在 GP MCU 主 Makefile 的默认目标内，需要按各自工程的要求单独构建。

烧录与升级

首次烧录

按以下步骤将固件烧录到开发板（对应 README.md 烧录与升级章节）：

连接硬件：将开发板通过 USB 或 UART 连接到 PC；
进入编程模式：按住开发板上的烧录按键，然后复位或重新上电；
打开 USB 升级工具：启动 isd_download.exe；
选择固件：选择编译生成的固件文件；
开始烧录：点击下载按钮，等待烧录完成。

注意：烧录前请确保 USB 升级工具正确连接且目标板已进入编程模式。

设计意图：步骤 2 的"按键 + 复位"组合是进入 bootloader 编程模式的标准手法，其作用是让芯片 ROM 引导代码识别升级请求，而非正常启动应用固件——这是保证可重复烧录（即使应用固件损坏）的机制。

OTA 升级

支持自定义双备份固件升级，详见升级模块文档。

来源：README.md 烧录与升级

双备份（A/B 分区）方案是嵌入式 OTA 的常见可靠性设计：升级时写入备份分区，校验通过后切换启动分区，避免升级中断导致设备变砖。相关实现位于 apps/common/update/ 与 include_lib/update/ 模块，本页不展开，详见升级模块文档。

核心流程

下图展示从执行编译命令到固件写入目标板的完整时序：

sequenceDiagram
    participant Dev as 开发者
    participant Build as 编译系统（Makefile / Code::Blocks / VS Code）
    participant TC as 杰理工具链（clang / pi32）
    participant Art as 编译产物（cpu/cd09/tools/sdk.elf）
    participant Tool as USB 升级工具（isd_download.exe）
    participant Board as AC82N 目标板

    Dev->>Build: make all -j`nproc`（或 IDE 触发）
    activate Build
    Build->>TC: 编译 apps/、cpu/ 源码并链接 liba 静态库
    TC-->>Build: 目标文件 / 链接结果
    Build-->>Art: 生成 sdk.elf 与固件镜像
    deactivate Build
    Dev->>Board: USB/UART 连接，按键+复位进入编程模式
    Dev->>Tool: 启动 isd_download.exe，选择固件
    Tool->>Board: 下载固件镜像
    Board-->>Tool: 烧录完成反馈
    Tool-->>Dev: 提示烧录成功

流程要点：

编译阶段只有"源码 + 静态库 + 工具链"三个输入，liba 缺失会直接链接失败；
产物生成后，烧录脚本自动引用 sdk.elf，开发者无需手工指定路径；
烧录前必须完成"进入编程模式"步骤，否则工具无法与芯片建立下载握手。

常见编译错误

编译失败时可按以下决策流程快速定位（对应 README.md 常见编译错误表）：

flowchart TD
    Start([开始编译]) --> Cmd{"使用哪种方式?"}
    Cmd -->|"Windows IDE"| CB["Code::Blocks 打开 AC82N_gp_mcu.cbp"]
    Cmd -->|"Windows 命令行"| MP["双击 tools/make_prompt.bat"]
    Cmd -->|"Linux/macOS"| MK["make all -j`nproc`"]
    CB --> Build["执行编译"]
    MP --> Build
    MK --> Build
    Build --> Err{"编译是否成功?"}
    Err -->|"否"| Diag{"错误类型?"}
    Diag -->|"clang 未找到"| Fix1["安装杰理工具链并配置环境变量"]
    Diag -->|"Too many open files"| Fix2["Linux 下执行 ulimit -n 8096"]
    Diag -->|"cannot find -lxxx"| Fix3["检查 cpu/cd09/liba/ 静态库"]
    Diag -->|"make 不是有效命令"| Fix4["使用 tools/make_prompt.bat"]
    Fix1 --> Build
    Fix2 --> Build
    Fix3 --> Build
    Fix4 --> Build
    Err -->|"是"| Flash["使用 USB 升级工具烧录"]
    Flash --> Done([完成])

错误提示	解决方法
`clang: command not found`	未安装杰理编译工具链，或环境变量未配置（Linux 检查 `/opt/jieli/pi32/bin/clang`）
`Too many open files`	Linux 下执行 `ulimit -n 8096` 增加文件描述符限制
`cannot find -lxxx`	缺少对应的 `.a` 库文件，检查 `cpu/cd09/liba/` 目录
`make: command not found`	Windows 下使用 `tools/make_prompt.bat` 打开编译命令环境

来源：README.md 常见编译错误

错误根因分析：

clang: command not found 是环境问题而非代码问题——工具链未安装或 PATH 未配置，Makefile 找不到交叉编译器；
Too many open files 是并行链接的副作用：-j 并行度越高，链接阶段同时打开的文件越多，Linux 默认描述符上限不足时触发，ulimit -n 8096 是官方建议值；
cannot find -lxxx 表明 SDK Release 代码与库文件命名不匹配——README 明确要求"配合对应命名规则的库文件 (lib.a) 进行编译"；
make: command not found 常见于 Windows 原生 CMD：tools/make_prompt.bat 已封装好 make 路径与全部环境变量，必须经由它进入编译环境。

使用示例

以下示例均提取自仓库 README，覆盖从克隆到烧录的完整操作序列。

示例 1：克隆仓库并进入 SDK 根目录

git clone https://gitee.com/Jieli-Tech/AC82N.git
cd AC82N/sdk

来源：README.md 快速开始

注意：仓库克隆后需进入 sdk/ 子目录执行编译——顶层 Makefile、AC82N_gp_mcu.cbp 工程文件都位于该目录。

示例 2：Linux 下完整编译流程

# 确保文件描述符限制足够大（链接阶段需要打开大量文件）
ulimit -n 8096

# 进入 SDK 根目录执行编译
make all -j`nproc`

来源：README.md Linux 编译注意事项

先提升文件描述符上限、再并行编译，是官方推荐的 Linux 标准操作序列；make all 同时完成编译与下载脚本衔接。

示例 3：Windows 下进入编译命令行环境

# Windows 用户
双击 tools/make_prompt.bat 打开命令行环境

来源：README.md 快速开始

tools/make_prompt.bat 是 Windows 编译的唯一命令行入口，脚本预置了 make、rm 等工具路径（对应 tools/utils/ 目录）与全部环境变量。

示例 4：验证工具链安装

# 验证工具链是否安装成功
clang --version

来源：README.md 环境搭建

示例 5：并行编译加速

# 使用 -j 参数进行并行编译
make all -j4

来源：README.md 常见问题

-j4 与 -jnproc`` 效果相同，只是显式指定并行度；多核机器上可显著缩短编译时间。

配置选项

编译与烧录相关的可调参数汇总如下（均来自 README 原文）：

选项/参数	类型	默认行为	说明
`make all`	命令	编译并下载	cd09 平台默认编译目标，烧录脚本自动调用 `sdk.elf`
`make clean`	命令	清理产物	删除编译中间产物，切换配置或排查链接问题时使用
`VERBOSE=1`	环境变量	关闭	显示详细编译过程（完整命令行），用于定位编译选项与头文件路径问题
`-j<N>` / `-j\`nproc``	参数	单线程	并行编译任务数，`nproc` 自动取 CPU 核数
`ulimit -n 8096`	Shell 限制	系统默认	Linux 链接阶段文件描述符上限，过低会报 `Too many open files`
`/opt/jieli/pi32/bin/clang`	路径	无	Linux 工具链安装位置，Makefile 依赖该路径
`tools/make_prompt.bat`	脚本	无	Windows 编译命令行入口，预置 make 路径与环境变量

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

环境类故障

工具链缺失/路径错误：Linux 下未安装或未解压到 /opt/jieli，表现为 clang: command not found；即使安装了工具链，环境变量（PATH）未配置也会触发同一错误，需同时检查安装位置与 PATH。
Windows 下 make 不可用：原生 CMD 或 PowerShell 中不存在 make，必须通过 tools/make_prompt.bat 进入预配置环境。

链接类故障

静态库不匹配：cannot find -lxxx 说明 cpu/cd09/liba/ 中缺少对应命名规则的 .a 文件。SDK 为 Release 代码 + 配套库文件的组合，更换 SDK 版本时必须同步更新库文件。
sdk.elf 未生成：编译中断或 make clean 后未重新编译，烧录脚本将无产物可用；先执行 make all 确认产物生成。

并发与资源边界

并行编译的文件描述符瓶颈：-j 并行度越高，链接阶段同时打开的文件越多，Linux 默认 ulimit -n（通常 1024）在大型链接时不足，官方建议 ulimit -n 8096。
并行编译的共享产物竞争：make all 内部依赖顺序由 Makefile 管理，开发者不应手工并行执行多个 make 实例指向同一构建目录，否则中间产物可能互相覆盖，产生难以排查的链接错误。

烧录边界情况

未进入编程模式：若未"按住烧录按键 + 复位/重新上电"，USB 升级工具无法与芯片握手，点击下载会失败或超时；需重新执行编程模式步骤。
固件选择错误：必须选择当前编译生成的固件文件，若选择其他平台或旧版本固件，可能导致启动异常；双备份 OTA 机制可在升级失败时回退。

性能与运维注意事项

编译提速：多核机器使用 make all -j\nproc`（Linux）或 make all -j4`（Windows 命令行环境），编译时间与核数近似线性下降；首次数编译较慢属于正常现象（需构建全部目标文件）。
详细日志：遇到编译选项或预处理宏相关问题时，使用 make all VERBOSE=1 查看完整命令行，便于核对头文件搜索路径与宏定义。
调试手段：烧录后可通过 UART 串口输出调试日志；也可利用空闲 GPIO 输出调试波形测量时序（对应 README 调试技巧）。
产物管理：make clean 后可彻底重建，避免旧产物干扰；cpu/cd09/tools/ 下的 sdk.elf 是烧录脚本的自动输入，勿手工改名或移动。

编译与烧录指南

Purpose and Scope

Overview

Architecture

环境搭建

前提条件

安装杰理编译工具链

安装烧录工具

编译方式

方式一：Code::Blocks（推荐 Windows 用户）

方式二：Makefile 命令行

方式三：VS Code 编译

编译命令速查表

编译产物

烧录与升级

首次烧录

OTA 升级

核心流程

常见编译错误

使用示例

示例 1：克隆仓库并进入 SDK 根目录

示例 2：Linux 下完整编译流程

示例 3：Windows 下进入编译命令行环境

示例 4：验证工具链安装

示例 5：并行编译加速

配置选项

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

环境类故障

链接类故障

并发与资源边界

烧录边界情况

性能与运维注意事项

扩展点

新工程创建

功能裁剪

独立工程

OTA 升级扩展

相关链接