快速开始与开发环境

本文档介绍杰理（Jieli）AC63 系列通用 MCU 固件仓库（fw-AC63_GP_MCU）的快速入门流程与开发环境搭建方法，涵盖硬件准备、工具链安装、编译构建、烧录下载以及常见问题处理。

Purpose and Scope

本页面面向首次接触 AC63 系列通用 MCU SDK 的开发者，完整说明从拿到开发板到成功烧录固件的端到端流程，包括：

仓库结构与 SDK 总体布局
硬件评估板与烧写工具的获取途径
Linux / Windows 双平台工具链安装与验证
顶层 Makefile 的构建目标与编译命令
固件产物（sdk.elf）与烧录脚本（download.sh / download.bat）的使用方式

以下内容不在本页范围内，分别由其他目录页覆盖：芯片外设 API 使用（ADC、IIC、SPI、PWM 等）、具体应用例程的代码解读、各 BSP 子工程的内部驱动实现、量产烧写工具的使用细节。本页聚焦"环境准备 + 构建入口"，让开发者能最快跑通第一个编译与烧录流程。

Overview

fw-AC63_GP_MCU 是杰理科技开源的 AC63 系列通用 MCU 固件 SDK，支持 AC632N、AC635N、AC636N、AC638N 四个型号。该系列 SoC 面向控制类、智能类、玩具类产品与低功耗场景，提供 ADC、IIC、SPI、PWM_LED、MCPWM、SD 卡、触摸按键、充电等丰富外设接口，并支持低功耗 RTC、闹钟和时基唤醒。

SDK 采用 顶层聚合 Makefile + 各芯片 BSP 子工程 Makefile 的二级构建结构：在 sdk/ 目录下执行 make ac632n 等命令，顶层 Makefile 会递归调用 sdk/bsp/AC632N/Makefile 等子工程完成编译。工具链基于 LLVM/Clang 定制，目标架构为杰理私有 q32s，编译过程中启用 LTO（链接时优化）以控制代码体积。

SDK 固件包本身不包含开发文档，正式开发前必须阅读在线 SDK 开发文档：https://doc.zh-jieli.com/GPMCU/zh-cn/master/index.html，该文档提供了完善的开发例程，帮助开发者快速顺利地进行方案开发。

Architecture

下图展示从开发主机到目标芯片的完整开发环境架构与构建数据流：

flowchart TD
    subgraph sg_Host["开发主机 (Host)"]
        OS["Linux / Windows"]
        TC_LINUX["工具链 /opt/jieli/q32s/bin<br/>(clang, lto-wrapper, lto-ar)"]
        TC_WIN["工具链 C:/JL/pi32/bin<br/>(clang.exe, q32s-lto-wrapper.exe)"]
        ULIMIT["ulimit -n ≥ 8096"]
    end

    subgraph sg_SDK["SDK 仓库 (fw-AC63_GP_MCU)"]
        TOP_MK["sdk/Makefile<br/>顶层构建入口"]
        BSP_MK["sdk/bsp/AC632N/Makefile<br/>(AC635N/AC636N/AC638N 同理)"]
        CFLAGS["CFLAGS: -target q32s -flto -Oz/-Os"]
        OUTPUT["sdk/bsp/AC632N/output/sdk.elf"]
    end

    subgraph sg_Flash["烧录与运行"]
        DL_SH["tools/download.sh (Linux)"]
        DL_BAT["tools/download.bat (Windows)"]
        CHIP["AC632N / AC635N / AC636N / AC638N"]
    end

    OS -->|"make ac632n"| TOP_MK
    TOP_MK -->|"$(MAKE) -C bsp/AC632N"| BSP_MK
    BSP_MK -->|"调用"| TC_LINUX
    BSP_MK -->|"调用"| TC_WIN
    ULIMIT -.->|"Linux 下建议"| BSP_MK
    BSP_MK --> CFLAGS
    CFLAGS --> OUTPUT
    OUTPUT -->|"POST_SCRIPT 后处理"| DL_SH
    OUTPUT -->|"POST_SCRIPT 后处理"| DL_BAT
    DL_SH --> CHIP
    DL_BAT --> CHIP

各组成部分职责

组件	职责	说明
`sdk/Makefile`	顶层构建调度器	定义 `all/clean` 及四个芯片目标，递归调用各 BSP 子工程
`sdk/bsp/<CHIP>/Makefile`	芯片级编译配置	设置工具链路径、CFLAGS、DEFINES、头文件与源码清单，产出 `sdk.elf`
杰理 q32s 工具链	交叉编译/链接	基于 LLVM/Clang 定制，Linux 装在 `/opt/jieli`，Windows 装在 `C:/JL`
`download.sh` / `download.bat`	烧录后处理脚本	编译完成后自动执行，将固件下载到目标芯片
目标芯片	运行固件	AC632N / AC635N / AC636N / AC638N 四款型号

设计意图：顶层聚合 + BSP 子工程拆分，使新增芯片型号只需在顶层 Makefile 增加一个目标并在 sdk/bsp/ 下新建子目录，即可复用同一套工具链与构建框架，将"新增型号支持"的成本降到最低。

硬件环境准备

根据仓库根目录 README.md 的说明，开始开发前需要准备两类硬件：

开发评估板：用于功能验证与方案评估，可通过官方淘宝店铺申请/购买。
生产烧写工具：为量产和裸片烧写而设计，与评估板烧录入口不同，需单独申请。

提示：评估板烧录通常走 SDK 自带的 download.sh/download.bat 脚本（通过 USB 下载），而生产烧写工具面向裸片与产线场景，两者用途不同，注意区分。

工具链安装与验证

Linux 环境

Linux 下编译方式在 sdk/Makefile 与 sdk/bsp/AC632N/Makefile 的注释中均有说明，步骤为：

从 http://pkgman.jieliapp.com/doc/all 找到工具链下载链接；
下载后解压到 /opt/jieli 目录，保证 /opt/jieli/common/bin/clang 存在（注意目录层次，这是最常出错的点）；
确认 ulimit -n 的结果足够大（建议大于 8096），否则链接阶段可能因打开文件过多而失败，可通过 ulimit -n 8096 临时调大。

Windows 环境

Windows 下工具链位于 C:/JL/pi32/bin，编译工具为 clang.exe、q32s-lto-wrapper.exe、llvm-ar.exe，系统库与头文件分别在 C:/JL/pi32/q32s-lib 与 C:/JL/pi32/q32s-include。仓库的 AC632N Makefile 通过 ifeq ($(OS), Windows_NT) 自动检测平台并切换工具链配置，无需手动修改。

平台差异要点

差异项	Linux	Windows
工具链根目录	`/opt/jieli/q32s/bin`	`C:/JL/pi32/bin`
编译器	`clang`	`clang.exe`
链接器	`lto-wrapper`	`q32s-lto-wrapper.exe`
归档器	`lto-ar`	`llvm-ar.exe`
系统库目录	`/opt/jieli/q32s/lib`	`C:/JL/pi32/q32s-lib`
系统头文件目录	`/opt/jieli/q32s/include`	`C:/JL/pi32/q32s-include`
额外宏定义	`-D__SHELL__`（保证正确处理 `download.c`）	无
PATH 分隔符	`:`	`;`
后处理脚本	`download.sh`（`bash` 执行）	`download.bat`

设计意图：__SHELL__ 宏在 Linux 下定义，是为了让下载/后处理相关源码（download.c）在 POSIX 环境下的行为与 Windows 批处理方式区分开，避免平台相关的命令执行逻辑互相干扰。

编译构建

支持的构建目标

顶层 sdk/Makefile 声明了全部目标：

# 支持的目标
# make ac636n
# make ac638n
# make ac632n
# make ac635n

.PHONY: all clean ac636n ac638n ac632n ac635n clean_ac636n clean_ac638n clean_ac632n clean_ac635n

all: ac636n ac638n ac632n ac635n
	@echo +ALL DONE

在 sdk/ 目录下执行：

make ac632n（或 ac635n / ac636n / ac638n）：编译对应芯片的固件；
make all：依次编译全部四个型号；
make clean_ac632n：清除对应子工程临时文件；
make clean：清除全部子工程临时文件。

子工程递归调用

每个芯片目标通过 $(MAKE) -C 递归进入 BSP 子目录执行：

ac636n:
	$(MAKE) -C bsp/AC636N -f Makefile

clean_ac636n:
	$(MAKE) -C bsp/AC636N -f Makefile clean

编译参数

子工程 Makefile（以 AC632N 为例）为 q32s 架构配置了完整的编译参数（源码位置）：

CFLAGS := \
	-flto \
	-target q32s \
	-integrated-as \
	-fno-builtin \
	-mllvm -inline-threshold=5 \
	-Oz \
	-integrated-as \
	-g \
	-O0 \
	-flto \
	-Os \
	-fallow-pointer-null \
	-Wincompatible-pointer-types \
	-Werror=implicit-function-declaration \
	-Werror=macro-redefined \
	-Werror=return-type \
	-Werror=int-conversion \
	-Wundef \
	-fprefer-gnu-section \
	-Wframe-larger-than=256 \
	-Wno-empty-body \
	-Werror=undef \
	-fms-extensions

要点解读：

-target q32s：指定交叉编译目标架构为杰理 q32s；
-flto 配合 -Oz/-Os：启用链接时优化与尺寸优化，这是 MCU 固件控制 Flash 占用空间的关键手段；
-Werror=implicit-function-declaration 等一组 -Werror：将常见错误（隐式函数声明、宏重定义、返回类型错误、整数转换错误、未定义宏）直接升级为编译失败，在编译期拦截隐患；
-fprefer-gnu-section：为链接阶段垃圾回收（section GC）做准备，进一步缩减固件体积；
-Wframe-larger-than=256：对栈帧大于 256 字节的函数告警，帮助规避 MCU 栈溢出风险。

同时定义了关键宏（DEFINES）：

DEFINES := \
	-DSUPPORT_MS_EXTENSIONS \
	-D__GCC_Q32S__ \
	-DCONFIG_OS_ENABLE=0 \
	-DCONFIG_FREE_RTOS_ENABLE \
	-DCONFIG_RELEASE_ENABLE \
	-DCONFIG_MMU_ENABLE

这些宏决定了固件特性组合：关闭通用 OS 调度而启用 FreeRTOS、开启 MMU 与 Release 模式，均由构建系统统一注入，应用代码无需自行判断。

固件产物与烧录

编译成功后，固件输出为 sdk/bsp/<CHIP>/output/sdk.elf（见 OUT_ELF 定义）。Makefile 会在构建完成后调用平台对应的后处理脚本完成下载：

Linux：tools/download.sh，通过 bash $(POST_SCRIPT) 执行；
Windows：tools/download.bat。

因此在开发主机连接评估板的情况下，直接执行 make ac632n 即可实现"编译并下载"一步完成，无需手工搬运固件文件。

Core Flow

下图展示从执行 make 命令到固件在芯片上运行的完整时序：

sequenceDiagram
    participant Dev as 开发者
    participant Top as sdk/Makefile
    participant Bsp as sdk/bsp/AC632N/Makefile
    participant TC as q32s 工具链 (clang/lto-wrapper)
    participant Out as output/sdk.elf
    participant DL as download.sh / download.bat
    participant Chip as AC632N 芯片

    Dev->>Top: make ac632n
    Top->>Bsp: $(MAKE) -C bsp/AC632N -f Makefile
    Bsp->>TC: clang -target q32s -flto ... (编译 .c 源文件)
    TC->>TC: LTO 链接 + 尺寸优化
    TC->>Out: 生成 sdk.elf
    Bsp->>DL: 执行 POST_SCRIPT 后处理脚本
    DL->>Chip: 通过 USB 下载固件
    Chip-->>DL: 下载完成
    DL-->>Bsp: 返回
    Bsp-->>Top: 完成
    Top-->>Dev: 命令行返回，固件已烧录

编译流程的关键设计是"构建即烧录"：后处理脚本直接挂在子工程 Makefile 的构建链上，避免开发者手动执行额外的烧录步骤，降低操作出错概率。

Usage Examples

示例一：Linux 下完整构建流程

以下命令序列在 Linux 开发机上完成工具链准备与固件编译（依据 sdk/Makefile 与 AC632N Makefile 的注释说明整理）：

# 1. 从 http://pkgman.jieliapp.com/doc/all 获取工具链下载链接
# 2. 解压到 /opt/jieli，确认 /opt/jieli/common/bin/clang 存在
# 3. 调整文件描述符上限，避免链接期打开文件过多而失败
ulimit -n 8096

# 4. 进入 SDK 根目录并编译目标芯片固件（编译并下载）
cd sdk
make ac632n

# 查看详细编译过程
make VERBOSE=1

# 清理临时文件
make clean_ac632n

示例二：顶层 Makefile 的目标委托

顶层 sdk/Makefile 通过 -C 递归委托子工程，新增芯片目标只需仿照现有条目添加（源码）：

ac636n:
	$(MAKE) -C bsp/AC636N -f Makefile

clean_ac636n:
	$(MAKE) -C bsp/AC636N -f Makefile clean

ac638n:
	$(MAKE) -C bsp/AC638N -f Makefile

clean_ac638n:
	$(MAKE) -C bsp/AC638N -f Makefile clean

ac632n:
	$(MAKE) -C bsp/AC632N -f Makefile

clean_ac632n:
	$(MAKE) -C bsp/AC632N -f Makefile clean

ac635n:
	$(MAKE) -C bsp/AC635N -f Makefile

clean_ac635n:
	$(MAKE) -C bsp/AC635N -f Makefile clean

示例三：平台自适应工具链切换

子工程 Makefile 用 ifeq ($(OS), Windows_NT) 一次性区分两个平台的工具链与后处理脚本，开发者无需维护两份工程（源码）：

# 工具路径设置
ifeq ($(OS), Windows_NT)
# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
CXX   := clang.exe
LD    := q32s-lto-wrapper.exe
AR    := llvm-ar.exe
MKDIR := mkdir_win -p
RM    := rm -rf

SYS_LIB_DIR := C:/JL/pi32/q32s-lib
SYS_INC_DIR := C:/JL/pi32/q32s-include
EXT_CFLAGS  := # Windows 下不需要 -D__SHELL__
export PATH:=$(TOOL_DIR);$(PATH)

## 后处理脚本
POST_SCRIPT     := ../../bsp/AC632N/tools/download.bat
RUN_POST_SCRIPT := ..\..\bsp\AC632N\tools\download.bat
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/q32s/bin
CC    := clang
CXX   := clang
LD    := lto-wrapper
AR    := lto-ar
MKDIR := mkdir -p
RM    := rm -rf
export OBJDUMP := $(TOOL_DIR)/objdump
export OBJCOPY := $(TOOL_DIR)/objcopy
export OBJSIZEDUMP := $(TOOL_DIR)/objsizedump

SYS_LIB_DIR := $(TOOL_DIR)/../lib
SYS_INC_DIR := $(TOOL_DIR)/../include
EXT_CFLAGS  := -D__SHELL__ # Linux 下需要这个保证正确处理 download.c
export PATH:=$(TOOL_DIR):$(PATH)

## 后处理脚本
POST_SCRIPT     := ../../bsp/AC632N/tools/download.sh
RUN_POST_SCRIPT := bash $(POST_SCRIPT)
endif

注意 Linux 分支额外导出了 OBJDUMP/OBJCOPY/OBJSIZEDUMP 环境变量，供构建后分析固件体积与段布局使用。

Configuration Options

以下为构建系统的可配置项（在子工程 Makefile 中定义，可按需修改）：

配置项	类型	默认值 (Linux / Windows)	说明
`TOOL_DIR`	路径	`/opt/jieli/q32s/bin` / `C:/JL/pi32/bin`	工具链可执行文件目录
`CC` / `CXX`	命令	`clang` / `clang.exe`	C/C++ 编译器
`LD`	命令	`lto-wrapper` / `q32s-lto-wrapper.exe`	LTO 链接器
`AR`	命令	`lto-ar` / `llvm-ar.exe`	静态库归档器
`SYS_LIB_DIR`	路径	`$(TOOL_DIR)/../lib` / `C:/JL/pi32/q32s-lib`	系统运行库目录
`SYS_INC_DIR`	路径	`$(TOOL_DIR)/../include` / `C:/JL/pi32/q32s-include`	系统头文件目录
`OUT_ELF`	路径	`../../bsp/AC632N/output/sdk.elf`	固件输出文件
`BUILD_DIR`	路径	`objs`	编译中间文件目录
`CFLAGS`	字符串	见上文（含 `-target q32s -flto -Os` 等）	C 编译参数
`DEFINES`	字符串	`CONFIG_FREE_RTOS_ENABLE`、`CONFIG_MMU_ENABLE` 等	预定义宏，决定固件特性
`EXT_CFLAGS`	字符串	`-D__SHELL__`（Linux）/ 空（Windows）	平台附加宏
`POST_SCRIPT`	路径	`tools/download.sh` / `tools/download.bat`	构建后烧录脚本

API Reference（Makefile 目标）

顶层 sdk/Makefile 暴露的伪目标即本 SDK 的"构建 API"：

目标	行为	说明
`all`	依次编译 AC636N、AC638N、AC632N、AC635N	全量构建，末尾输出 `+ALL DONE`
`ac632n` / `ac635n` / `ac636n` / `ac638n`	递归编译对应 BSP 子工程	单芯片构建入口
`clean`	依次清理全部子工程	输出 `+CLEAN DONE`
`clean_ac632n` 等	清理单个子工程	按芯片粒度清理

子工程 Makefile 的常用目标（见 AC632N Makefile 头部注释）：

目标/变量	行为	说明
`make`	编译并下载	默认目标，构建 `sdk.elf` 后自动执行烧录脚本
`make VERBOSE=1`	显示编译详细过程	排查编译问题时开启
`make clean`	清除编译临时文件	在子工程目录执行

失败模式、边界情况与并发注意事项

基于 Makefile 源码注释与构建配置，开发环境搭建与构建过程中的常见失败模式如下：

失败模式	触发条件	现象与处理
工具链目录层次错误	Linux 下解压后 `/opt/jieli/common/bin/clang` 不存在	编译器找不到，直接报错；按注释要求核对目录层次后重新解压
文件描述符耗尽	`ulimit -n` 小于 8096，且源码文件较多	链接阶段因打开文件过多而失败，这是最隐蔽的问题；执行 `ulimit -n 8096` 调大后重试
平台宏缺失	Linux 下未定义 `-D__SHELL__`	`download.c` 的下载逻辑无法正确处理，导致后处理/下载行为异常；该宏由 `EXT_CFLAGS` 注入，无需手动添加
Windows 路径问题	工具链未安装到 `C:/JL/pi32`	`PATH` 中找不到 `clang.exe` 等；按 Makefile 约定的目录安装
隐式函数声明等编译错误	代码存在隐患	`-Werror=implicit-function-declaration` 等参数将警告升级为错误，需要修复源码后重编（这是刻意设计，用于提前拦截问题）
栈帧过大	函数栈帧超过 256 字节	`-Wframe-larger-than=256` 告警，提示重构以规避 MCU 栈溢出风险
未接评估板时执行 `make`	主机未连接目标芯片	编译可能成功，但后处理烧录脚本失败；先连接开发板再执行，或仅编译不烧录

并发与一致性

顶层 make all 的四个目标按顺序串行执行（make 默认串行），不会出现多芯片工程同时写同一目录的竞争；
每个 BSP 子工程使用独立的 objs 目录与独立的 sdk.elf 输出路径，多芯片构建互不干扰；
Make 依赖 OBJ_FILE（sdk.elf.objs.txt）等中间文件跟踪增量编译，make clean 可彻底重置构建状态。

性能与运维注意事项

链接时优化（LTO）：-flto 配合 -Oz/-Os 与 -fprefer-gnu-section 显著压缩固件体积，适合 Flash 受限的 MCU，代价是编译时间变长、内存占用升高，建议开发机配置足够的内存；
增量编译：修改单个源文件后，make 仅重编受影响部分；若怀疑构建缓存异常，先执行 make clean 再全量重编；
文件描述符上限：链接器会并行打开大量目标文件，Linux 下务必保证 ulimit -n 足够大，这是链接稳定性的第一前提；
构建产物定位：所有固件输出统一在 sdk/bsp/<CHIP>/output/sdk.elf，日志与体积分析可通过 OBJSIZEDUMP/OBJDUMP 工具查看。

扩展点

新增芯片型号：在 sdk/bsp/ 下复制现有子工程目录并适配，然后在顶层 sdk/Makefile 添加对应 make <chip> 与 clean_<chip> 目标即可接入统一构建框架；
调整固件特性：通过修改子工程 Makefile 的 DEFINES 宏开关（如 CONFIG_OS_ENABLE、CONFIG_FREE_RTOS_ENABLE、CONFIG_MMU_ENABLE、CONFIG_RELEASE_ENABLE）组合出不同特性集，无需改动应用代码；
更换烧录后处理：替换 POST_SCRIPT 指向的 download.sh/download.bat，即可接入自定义下载/量产流程；
扩展编译告警策略：在 CFLAGS 中追加 -Werror=... 或调整 -Wframe-larger-than 阈值，定制团队的代码质量门槛。

在线 SDK 开发文档（官方）：https://doc.zh-jieli.com/GPMCU/zh-cn/master/index.html
仓库说明 README.md
英文版说明 README-en.md
顶层构建入口 sdk/Makefile
子工程构建配置示例 sdk/bsp/AC632N/Makefile
工具链下载入口：http://pkgman.jieliapp.com/doc/all
相关页面：芯片外设与应用例程（ADC、IIC、SPI、PWM 等）请参见对应应用文档页；各 BSP 驱动实现请参见 BSP 子工程相关页面。