环境搭建与工具链

本页介绍 AW30N BLE SDK（fw-AW30N_BLE_SDK）的开发环境搭建、编译工具链安装与验证、Makefile 构建系统、IDE 工程入口，以及烧录与调试工具的使用方法，帮助开发者从零开始完成 SDK 的编译与烧录。

Purpose and Scope

本页面向希望在本地搭建 AW30N 系列芯片开发环境的嵌入式工程师，覆盖以下内容：

• 支持的操作系统平台（Windows / Linux / macOS）与各自的前提条件
• 杰理编译工具链（pi32 平台 clang/LLVM 工具链）的获取、安装与验证
• sdk/Makefile 构建系统的工具路径、编译参数、宏定义与头文件搜索路径解析
• Code::Blocks、Makefile 命令行、VS Code 三种编译方式
• USB 升级工具、生产烧写工具、无线测试盒等烧录/测试工具
• 编译过程中的常见故障与排查建议

本页不涵盖以下内容（属于兄弟页面）：

• 具体的应用开发流程（BLE 遥控器、对讲机、小音箱等示例应用）——请参见应用开发相关页面
• 芯片硬件规格、原理图设计——请参见硬件设计相关页面
• 固件升级协议细节（U 盘/SD 卡升级、测试盒升级、手机 OTA 等）——请参见固件升级相关页面

概述

AW30N 系列是杰理科技推出的带 BLE 5.4 蓝牙功能的 32bit DSP MCU，SDK 采用 Release 源码 + 预编译库（lib.a） 的发布方式：仓库中包含应用层源码与构建脚本，芯片底层驱动以预编译库形式提供，需配合对应命名规则的库文件进行编译（见 README.md）。

SDK 的编译目标平台为杰理自研 pi32 架构（DSP 内核），因此不能使用通用的 GCC/Clang 工具链，而必须使用杰理提供的专用交叉编译工具链。该工具链以 clang/LLVM 为基础，针对 pi32 目标进行了定制（-target pi32 及多个 -mllvm 后端优化选项）。

构建系统的核心是位于 sdk/ 根目录的顶层 Makefile，它根据操作系统自动选择工具链路径、编译命令与后处理脚本；同时仓库预置了 Code::Blocks 工程（AW30N_mbox_flash.cbp）和 VS Code 任务，便于不同习惯的开发者使用。

架构

下图展示了从开发环境到固件产物的完整构建链架构：

flowchart TD
    subgraph sg_Host["宿主机环境"]
        OS["Windows / Linux / macOS"]
        TC["杰理 pi32 编译工具链<br/>(clang / lto-wrapper / llvm-ar)"]
        IDE["Code::Blocks / VS Code"]
        MAKE["Makefile 构建系统"]
    end

    subgraph sg_SDK["SDK 源码（仓库）"]
        APPS["apps/ 应用源码"]
        INCLIB["include_lib/ 头文件与预编译库"]
        TOOLS["tools/ 工具脚本<br/>(make_prompt.bat / utils)"]
        POST["post_build/ 后处理脚本<br/>(download.bat / download.sh)"]
    end

    subgraph sg_Output["构建产物"]
        ELF["sdk.elf"]
        BIN["固件镜像"]
    end

    subgraph sg_Target["目标与工具"]
        TARGET["AW30N 目标板"]
        FLASHTOOL["USB 升级工具 / 生产烧写工具 / 无线测试盒"]
    end

    OS --> TC
    IDE --> MAKE
    MAKE --> TC
    MAKE --> APPS
    MAKE --> INCLIB
    MAKE --> TOOLS
    MAKE --> POST
    TC --> ELF
    APPS --> ELF
    INCLIB --> ELF
    POST --> BIN
    ELF --> BIN
    BIN --> FLASHTOOL
    FLASHTOOL --> TARGET

架构说明

• 宿主机环境：SDK 支持 Windows（推荐 Code::Blocks）、Linux（Makefile 命令行）与 macOS（需自行配置交叉编译工具链）。三种平台的差异集中在工具链安装路径与后处理脚本上。
• 编译工具链：pi32 目标专用 clang 工具链，Windows 下安装于 C:/JL/pi32/bin，Linux 下安装于 /opt/jieli/pi32/bin。这是整个构建链的基石。
• Makefile 构建系统：顶层 Makefile 是构建枢纽，负责将 apps/ 应用源码、include_lib/ 头文件与预编译库组合，调用工具链生成 sdk.elf，再通过 post_build/ 脚本做固件后处理。
• 固件烧录：编译产物最终通过 USB 升级工具、生产烧写工具或无线测试盒写入目标板。

平台支持与前提条件

设计意图：Linux 与 Windows 的主要差异在于下载/后处理脚本（download.sh 与 download.bat）以及 bat 文件的编码处理（UTF-8 与 GBK）。Makefile 通过 OS 环境变量自动判断平台并切换，避免开发者手工维护两套构建配置。

编译工具链安装

获取工具链

1. 从杰理官方文档中心下载 杰理编译工具链：开发环境工具下载
2. Linux 用户可从 pkgman.jieliapp.com 获取下载链接：
   • 下载后解压到 /opt/jieli 目录
   • 确保 /opt/jieli/pi32/bin/clang 存在（注意目录层次）
3. 安装完成后验证：

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

来源：README.md

Windows 工具链路径

Windows 下 Makefile 默认在以下位置查找工具链（见 sdk/Makefile）：

# Windows 下工具链位置
TOOL_DIR := C:/JL/pi32/bin
CC    := clang.exe
CXX   := clang.exe
LD    := lto-wrapper.exe
AR    := llvm-ar.exe
MKDIR := mkdir_win -p
RM    := rm -rf

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

设计意图：Makefile 将 TOOL_DIR 加入 PATH 环境变量（export PATH:=$(TOOL_DIR);$(PATH)），使编译过程中调用的子工具（clang、lto-wrapper、llvm-ar 等）都能被解析到，无需开发者手动修改系统 PATH。

Linux 工具链路径与注意事项

Linux 下 Makefile 默认在 /opt/jieli/pi32/bin 查找工具链（见 sdk/Makefile）：

# Linux 下工具链位置
TOOL_DIR := /opt/jieli/pi32/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)

Linux 平台还需要注意文件描述符限制，Makefile 头部注释明确给出了警告（见 sdk/Makefile）：

# 3. 确认 ulimit -n 的结果足够大（建议大于8096），否则链接可能会因为打开文件太多而失败
#    可以通过 ulimit -n 8096 来设置一个较大的值

故障预防：LTO（链接时优化）阶段会同时打开大量中间文件，若 ulimit -n 过小，链接器会因"打开文件过多"（EMFILE）而失败。建议在编译前执行 ulimit -n 8096。

平台差异汇总

构建系统：Makefile 详解

顶层目标与用法

Makefile 头部注释定义了三种常用目标（见 sdk/Makefile）：

# make 编译并下载
# make VERBOSE=1 显示编译详细过程
# make clean 清除编译临时文件

编译参数（CFLAGS）

核心编译参数面向 pi32 目标做了深度定制（见 sdk/Makefile）：

CFLAGS := \
	-target pi32 \
	-integrated-as \
	-fno-builtin \
	-mllvm -pi32-memreg-opt \
	-mllvm -pi32-mem-offset-adj-opt \
	-mllvm -pi32-const-spill \
	-mllvm -pi32-enable-jz \
	-mllvm -pi32-tailcall-opt \
	-mllvm -inline-threshold=5 \
	-mllvm -pi32-enable-itblock=1 \
	-Oz \
	-flto \
	-integrated-as \
	-g \
	-O0 \
	-flto \
	-Os \
	-Wcast-align \
	-fallow-pointer-null \
	-Wincompatible-pointer-types \
	-Wundef \
	-nostrictpi32 \
	-fprefer-gnu-section \
	-Werror \
	-Werror=implicit-function-declaration \
	-Werror=return-type \
	-Werror=undef \
	-Wno-format

要点解析：

• -target pi32：指定交叉编译目标架构为 pi32（杰理 DSP 内核），这是整个工具链的关键参数。
• -mllvm -pi32-*：一组 LLVM 后端优化选项（内存寄存器优化、内存偏移调整、常量溢出、jz 分支使能、尾调用优化、IT 块使能等），针对 pi32 微架构特性调优。
• -flto：启用链接时优化，使跨编译单元的优化成为可能（这也是链接器使用 lto-wrapper 的原因）。
• -Werror 系列：把隐式函数声明、返回类型、未定义宏等警告升级为错误，保证代码质量。
• -fprefer-gnu-section：偏好 GNU section 布局，配合链接脚本控制固件内存布局。

宏定义（DEFINES）

Makefile 通过 -D 宏开关配置 SDK 功能集合，分为三类（见 sdk/Makefile）：

1. 平台宏：CONFIG_CPU_BD49=1（CPU 型号）、APP_BT_BLE=1（应用类型）、__FPGA=0、DD_MASKROM_CODE=0、DD_IS_FLASH_SYSTEM 等。
2. 编解码器宏：HAS_MP3_ST_DECODER、HAS_WAV_DECODER、HAS_MP3_ENCODER、HAS_OPUS_ENCODER 等，控制音频编解码能力的编译包含。
3. 功能宏：HAS_BLE_EN=1、HAS_USB_EN=1、HAS_SDMMC_EN=1、HAS_UPDATE_V2_EN=1、HAS_TESTBOX_BT_UPDATE_EN=1、HAS_CONFIG_APP_OTA_EN=1 等，控制外设与升级功能。

DEFINES := \
	-D__FPGA=0 \
	-DCONFIG_CPU_BD49=1 \
	-DAPP_BT_BLE=1 \
	-DSUPPORT_MS_EXTENSIONS \
	-DD_MASKROM_CODE=0 \
	-DD_IS_FLASH_SYSTEM \
	-DD_SFC_DEVICE_EN \
	...
	-DHAS_BLE_EN=1 \
	-DHAS_UPDATE_V2_EN=1 \
	-DHAS_SD_UPDATE_EN=1 \
	-DHAS_UDISK_UPDATE_EN=1 \
	-DHAS_TESTBOX_BT_UPDATE_EN=1 \
	-DHAS_TESTBOX_UART_UPDATE_EN=1 \
	-DHAS_CONFIG_APP_OTA_EN=1 \
	...
	-DNOFLOAT

DEFINES += $(EXT_CFLAGS) # 额外的一些定义

来源：sdk/Makefile

设计意图：采用编译期宏开关而非运行时配置，是为了在嵌入式场景下最大化代码裁剪能力——未启用的功能（如特定解码器、升级通道）不会进入最终固件，从而节省 FLASH 空间。DEFINES += $(EXT_CFLAGS) 将平台差异（Linux 的 -D__SHELL__）统一注入。

头文件搜索路径（INCLUDES）

Makefile 通过 -I 参数指定分层头文件搜索路径（见 sdk/Makefile）：

INCLUDES := \
	-Iapps/include_lib/fs/sydf \
	-Iapps/include_lib/fs/nor_fs \
	-Iapps/include_lib/fs/fat \
	-Iapps/app/bsp/common/decoder/mio \
	-Iapps/include_lib/encoder \
	-Iapps/include_lib/encoder/list \
	-Iapps/include_lib/ans \
	-Iapps/app/src \
	-Iapps/app/post_build/bd49 \
	-Iapps/app/bsp \
	-Iapps/app/bsp/common \
	-Iapps/app/bsp/common/key \
	-Iapps/app/bsp/common/power_manage \
	-Iapps/app/bsp/common/usb/usr \
	-Iapps/app/bsp/lib \
	-Iapps/app/bsp/cpu/bd49 \
	-Iapps/app/bsp/device \
	-Iapps/app/bsp/rf \
	-Iapps/app/bsp/start \
	-Iapps/app/bsp/start/bd49

路径覆盖 include_lib（预编译库公开头文件）、bsp（板级支持包）、app/src（应用源码）与 post_build（后处理），保证应用层、驱动层与库层头文件均可被正确解析。

构建产物路径

# 输出文件设置
OUT_ELF   := apps/app/post_build/bd49/sdk.elf
OBJ_FILE  := $(OUT_ELF).objs.txt
# 编译路径设置
BUILD_DIR := objs

来源：sdk/Makefile

编译中间文件（.o、.d 等）输出到 sdk/objs/ 目录，最终 ELF 固件输出到 apps/app/post_build/bd49/sdk.elf，与后处理脚本同目录，方便 download.sh/download.bat 就地处理。

编译方式

SDK 提供三种编译方式，覆盖不同开发习惯（见 README.md）。

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

1. 双击打开工程文件 AW30N_mbox_flash.cbp（位于 sdk/ 根目录）
2. 点击 Build → Build（快捷键 Ctrl+F9）
3. 编译成功后，使用 USB 升级工具烧录生成的固件

Code::Blocks 工程本质上是把 Makefile 的编译逻辑封装为 IDE 图形化操作，适合不熟悉命令行或希望利用 IDE 调试（断点、变量监视）的开发者。

方式二：Makefile 命令行

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

# 编译
make -j4

# 显示编译详情
make VERBOSE=1 -j4

提示：编译前请确保 USB 升级工具正确连接且目标板已进入编程模式。（见 README.md）

make_prompt.bat 位于 sdk/tools/ 目录，为 Windows 用户提供一个预先配置好 PATH（工具链 + tools/utils 下的 make、rm 等辅助工具）的命令行环境。

方式三：VS Code 编译

仓库已预配置 VS Code 任务，按 Ctrl+Shift+B 即可选择编译目标。VS Code 方式适合偏好现代编辑器的开发者，任务配置已内置于仓库。

核心流程：从源码到固件

flowchart TD
    Start([开始]) --> PreCheck{"工具链已安装？<br/>clang --version"}
    PreCheck -->|"否"| InstallTC["安装杰理工具链<br/>Windows: C:/JL/pi32<br/>Linux: /opt/jieli"]
    InstallTC --> PreCheck
    PreCheck -->|"是"| EnvCheck{"平台环境检查<br/>Windows: make_prompt.bat<br/>Linux: ulimit -n ≥ 8096"}
    EnvCheck -->|"不满足"| FixEnv["修复环境<br/>调整 ulimit / 环境变量"]
    FixEnv --> EnvCheck
    EnvCheck -->|"满足"| Make["执行 make 或 IDE 构建"]
    Make --> Compile["clang 编译（-target pi32）<br/>应用源码 + 预编译库"]
    Compile --> LTO["lto-wrapper 链接（LTO 优化）<br/>生成 sdk.elf"]
    LTO --> PostProc["post_build 后处理<br/>download.bat / download.sh"]
    PostProc --> Flash{"自动下载/烧录？"}
    Flash -->|"是（make 默认）"| Burn["连接 USB 升级工具<br/>写入目标板"]
    Flash -->|"否（仅编译）"| Manual["手工使用烧录工具<br/>烧录固件镜像"]
    Burn --> Done([完成])
    Manual --> Done

编译时序

sequenceDiagram
    participant Dev as 开发者
    participant Make as Makefile
    participant TC as pi32 工具链
    participant Post as post_build 脚本
    participant Board as 目标板

    Dev->>Make: make -j4（或 IDE 触发）
    Make->>TC: clang 编译（-target pi32 -flto）
    TC-->>Make: 目标文件（objs/ 目录）
    Make->>TC: lto-wrapper 链接
    TC-->>Make: sdk.elf
    Make->>Post: 调用 download.bat / download.sh
    Post->>Post: fixbat 编码处理（Windows）/ 固件打包
    Post->>Board: 通过 USB/串口下载固件
    Board-->>Post: 烧录完成
    Post-->>Dev: 编译与下载结束

设计意图：make 默认目标在编译后直接下载固件到目标板，实现"一键编译烧录"；而仅希望得到固件镜像（如交给产线）时，可绕过自动下载步骤或直接取用 sdk.elf 及后处理产物。

烧录与调试工具

来源：README.md

工具分工：USB 升级工具面向开发阶段的固件烧录与验证；生产烧写工具面向量产产线（裸片/整机烧写）；无线测试盒支持空中（蓝牙）升级、射频指标标定与产测，与 SDK 中 HAS_TESTBOX_BT_UPDATE_EN、HAS_TESTBOX_UART_UPDATE_EN 等宏开关对应。

配置选项

以下配置项全部位于 sdk/Makefile 中，按平台条件赋值：

API 参考：工具链命令

clang --version

验证工具链是否安装成功。

参数：无

返回：clang 版本信息（含目标架构支持信息）

Throws：若命令不存在（command not found），说明工具链未安装或未加入 PATH。

make [目标]

参数：

• 无（默认目标）：编译并下载固件到目标板
• VERBOSE=1：显示完整编译命令行，便于排查编译错误
• clean：清除 objs/ 下的编译临时文件，用于全量重编
• -j4：并行编译，4 个编译任务同时执行以缩短构建时间

返回：退出码 0 表示成功；非 0 表示编译/链接/下载失败。

Throws：

• 工具链路径错误（clang: No such file or directory）：TOOL_DIR 与实际安装路径不符
• 链接期"打开文件过多"（EMFILE）：Linux 下 ulimit -n 过小
• download.sh/download.bat 执行失败：目标板未进入编程模式或 USB 未连接

故障模式与排查

常见故障

边界与一致性说明

• 平台一致性：Makefile 的 ifeq ($(OS), Windows_NT) 分支决定了工具链与脚本差异。若在 Linux 上使用 Windows 风格路径（或反之），会导致工具定位失败。建议严格按平台分支安装。
• 工具链版本一致性：SDK 为 Release 发布，预编译库（lib.a）与工具链版本存在对应关系；升级工具链版本前应确认与 SDK 发布说明兼容，否则可能产生 ABI 或链接问题。
• 并行编译：make -j4 并行任务共享同一工具链与中间目录，若并发数过高（如 -j32）可能加剧文件描述符压力，Linux 下需同步调大 ulimit -n。
• 构建目录清理：切换宏配置（如增删 HAS_* 开关）后，建议先 make clean 再全量重编，避免陈旧目标文件残留导致行为不一致。

性能与运维注意事项

• 构建时间：-flto（链接时优化）会显著增加链接阶段耗时，但对最终代码密度与性能有利。-j4 并行可有效缩短整体编译时间。
• 文件描述符：Linux 下务必满足 ulimit -n ≥ 8096 的要求，这是 LTO 链接成功的前提，也是构建系统最常被忽略的运维项。
• 增量编译：objs/ 目录保留中间文件，Makefile 依赖 .d 依赖文件实现增量编译；改动宏定义或工具链后建议 make clean 全量重编。
• 固件体积：-Oz/-Os 优化级别与 -fprefer-gnu-section 配合，可有效压缩 pi32 代码体积；新增功能宏会增大固件，需关注 FLASH 容量约束。

扩展点

• 新增应用工程：仓库以 sdk/ 根目录的 .cbp 工程文件（如 AW30N_mbox_flash.cbp）组织工程；新增应用可参考现有工程结构与 apps/app/src/ 目录布局创建对应源码目录并调整 Makefile 的源文件收集逻辑。
• 宏开关扩展：在 DEFINES 中新增 -DHAS_XXX_EN=1 并配套 #ifdef HAS_XXX_EN 条件编译代码，即可按产品需求裁剪/扩展功能集合。
• 后处理脚本定制：POST_SCRIPT（download.bat/download.sh）是编译后处理的挂载点，可在此扩展固件打包、签名、加密、量产烧录等自定义步骤。
• 下载脚本适配：Linux 用户需重写 download_sh.c 以适配本机 USB/串口环境，这也是官方明确指出的平台扩展点。

测试与验证

SDK 仓库本身不包含独立单元测试工程，其"验证"环节以编译通过 + 目标板运行为准：

• 编译验证：make 成功生成 sdk.elf 且无 -Werror 升级的编译错误，是每次改动后的基本验证门槛。
• 工具链验证：clang --version 输出正常，且能完成一次完整 make，即可确认环境搭建成功。
• 功能验证：编译产物通过 USB 升级工具烧录后，在目标板上验证 BLE 广播/连接、音频播放等应用行为。

建议在修改工具链版本或系统环境（如升级 LLVM 依赖）后，先以默认工程执行一次全量 make clean && make，确认基线可复现，再进行业务开发。

相关链接

• README.md（仓库总览与环境搭建章节）
• README-en.md（英文版 README）
• sdk/Makefile（顶层构建系统）
• 杰理文档中心（开发工具/文档总入口）
• 杰理编译工具链下载页
• pkgman.jieliapp.com（Linux 工具链下载）
• USB 升级工具使用文档
• 生产烧写工具使用文档
• 无线测试盒使用文档