蓝牙与扩展连接接口

本文档介绍 fw-AD16N_GP-MCU_SDK 平台库中「蓝牙与扩展连接」的集成接口，涵盖经典蓝牙（BR/EDR）与低功耗蓝牙（BLE）双协议栈的宿主（Host）/控制器（Controller）分层、编译期配置宏、系统掉电存储（VM）中的蓝牙配置项，以及蓝牙库在固件中的链接与内存布局方式。

Purpose and Scope

本页面向 SDK 使用者和平台工程师，说明如何在 AD16N 平台上接入、配置并调试蓝牙连接能力。内容包括：

蓝牙双协议栈（btstack 主机层 + BT 控制器层）的分层结构与链接方式
bt_includes.h 集成头文件中的编译期配置宏及其设计意图
sys_memory.h 中蓝牙/BLE 相关的 VM 掉电存储配置项
蓝牙库在 text/data/bss 段的内存布局（链接脚本）
上电初始化、连接建立与数据收发的典型流程

本页不涵盖以下内容（由其他目录页负责）：音频编解码与 EQ 处理、电源管理与低功耗策略、GPIO/UART 等外设驱动、TWS 具体配对算法（平台默认关闭）。仓库中的蓝牙协议栈以预编译库形式提供，具体 profile API 的签名（如 GATT/SPP 函数原型）未包含在本仓库源码中，本文基于仓库内可验证的集成面进行说明，并明确标注信息边界。

Overview

AD16N 平台（BD49 CPU）的蓝牙连接能力采用经典的双层软件架构：

BT 控制器（Controller）：负责物理层（RF）、基带与链路层（Link Layer）处理，以预编译库形式提供，链接脚本位于 sdk/apps/include_lib/bt_controller_include/（btctler_lib_bss.ld、btctler_lib_data.ld、btctler_lib_text.ld）。
BT 主机（Host / btstack）：实现 HCI、L2CAP、SDP、GATT、AVCTP 等协议与 profile，同样以预编译库提供，链接脚本位于 sdk/apps/include_lib/bt_include/（btstack_lib.ld 及 bss/data/text 三个段的辅助脚本）。

上层应用通过 bt_includes.h 这一统一入口包含 CPU、时钟、CRC、日志、硬件中断、自旋锁、电源接口、看门狗、tick 定时器等基础依赖，从而保证蓝牙库与整个固件运行环境的一致性。与此同时，蓝牙状态（本地信息、模式、远端数据库、频偏校准等）通过 sys_memory.h 定义的 VM（掉电可保存存储）配置项持久化，使配对与连接信息在设备重启后仍能恢复。

设计上，这种「预编译库 + 链接脚本 + 编译期宏」的集成方式，把协议栈实现细节与产品代码隔离：产品工程师只需在头文件中用宏开关选择功能（如 BR/EDR、TWS、EDR API），链接器脚本负责把库的代码/数据放置到正确的内存段，应用代码则通过统一的系统存储接口读写蓝牙状态。

Architecture

flowchart TD
    subgraph sg_App["应用层（产品代码）"]
        App["应用 / profile 业务逻辑"]
    end

    subgraph sg_Host["BT 主机层（btstack 预编译库）"]
        BTStack["btstack 主机<br/>btstack_lib.ld"]
        Profile["AVCTP / SPP / GATT 等 profile"]
    end

    subgraph sg_Ctrl["BT 控制器层（预编译库）"]
        Controller["BT 控制器<br/>btctler_lib_*.ld"]
        RF["RF / 基带硬件"]
    end

    subgraph sg_Sys["平台系统服务"]
        SysMem["VM 掉电存储<br/>sys_memory.h"]
        BtLog["蓝牙日志<br/>bt_log.h"]
        BtInc["集成入口<br/>bt_includes.h"]
    end

    App --> BtInc
    BtInc --> BTStack
    BTStack --> Profile
    BTStack --> Controller
    Controller --> RF
    BTStack --> SysMem
    Controller --> SysMem
    App --> BtLog
    BTStack --> BtLog

架构要点：

分层调用链：应用代码不直接接触射频硬件，而是经过 btstack 主机层 → BT 控制器层 → RF 硬件。主机层封装了协议细节，控制器层屏蔽了基带时序，二者通过 HCI 命令/事件交互。
统一集成入口：bt_includes.h 聚合了蓝牙库编译所需的全部平台基础头文件（cpu.h、crc16.h、clock.h、bt_log.h、hwi.h、spinlock.h、power_interface.h、wdt.h、tick_timer_driver.h 等），保证库与系统时钟、中断、电源、看门狗服务的版本一致。
持久化解耦：配对信息、远端设备数据库、BLE 模式信息通过 VM 存储读写，使协议栈状态与具体存储介质（flash）解耦，便于跨平台移植。
预编译库 + 段布局：btstack_lib.ld / btctler_lib_*.ld 将库的 text（代码）、data（已初始化数据）、bss（未初始化数据）放置到链接器脚本指定的内存区域，这是裸机平台把第三方预编译库接入自身内存映射的标准做法。

REGISTER_UPDATE_TARGET 是典型的「段属性」注册宏：任何模块通过它声明一个 struct update_target 变量放入 .update_target 链接段，升级框架遍历该段即可找到所有可升级目标，无需维护注册表。__BANK_* 宏则标记 AVCTP（音频/视频控制传输协议）与 RF 相关代码所属的 bank，供链接脚本在 bank 切换方案中定位代码。

预编译库链接脚本

蓝牙栈在 AD16N 上以预编译库（archive）形式提供，仓库内只包含其链接脚本。链接脚本的作用是把库中的代码和数据精确放置到目标内存：

库	链接脚本	作用
btstack 主机	`sdk/apps/include_lib/bt_include/btstack_lib.ld`	主机库整体布局
btstack 主机	`btstack_lib_bss.ld` / `btstack_lib_data.ld` / `btstack_lib_text.ld`	分别定义库的未初始化数据、已初始化数据、代码段放置
BT 控制器	`sdk/apps/include_lib/bt_controller_include/btctler_lib_bss.ld` / `btctler_lib_data.ld` / `btctler_lib_text.ld`	控制器库的三段放置

这种 text/data/bss 三段分离的脚本约定，使同一份预编译库可以适配不同 RAM/ROM 布局的芯片变体，也方便把耗时关键的控制器代码固定到高速内存区域。

系统存储中的蓝牙配置项

蓝牙状态通过 sys_memory.h 中的 VM 枚举持久化。与蓝牙直接相关的配置项如下：

CFG_BT_TRIM_INFO            = 4,
VM_BLE_LOCAL_INFO           = 5,
CFG_BT_FRE_OFFSET           = 6,    //BT 频偏
...
//蓝牙类配置项[]
CFG_BLE_MODE_INFO           = 15,
CFG_TWS_PAIR_AA,
...
VM_BLE_REMOTE_DB_INFO,
VM_BLE_REMOTE_DB_00,
VM_BLE_REMOTE_DB_01,
VM_BLE_REMOTE_DB_02,
VM_BLE_REMOTE_DB_03,
VM_BLE_REMOTE_DB_04,
VM_BLE_REMOTE_DB_05,
VM_BLE_REMOTE_DB_06,
VM_BLE_REMOTE_DB_07,
VM_BLE_REMOTE_DB_08,

Source: sys_memory.h

各配置项含义：

CFG_BT_TRIM_INFO：BT 射频 trim（校准）信息，出厂校准后写入，掉电不丢。
VM_BLE_LOCAL_INFO：BLE 本地信息（如设备地址、随机地址等），VM 前缀表明这是可运行时改写并持久化的存储。
CFG_BT_FRE_OFFSET：BT 频偏补偿值，用于射频性能补偿。
CFG_BLE_MODE_INFO：BLE 模式信息（广播/连接等模式状态）。
CFG_TWS_PAIR_AA：TWS 配对地址信息（TWS 使能时使用）。
VM_BLE_REMOTE_DB_INFO + VM_BLE_REMOTE_DB_00 ~ 08：BLE 远端设备数据库（共 9 个槽位），用于保存已配对远端设备信息，实现重连免配对。

设计意图：把「配置（CFG_，出厂/编译期决定）」与「易变数据（VM_，运行时改写）」分开命名，体现了系统存储的分层语义——校准与模式信息适合只读配置管理，而配对数据库必须支持运行时写回。

Core Flow

上电初始化与连接建立流程

flowchart TD
    Start([上电复位]) --> Inc["包含 bt_includes.h<br/>引入平台基础头文件"]
    Inc --> Macro{"编译期宏配置<br/>CONFIG_NEW_BREDR_ENABLE / TWS / EDR"}
    Macro -->|"按宏裁剪功能"| Link["链接 btstack 与 btctler 库<br/>text/data/bss 段布局"]
    Link --> VM["读取 VM 蓝牙配置<br/>VM_BLE_LOCAL_INFO / REMOTE_DB 等"]
    VM --> Stack["BT 栈初始化<br/>（主机层 + 控制器层）"]
    Stack --> Idle["等待连接 / 广播"]
    Idle --> Conn["连接建立"]
    Conn --> Pair{"已配对设备?"}
    Pair -->|"是（命中 VM_BLE_REMOTE_DB）"| Reconnect["免配对重连"]
    Pair -->|"否"| Pairing["配对流程"]
    Pairing --> Save["保存远端信息到 VM<br/>VM_BLE_REMOTE_DB_xx"]
    Reconnect --> Active["数据收发<br/>（ACL / ATT）"]
    Save --> Active

流程说明：

编译期裁剪：bt_includes.h 中的宏在编译时决定库功能集合（如是否含 TWS、是否保留 EDR API）。这一步发生在链接之前，直接影响最终固件体积。
段放置：链接脚本把 btstack 与控制器库的 text/data/bss 段放入各自内存区域，保证预编译库与固件其余部分共存。
状态恢复：栈初始化阶段读取 VM 中的蓝牙配置（本地信息、频偏、模式、远端数据库），使设备具备「重启后保持上次连接状态」的能力。
连接与配对：连接建立后，栈查询远端数据库决定是否需要重新配对；配对成功后把远端信息写入 VM_BLE_REMOTE_DB_xx 槽位，供下次快速重连。

主机-控制器交互时序

sequenceDiagram
    participant App as 应用层
    participant Host as btstack 主机库
    participant Ctrl as BT 控制器库
    participant RF as 射频硬件
    participant VM as VM 存储

    App->>Host: 发起连接/开启广播
    Host->>Ctrl: HCI 命令（寻呼/扫描）
    Ctrl->>RF: 基带/RF 操作
    RF-->>Ctrl: 链路事件
    Ctrl-->>Host: HCI 事件（连接完成）
    Host-->>App: 连接建立回调
    Host->>VM: 保存远端信息<br/>VM_BLE_REMOTE_DB_xx
    App->>Host: 数据发送（ACL/ATT）
    Host->>Ctrl: 数据包下发
    Ctrl-->>Host: 数据确认/接收
    Host-->>App: 数据接收回调

该时序展示了经典的 HCI 分层模型：应用只与主机层交互，主机层负责将连接请求翻译为 HCI 命令、把控制器上报的事件转译为应用回调，并在关键状态变化时（如配对完成）通过 VM 存储持久化。

使用示例

示例 1：配置蓝牙功能宏（编译期裁剪）

在 bt_includes.h 中调整宏以控制蓝牙子系统功能集合：

#define CORE_V42_PHY_DEBUG_EN 0
// #define CONFIG_FPGA_ENABLE
#define THIRD_PARTY_PROFILE_ENABLE 0
#define CONFIG_NEW_BREDR_ENABLE
#define TCFG_USER_TWS_ENABLE 0
#define CLOSE_EDR_API 0

Source: bt_includes.h

典型用法：默认配置关闭 TWS、保留 EDR API、使能经典蓝牙。需要减小固件体积时可设 CLOSE_EDR_API 1；需要 TWS 的产品应设 TCFG_USER_TWS_ENABLE 1 并配套实现配对逻辑。

示例 2：注册升级目标（库升级集成）

蓝牙库升级通过 REGISTER_UPDATE_TARGET 宏把升级目标放入 .update_target 段：

#define REGISTER_UPDATE_TARGET(target) \
        const struct update_target target sec(.update_target)

Source: bt_includes.h

设计意图：任何模块声明 REGISTER_UPDATE_TARGET(xxx) 后，升级框架遍历 .update_target 段即可发现全部升级目标，新增目标无需改动框架代码——这是嵌入式平台常见的「链接期注册」模式。

示例 3：引用蓝牙 VM 配置项（持久化状态）

应用代码通过 sys_memory.h 中的枚举访问蓝牙掉电存储项：

CFG_BT_TRIM_INFO            = 4,
VM_BLE_LOCAL_INFO           = 5,
CFG_BT_FRE_OFFSET           = 6,    //BT 频偏
...
//蓝牙类配置项[]
CFG_BLE_MODE_INFO           = 15,
CFG_TWS_PAIR_AA,
...
VM_BLE_REMOTE_DB_INFO,
VM_BLE_REMOTE_DB_00,

Source: sys_memory.h

这些枚举值直接用于系统存储 API（读取/写入 VM 项），例如配对完成后将远端设备信息写入某个 VM_BLE_REMOTE_DB_xx 槽位。具体存储 API 的签名位于系统存储模块（见相关链接），本页不重复展开。

配置选项

编译期宏（bt_includes.h）

宏	类型	默认值	说明
`CONFIG_NEW_BREDR_ENABLE`	宏定义	定义（使能）	启用新一代 BR/EDR（经典蓝牙）支持
`TCFG_USER_TWS_ENABLE`	整数	0	用户 TWS 功能开关；1=使能
`CLOSE_EDR_API`	整数	0	是否裁剪 EDR API；1=裁剪以减小体积
`THIRD_PARTY_PROFILE_ENABLE`	整数	0	第三方 profile 支持开关
`CORE_V42_PHY_DEBUG_EN`	整数	0	BLE 4.2 PHY 调试开关
`CONFIG_FPGA_ENABLE`	宏定义	注释掉（关闭）	FPGA 验证平台模式

蓝牙 VM/配置存储项（sys_memory.h）

配置项	编号	类型	说明
`CFG_BT_TRIM_INFO`	4	只读配置	BT 射频 trim（校准）信息
`VM_BLE_LOCAL_INFO`	5	可写 VM	BLE 本地信息
`CFG_BT_FRE_OFFSET`	6	只读配置	BT 频偏补偿值
`CFG_BLE_MODE_INFO`	15	配置	BLE 模式信息
`CFG_TWS_PAIR_AA`	16（紧随 15）	配置	TWS 配对地址信息
`VM_BLE_REMOTE_DB_INFO`	枚举	可写 VM	BLE 远端数据库元信息
`VM_BLE_REMOTE_DB_00 ~ 08`	枚举	可写 VM	BLE 远端设备数据库槽位（9 个）

注：编号列来自 sys_memory.h 中的显式赋值（4、5、6、15），其余枚举项由编译器自动递增。

API Reference

信息边界说明：AD16N 的蓝牙协议栈（btstack 主机 + BT 控制器）以预编译库形式发布，本仓库仅包含其链接脚本与集成头文件，profile 级 API 的函数原型未包含在本仓库源码中（参见 sdk/apps/include_lib/bt_include/ 与 sdk/apps/include_lib/bt_controller_include/ 目录）。以下列出仓库内可验证的接口面：

`REGISTER_UPDATE_TARGET(target)`（宏）

将升级目标注册到 .update_target 链接段。

参数：target — struct update_target 类型的变量名
返回值：无（声明语句）
使用方式：在任意编译单元中 REGISTER_UPDATE_TARGET(my_target);，升级框架遍历该段完成发现
来源：bt_includes.h#L102-L103

库分段标记宏（`__BANK_*`）

宏	用途
`__BANK_AVCTP_ENTRY` / `__BANK_AVCTP`	标记 AVCTP（音频/视频控制传输协议）代码所属 bank
`__BANK_RF_ENTRY` / `__BANK_RF` / `__BANK_RF_TRIM`	标记 RF 相关代码与 trim 代码的 bank 归属

来源：bt_includes.h#L107-L111

TWS 默认关闭：TCFG_USER_TWS_ENABLE 默认 0。若产品需要 TWS 而忘记打开该宏，CFG_TWS_PAIR_AA 等存储项将不被使用，配对状态无法持久化，表现为「每次重启都重新配对」。
EDR API 裁剪影响：设 CLOSE_EDR_API 1 后，依赖 EDR 的 profile 将不可用。启用裁剪前必须确认产品特性集（如高速数据传输场景）不依赖 EDR。
远端数据库槽位有限：VM_BLE_REMOTE_DB_00 ~ 08 共 9 个槽位。超过槽位上限时，旧的远端信息可能被覆盖或无法保存，表现为多设备交替连接场景下的重连失败。应用层需要自行实现槽位替换策略。
预编译库版本一致性：库以预编译形式提供，链接脚本必须与库版本匹配。text/data/bss 段布局不匹配会导致链接错误或运行时内存越界——这是库升级时最易出现的故障，应通过 REGISTER_UPDATE_TARGET 走标准升级流程。
VM 写入时机与掉电：配对信息写入 VM 属于运行时写操作，若在写入过程中掉电，可能导致存储项损坏。产品设计上应在配对流程的稳定阶段（连接建立后）写库，并利用 VM 机制的原子性保证（由系统存储模块提供）。
并发与中断上下文：蓝牙事件（HCI 事件回调）可能在中断/高优先级任务上下文中到达，应用回调中不应执行长时间阻塞操作或直接调用 VM 写入；建议通过任务队列转发到应用上下文处理。

性能与运维注意事项

内存占用：btstack 主机库与控制器库的 bss/data 占用与编译期宏相关——关闭 TWS（TCFG_USER_TWS_ENABLE 0）、裁剪 EDR（CLOSE_EDR_API 1）、关闭第三方 profile 可显著减小 RAM/ROM 占用，适合资源紧张的 MCU 产品。
代码放置：控制器库的 text 段（btctler_lib_text.ld）承载对时序敏感的基带处理，链接时应放置于高性能内存；RF trim 代码（__BANK_RF_TRIM）与频偏补偿（CFG_BT_FRE_OFFSET）直接影响射频性能，出厂前必须完成校准写入。
日志开销：bt_log.h 日志在调试阶段可全量开启；量产固件建议关闭或降级，避免日志 IO 干扰蓝牙实时性。
升级路径：蓝牙库的升级通过 .update_target 段注册目标实现，升级框架遍历该段即可更新协议栈，无需重新烧录整个固件。

扩展点

编译期宏裁剪（bt_includes.h）：通过宏开关选择协议栈功能集合，是最主要的扩展/裁剪入口。
VM 存储槽位（sys_memory.h）：VM_BLE_REMOTE_DB_xx 为多设备配对提供了可扩展的持久化模型；新增槽位需在枚举中追加项并注意与既有存储布局的兼容。
升级目标注册（REGISTER_UPDATE_TARGET）：新增可升级组件只需声明宏即可接入统一升级框架。
第三方 profile：THIRD_PARTY_PROFILE_ENABLE 预留了第三方 profile 的接入开关；启用后需按预编译库约定的接口实现 profile 注册。
日志框架：bt_log.h 作为蓝牙日志的统一出口，可对接平台级日志系统实现分级输出与远程抓取。

测试与验证建议

仓库内蓝牙相关文件以链接脚本与集成头文件为主，未包含协议栈单元测试源码（协议栈以预编译库提供）。建议的验证手段：

编译冒烟：验证各宏组合（TWS 开/关、EDR 裁剪、第三方 profile 开关）下链接脚本与内存布局正确，无 text/data/bss 段溢出。
连接回归：验证配对信息写回 VM_BLE_REMOTE_DB_xx 后，重启可免配对重连；验证 9 个槽位在多设备交替场景下的行为。
校准验证：确认 CFG_BT_TRIM_INFO 与 CFG_BT_FRE_OFFSET 写入后射频指标（频偏、灵敏度）达标。
升级验证：通过 REGISTER_UPDATE_TARGET 注册的升级目标执行库升级，验证升级后协议栈功能完整。

系统存储与 VM 配置（sys_memory.h）
蓝牙集成头文件（bt_includes.h）
蓝牙日志（bt_log.h）
btstack 主机库链接脚本
BT 控制器库链接脚本
相关目录页：音频处理平台库（audio_eq）、电源管理平台库、外设驱动平台库（GPIO/UART）