固件裁剪与资源优化

AW30N BLE SDK 提供了一套以编译宏配置 + 链接脚本段布局为核心的固件裁剪与资源优化机制，使同一份 SDK 能够针对不同 Flash 容量（256KB / 512KB+）和不同产品功能集（HID、BLE 测试、声箱等）生成最精简的固件镜像，同时通过段放置与库裁剪最大化 RAM 利用率。

Purpose and Scope

本文档面向需要**控制固件体积（Code/Const 区）与内存占用（BSS/Data 区）**的 SDK 使用者，系统说明 AW30N 固件裁剪的完整机制：

• 裁剪的分层架构：配置裁剪层（lib_*_config.c 编译宏）与链接脚本层（.ld 段布局）如何协同工作；
• 官方 256KB Flash 裁剪补丁包的使用方式与核心配置项；
• 蓝牙协议栈、控制器、Profile、驱动、系统、升级等各模块的裁剪开关及其对体积/功能的影响；
• 裁剪相关的配置符号、边界条件与失败模式。

不属于本文范围的内容：具体外设驱动开发、BLE 应用逻辑（见对应 BLE 应用文档页）、升级流程本身（update.ld 仅作为链接产物在此提及，升级机制细节见升级相关页面）。

Overview

AW30N 的固件由三大部分构成：蓝牙控制器（bt_controller）、蓝牙协议栈（btstack）和应用层（app）。它们以静态库 + 链接脚本的形式被链接进最终镜像。固件裁剪的本质，是在编译期通过宏开关剔除不需要的库代码与数据结构，并在链接期通过段（section）放置决定哪些内容进入 Flash、哪些进入 RAM。

SDK 中与裁剪相关的核心资产包括：

• 配置源文件（编译期裁剪）：lib_btctler_config.c、lib_btstack_config.c、lib_profile_config.c、lib_driver_config.c、lib_system_config.c、lib_update_config.c、log_config.c 等，位于各工程目录（如 app/bsp/bt_common/hid/config/、app/bsp/bt_common/ble_test/）；
• 链接脚本（链接期布局）：btctler_lib_text.ld / btctler_lib_bss.ld / btctler_lib_data.ld（控制器库）、btstack_lib_text.ld / btstack_lib_bss.ld / btstack_lib_data.ld / btstack_lib.ld（协议栈库）、update.ld（升级程序）与 maskrom_stubs.ld（MaskROM 桩函数）；
• 官方裁剪补丁包：补丁包/AW30N_v1.2.0_SDK裁剪到256KB以内的补丁包_20240815/，演示了如何把完整 SDK 裁剪进 256KB Flash，是理解裁剪流程的最佳范例。

裁剪的收益除了 Flash 体积，还包括 RAM：协议栈通过 config_le_* 系列配置控制并发连接数、GATT Server/Client 角色数、加密配对支持，这些值直接决定协议栈 BSS/Data 段分配的数据结构大小。

Architecture

固件裁剪与资源优化的整体架构如下：

flowchart TD
    subgraph sg_Config["配置裁剪层（编译期宏）"]
        C1["lib_btctler_config.c<br/>（控制器配置）"]
        C2["lib_btstack_config.c<br/>（协议栈 Code & RAM 优化）"]
        C3["lib_profile_config.c<br/>（Profile 裁剪）"]
        C4["lib_driver_config.c<br/>（驱动裁剪）"]
        C5["lib_system_config.c / lib_update_config.c / log_config.c"]
    end

    subgraph sg_Link["链接脚本层（链接期段布局）"]
        L1["btctler_lib_text / bss / data.ld"]
        L2["btstack_lib_text / bss / data.ld"]
        L3["update.ld"]
        L4["maskrom_stubs.ld"]
    end

    subgraph sg_Out["构建产物"]
        B1["Flash 镜像（Code + Const）"]
        B2["RAM 映像（BSS + Data）"]
    end

    C1 -->|"CONFIG_SOUNDBOX_FLASH_256K 等"| C2
    C2 -->|"CONFIG_BTSTACK_BIG_FLASH_ENABLE / config_le_*"| L2
    C2 -->|"#pragma 段放置 .ble_app_*"| B2
    L1 --> B1
    L2 --> B1
    L3 --> B1
    L4 --> B1
    C3 --> B1
    C4 --> B1
    C5 --> B1

各层职责与设计意图：

• 配置裁剪层：位于 app/bsp/bt_common/ 下各工程的 config/ 目录。每个 lib_*_config.c 把 SDK 顶层配置头文件（如 hid_app_config.h、includes.h、btcontroller_config.h）中的宏翻译成各预编译库（controller、btstack、profile、driver、system、update）能识别的全局符号。设计意图：预编译库无法重新编译，因此通过"编译期常量符号"而非运行时判断来控制库内代码是否链接进固件——值为 0 的符号对应的库分支会被链接器作为死代码剔除。
• 链接脚本层：include_lib/bt_controller_include/ 与 include_lib/bt_include/ 下的 .ld 文件按 text / bss / data 三类段分别声明库的内存布局。text 段进 Flash（代码与常量），bss/data 段进 RAM。设计意图：把 bss 与 data 分离，便于链接器精确统计 RAM 占用，并让未使用的库段整体不参与链接。
• 构建产物：最终固件体积 = Code + Const（Flash），运行时内存 = BSS + Data（RAM）。裁剪的目标就是同时压缩这两个指标。

裁剪的完整机制

1. 编译宏驱动的库裁剪（Code & RAM）

lib_btstack_config.c 是协议栈裁剪的枢纽文件，文件头明确标注了其用途 "Optimized Code & RAM (编译优化配置)"。它通过条件编译把应用层宏翻译为协议栈库的全局配置符号：

#if (TRANS_DATA_HID_EN)
#ifdef CONFIG_SOUNDBOX_FLASH_256K
const int CONFIG_BTSTACK_BIG_FLASH_ENABLE     = 0;
#else
const int CONFIG_BTSTACK_BIG_FLASH_ENABLE     = 1;
#endif

#if TCFG_BT_SUPPORT_AAC
const int CONFIG_BTSTACK_SUPPORT_AAC    = 1;
#else
const int CONFIG_BTSTACK_SUPPORT_AAC    = 0;
#endif

#if SNIFF_MODE_RESET_ANCHOR
//协议栈接收到命令是否自动退出sniff
const int config_btstask_auto_exit_sniff = 0;
#else
const int config_btstask_auto_exit_sniff = 1;
#endif

#if SMART_BOX_EN
const int config_rcsp_stack_enable = 1;
#else
const int config_rcsp_stack_enable = 0;
#endif

Source: lib_btstack_config.c

关键设计点：

• CONFIG_BTSTACK_BIG_FLASH_ENABLE：当定义 CONFIG_SOUNDBOX_FLASH_256K（256KB Flash 工程）时置 0，否则置 1。这是整个裁剪体系的总开关——置 0 会让协议栈库走"小 Flash"代码路径，剔除大容量 Flash 才需要的高级特性分支（如大缓冲、复杂调度）。
• CONFIG_BTSTACK_SUPPORT_AAC：AAC 音频编解码支持，开启会显著增加 Code 区体积，非声箱/非音乐场景应关闭。
• config_rcsp_stack_enable：RCSP（瑞昱/杰理私有智能音箱协议）栈使能，由 SMART_BOX_EN 控制。
• config_btstask_auto_exit_sniff：协议栈收到命令是否自动退出 sniff 省电模式，属于功耗与响应延迟的权衡项。

2. BLE 连接资源的 RAM 裁剪

BLE 协议栈的 RAM 占用主要由并发连接数、GATT Server/Client 角色数和加密配对支持决定。lib_btstack_config.c 把这些能力集中映射为 4 个符号，全部为编译期常量：

#if TCFG_USER_BLE_ENABLE
//le 配置,可以优化代码和RAM
const int config_le_hci_connection_num = CONFIG_BT_GATT_CONNECTION_NUM;//支持同时连接个数
const int config_le_sm_support_enable = CONFIG_BT_SM_SUPPORT_ENABLE; //是否支持加密配对
const int config_le_gatt_server_num = CONFIG_BT_GATT_SERVER_NUM;   //支持server角色个数
const int config_le_gatt_client_num = CONFIG_BT_GATT_CLIENT_NUM;   //支持client角色个数

#else
const int config_le_hci_connection_num = 0;//支持同时连接个数
const int config_le_sm_support_enable = 0; //是否支持加密配对
const int config_le_gatt_server_num = 0;   //支持server角色个数
const int config_le_gatt_client_num = 0;   //支持client角色个数
#endif

Source: lib_btstack_config.c

设计意图：连接数/角色数/加密是 BLE 协议栈 RAM 开销的最大变量。每增加一个并发连接，协议栈就需为 ACL、加密引擎、ATT 通道等分配一组固定大小的缓冲。当 TCFG_USER_BLE_ENABLE 关闭（纯经典蓝牙应用）时，四个符号全部归 0，协议栈的 BLE 部分可整体不分配 RAM——这正是"纯 HID/经典蓝牙产品可以做到极小内存占用"的根本原因。

3. 段放置指令（#pragma section placement）

配置文件的另一项重要职责是把 BLE 应用的数据与代码放置到专用段，便于链接脚本统一管理内存布局：

#ifdef SUPPORT_MS_EXTENSIONS
#pragma bss_seg(".ble_app_bss")
#pragma data_seg(".ble_app_data")
#pragma const_seg(".ble_app_text_const")
#pragma code_seg(".ble_app_text")
#endif

Source: lib_btstack_config.c

设计意图：

• bss_seg / data_seg：把零初始化数据与已初始化数据分别归入 .ble_app_bss / .ble_app_data，使链接器可以精确统计 BLE 应用占用的 RAM，并与库段（btctler_lib_bss / btstack_lib_bss）分开管理；
• const_seg / code_seg：把只读常量与代码归入 .ble_app_text_const / .ble_app_text，与库的 text 段分离后，链接脚本可以在 Flash 不足时优先裁剪应用段；
• SUPPORT_MS_EXTENSIONS 门控说明这些 pragma 是 Keil（ARMCC）风格的扩展语法，使用 GCC/其他工具链时需要等价替代方案。

4. 链接脚本（.ld）的段布局

SDK 在 sdk/apps/include_lib/ 下按库划分链接脚本，命名即职责：

（注：以上职责由 sdk/apps/app/post_build/bd49/ 与 sdk/apps/include_lib/ 目录结构及文件命名得出；具体段内符号以实际 .ld 内容为准。）

设计意图：text / bss / data 三分离是嵌入式链接脚本的经典做法——text 决定 Flash 占用，bss+data 决定 RAM 占用。裁剪时只需关注：

1. Flash 超限 → 裁剪 text/const：关闭 AAC、RCSP、多余 Profile、减少 GATT 角色数；
2. RAM 超限 → 裁剪 bss/data：减少并发连接数 config_le_hci_connection_num、关闭 SM 加密、关闭 BLE 整体支持。

update.ld 与 maskrom_stubs.ld 的存在说明裁剪必须同时考虑升级程序段与 MaskROM 符号对齐，避免裁剪后升级代码越界。

5. 256KB 裁剪补丁包：端到端裁剪流程

官方补丁包 补丁包/AW30N_v1.2.0_SDK裁剪到256KB以内的补丁包_20240815/ 演示了从完整 SDK 裁剪到 256KB Flash 的全部落地文件，目录结构揭示裁剪涉及的所有层面：

• 工程配置层：app/bsp/bt_common/hid/config/ 下的 lib_btctler_config.c、lib_btstack_config.c、lib_profile_config.c、lib_driver_config.c、lib_system_config.c、lib_update_config.c、log_config.c —— 全部七个配置源文件都提供了裁剪版；
• BLE 测试变体：app/bsp/bt_common/ble_test/ 下的 lib_btctler_config.c、lib_btstack_config.c、lib_profile_config.c、test_app_config.h、bt_ble.c、ble_master.c、ble_slave.c —— 测试工程同样需要裁剪配置；
• 库链接脚本：include_lib/bt_controller_include/ 与 include_lib/bt_include/ 下的全部 .ld 文件 —— 与 SDK 主树一一对应；
• 应用层：app/bsp/bt_common/bt_ble.h、bt_profile_cfg.h、app_action.h、hid/app_main.c 等 —— 裁剪后的应用入口。

这印证了裁剪不是改一个宏，而是配置层、链接层、应用层三处联动的工程化过程。

Core Flow

典型的固件裁剪决策流程如下：

flowchart TD
    S([开始裁剪]) --> Q1{"目标 Flash 容量?"}
    Q1 -->|"256KB"| P1["定义 CONFIG_SOUNDBOX_FLASH_256K"]
    Q1 -->|"512KB 及以上"| P2["保持 BIG_FLASH_ENABLE=1<br/>可启用 AAC / RCSP 等"]
    P1 --> P3["lib_btstack_config.c 中<br/>CONFIG_BTSTACK_BIG_FLASH_ENABLE=0"]
    P3 --> P4["评估功能需求"]
    P4 --> Q2{"需要 AAC 音频?"}
    Q2 -->|"否"| P5["TCFG_BT_SUPPORT_AAC=0"]
    Q2 -->|"是"| P6["保留 AAC（占用 Code 区）"]
    P4 --> Q3{"需要加密配对?"}
    Q3 -->|"否"| P7["CONFIG_BT_SM_SUPPORT_ENABLE=0"]
    Q3 -->|"是"| P8["保留 SM"]
    P4 --> Q4{"并发连接数?"}
    Q4 -->|"1 个"| P9["CONFIG_BT_GATT_CONNECTION_NUM=1<br/>节省 RAM"]
    Q4 -->|"多个"| P10["按需增大"]
    P5 --> P11["重新编译，检查 map 文件"]
    P6 --> P11
    P7 --> P11
    P8 --> P11
    P9 --> P11
    P10 --> P11
    P11 --> Q5{"Flash / RAM 仍超限?"}
    Q5 -->|"是"| P12["进一步裁剪 Profile<br/>/ 关闭 BLE 整体支持"]
    P12 --> P11
    Q5 -->|"否"| E([完成])

裁剪后各配置文件必须与链接脚本、应用代码保持同步替换（直接覆盖 SDK 对应路径即可，补丁包目录结构即 SDK 路径镜像），否则会出现库配置符号缺失导致的链接错误或功能异常。

Configuration Options

以下是协议栈裁剪相关的核心配置符号（编译期常量，定义于 lib_btstack_config.c / 顶层应用配置头文件）：

注：所有 config_le_* / CONFIG_BTSTACK_* 均为 const int 全局符号而非宏，这是为了让预编译的协议栈库在链接期读取这些值并剔除死代码分支。修改后必须全量重新编译应用，且符号必须实际存在于工程中（否则链接器报 undefined symbol）。

API Reference

裁剪体系没有传统意义上的运行期 API，其"接口"是链接脚本与配置符号。以下是最关键的符号契约：

CONFIG_BTSTACK_BIG_FLASH_ENABLE : const int

• 描述：协议栈大 Flash 模式总开关。置 0 时协议栈库走 256KB 小 Flash 优化路径。
• 取值：0（定义 CONFIG_SOUNDBOX_FLASH_256K 时）或 1。
• 约束：仅在 TRANS_DATA_HID_EN 为真时生效；修改后需同步替换对应版本的 btstack_lib_*.ld 链接脚本。

config_le_hci_connection_num : const int

• 描述：BLE 协议栈支持的最大并发连接数，直接决定 HCI/ACL 缓冲区的 RAM 分配。
• 取值：0（TCFG_USER_BLE_ENABLE=0）或 CONFIG_BT_GATT_CONNECTION_NUM。
• 影响：每增加 1 个连接，协议栈需为 ACL 数据包、加密上下文、ATT 通道分配固定 RAM，是 BLE 场景 RAM 裁剪的第一优先级。

config_le_gatt_server_num / config_le_gatt_client_num : const int

• 描述：GATT Server / Client 角色实例数。
• 设计意图：纯外围设备（如 HID 键盘）只需 Server 角色，可将 Client 置 0 节省 RAM；需要连接手机并读写手机服务的设备才需 Client。

config_le_sm_support_enable : const int

• 描述：是否支持 SMP 加密配对。
• 影响：置 1 时引入 SM 协议处理代码与配对密钥存储；不需要绑定的透传设备可置 0。

段放置 pragma（#pragma bss_seg / data_seg / const_seg / code_seg）

• 描述：将 BLE 应用的数据/代码放入专用段（.ble_app_bss、.ble_app_data、.ble_app_text_const、.ble_app_text）。
• 约束：仅 SUPPORT_MS_EXTENSIONS（Keil/ARMCC）环境下生效；换用 GCC 工具链需改用 __attribute__((section(...))) 等价写法。

Failure Modes, Edge Cases & Concurrency

裁剪配置不一致导致的链接失败

配置符号（如 CONFIG_BTSTACK_BIG_FLASH_ENABLE）是普通 C 全局变量，若补丁包只替换了 lib_btstack_config.c 而未同步替换 lib_btctler_config.c 或 .ld 脚本，可能报 undefined symbol 或重复定义。应对：按补丁包的目录镜像整体覆盖，不要单独挑文件替换。

功能静默丢失（裁剪过度）

config_le_* 置 0 后对应功能在编译期被剔除，不会在运行期报错——例如把 config_le_gatt_client_num 置 0 后仍调用 client 角色 API，会出现未定义行为或链接缺失。应对：裁剪前明确产品功能清单（连接数、角色、配对、AAC、RCSP），对照 Configuration Options 表逐项勾选。

Flash 裁剪与升级兼容

裁剪影响 update.ld 与升级分区布局。补丁包同时提供了 include_lib/update/code_v2/update.ld，说明 256KB 裁剪必须同步调整升级代码段，否则 OTA 升级可能覆盖到错误地址。升级机制细节见升级相关页面。

sniff 省电与响应延迟

config_btstask_auto_exit_sniff = 0（SNIFF_MODE_RESET_ANCHOR 定义时）表示协议栈收到命令不自动退出 sniff，可降低功耗但增加命令响应延迟——这是低功耗产品裁剪时必须做的取舍。

并发/多连接场景

BLE 并发连接数受 config_le_hci_connection_num 硬性约束，超过该值的连接请求会被协议栈拒绝。裁剪到 1 连接的产品若后续需求升级为多连接，必须重新调整配置并全量重编，无法运行期动态扩展（符号是 const int，不可变）。

功耗边界（来自官方 README 数据）

SDK 当前宣称 SOFT OFF 关机功耗 2 µA+、POWER DOWN 睡眠功耗 61 µA+（官方注明"to be greatly optimized in future"）。裁剪配置（如关闭 BLE、关闭 RCSP）可降低睡眠期间的协议栈维护开销，但 61 µA 的量级说明深度睡眠路径仍有优化空间，低功耗产品需结合硬件电源域设计。

Source: README-en.md

Usage Examples

示例 1：256KB Flash 工程的协议栈裁剪配置

以下代码来自官方 256KB 裁剪补丁包，展示最小配置模式（关闭大 Flash 特性、按需关闭 AAC/RCSP、限制 BLE 资源）：

#ifdef CONFIG_SOUNDBOX_FLASH_256K
const int CONFIG_BTSTACK_BIG_FLASH_ENABLE     = 0;
#else
const int CONFIG_BTSTACK_BIG_FLASH_ENABLE     = 1;
#endif

#if TCFG_BT_SUPPORT_AAC
const int CONFIG_BTSTACK_SUPPORT_AAC    = 1;
#else
const int CONFIG_BTSTACK_SUPPORT_AAC    = 0;
#endif

Source: lib_btstack_config.c

使用方式：在工程配置头文件（如 hid_app_config.h）中定义 CONFIG_SOUNDBOX_FLASH_256K，并将补丁包中的 lib_btstack_config.c 等七个配置文件覆盖到工程对应路径。

示例 2：BLE 连接资源的 RAM 裁剪

#if TCFG_USER_BLE_ENABLE
//le 配置,可以优化代码和RAM
const int config_le_hci_connection_num = CONFIG_BT_GATT_CONNECTION_NUM;//支持同时连接个数
const int config_le_sm_support_enable = CONFIG_BT_SM_SUPPORT_ENABLE; //是否支持加密配对
const int config_le_gatt_server_num = CONFIG_BT_GATT_SERVER_NUM;   //支持server角色个数
const int config_le_gatt_client_num = CONFIG_BT_GATT_CLIENT_NUM;   //支持client角色个数
#else
const int config_le_hci_connection_num = 0;//支持同时连接个数
const int config_le_sm_support_enable = 0; //是否支持加密配对
const int config_le_gatt_server_num = 0;   //支持server角色个数
const int config_le_gatt_client_num = 0;   //支持client角色个数
#endif

Source: lib_btstack_config.c

对于单连接外设（如 HID 键盘），推荐 CONFIG_BT_GATT_CONNECTION_NUM=1、CONFIG_BT_GATT_CLIENT_NUM=0、CONFIG_BT_SM_SUPPORT_ENABLE=0，可最大化 RAM 收益；TCFG_USER_BLE_ENABLE=0 时协议栈 BLE 部分完全零分配。

示例 3：BLE 应用段的显式放置

#ifdef SUPPORT_MS_EXTENSIONS
#pragma bss_seg(".ble_app_bss")
#pragma data_seg(".ble_app_data")
#pragma const_seg(".ble_app_text_const")
#pragma code_seg(".ble_app_text")
#endif

Source: lib_btstack_config.c

该段放置通常配合链接脚本中的段符号使用，使 map 文件可以分别统计 BLE 应用与库的 Flash/RAM 占用，是裁剪后核对体积的第一手依据。

Performance & Operational Considerations

• 裁剪收益度量：裁剪后应检查链接器生成的 map 文件，重点核对 .ble_app_text、btctler_lib_text、btstack_lib_text 等段的最终地址与大小，确认 Flash 占用与 RAM 占用符合产品预算。
• 构建时间：const int 配置符号修改后需全量重编（符号值参与库的死代码剔除，增量编译可能保留旧分支），CI 中建议对裁剪配置变化触发 clean build。
• 升级兼容性：任何裁剪调整若影响 update.ld 布局，必须同步验证 OTA 分区，防止升级镜像与运行镜像段地址错位。
• 功耗链路：配合 config_btstask_auto_exit_sniff 与 SOFT OFF / POWER DOWN 睡眠模式使用；裁剪掉不需要的协议栈模块可减少周期唤醒开销，但当前 SDK 的 POWER DOWN 睡眠仍为 61 µA+ 量级，低功耗产品需在硬件电源域层面继续优化。

Extension Points

• 新增功能模块裁剪开关：在 lib_*_config.c 中新增 const int 符号，并在顶层配置头文件中用宏控制其值，即可让预编译库按需裁剪新模块；模式参照 config_rcsp_stack_enable。
• 自定义段布局：在 .ld 中新增自定义段，并用 #pragma 或 __attribute__((section())) 将特定代码/数据放入，可精确控制其落在 Flash 还是 RAM。
• 多工程变体：补丁包同时维护 hid/ 与 ble_test/ 两套配置，说明同一 SDK 支持按产品（HID、BLE 透传测试、声箱）维护多套裁剪配置，建议用工程级配置头文件隔离差异，避免污染公共代码。
• SDK 版本升级路径：仓库内另有 补丁包/v1.2.0升级至v1.3.0蓝牙补丁/，升级蓝牙补丁后需重新核对裁剪配置与链接脚本是否仍然匹配，避免新库引入的符号与旧裁剪配置冲突。

Related Links

• AW30N README（中文） — 芯片特性与功耗基线
• README-en.md — 功耗声明（SOFT OFF 2 µA+ / POWER DOWN 61 µA+）
• lib_btstack_config.c（256KB 裁剪版） — 协议栈 Code & RAM 优化配置
• btstack 库链接脚本目录 — btstack_lib_text/bss/data.ld
• bt_controller 库链接脚本目录 — btctler_lib_text/bss/data.ld
• 256KB 裁剪补丁包目录 — 裁剪落地文件全镜像
• 相关页面：BLE 应用开发（GATT 角色配置）、OTA 升级（update.ld 布局）、低功耗设计（sniff / POWER DOWN）