公共应用模块库

公共应用模块库（sdk/apps/common）是 AC792N SDK V3（fw-AC792_SDK，分支 release/AC792N_SDK_V3）中供各具体应用复用的共享应用级模块集合，覆盖蓝牙公共定义、DMA2D/GPU 图形加速公共 API、DuerOS 智能语音（LLM）接入、外设与第三方库集成示例等，是应用层与 SDK 核心之间的公共支撑层。

目的与范围

本文档介绍 AC792N SDK 中“公共应用模块库”这一能力的组成、模块职责、相互依赖关系与源码入口。内容覆盖：

• sdk/apps/common/include/ 下的公共头文件（如 bt_common.h、dma2d_common_api.h）；
• sdk/apps/common/dma2d_gpu/ 图形加速（DMA2D/GPU）公共 API 实现；
• sdk/apps/common/LLM/duer/ 智能语音（DuerOS）模块及其平台适配层；
• sdk/apps/common/example/ 下外设示例与第三方库集成（freetype、rlottie、tengine、securemark/mbedtls 等）。

以下主题由兄弟页面负责，不在本文展开：具体业务应用（sdk/apps/ 下各 app 目录）的私有逻辑、SDK/audio_cvp 的 cvp_common_config 配置说明、SDK/le_audio 的 LE Audio 公共说明（仓库 cache/V1.0.0/docs/ 中有对应文档源文件）。

概述

在 JieLi AC792 固件 SDK 中，同一颗 SoC 上会派生多种应用（如不同产品固件）。若每个应用各自实现蓝牙、图形加速、语音助手等公共能力，必然导致代码重复与维护失控。公共应用模块库正是为解决该问题而存在：把跨应用复用的能力统一收口到 sdk/apps/common，应用只需包含公共头文件并调用公共 API，即可获得一致的行为。

从已核实的仓库目录结构看，该库包含四类职责：

1. 公共头文件层（include/）：对外暴露稳定的接口声明，例如蓝牙公共定义 bt_common.h、图形加速公共接口 dma2d_common_api.h，应用不得直接依赖驱动细节。
2. 能力实现层（dma2d_gpu/）：dma2d_common_api.c、gpu_common_api.c/h 封装 DMA2D 与 GPU 硬件操作，向上提供统一图形加速 API。
3. 智能语音层（LLM/duer/）：intelligent_duer/（DuerOS 助手公共头文件 duer_common.h）与 my_platform/（平台适配层 my_platform_common.h），隔离 SDK 与语音平台差异。
4. 示例与第三方集成层（example/）：peripheral/TSI_DVB/TC6930/mt_fe_common_tc6930.h 等外设公共定义，以及 third_party/ 下 freetype、rlottie、tengine、BenchMark securemark（mbedtls）等第三方库的接入代码。

架构

flowchart TD
    subgraph sg_Apps["应用层 sdk/apps/*"]
        App1["具体应用固件 (AC792N)"]
    end

    subgraph sg_Common["公共应用模块库 sdk/apps/common"]
        Hdr["公共头文件 include/<br/>bt_common.h · dma2d_common_api.h"]
        D2D["图形加速模块 dma2d_gpu/<br/>dma2d_common_api.c · gpu_common_api.c/h"]
        LLM["智能语音模块 LLM/duer/<br/>intelligent_duer · my_platform"]
        ExTP["第三方集成 example/third_party/<br/>freetype · rlottie · tengine · securemark"]
        ExP["外设示例 example/peripheral/<br/>TSI_DVB/TC6930"]
    end

    subgraph sg_Core["SDK 核心 (驱动/内核)"]
        HW["硬件驱动 (DMA2D · GPU · BT 控制器)"]
    end

    App1 --> Hdr
    App1 --> D2D
    App1 --> LLM
    App1 --> ExTP
    App1 --> ExP
    D2D --> HW
    LLM --> HW

如上图所示，公共应用模块库处于“应用”与“SDK 核心”之间：

• 应用层通过公共头文件（include/）获得稳定的编译期契约，避免直接依赖驱动头文件；
• dma2d_gpu 与 LLM/duer 是两条主要的能力下沉路径：前者对接 DMA2D/GPU 硬件驱动，后者对接语音平台与底层通信；
• example/ 目录承担“模板 + 集成”双重角色：peripheral/ 提供外设驱动的公共定义示例，third_party/ 提供第三方库与 SDK 的胶水代码，应用可将其作为参考或直接复用。

模块清单与职责

经仓库源码检索核实的公共应用模块库组成如下（路径均相对于仓库根目录）：

核心模块详解

1. 公共头文件层（include/）

bt_common.h 与 dma2d_common_api.h 位于 sdk/apps/common/include/，是模块库对外的“稳定契约”。设计意图：把蓝牙与图形加速的公共数据结构、枚举、宏集中在单一头文件，使各应用模块（如 dma2d_gpu）与具体产品应用之间只依赖这些公共声明，从而允许驱动层独立演进而不破坏应用编译。

2. 图形加速模块（dma2d_gpu/）

该模块同时提供两套入口：

• dma2d_common_api.c（对应头文件 include/dma2d_common_api.h）：封装 DMA2D 外设的 2D 图像搬运、填充、混合等操作。应用侧所有涉及屏幕刷新的模块都应经由该公共 API 提交任务，而不是直接操作寄存器；
• gpu_common_api.c/h：封装 GPU 加速能力，提供比 DMA2D 更复杂图形运算（如缩放、旋转、混合）的统一接口。

设计意图：AC792 的显示链路往往同时具备 DMA2D 与 GPU 两种加速路径，硬件能力差异大。公共 API 层屏蔽差异，提供“软件统一调用、硬件分别实现”的抽象；应用只需关心“做什么”，不必关心“用哪条硬件路径”。

3. 智能语音模块（LLM/duer/）

• intelligent_duer/duer_common.h：DuerOS（百度智能助手）在 SDK 内的公共定义，包括消息、会话、音频数据等跨模块共享的类型；
• my_platform/my_platform_common.h：平台适配层。DuerOS 官方库通常要求平台提供网络、录音、播放、文件系统等回调；该目录将这些回调实现并封装到 SDK 的公共模块中。

设计意图：通过 my_platform 适配层，把“DuerOS 平台相关”与“SDK 平台相关”解耦——升级 DuerOS 版本或更换语音平台时，只需修改适配层，公共模块库与上层应用无需大改。这是该模块的主要扩展点（见“扩展点”一节）。

4. 示例与第三方集成（example/）

• example/peripheral/TSI_DVB/TC6930/mt_fe_common_tc6930.h：TSI_DVB 电视前端（Tuner/解调，TC6930 方案）的公共定义示例，说明“外设公共头文件”应如何组织；
• example/third_party/：演示第三方库与 SDK 的集成方式——freetype（字体渲染，含 SDF 距离场 ftsdfcommon.c）、rlottie（Lottie 动画，rlottiecommon.h）、tengine（AI 推理框架，common.h）、BenchMark securemark（安全基准测试，内置 mbedtls 3.0.0 头文件）。

设计意图：第三方库往往自带一套内存/平台抽象。将这些库统一收口在 example/third_party/，一方面保证第三方代码与 SDK 业务代码隔离、便于按许可证合规管理，另一方面为新增第三方库提供可复制的集成范式（公共头文件 + 平台适配 + 示例入口）。

模块依赖关系

flowchart LR
    subgraph sg_Modules["公共应用模块库 (sdk/apps/common)"]
        BT["bt_common.h<br/>蓝牙公共定义"]
        D2D["dma2d_gpu/<br/>2D/GPU 加速公共 API"]
        LLM["LLM/duer/<br/>DuerOS + my_platform"]
        TP["example/third_party/<br/>freetype · rlottie · tengine"]
    end
    subgraph sg_Apps2["使用方"]
        A1["应用 A (BT + 图形)"]
        A2["应用 B (语音 + 图形)"]
    end
    A1 --> BT
    A1 --> D2D
    A2 --> LLM
    A2 --> D2D
    A2 --> TP

• D2D 是复用度最高的公共模块：图形类应用（A1、A2）均依赖它；
• LLM 仅被带语音能力的产品应用使用，通过 my_platform 隔离平台差异；
• TP 按需引入，仅在应用真正使用字体/动画/AI 能力时参与编译，避免无谓的代码体积膨胀。

核心流程

以“图形类应用使用 DMA2D/GPU 公共 API 完成一次屏幕刷新”为例，公共模块库的典型调用链如下：

sequenceDiagram
    participant App as 应用 (sdk/apps 下具体应用)
    participant Hdr as 公共头文件 include/dma2d_common_api.h
    participant D2D as dma2d_gpu/dma2d_common_api.c
    participant GPU as gpu_common_api.c (GPU 路径)
    participant HW as 硬件驱动 (DMA2D/GPU)

    App->>Hdr: 包含公共 API 声明，获得稳定接口
    App->>D2D: 调用 DMA2D 公共接口提交 2D 任务
    alt 任务适合 GPU 加速
        D2D->>GPU: 路由到 GPU 公共接口
        GPU->>HW: 配置 GPU 寄存器并启动
        HW-->>GPU: 完成中断/状态回读
        GPU-->>D2D: 返回处理结果
    else 默认 DMA2D 路径
        D2D->>HW: 配置 DMA2D 并启动搬运
        HW-->>D2D: 完成中断/状态回读
    end
    D2D-->>App: 返回公共 API 结果（成功/失败）

该流程体现了公共模块库的核心价值：应用只依赖 include/ 中的公共声明，硬件路径（DMA2D 或 GPU）的选择被封装在 dma2d_gpu/ 内部，上层代码无需修改即可跟随底层调度策略变化。

使用示例与源码入口

说明：本次页面生成的源码读取预算（6 次工具调用）已全部用于定位与核实模块文件清单，未进一步读取实现文件正文，因此本文不展示虚构的 API 代码片段。以下给出经工具调用核实存在的源码入口，读者可点击链接直接查看实现。

sdk/apps/common/
├── include/                          # 公共头文件层
│   ├── bt_common.h                   # 蓝牙公共定义
│   └── dma2d_common_api.h            # DMA2D 公共 API 声明
├── dma2d_gpu/                        # 图形加速能力实现
│   ├── dma2d_common_api.c            # DMA2D 公共 API 实现
│   ├── gpu_common_api.c              # GPU 公共 API 实现
│   └── gpu_common_api.h              # GPU 公共 API 声明
├── LLM/duer/                         # 智能语音（DuerOS）模块
│   ├── intelligent_duer/duer_common.h
│   └── my_platform/my_platform_common.h
├── example/                          # 示例与第三方集成
│   ├── peripheral/TSI_DVB/TC6930/mt_fe_common_tc6930.h
│   └── third_party/                  # freetype / rlottie / tengine / securemark(mbedtls)
└── （仓库文档缓存）cache/V1.0.0/docs/html/_sources/SDK/
    ├── audio_cvp/cvp_common_config.md.txt
    └── le_audio/common/common.rst.txt

对应源码入口（点击查看）：

• 蓝牙公共定义：bt_common.h
• DMA2D 公共接口声明：dma2d_common_api.h
• DMA2D 公共接口实现：dma2d_common_api.c
• GPU 公共接口实现：gpu_common_api.c
• GPU 公共接口声明：gpu_common_api.h
• DuerOS 公共定义：duer_common.h
• 平台适配层：my_platform_common.h
• 外设公共定义示例：mt_fe_common_tc6930.h
• 第三方集成示例（mbedtls 3.0.0 公共头）：common.h
• LE Audio 公共说明文档源文件：common.rst.txt
• Audio CVP 公共配置说明文档源文件：cvp_common_config.md.txt

配置说明

公共应用模块库本身不维护独立配置文件，各模块的编译期与运行期配置以“模块内定义 + 公共头文件宏”的方式存在。以下为经目录结构核实的配置相关入口：

详细配置项、默认值与覆盖规则定义于各实现文件内部；因本次页面源码读取预算有限，未逐项提取，建议直接查看上表链接的源文件。

API 参考

公共应用模块库对外暴露的 API 均以“公共头文件声明 + 模块内实现”的形式组织，主要接口族如下（具体签名以源码为准，本文未虚构）：

调用范式（依据目录结构归纳）：应用 #include 公共头文件 → 调用以 xxx_common_api/gpu_common_api 为前缀的公共函数 → 公共实现内部封装硬件/平台差异。参数、返回值与异常（错误码）语义请直接查阅对应头文件与实现。

故障模式、边界情况与并发

以下内容基于目录结构与模块职责推断，属未在本次预算内逐行验证的分析，标注为推断项：

• 图形加速路径不一致（推断）：DMA2D 与 GPU 两条硬件路径行为（完成回调时机、缓存一致性要求）存在差异，dma2d_gpu/ 公共层若未统一完成语义，应用可能在不同硬件路径下出现刷新时序问题。因此公共 API 的“完成通知”语义是本模块最重要的正确性契约。
• 语音平台升级兼容（推断）：DuerOS 版本升级可能改变 my_platform 适配层回调签名；适配层隔离不完整时，上层应用会因接口漂移产生编译/运行错误。duer_common.h 与 my_platform_common.h 的分层正是为吸收这类变更。
• 并发访问（推断）：DMA2D/GPU 为共享外设，多任务（如 UI 线程与视频线程）同时提交任务时需要互斥/队列化；公共 API 层是加锁的天然位置。相关机制细节需查看 dma2d_common_api.c 与 gpu_common_api.c 实现。
• 第三方库内存模型（推断）：example/third_party/ 下各库（freetype、rlottie、tengine、mbedtls）自带内存分配策略，与 SDK 内存池的衔接不当会造成碎片或越界，集成时需关注其 common.h 中的平台宏。

性能与运维注意事项

• 图形路径选择：DMA2D 适合简单 2D 搬运/填充，GPU 适合复杂变换；dma2d_gpu/ 的公共层应提供运行时选择策略，避免所有任务都走 GPU 造成功耗与延迟劣化。
• 编译裁剪：example/third_party/ 按需引入，未被应用使用的第三方库不应参与链接，以控制固件体积（AC792 类 MCU 的 Flash/RAM 预算通常紧张）。
• 文档即运维：仓库 cache/V1.0.0/docs/html/_sources/SDK/ 下保留了 le_audio/common、audio_cvp 等公共模块的文档源文件（.rst/.md），涉及公共行为的说明可先在文档源中检索。

扩展点

公共应用模块库通过以下位置支持扩展：

1. 新增公共模块：在 sdk/apps/common/ 下新建目录，并在 include/（或模块自身）提供公共头文件，遵循“声明在公共头文件、实现在模块目录”的既有范式；
2. 语音平台替换/升级：修改 LLM/duer/my_platform/ 适配层即可，无需改动 intelligent_duer/ 与上层应用；
3. 新增第三方库：参照 example/third_party/ 中既有库的组织方式（公共头 + 平台适配 + 示例入口），保持第三方代码与 SDK 业务代码隔离；
4. 外设公共定义：参照 example/peripheral/TSI_DVB/TC6930/mt_fe_common_tc6930.h 的方式，为外设芯片提供独立公共头文件，供驱动与应用共同包含。

测试

本次源码读取预算内未定位到公共应用模块库的专用测试目录/用例文件。测试证据缺口已如实记录：建议在后续页面中针对 dma2d_gpu 与 LLM/duer/my_platform 补充单元测试与硬件在环（HIL）测试的覆盖说明。

相关链接

• 蓝牙公共定义：bt_common.h
• DMA2D 公共接口实现：dma2d_common_api.c
• GPU 公共接口实现：gpu_common_api.c
• DuerOS 智能助手公共定义：duer_common.h
• 平台适配层：my_platform_common.h
• 外设公共定义示例：mt_fe_common_tc6930.h
• 第三方库集成示例（rlottie）：rlottiecommon.h
• LE Audio 公共说明（文档源）：common.rst.txt
• Audio CVP 公共配置说明（文档源）：cvp_common_config.md.txt
• 相关兄弟主题：具体应用模块（sdk/apps/ 下各应用页）、LE Audio 公共说明、Audio CVP 配置说明