工程目录布局

本文档介绍 fw-AW30N_BLE_SDK 仓库的完整目录布局：顶层目录划分、sdk/ 主目录各子目录的职责、应用层与预编译库的组织方式，以及构建系统（Makefile / Code::Blocks 工程）在目录结构中的位置。

Purpose and Scope

本页面向需要理解「仓库里有什么、各目录承担什么职责、从哪里进入工程」的开发者，系统性地梳理 AW30N BLE SDK 的工程目录布局：

顶层目录（sdk/、doc/、README）的划分与职责；
sdk/apps/ 应用层（app/ 与 include_lib/）的组织方式；
sdk/tools/、sdk/Makefile、sdk/AW30N_mbox_flash.cbp 等构建入口在目录中的位置；
构建产物与后处理脚本（post_build/）的输出路径约定。

以下相关主题属于其他页面，本文仅作交叉指引，不展开讨论：

具体的编译命令与环境搭建 → 参见「编译指南」相关页面；
各应用功能（BLE 遥控器、对讲机、小音箱等）→ 参见「应用与示例」相关页面；
芯片特性与配置宏 → 参见「配置说明」相关页面。

Overview

fw-AW30N_BLE_SDK 是杰理科技为 AW30N 系列芯片（带 BLE 5.4 蓝牙功能的 32bit DSP MCU）提供的通用 BLE SDK 固件程序仓库，主要面向蓝牙遥控器、蓝牙对讲机、BLE Dongle、语音玩具、小音箱与通用 MCU 等应用场景。

仓库采用杰理 SDK 一贯的三段式布局：根目录（README / LICENSE）→ sdk/（全部源码、库与构建系统）→ doc/（芯片手册、SDK 手册、硬件设计指南等 PDF 资料）。所有应用代码集中在 sdk/apps/ 下，其中 app/ 存放应用入口与板级支持，include_lib/ 存放公开头文件与预编译静态库（.a），这一「源码 + 预编译库」分离的设计使得固件体积与编译时间可控，同时把芯片底层实现以二进制形式交付给应用开发者。

仓库当前发布的应用工程为 AW30N_mbox_flash.cbp（BLE 蓝牙 / 小音箱 / 音频播放），其应用源码入口位于 sdk/apps/app/src/mbox_flash/，是理解整个目录布局的最佳起点。

Architecture

下图展示仓库的目录层级与各部分的归属关系（依据 README 的工程结构章节与仓库实际文件核实）：

flowchart TD
    subgraph sg_Root["仓库根目录 fw-AW30N_BLE_SDK"]
        README["README.md / README-en.md"]
        SDK["sdk/ — SDK 主目录"]
        DOC["doc/ — 文档资料"]
    end

    subgraph sg_SDK["sdk/ 主目录"]
        APPS["apps/ — 应用层"]
        TOOLS["tools/ — 编译工具与脚本"]
        MK["Makefile — 顶层构建脚本"]
        CBP["AW30N_mbox_flash.cbp — Code::Blocks 工程"]
        BATCH["make_prompt.bat — Windows 命令行入口"]
    end

    subgraph sg_APPS["apps/ 应用层"]
        APP["app/ — 应用入口源码"]
        INCLIB["include_lib/ — 头文件与预编译库"]
    end

    subgraph sg_APP["app/ 应用入口"]
        SRC["src/mbox_flash/ — BLE/小音箱/音频应用"]
        BSP["bsp/ — 板级支持包 BSP"]
        PB["post_build/ — 编译后处理脚本"]
    end

    subgraph sg_INCLIB["include_lib/ 组成"]
        MODS["cpu/ decoder/ encoder/ audio/ device/ common/ config/ msg/ update/"]
        LIBA["liba/ — 预编译 .a 静态库"]
    end

    SDK --> APPS
    SDK --> TOOLS
    SDK --> MK
    SDK --> CBP
    APPS --> APP
    APPS --> INCLIB
    APP --> SRC
    APP --> BSP
    APP --> PB
    INCLIB --> MODS
    INCLIB --> LIBA
    DOC --> PDF["AW30N_SDK手册 / 芯片手册 / 硬件设计指南 等 PDF"]

各组成部分说明：

目录/文件	角色	设计意图
`sdk/`	SDK 主目录	承载全部代码、库、构建脚本，是编译的唯一工作目录
`sdk/apps/`	应用层	区分「应用源码」与「库接口」，让应用开发者只关注 `app/`
`sdk/apps/app/`	应用入口	含 `src/`、`bsp/`、`post_build/` 三个固定子目录
`sdk/apps/include_lib/`	头文件 + 预编译库	以二进制 `.a` 交付底层实现，保证接口稳定、编译提速
`sdk/tools/`	工具集	存放 `make_prompt.bat`、`utils/`（make、rm 等 Windows 辅助工具）
`sdk/Makefile`	顶层构建脚本	统一 Windows/Linux 两套工具链与后处理流程
`sdk/AW30N_mbox_flash.cbp`	Code::Blocks 工程	Windows 推荐的图形化编译入口
`doc/`	文档资料	芯片手册、SDK 手册、硬件设计指南、选型表等 PDF
`README.md`	仓库入口文档	概述、环境搭建、工程结构、编译/烧录/配置指引

这种「单一 SDK 主目录 + 固定子目录约定」的布局，使得多应用（未来新增工程）可以共享同一套 include_lib/ 与 tools/，而每个应用只需在 apps/app/ 下维护自己的源码与 BSP。

顶层目录结构

仓库根目录仅包含三个实体，简洁清晰：

路径	类型	说明
`README.md`	文件	中文主文档：概述、支持平台、环境搭建、快速开始、工程结构、应用示例、编译/烧录/配置指南
`README-en.md`	文件	英文版 README
`LICENSE`	文件	开源许可证
`sdk/`	目录	SDK 主目录（全部代码、库、构建脚本）
`doc/`	目录	文档资料（芯片手册、SDK 手册、硬件设计指南等 PDF）

README 从「概述 → 支持的芯片 → 环境搭建 → 快速开始 → 工程结构 → 应用与示例 → 编译指南 → 烧录与升级 → 配置说明 → 常见问题」的顺序组织，本身即是理解目录布局的导航地图。

doc/ 文档目录

doc/ 目录在仓库中存放以下资料文件（来自仓库实际文件列表）：

文件	内容
`AW30N_SDK手册_V1.7.pdf`	SDK 使用手册（主要参考文档）
`AW30N_SDK_发布版本信息.pdf`	SDK 发布版本历史
`AW30N_芯片手册_V1.1.pdf`	芯片数据手册
`AW30N硬件设计指南V1.2.pdf`	硬件参考设计
`杰理AD1x-45678_MIDI应用说明文档.pdf`	MIDI 应用说明
`杰理科技AW30N系列芯片选型表_20240816.pdf`	芯片选型表

说明：README 的工程结构章节还提到 doc/datasheet/、doc/schematic/、doc/stuff/ 等子目录，属于文档中心分发时的完整形态；本仓库实际提交中直接以 PDF 平铺于 doc/ 下。硬件资料与芯片规格的查询入口可参考 README 的「支持的芯片与平台」一节。

sdk/ 主目录详解

sdk/ 是整个 SDK 的核心，编译、烧录、升级相关的一切都发生在这里。克隆仓库后进入 sdk/ 即可开始编译（git clone 后 cd AW30N/sdk）。

构建入口文件

文件	平台	作用
`AW30N_mbox_flash.cbp`	Windows	Code::Blocks 工程文件，双击打开后 Ctrl+F9 编译
`Makefile`	Windows / Linux	顶层 make 构建脚本，`make -j4` 编译、`make clean` 清理
`make_prompt.bat`	Windows	双击打开带工具链 PATH 的命令行环境，用于执行 make

三个入口的定位不同：.cbp 面向 IDE 图形化操作，Makefile 是真正的构建逻辑所在，make_prompt.bat 仅为 Windows 用户准备好命令行环境（把 C:/JL/pi32/bin 等工具链目录加入 PATH）。

apps/ 应用层

apps/ 下固定分为两个兄弟目录：

apps/
├── app/                  # 应用入口源码
│   ├── src/
│   │   └── mbox_flash/   # BLE 蓝牙/小音箱/音频播放应用源码
│   ├── bsp/              # 板级支持包（BSP）
│   └── post_build/       # 编译后处理脚本与工具
│       └── bd49/         # BD49 平台的 download.bat/download.sh 等
└── include_lib/          # 头文件与预编译库
    ├── cpu/              # CPU 平台头文件
    ├── decoder/          # 解码器 API 头文件
    ├── encoder/          # 编码器 API 头文件
    ├── audio/            # 音频 API 头文件
    ├── device/           # 设备驱动头文件
    ├── common/           # 公共头文件
    ├── config/           # 配置头文件
    ├── msg/              # 消息机制
    ├── update/           # 固件升级
    └── liba/             # 预编译库 (.a)

app/ 与 include_lib/ 的分工是杰理 SDK 的核心设计：应用开发者面向 include_lib/ 的公开头文件编程，底层实现以 .a 静态库提供。这样既保护了芯片底层代码，也缩短了链接时间，同时保证 API 层稳定。

tools/ 工具目录

sdk/tools/ 存放构建辅助工具，README 工程结构章节记载其下包含 make_prompt.bat 与 utils/（工具集：make、rm 等）。Makefile 中引用了 tools\utils\fixbat.exe（Windows 下用于把后处理 bat 脚本从 UTF-8 转为 GBK 编码），说明 utils/ 内集中放置了编译链需要的可执行工具。

构建系统与目录配合

Makefile 的关键目录约定

Makefile 集中定义了构建过程中所有与目录相关的路径，是理解目录布局如何被「使用」的最佳入口。以下为工具链与输出路径的核心片段：

# 工具路径设置
ifeq ($(OS), Windows_NT)
# 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__

## 后处理脚本
FIXBAT          := tools\\utils\\fixbat.exe # 用于处理 utf8->gbk 编码问题
POST_SCRIPT     := apps/app/post_build/bd49/download.bat
RUN_POST_SCRIPT := apps\\app\\post_build\\bd49\\download.bat
else
# Linux 下工具链位置
TOOL_DIR := /opt/jieli/pi32/bin
CC    := clang
CXX   := clang
LD    := lto-wrapper
AR    := lto-ar
MKDIR := mkdir -p
RM    := rm -rf

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

## 后处理脚本
FIXBAT          := touch # Linux下不需要处理 bat 编码问题
POST_SCRIPT     := apps/app/post_build/bd49/download.sh
RUN_POST_SCRIPT := bash $(POST_SCRIPT)
endif

Source: sdk/Makefile

这段代码揭示了目录布局的三个设计要点：

平台差异集中在文件头部：Windows（C:/JL/pi32/bin）与 Linux（/opt/jieli/pi32/bin）两套工具链路径、两套后处理脚本（download.bat vs download.sh）通过 ifeq ($(OS), Windows_NT) 一次性切换，构建逻辑主体不因平台分裂。
后处理脚本位于 apps/app/post_build/bd49/：post_build/ 目录按芯片平台（bd49）分子目录，下载/烧录脚本与固件输出同处一地，sdk.elf 也输出到这里。
tools/utils/ 承载平台差异工具：fixbat.exe 仅 Windows 需要（处理 bat 编码），Linux 用 touch 占位，工具层与构建逻辑解耦。

输出与中间文件路径约定如下：

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

Source: sdk/Makefile

即：编译中间文件统一输出到 sdk/objs/（BUILD_DIR），最终 ELF 与下载脚本输出到 sdk/apps/app/post_build/bd49/。make clean 只需清理 objs/ 与 post_build/ 下的产物，目录边界清晰。

编译流程与目录的交互

flowchart LR
    subgraph sg_Entry["构建入口"]
        CBP["AW30N_mbox_flash.cbp"]
        BATCH["make_prompt.bat"]
    end
    subgraph sg_Build["构建核心"]
        MK["Makefile (sdk/)"]
        SRC["apps/app/src/mbox_flash/"]
        LIB["include_lib/ (头文件 + .a 库)"]
    end
    subgraph sg_TC["工具链"]
        TC["clang -target pi32 (C:/JL/pi32/bin 或 /opt/jieli/pi32/bin)"]
    end
    subgraph sg_Out["构建产物"]
        OBJ["objs/ 中间文件"]
        ELF["post_build/bd49/sdk.elf"]
        DL["download.bat / download.sh 烧录脚本"]
    end

    CBP --> MK
    BATCH --> MK
    MK --> SRC
    MK --> LIB
    SRC --> TC
    LIB --> TC
    TC --> OBJ
    OBJ --> ELF
    ELF --> DL

应用层代码入口

当前唯一发布的工程是 AW30N_mbox_flash.cbp，其应用源码位于 sdk/apps/app/src/mbox_flash/。该应用覆盖 BLE 5.4 从机/主机、GATT 数据收发、蓝牙 OTA、音乐播放（FLASH/SD/U 盘，MP3/WAV/OPUS 等）、录音、USB Device、LINEIN、扩音等功能。新增应用时，按照「在 apps/app/src/ 下新建目录 + 在 Makefile 或 .cbp 中登记源文件」的模式扩展即可。

使用示例

从仓库结构定位工程入口

以下示例来自 README 的「快速开始」章节，展示了如何从克隆仓库走到应用源码：

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

# 应用代码入口：蓝牙语音遥控器/对讲机/小音箱/音频播放应用
sdk/apps/app/src/mbox_flash/

Source: README.md

完整目录树（README 记载）

README「五、工程结构」一节给出了官方的完整目录树，与仓库实际文件核对一致：

fw-AW30N/
├── sdk/                           # SDK 主目录
│   ├── apps/                      # 应用层代码
│   │   ├── app/                   #   应用入口源码
│   │   │   ├── src/               #     应用源码
│   │   │   │   └── mbox_flash/    #       BLE 蓝牙/小音箱/音频播放应用
│   │   │   ├── bsp/               #     板级支持包（BSP）
│   │   │   └── post_build/        #     编译后处理脚本与工具
│   │   └── include_lib/           #   头文件与预编译库
│   │       ├── cpu/               #     CPU 平台头文件
│   │       ├── decoder/           #     解码器 API 头文件
│   │       ├── encoder/           #     编码器 API 头文件
│   │       ├── audio/             #     音频 API 头文件
│   │       ├── device/            #     设备驱动头文件
│   │       ├── common/            #     公共头文件
│   │       ├── config/            #     配置头文件
│   │       ├── msg/               #     消息机制
│   │       ├── update/            #     固件升级
│   │       └── liba/              #     预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档
│   └── *.pdf                      # SDK 手册、芯片手册、硬件设计指南等
└── README.md                      # 本文件

Source: README.md

配置选项

目录布局相关的可配置项集中在 sdk/Makefile 头部，按平台分支设置：

变量	类型	Windows 默认值	Linux 默认值	说明
`TOOL_DIR`	路径	`C:/JL/pi32/bin`	`/opt/jieli/pi32/bin`	交叉编译工具链目录
`CC` / `CXX`	命令	`clang.exe`	`clang`	C/C++ 编译器
`LD`	命令	`lto-wrapper.exe`	`lto-wrapper`	链接器（LTO）
`AR`	命令	`llvm-ar.exe`	`lto-ar`	静态库打包工具
`SYS_LIB_DIR`	路径	`C:/JL/pi32/libc`	`$(TOOL_DIR)/../lib`	系统库目录
`SYS_INC_DIR`	路径	`C:/JL/pi32/include/libc`	`$(TOOL_DIR)/../include`	系统头文件目录
`FIXBAT`	命令	`tools\utils\fixbat.exe`	`touch`	后处理 bat 编码修正工具
`POST_SCRIPT`	路径	`apps/app/post_build/bd49/download.bat`	`apps/app/post_build/bd49/download.sh`	编译后处理/下载脚本
`OUT_ELF`	路径	`apps/app/post_build/bd49/sdk.elf`	同左	最终 ELF 输出路径
`OBJ_FILE`	路径	`$(OUT_ELF).objs.txt`	同左	目标文件清单
`BUILD_DIR`	路径	`objs`	`objs`	编译中间文件目录
`EXT_CFLAGS`	宏	（空）	`-D__SHELL__`	平台附加宏

源码出处：sdk/Makefile

此外，Makefile 的 DEFINES 区块集中声明芯片/功能宏（如 CONFIG_CPU_BD49=1、APP_BT_BLE=1、HAS_MP3_ST_DECODER、HAS_WAV_DECODER 等），对应 include_lib/config/ 下的配置头文件体系，属于「配置说明」页面的范畴。

常用构建目标

目标	命令（在 `sdk/` 下执行）	作用
编译	`make -j4`	增量编译并生成固件
详细编译	`make VERBOSE=1 -j4`	输出完整编译命令与过程
清理	`make clean`	清除 `objs/` 中间文件与构建产物

失败模式与边界情况

Windows/Linux 工具链路径不一致：Makefile 通过 ifeq ($(OS), Windows_NT) 分支切换 TOOL_DIR。若未按 README 把工具链安装到 C:/JL/pi32/bin（Windows）或 /opt/jieli/pi32/bin（Linux），make 会因找不到 clang 直接失败。Linux 下还要求 ulimit -n 足够大（建议 >8096），否则链接阶段可能因打开文件过多而失败（Makefile 头部注释明确提示）。
后处理脚本平台绑定：Windows 走 download.bat（经 fixbat.exe 修正 UTF-8→GBK 编码），Linux 走 download.sh（通过 bash 执行）。在错误平台上直接运行对方脚本会失败；Linux 下还需要 -D__SHELL__ 宏保证 download.c 处理正确。
include_lib/ 缺失或版本不匹配：应用源码依赖 include_lib/ 下的头文件与 liba/ 预编译库。仓库仅包含 SDK Release 代码，需配合对应命名规则的库文件（lib.a）编译；库与源码版本不一致时会出现链接符号缺失或 ABI 不匹配，这是该目录结构下最典型的集成故障。
post_build/ 输出目录被清理：make clean 会清掉 objs/ 与产物，若依赖旧固件文件做差分包或回退，需注意重新生成。

操作与扩展点

新增应用：在 sdk/apps/app/src/ 下新建应用目录（参照 mbox_flash/），并在 Makefile / .cbp 中登记源文件与宏（如 APP_BT_BLE 一类功能开关）。include_lib/ 与 tools/ 可完全复用，无需改动。
新增芯片平台：post_build/ 下按平台分子目录（当前为 bd49），新增平台时复制该目录并调整 POST_SCRIPT 变量即可，构建框架无需重构。
切换解码/编码功能：通过 Makefile DEFINES 中的 HAS_* 宏（HAS_MP3_ST_DECODER、HAS_WAV_DECODER 等）裁剪功能，对应 include_lib/decoder、include_lib/encoder 头文件暴露的 API。
文档资料：doc/ 下的 PDF（SDK 手册 V1.7、芯片手册 V1.1、硬件设计指南 V1.2、发布版本信息、选型表）是目录布局与 API 的权威补充资料。

测试与验证

仓库根目录未包含独立测试工程；验证目录布局正确性的方式是走通「快速开始」流程：进入 sdk/ → make -j4（或 Code::Blocks 编译）→ 检查 apps/app/post_build/bd49/sdk.elf 生成 → 用 USB 升级工具烧录。若该链路各目录职责正常，即证明布局与构建脚本配置一致。

README.md（工程结构章节）
sdk/Makefile（构建与目录配置）
sdk/AW30N_mbox_flash.cbp（Code::Blocks 工程）
sdk/make_prompt.bat（Windows 命令行入口）
doc/（SDK 手册、芯片手册、硬件设计指南）
编译命令与环境搭建 → 参见「编译指南」相关页面
应用功能细节 → 参见「应用与示例」相关页面
配置宏与芯片特性 → 参见「配置说明」相关页面