SDK 目录结构与模块分层

本文档系统阐述 fw-AD16N_GP-MCU_SDK 的仓库目录组织、模块分层架构与各层职责，帮助开发者快速定位应用代码、BSP、库文件、工具链与文档资源。

Purpose and Scope

本页面向首次接触 AD16N SDK 的开发者，完整说明：

• 仓库顶层目录结构与 sdk/ 主目录的工程组织方式；
• 应用层（apps/）、库层（include_lib/）、板级支持层（bsp/）、工具链（tools/）的分层边界与依赖方向；
• 各层内部子模块（解码器、编码器、音频、设备驱动、消息机制、固件升级等）的职责；
• 从源码到固件的编译入口与构建流程。

本页是架构导航页，不深入单个模块的 API 细节。关于具体芯片选型、环境搭建、烧录升级与常见问题，请分别参见同目录下对应子页面（例如芯片规格、编译指南、烧录与升级、配置说明）。

Overview

fw-AD16N_GP-MCU_SDK 是杰理科技为 AD16N 系列芯片提供的通用 MCU SDK 开发包，覆盖语音玩具（故事机、学习机、MIDI 乐器）、小音箱（MP3 播放器、录音笔、扩音器）、通用 MCU（智能控制、传感器采集、USB 音频设备）三大应用场景。

SDK 采用经典的分层架构设计：

1. 应用层（apps/app/）：存放具体产品工程（当前为 mbox_flash 小音箱/音频播放应用）及其板级支持包（BSP）；
2. 库层（apps/include_lib/）：对外提供全部 SDK 能力（音频解码/编码、设备驱动、消息机制、固件升级等）的头文件 + 预编译静态库（lib.a），应用层通过 API 头文件调用底层实现；
3. 工具层（tools/、Makefile、*.cbp）：提供 Windows 命令行编译入口、Code::Blocks 工程与编译后处理脚本；
4. 文档层（doc/）：芯片规格书、原理图、SDK 手册、选型表等资料。

这种"头文件开放、实现闭源（预编译 .a）"的发布模式是杰理 SDK 的显著特征：开发者可修改应用层与 BSP 实现产品逻辑，而底层 CPU 平台、解码算法等以二进制库形式交付，保证了代码稳定性并缩短编译时间。

Architecture

下图展示了 SDK 的目录分层与依赖关系（节点名称均对应仓库真实目录）：

flowchart TD
    subgraph sg_Apps["应用层 apps/"]
        AppSrc["app/src/mbox_flash<br/>应用源码"]
        AppBsp["app/bsp<br/>板级支持包 (BSP)"]
        PostBuild["app/post_build<br/>编译后处理"]
    end

    subgraph sg_Lib["库层 include_lib/"]
        Headers["API 头文件<br/>cpu / decoder / encoder<br/>audio / device / common"]
        LibA["预编译库 liba/*.a"]
        Msg["消息机制 msg/"]
        Update["固件升级 update/"]
    end

    subgraph sg_Tools["构建层 sdk/ 根目录 + tools/"]
        Makefile["顶层 Makefile"]
        CBp["AD16N_mbox_flash.cbp"]
        Bat["make_prompt.bat<br/>MIDI_VER_SELECT.bat"]
    end

    subgraph sg_Doc["文档层 doc/"]
        DocPdf["SDK 手册 / 芯片手册<br/>选型表 / 硬件设计指南"]
    end

    Makefile --> AppSrc
    CBp --> AppSrc
    Bat --> Makefile
    AppSrc --> Headers
    AppSrc --> LibA
    AppSrc --> AppBsp
    AppBsp --> Headers
    AppBsp --> LibA
    PostBuild -->|"生成/校验固件"| Firmware["固件输出"]
    DocPdf -.->|"查阅资料"| AppSrc

各层职责说明

依赖方向是单向的：应用层 → 库层接口 → 预编译库实现，底层库不反向依赖应用代码，这保证了多产品工程复用同一套 SDK 核心。

顶层目录结构

仓库根目录由 sdk/（SDK 主目录）、doc/（文档）与 README.md 构成。README 中给出了权威的工程结构树，核心内容如下（节选自 README.md）：

fw-AD16N/
├── sdk/                           # SDK 主目录
│   ├── apps/                      # 应用层代码
│   │   ├── app/                   #   应用入口源码
│   │   │   ├── src/               #     应用源码
│   │   │   │   └── mbox_flash/    #       小音箱/音频播放应用
│   │   │   ├── bsp/               #     板级支持包（BSP）
│   │   │   └── post_build/        #     编译后处理脚本与工具
│   │   └── include_lib/           #   头文件与预编译库
│   │       ├── cpu/               #     CPU 平台头文件
│   │       ├── decoder/           #     解码器 API 头文件
│   │       ├── encoder/           #     编码器 API 头文件
│   │       ├── audio/             #     音频 API 头文件
│   │       ├── device/            #     设备驱动头文件
│   │       ├── common/            #     公共头文件
│   │       ├── config/            #     配置头文件
│   │       ├── sound_effect_list/ #     音效算法
│   │       ├── pcm_eq/            #     PCM EQ
│   │       ├── msg/               #     消息机制
│   │       ├── update/            #     固件升级
│   │       ├── apple_dock/        #     Apple Dock
│   │       └── liba/              #     预编译库 (.a)
│   ├── tools/                     # 编译工具与脚本
│   │   ├── make_prompt.bat        #   Windows 编译命令行入口
│   │   └── utils/                 #   工具集（make、rm 等）
│   ├── midi_2byte.bat             # MIDI 2字节模式切换
│   ├── midi_4byte.bat             # MIDI 4字节模式切换
│   ├── MIDI_VER_SELECT.bat        # MIDI 版本选择
│   ├── Makefile                   # 顶层 Makefile
│   └── *.cbp                      # Code::Blocks 工程文件
├── doc/                           # 文档
│   ├── datasheet/                 #   芯片规格书
│   ├── schematic/                 #   原理图
│   ├── stuff/                     #   杂项
│   ├── README.md                  #   芯片选型说明
│   └── *.pdf                      #   手册 / 版本信息 / 硬件设计指南
└── README.md                      # 本文件

模块分层详解

1. 应用层 apps/app/

应用层是开发者最主要的活动区域，按产品划分工程。当前仓库提供 mbox_flash（小音箱/音频播放） 应用，功能覆盖：

工程入口文件为 sdk/apps/app/src/mbox_flash/ 下的应用源码，由 sdk/ 根目录的 AD16N_mbox_flash.cbp（Code::Blocks 工程）与顶层 Makefile 引用。

2. 板级支持层 apps/app/bsp/

BSP 提供与具体硬件板卡相关的驱动与适配代码。仓库中可见的 BSP 子模块（依据目录扫描结果）包括：

• common/key/：按键驱动抽象，支持多种按键类型 —— key_drv_ad.h（ADC 按键）、key_drv_io.h（IO 按键）、key_drv_matrix.h（矩阵按键）、key_drv_mic.h、key_ir.h（红外遥控）、key_lptouch.h、key_touch.h（触摸）以及统一接口 key.h；
• common/power_manage/：app_power_mg.h 电源管理（低功耗、关机流程，SDK 宣传关机功耗低至 1.7µA+）；
• common/usb/：usb_common_def.h 公共定义、device/ 下 cdc.h/cdc_defs.h（虚拟串口）、uac_stream.h（USB Audio Class 音频流）；
• common/midi_open/：MIDI 开放引擎，含 midi_2byte/、midi_4byte/ 两种指令格式解码器与 pi32v2_lto_r1/midi_asm.h 汇编优化实现；
• common/reserved_area/：reserved_area.h 保留区管理。

BSP 是"开放源码"层：当产品板卡按键、电源或 USB 配置与参考设计不同时，修改此目录即可，无需触碰预编译库。

3. 库层 apps/include_lib/

库层是 SDK 能力的中枢，采用"接口开放、实现预编译"的发布策略：

• 头文件分组（按能力域划分）：
  • cpu/：CPU 平台头文件（芯片寄存器、启动相关）；
  • decoder/：解码器 API（MP3/WMA/WAV/.a/.b/.e/.f1x 等）；
  • encoder/：编码器 API（MP2/UMP3/A 格式录音编码）；
  • audio/：音频 API（16bit DAC 双声道 + 16bit ADC 单声道，8K–96K 采样率、硬件重采样、多段 EQ/DRC）；
  • device/：设备驱动头文件（FLASH、SD/MMC、U 盘、FAT 文件系统）；
  • common/：公共头文件；config/：配置头文件；
  • sound_effect_list/、pcm_eq/：音效算法与 PCM EQ；
  • msg/：消息机制（任务间/模块间通信）；
  • update/：固件升级；apple_dock/：Apple Dock 协议；
• 实现库 liba/：存放预编译静态库（lib.a）。README 明确指出"本仓库包含 SDK Release 版本代码及示例工程，需配合对应命名规则的库文件（lib.a）进行编译"。

4. 构建层 sdk/ 根目录与 tools/

构建层决定"如何把源码变成固件"：

• Makefile：顶层构建脚本，支持 make -j4 并行编译与 make VERBOSE=1 详细输出；
• AD16N_mbox_flash.cbp：Code::Blocks 工程文件（Windows 推荐方式）；
• tools/make_prompt.bat：一键打开配置好环境的 Windows 命令行；
• tools/utils/：内置工具集（make、rm 等）；
• midi_2byte.bat / midi_4byte.bat / MIDI_VER_SELECT.bat：MIDI 指令格式与版本切换脚本，用于在 2 字节/4 字节 MIDI 模式间切换编译配置；
• apps/app/post_build/：编译后处理脚本与工具（固件打包/校验）。

5. 文档层 doc/

doc/ 提供完整的产品资料：datasheet/（规格书）、schematic/（原理图）、AD16N_开源SDK手册_V1.2.pdf、AD16N_FLASH_SDK_发布版本信息.pdf、AD16N_芯片手册_V1.2.pdf、AD16N通用音频MCU硬件设计指南V1.3.pdf 以及 README.md 芯片选型表。选型表按封装、内置 Flash、GPIO、外设资源（SPI/I2C/UART/SDIO/QDEC/2812LED/IRDA/TIM PWM/MCPWM）、音频能力（MIC/AUX/AUD DAC/直推耳机）等维度逐型号列出（见 doc/README.md），是选型与硬件设计的首要参考。

核心流程：从源码到固件

SDK 提供三条等价编译路径：Code::Blocks 图形化编译、Makefile 命令行编译、VS Code 任务编译。其共同流程如下：

sequenceDiagram
    participant Dev as 开发者
    participant Build as 构建入口 (Makefile / cbp)
    participant App as 应用层 (app/src)
    participant Lib as 库层 (include_lib)
    participant Post as post_build
    participant FW as 固件输出

    Dev->>Build: 触发编译 (make -j4 / Ctrl+F9)
    Build->>Build: 解析工程配置 (芯片型号/功能宏)
    Build->>App: 编译应用源码 (mbox_flash)
    App->>Lib: 引用 API 头文件
    Build->>Lib: 链接预编译静态库 liba/*.a
    Lib-->>Build: 静态链接完成
    Build->>Post: 执行编译后处理
    Post->>FW: 生成/打包烧录固件
    FW-->>Dev: 固件文件 (供 USB 升级工具烧录)

流程要点：

1. 配置解析：Makefile / cbp 根据目标芯片（AD16N 全系列）与功能开关（如 MIDI 版本、编码器、音效）组织编译单元；
2. 应用编译：仅应用层与 BSP 源码参与编译，liba/ 预编译库直接链接，因此整体编译速度主要取决于应用代码量；
3. 静态链接：SDK 核心以静态库形式合入固件，最终产物为可直接烧录的固件镜像；
4. 后处理：post_build/ 负责生成最终烧录文件（校验、打包），随后使用 USB 升级工具或生产烧写工具烧录到目标板。

Usage Examples

克隆仓库并进入 SDK（快速开始）

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

Source: README.md

命令行编译（Linux / Windows）

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

# 编译
make -j4

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

Source: README.md

工具链验证

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

Source: README.md

引用 BSP 按键驱动的头文件示例

BSP 层以头文件形式向应用暴露统一按键接口，不同按键类型各自实现：

// key.h 统一接口 / key_drv_io.h IO按键 / key_drv_matrix.h 矩阵按键
#include "key.h"
#include "key_drv_io.h"
#include "key_drv_matrix.h"

Source: sdk/apps/app/bsp/common/key/

Configuration Options

SDK 的"配置"分散在构建脚本与配置文件头中，主要开关如下：

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

基于 README 中的明确说明，以下边界情况值得注意：

• 平台差异：Linux 下命令行编译需要重写 download_sh.c 脚本适配 Linux 环境；macOS 需自行配置交叉编译工具链；Windows 推荐 Code::Blocks。
• 工具链依赖：必须安装杰理编译工具链，Linux 用户解压到 /opt/jieli 并确保 /opt/jieli/pi32/bin/clang 存在；工具链缺失或路径错误是编译失败的首要原因。
• 库文件配套：SDK Release 代码"需配合对应命名规则的库文件（lib.a）进行编译"——升级 SDK 时若 liba/ 与头文件版本不匹配，可能出现链接错误或 API 签名不一致，务必保持版本对应。
• 烧录前置条件：编译前需确保 USB 升级工具正确连接且目标板已进入编程模式，否则烧录失败。
• 功能受限：变速变调播放需系统时钟 100MHz 以上；内置 Flash 型号（如 AD162A4）与外挂 Flash 型号（AD160A0）资源不同，功能裁剪需对照选型表。

扩展点与延伸阅读

• 新增产品工程：以 mbox_flash 为模板，在 apps/app/src/ 下新建应用目录，并在 sdk/ 根目录添加对应 .cbp/Makefile 目标即可；
• 板级适配：修改 apps/app/bsp/ 下的按键、电源、USB 驱动以匹配自有硬件；
• 功能开关：通过 include_lib/config/ 配置头文件与构建脚本启用/禁用解码器、编码器、音效等模块。

Related Links

• SDK 概览与快速开始（本文档）
• README.md（仓库主文档）
• doc/README.md（芯片选型表）
• sdk/apps/app/bsp/common/key/key.h（BSP 按键接口）
• sdk/apps/app/bsp/common/usb/device/cdc.h（USB CDC 接口）