SDK 开发指南

概述

本指南介绍 HiDiTingV100 SDK 的目录与构建系统、组件接入、特性配置、系统适配、固件部署和调试方法，帮助开发者在现有 SDK 框架中完成应用及产品功能开发。

阅读说明

目标读者

本文面向第一次接触 HiDiTingV100 SDK，或需要完成以下工作的开发者：

• 搭建并检查开发环境；
• 选择目标、编译 A 核应用或生成完整固件包；
• 理解 SDK 目录、启动流程和组件接入方式；
• 配置显示、蓝牙、媒体、音频、低功耗、外设、时钟和 Flash；
• 获取构建产物、烧录固件并使用 UART/RTT 调试；
• 在现有 SDK 框架中集成自有代码或第三方静态库。

接口参数、返回值、结构体和错误码不在本文重复展开，请从 API 参考进入对应模块；可运行示例的索引请参见 Samples 示例代码。

适用范围与约定

• 本文适用于当前 HiDiTingV100 SDK，命令默认在 hs-fbb/src 目录执行。
• 目标、组件、宏和路径以 SDK 中的 config.py、Kconfig、CMake、构建脚本及实际源码为准。
• 接口参数、返回值、结构体和错误码由 API 参考说明，本文只描述开发流程和集成位置。
• SEGGER RTT、AW88166 等未随 SDK 完整提供的第三方源码，需要从版权所有者处合法取得并完成适配验证。
• 清理输出目录、修改分区或覆盖二进制文件前，应先确认 SDK 根目录并备份相关文件。

按任务阅读

任务	建议阅读
第一次编译完整固件	开发准备 → 快速开始 → 启动编译
了解可修改范围	SDK 目录与构建系统 → 系统适配对接 → 系统启动适配
添加组件或第三方库	CMake 编译系统 → 三方库集成编译
修改产品特性	特性配置 → 对应的显示、蓝牙、媒体、音频、低功耗、外设、时钟或 Flash 小节
获取、烧录和核对产物	编译结果获取 → Bin 文件描述 → 烧录 → 代码部署
调试运行问题	调试环境 → RTT 调试

开发准备

HiDiTingV100 SDK 按照交付和集成方式提供两类编译构建模式：

• 对接型编译系统：SDK 作为芯片解决方案提供底层能力，与产品既有编译框架对接。HiDiTingV100 支持基于 CMake 的编译框架对接。
• 开发者模式编译系统：使用 SDK 提供的完整编译框架，通过 HiSpark Studio 或命令行工具进行工程开发、特性配置和固件构建。

开发环境选择

说明： 本文示例命令以一站式 CLI 为主。实际开发可从以下三种环境中选择，推荐使用一站式 CLI。

开发环境	适用场景	使用指南
一站式 CLI（推荐）	快速完成目标选择、构建、烧录和串口监视	一站式 CLI 开发环境使用指南
HiSpark Studio for VS Code	图形化编辑、编译、烧录和调试	HiSpark Studio for VS Code 开发环境使用指南
WSL 与 Docker	在 Windows 上使用一致的 Linux 容器构建环境	WSL 与 Docker 环境使用指南

HiDiTingV100 SDK 支持命令行、HiSpark Studio 和 WSL/Docker 等开发环境。安装和配置方法统一参见开发环境快速入门，建议优先使用一站式 CLI 开发环境。

编译系统注意事项

HiDiTingV100 SDK 支持 Windows 和 Linux 环境下的 Python、CMake 与 LLVM 构建流程，也支持在 Windows 下通过 HiSpark Studio 构建。Windows 构建需要 Ninja，SDK 工具包中提供对应的 ninja.exe。

diting-community 的 config.py 默认直接传递公共头文件和宏。遇到命令行长度限制时，可在确认工具链支持响应文件后启用 CONFIG_PUBLIC_OPTION_IN_FILES，配置位置见图 1。

图 1 Windows 编译宏配置

准备一台 HiDiTingV100 开发板、可传输数据的 USB 线和一台 Windows 或 Linux 开发主机。使用命令行流程时，先完成一站式 CLI 环境安装；使用图形化流程时，先完成 HiSpark Studio 工程配置。

快速开始

环境安装、目标选择、固件构建、打包、烧录和串口验证请参见开发环境快速入门，建议优先使用一站式 CLI 开发环境。

本文后续章节聚焦 SDK 目录、组件接入、目标配置、系统适配和调试方法。完成源码或配置修改后，按上述快速入门重新构建对应目标，并检查产物、链接映射与目标板运行结果。

SDK 目录与构建系统

src 目录存放 SDK 软件代码、构建工程，以及 A 核、BT 核和 DSP 核运行所需的二进制文件。SDK 支持基于 A 核源码进行增量开发；BT 核以固定二进制提供。DSP 基础镜像 dsp_main.bin 不支持修改，dsp_overlay.bin 可按本指南的受控流程替换 SDK 已提供的算法或参数文件。

以下路径均相对于 hs-fbb/src。

src 目录包含如表 1所示子目录。

表 1 src目录

application	应用目录，支持用户在此目录下增量开发上层系统内容以及应用内容。全系统启动的代码也在此目录下。当前SDK会在此目录下提供部分sample代码用于客户开发参考。
bootloader	用于存放系统启动过程中二进制文件加载流程的代码。
build	编译构建工程代码。
drivers	设备驱动代码，提供BSP驱动代码。
include	公共头文件。
interim_binary	软件库、二进制文件存放目录。
kernel	操作系统以及操作系统功能封装代码。
libs_url	存放部分编译脚本。
middleware	中间件代码，提供系统框架代码。
ohos	开源相关组件代码。
open_source	开源相关组件代码。
protocol	协议相关组件代码。
output	编译构建版本生成目录（发布的SDK下无此目录，用户构建后生成）。
tools	开发工具及编译工具链。
vendor	用于存放第三方应用或外部组件。需要接入外部组件时可创建该目录，SDK 根目录的 CMake 配置会按目录存在性加载。
build.py	编译入口脚本。
CMakeLists.txt	cmake编译公共文件。
config.in	Kconfig公共配置文件。

SDK 构建系统由 CMake 组件、目标配置、构建脚本和工具链共同组成。以下内容依次说明构建框架、目标选择、产物获取和第三方库接入。

CMake 编译系统

CMake编译系统框架描述：

|-- cmake
|   |-- build_component.cmake       // 组件编译相关
|   |-- build_function.cmake        // 编译系统公共函数
|   |-- build_linker.cmake          // 链接脚本处理
|   |-- global_variable.cmake       // 初始化全局变量，避免因为增量编译导致CMakeCache膨胀
|   |-- fbb-config.cmake            // fbb 构建入口配置
|-- config             // 构建及工具配置
|   |-- target_config/3322  // 编译target配置
|       |-- target_config.py        // target模板配置
|       |-- config.py          // 项目具体的配置， 最终的配置为模板配置 + 具体配置
|       |-- ../common_config.py // 构建公共参数配置，存放公共宏、公共编译选项和组件集合
|-- script                      // 编译框架公共脚本
|   |-- cmake_builder.py            // 组件构建命令
|   |-- enviroment.py               // 用于接收和解析命令，根据target_name组织各种编译参数
|   |-- utils/build_utils.py        // 构建脚本公共函数
|-- toolchains          // 存放工具链
|   |-- clang_riscv_linx_26_03_1.cmake // 当前 RISC-V 编译工具链配置

启动构建

目标选择、命令行构建、完整固件打包及图形化构建步骤请参见开发环境快速入门，建议优先使用一站式 CLI 开发环境。

SDK 的底层构建入口见 build.py，目标定义见 config.py，构建产物统一写入 <FBB_SDK_DIR>/output。需要排查底层参数时，以当前源码中的入口定义为准。

底层构建入口未直接匹配到唯一 target 时，会列出可选 target 和整包别名供开发者选择。当前 config.py 定义 8 个独立 target 和 4 个整包 target group；实际列表以当前源码为准。

图 1 SDK 构建目标选择界面

图 2 完整固件包构建目标选择界面

各组件编译描述

编译 target 与对应二进制关系如表 1所示。

表 1 编译target与bin文件对应关系

编译target	bin文件	说明
diting-community、diting-community-native-js、diting-community-xts、diting-community-bike	application.bin	LiteOS A 核应用镜像。
3322-ssb	ssb.bin	用于启动和加载的版本。

编译结果获取

对应二进制获取路径如表 1所示。

表 1 二进制获取路径

bin文件	路径
ssb.bin / ssb_signed.bin（Linux环境下编译）	src\output\3322\acore\3322-ssb\（备份签名镜像另见 backup3322-ssb\ssb_backup_signed.bin）
application.bin（Linux环境下编译）	src\output\3322\acore\<target>\，例如 diting-community-bike 输出到 src\output\3322\acore\diting-community-bike\
ssb.bin / ssb_signed.bin（Windows环境下编译）	src\output\3322\acore\3322-ssb\（备份签名镜像另见 backup3322-ssb\ssb_backup_signed.bin）
application.bin（Windows环境下编译）	src\output\3322\acore\<target>\，例如 diting-community-bike 输出到 src\output\3322\acore\diting-community-bike\

Bin文件描述

表 1 bin文件说明

bin文件	说明
ssb_signed.bin	boot启动加载所需二进制文件。
application.bin	A 核系统版本二进制文件，可通过 SDK 的 A 核源码增量开发后生成。
bt_signed.bin	bt核系统二进制文件，固定版本发布，不支持增量开发。
dsp_main.bin / dsp_overlay.bin	dsp_main.bin 为固定发布的 DSP 基础镜像；dsp_overlay.bin 可按音频 DSP 镜像章节的流程替换已交付算法或参数。

当前版本的bt和dsp组件通过文件系统加载，需通过DebugKits将“\src\tools\pkg\bin\3322\bt_signed.bin”和“\src\tools\pkg\bin\3322\dsp\normal\”下的“dsp_main.bin”、“dsp_overlay.bin”上传，具体加载路径为：

• dsp加载路径：/boot/dsp/dsp_overlay.bin
• dsp加载路径：/boot/dsp/dsp_main.bin
• bt加载路径：/boot/bt/bt_signed.bin；社区开发板不推这个组件，喂看门狗超时20s会导致重启。

target简介

系统默认适配了多个 target，继承关系与关键差异可在当前 config.py 中核对：

表 1 编译任务简介

target	用途	关键能力
3322-ssb	安全启动阶段	基于 target_ssb_template_3322，生成 SSB 启动镜像。
3322-seliteos-release	SELiteOS 安全侧镜像	包含 TA、PSA Crypto、Storage 和 Attestation 等安全组件。
3322-loaderboot	LoaderBoot 镜像	提供装载、Flash 操作、上传和软件哈希等启动阶段能力。
3322-recovery	恢复镜像	用于升级恢复和文件系统装载，不作为上层应用开发目标。
diting-community-native-js	Native/JS 上层应用	LiteOS、UIkit、NandFlash、MIPI、PSRAM、Native-JS 应用框架；使用 8 MiB Nor Flash 配置。
diting-community-xts	OpenHarmony XTS 测试镜像	继承 diting-community-native-js，增加 XTS_SUPPORT、CONFIG_DITING_XTS 和 XTS 组件集。
diting-community	Diting 蜂窝产品	LiteOS、UIkit、NandFlash、MIPI、PSRAM、Native-JS、GNSS 与 CAT1 通话；启用 GNSS/CAT1 相关组件并使用 16 MiB Nor Flash 配置。
diting-community-bike	Diting Bike 产品	基于 Bike 应用模板，使用 800×480 高分辨率图形配置、media_bike、ohos_bike_set、bike_set 和 Bike DSP，并使用 16 MiB Nor Flash 配置。

完整固件使用 target group 构建。四个组合分别是 pack_diting_community_native_js、pack_diting_community_xts、pack_diting_community 和 pack_diting_community_bike，都会联动构建 LoaderBoot、SSB、Recovery、SELiteOS 以及对应应用 target。开发者通常选择 target group 生成可烧录的 .fwpkg，仅在调试单个镜像时选择独立 target。

三方库集成编译

库的引入一般是头文件+库，此处以“libsample_b.a”为例。分为两步：

1. 在依赖三方库的组件的“CMakeLists.txt”下，添加头文件依赖，示例如下：

   假设将“sample_b.h”放置在CMakeLists根路径下。

   

2. 在依赖三方库的组件的“CMakeLists.txt”下，添加三方库，示例如下：

   假设将“libsample_b.a”放置在“CMakeLists.txt”根路径下：

   find_library(LIB_SAMPLE_B "libsample_b.a" ${CMAKE_CURRENT_SOURCE_DIR})
   target_link_libraries(${TARGET_NAME} PRIVATE
       -Wl,--whole-archive
       ${LIB_SAMPLE_B}
       -Wl,--no-whole-archive
   )
   

   --whole-archive 必须使用 --no-whole-archive 成对收束，避免影响后续库。该写法与 SDK 现有 /src/libs_url/3322/cmake/ims.cmake 的链接方式一致。配置阶段若出现 LIB_SAMPLE_B-NOTFOUND，先检查库文件名、路径和库的 RISC-V ABI，不要继续打包。

   

特性配置与系统集成

特性配置

硬件配置特性

当前编译系统提供了对应的编译选项以方便用户在不同硬件设备间进行驱动切换。

具体设置编译选项方法：

1. 进入 build/config/target_config/3322 目录，打开产品目标配置 config.py。target_config.py 是公共模板，不建议为单个产品直接修改。

2. 如需切换 QSPI 显示通路，在目标的 defines 中添加 SUPPORT_GPU_QSPI，并通过构建系统支持的删除语法添加 -:MIPI_ULPS_SUPPORT，避免继承模板中的 MIPI ULPS 配置。配置位置如图4所示。

   图 4 在 defines 属性内添加宏

   

3. 显示通路通过 SUPPORT_GPU_QSPI 区分。

   • 未设置 SUPPORT_GPU_QSPI 时使用目标默认的非 QSPI 通路；
   • 设置 SUPPORT_GPU_QSPI 时启用 QSPI 相关驱动分支；
   • 使用 QSPI 时应移除 MIPI_ULPS_SUPPORT，并结合实际板级文件核对引脚和屏幕配置。

蓝牙相关特性

蓝牙当前版本支持通过编译宏和增删组件的方式来配置单模 BLE 和双模 BLE/BT 特性，具体在 config.py 中的 target 配置。由于蓝牙接口闭源提供在 .a 中，以下特性宏不影响蓝牙接口的使用，只影响开源代码中其他模块对于蓝牙接口调用的逻辑，如 media、lwip 等模块。

表 1 蓝牙特性编译宏及方案

蓝牙特性方案	宏‘SUPPORT_BLE’	宏‘SUPPORT_BREDR’
单BLE特性	打开	关闭
双模BLE/BT特性	打开	打开

说明： 蓝牙当前版本只支持以上两种特性方案。

媒体相关特性

媒体组件支持配置，相关特性集合为‘media’。

‘media’支持音视频相关特性，具体请参见 common_config.py。

可以在 config.py 文件中 target 的“ram_component_set”中配置媒体相关的特性集合。

例如：diting-community-native-js里面配置为‘media’。

音频相关特性

3A算法

3A算法参数配置

3A 算法参数记录在 app.json 文件中，分为以下两套参数：

• audio_vqe_param：key_id为0x320C，用于通话场景和录音场景。

  

• audio_vqe_kws_param：key_id为0x320D，用于语言唤醒场景和命令词识别场景。

  

value成员里的数组即为3A算法参数。需要更新时，只需将新参数替换掉旧参数，重新编译即可。

3A算法bypass

产线测试可能需要 bypass 3A 算法以获取麦克风原始数据。本版本没有定义通用的 product_test_mode NV 项；产测版本应使用配套音频算法和 NV 配置提供的正式 Key 或产测接口，并按《产测工具使用指南》执行。新增 NV Key 前，应先在 Key 声明和默认配置中完成注册。

SmartPA驱动

SmartPA适配

SDK提供外置Codec适配示例，版本提供的示例为SmartPA的适配。

版本默认使用DAC对接模拟PA的低成本方案，不需要适配SmartPA；

如有使用I2S对接SmartPA的需求，可参考该章节。

SmartPA芯片驱动的适配

• 版本默认提供参考的是EVB板子的AW88262，可以通过宏开关切换。

• SmartPA驱动初始化入口：thread_pri_init.c。

• SmartPA 型号由 config.py 中的特性宏选择，例如 AUDIO_SMARTPA_AW88262。diting-community 当前同时包含 AW88262 和模拟 PA 的注册宏；产品化时只启用实际硬件所需驱动，并核对 I2S/DAC 端口。

  以下代码直接摘自当前 application/3322/3322_app_standard/thread_pri_init.c：

  #ifdef AUDIO_SMARTPA_AW88262
  #define AUDIO_SMARTPA_AW88262_I2S_ID UAPI_SND_OUT_PORT_I2S0
  
  td_s32 audio_aw88262_init(const uapi_vendor_codec_attr *attr);
  td_s32 audio_aw88262_deinit(td_void);
  
  static void audio_smartpa_init(void)
  {
      static uapi_vendor_driver g_aw88262_driver = {
          .out_port = AUDIO_SMARTPA_AW88262_I2S_ID,
          .init = audio_aw88262_init,
          .deinit = audio_aw88262_deinit,
          .set_aef_profile = TD_NULL,
      };
  
      td_s32 ret = uapi_audio_vendor_register(&g_aw88262_driver);
      if (ret != 0) {
          PRINT("aw88262 register driver error, ret = %d"NEWLINE, ret);
      }
  }
  #endif
  

• SmartPA 驱动的基本流程：初始化入口在开机阶段调用，并通过 uapi_audio_vendor_register 注册到音频驱动。AW88166 的接口契约见 /src/application/audio/vendor/aw88166/include/aw88166.h：

  • 驱动对外一共五个接口，声明见 /src/application/audio/vendor/aw88166/include/aw88166.h。
  • 驱动的init/deinit接口跟随MCU的上电和下电流程调用。
  • 驱动的 set_aef_profile 接口跟随业务的输出音效配置接口 uapi_snd_set_aef_profile 回调。

  • 驱动的 start/stop 接口跟随下行通路的创建和销毁调用，通过 uapi_audio_vendor_register 注册音频下行模块；stop 接口会让 SmartPA 进入低功耗待机状态。

    AW88166 的完整 .c 驱动需要从芯片厂商获取；注册方式可参考本节上方 AW88262 的实现。

• 将新增的驱动文件增加到 CMakeLists.txt 中，如图所示（需要删去图中默认的 aw88262 驱动文件，替换为新增的驱动文件）。

  

  新增驱动时，需要把全部源文件和头文件目录加入 COMPONENT_SRC、COMPONENT_INC。AW88166 分支的配置如下：

  set(COMPONENT_SRC ${COMPONENT_SRC}
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/aw88166.c
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/aw883xx.c
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/aw883xx_calib.c
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/aw883xx_device.c
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/product_init_files/aw88166/aw883xx_pid_2066_init.c
  )
  set(COMPONENT_INC ${COMPONENT_INC}
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/product_init_files/aw88166
      ${CMAKE_CURRENT_SOURCE_DIR}/aw88166/config/aw88166/mono/16bit
  )
  

  前置条件： SDK 包含 AW88166 的部分头文件、参数和说明文件。使用 AW88166 前，应从芯片厂商取得适配当前 SDK 的完整驱动包，补齐 CMakeLists.txt 引用的文件，再进行组件级和整包编译验证。

• 适配SmartPA驱动的注意事项：以AW88166为例。

  • 根据硬件连接情况，正确配置SmartPA芯片的上电管脚。
  • 根据硬件连接情况，正确配置SmartPA芯片的I2C通信的序号。

  • 根据硬件连接情况以及芯片手册，正确配置SmartPA芯片的I2C设备地址。

    S_MGPIO4、I2C_BUS_0 和设备地址 0x34 不能直接作为新硬件的默认值；实际值必须来自产品原理图和对应 AW88166 驱动包。

SmartPA音效算法的适配

SmartPA音效算法的适配需要提供整机到SmartPA芯片厂商调音，刷新音效算法和音效参数。

SmartPA有两种：

无DSP型：音效处理由SOC芯片中的DSP完成，例如艾为的AW88262。

带DSP型：音效算法直接在PA内部的DSP上运行，例如艾为的AW88166。

• 对于PA芯片内部不带DSP的型号（如 AW88262），发布版本默认集成了一个艾为提供的音效算法（dsp_overlay.bin中的aef.bin）。
  • 算法版本：MiniSKTune_MTK_DSP_HIFI3_AAPI_Porting，版本号为V0.0.0.19；（需要与艾为确认PA选型与该算法版本是否适配）。
  • 算法版本升级或者更换需要参见《AEF overlay 开发指南》重新刷新 aef.bin。

  • PA音效调测：为了获取准确的音效算法参数，需要整机厂商提供最终整机给SmartPA芯片厂商，用于进行音效参数调节。调节完成后进行参数bin的刷新。

    1. 音效参数bin打包在DSP镜像包的“dsp_overlay.bin”中。

    2. 音效参数bin根据业务场景分为3个：aef_music.bin、aef_voip.bin、aef_ringtone.bin。要求把PA厂商调测好的参数bin重命名成这仨参数bin替换到“dsp_overlay.bin”中。

       举例：MCU在创建本地音乐通路的时候会在打印log。

       “[A][ALERT][ao_get_aef_param_bin_by_profile:701] <aef_music.bin>”。

    3. 替换“dsp_overlay.bin”中音效参数bin的方法：

       1. 解包/打包工具：/src/application/audio/sample_dsp_overlay/packet_tool_dsp_overlay.py

          直接执行该脚本，会输出脚本的使用指南/help信息：

          python3 application/audio/sample_dsp_overlay/packet_tool_dsp_overlay.py
          

       2. 音效参数替换简略步骤

① 进入 sample_dsp_overlay 目录。

            ② dsp\_overlay.bin的解包。

            ```bash
            python3 packet_tool_dsp_overlay.py unpacket normal 3322
            ```

            ③ 解包在当前路径的“out/overlay\_bin”目录下。

            ④ 替换“out/overlay\_bin”下面的音效参数bin。

            ⑤ 用脚本重新打包。

            ```bash
            python3 packet_tool_dsp_overlay.py packet normal 3322
            ```

            ⑥ 按往常一样编译镜像包烧录“dsp\_overlay.bin”。

• 对于 PA 芯片内部自带 DSP 的型号（如 AW88166），音效算法运行在 SmartPA 芯片内部的 DSP 上，SoC DSP 的音效算法库需要替换为 bypass 版本。具体参见《AEF overlay 开发指南》，使用 bypass 版本的 aef.bin 替换 dsp_overlay.bin 中的 aef.bin。

• PA的音效参数由PA的MCU驱动下发：PA驱动的适配层set_aef_profile接口就是注册给音频模块根据场景切换音效参数使用。

  可以参照audio_aw88166_set_aef_profile的具体实现，音频模块会根据业务场景配置的profile选择PA的音效场景。

  所以音效参数就在PA供应商的驱动包中：/src/application/audio/vendor/aw88166/config/aw88166/mono/16bit

模拟PA使能控制

• SDK默认支持S_AGPIO30控制模拟PA使能，提供了其适配示例，可以通过‘SUPPORT_AUDIO_ANAPA_POWER_CTRL’宏开关该功能。
• 使能控制功能的注册入口：thread_pri_init.c
• 使能控制功能适配注意点：
  • 需要根据硬件连接配置正确的GPIO管脚，将‘AUDIO_ANAPA_POWER_CTL_GPIO_ID’宏设置为实际PA使能管脚所对应的GPIO管脚。
  • 根据对接的DAC端口对‘AUDIO_ANAPA_DAC_ID’宏进行正确配置。

音频输入输出硬件端口选择与配置

具体音频业务的端口切换配置请参考《多媒体软件开发指南》中的“音频配置”章节。

• 音频输入端口

  本地音频输入端口

  • 模拟输入：支持ADC和LPADC，一般选择LPADC，对接AMIC器件，不需要额外配置管脚复用（pinmux）。

  • 数字输入：支持PDM和I2S，PDM对接DMIC器件，I2S对接I2S接口的器件/模块，需要根据硬件使用的芯片管脚配置管脚复用（pinmux）。

    管脚复用在平台侧的板型配置文件中统一管理；3322 EVB 的配置文件为 board_evb.h。

• 音频输出端口：

  本地音频输出端口

  • 模拟输出：支持DAC，对接模拟PA或者喇叭，不需要额外配置管脚复用（pinmux）。

  • 数字输出：支持I2S，对接I2S接口的器件/模块，常见的有数字PA和音频模组，需要根据硬件使用的芯片管脚配置管脚复用（pinmux）。

    管脚复用在平台侧的板型配置文件中统一管理；3322 EVB 的配置文件为 board_evb.h。

音频DSP镜像

音频DSP镜像介绍

音频DSP镜像涉及两个bin：dsp_main.bin和dsp_overlay.bin。

• dsp_main.bin：基础DSP框架代码，不支持增删改。

• dsp_overlay.bin：动态加载的算法/参数bin的合集，bin包，支持按需增删替换。

  dsp_overlay.bin的bin包介绍如下：

  • aef.bin：软音效算法，用于本地下行播放通路的音效处理，适用于本地音乐、提示音、通话、蓝牙sink音乐场景，对接喇叭播放的音效算法。
  • amrwb.bin：AMRWB编解码算法，通过SPI对接CAT1的通话场景的上下行编解码算法。
  • dsp_rom.bin：DSP基础框架依赖，作为基础必备组件，不可裁剪。
  • mp3_enc.bin：MP3编码算法，用于上行录音的编码，适用于语音备忘录录音场景。
  • opus_dec.bin：OPUS格式解码算法，用于下行解码播放，适用于本地音乐和蓝牙source音乐场景，解码本地OPUS格式的音频文件（流）。
  • pcm_dec.bin：PCM解码算法，用于下行解码播放，适用于本地音乐、蓝牙source音乐、蓝牙通话（CVSD）场景，用于支持WAV格式的音频解码播放以及CVSD格式的通话下行解码播放。
  • phs_gru.bin：本地固定命令词（唤醒词）识别算法，用于语音识别功能的前级离线固定命令词和唤醒词识别场景。
  • see_1mic.bin：传统3A算法/AI降噪增强算法，上行录制场景使用，用于本地录音/语音识别/通话上行场景。
  • silk_dec.bin：SILK解码算法，用于微信语音播放场景。
  • silk_enc.bin：SILK编码算法，用于微信语音录制场景。

SDK 的 DSP 版本枚举包含 normal、mini 和 nano，三种镜像的功能差异见下表。本交付包可直接选择和打包 normal 版本；mini 和 nano 需使用包含对应目录及完整二进制的配套版本包。

• 镜像路径说明：

  • normal 版本：src/tools/pkg/bin/3322/dsp/normal；
  • mini 版本：由配套版本包在 3322 DSP 镜像目录下提供 mini 子目录；
  • nano 版本：由配套版本包在同一位置提供 nano 子目录。

• 镜像功能说明：

  1. normal和mini版本支持传统ANR、增强算法AGC、回声消除算法AEC，nano版本支持AI降噪增强算法，不支持回声消除功能。
  2. normal和nano版本支持下行通路的软件音效算法，mini版本暂不支持。
  3. nano版本不支持本地固定命令词（唤醒词）识别算法。

表 1 音频DSP镜像bin文件说明

bin文件		normal版本	mini版本	nano版本
dsp_main.bin		支持	支持	支持
dsp_overlay	aef.bin	支持	不支持	支持
	amrwb.bin	支持	支持	支持
	dsp_rom.bin	支持	支持	支持
	mp3_enc.bin	支持	支持	支持
	opus_dec.bin	支持	支持	支持
	pcm_dec.bin	支持	支持	支持
	phs_gru.bin	支持	支持	不支持
	see_1mic.bin	支持 传统3A算法	支持 传统3A算法	支持 AI降噪增强算法
	silk_dec.bin	支持	支持	支持
	silk_enc.bin	支持	支持	支持

A 核系统版本默认适配 DSP normal 版本，当前 diting-community 的 dsp_version 也为 normal。只有 SDK 确实包含 mini 或 nano 目录时，才可将 /src/build/config/target_config/3322/config.py 中目标的 dsp_version 改为对应目录名。dsp_version 的配置位置如下：

音频DSP镜像解包和打包

音频sample目录提供python脚本，供客户解包dsp_overlay.bin，按需增删、替换bin，再重新打包成新的dsp_overlay.bin。

Python 脚本为 application/audio/sample_dsp_overlay/packet_tool_dsp_overlay.py；不带参数直接执行会输出帮助。脚本要求依次提供操作、DSP 版本和芯片版本三个参数，例如 unpacket normal 3322。

操作步骤/方法如下：

注意： unpacket 会清空 out/overlay_bin 中已有文件；packet 会覆盖 src/tools/pkg/bin/3322/dsp/normal/dsp_overlay.bin。操作前应将原始 dsp_overlay.bin 复制到 SDK 目录外备份，并确认工作区中没有仍需使用的解包文件。

1. 进入工作目录 application/audio/sample_dsp_overlay。

2. 执行 python3 packet_tool_dsp_overlay.py unpacket normal 3322 解包 dsp_overlay.bin。

   • 解包后，在当前路径的“out/overlay_bin”目录下，会生成dsp_overlay.bin中包含的所有算法和参数的独立bin文件；
   • 解包操作的dsp_overlay.bin是从镜像归档目录拷贝过来解包的。

3. 按需增删替换 bin 文件：到当前路径的 out/overlay_bin 目录增删替换算法/参数 bin 文件。

4. 执行 python3 packet_tool_dsp_overlay.py packet normal 3322 重新打包。

   打包后，“out/overlay_bin”目录下的所有bin文件会被重新打包成一个总的dsp_overlay.bin，并拷贝到镜像归档目录，覆盖原先的旧dsp_overlay.bin。

5. 按开发环境快速入门完成整包构建，确认新 dsp_overlay.bin 已进入 diting-community.fwpkg，再按整包烧录流程部署；只有产品已经提供并验证了独立 DSP 升级通道时，才使用对应升级流程单独推送。

低功耗相关特性

具体低功耗相关特性配置请参见《低功耗软件开发指南》。

驱动相关特性

• ADC自动采样需要开启宏‘CONFIG_ADC_SUPPORT_AUTO_SCAN’，手动采样需要关闭该宏。

  如图 1所示，通过 Kconfig 配置开启 ADC 自动采样。

  图 1 ADC自动采样开启示意图

  

  说明： ADC自动采样与手动采样互斥。

• SPI 支持轮询与 DMA 自动切换。在目标配置中依次启用 CONFIG_SPI_SUPPORT_DMA、CONFIG_SPI_SUPPORT_POLL_AND_DMA_AUTO_SWITCH，再设置 CONFIG_SPI_AUTO_SWITCH_DMA_THRESHOLD。当前 Kconfig 默认阈值为 32，驱动在传输长度大于阈值时选择 DMA；当前 diting-community 默认配置未启用自动切换。

• I2C 支持轮询与 DMA 自动切换。应通过 menuconfig 启用 CONFIG_I2C_SUPPORT_DMA、CONFIG_I2C_SUPPORT_POLL_AND_DMA_AUTO_SWITCH，再设置 CONFIG_I2C_POLL_AND_DMA_AUTO_SWITCH_THRESHOLD。当前 Kconfig 默认阈值为 0x10，驱动在传输长度大于阈值时选择 DMA；当前 diting-community 已启用 I2C DMA，但未启用自动切换。

  须知： 当‘QSPI_DISPLAY’、‘TPTYPE_TMA525B’均设置时，即显示为QSPI显示通路时，由于QSPI屏幕侧器件限制，此时建议关闭DMA模式，使用轮询模式，避免QSPI显示出现异常。

32k时钟源相关特性

SDK 支持 XO 32 kHz 与片内 RC 32 kHz 两类时钟源。RC 校准入口位于 Kconfig：src/drivers/chips/3322/Kconfig 中的 ENABLE_RC_CALIBRATION，生成的编译宏为 CONFIG_ENABLE_RC_CALIBRATION，默认关闭。

• XO 32 kHz：保持默认关闭 RC 校准的配置，并按产品原理图和硬件规范测量时钟精度。
• RC 32 kHz：在目标配置中启用 enable rc32k calibration，保存后按快速入门重新构建。

须知：

• 本版本通过 Kconfig 配置时钟源，不使用 SUPPORT_RC_CALIBRATION 与 SUPPORT_32K_MEAS。
• RC 校准依赖蓝牙广播或连接，XO 需要测量时钟精度；具体硬件版本应结合蓝牙校准流程、原理图与实测结果确认。

具体设置方法：

1. 按开发环境快速入门完成一次 diting-community 目标构建，确保该目标的 .config 已生成。

2. 在目标配置中启用 enable rc32k calibration，保存后按上述快速入门重新构建并打包目标。

   图 1 添加编译选项切换RC 32k时钟源

   

   图1用于说明配置位置，具体选项以当前 Kconfig 菜单为准。

3. 如需切换回 XO 32 kHz，关闭上述设置，保存并重新执行完整构建。

Nor Flash部署

SDK 提供 8 MiB 和 16 MiB 两种 Nor Flash 部署方案。对应 target 分别声明 CFG_FLASH_SPECS_8M 或 CFG_FLASH_SPECS_16M，两个宏互斥。当前 diting-community 在 /src/build/config/target_config/3322/config.py 中使用 CFG_FLASH_SPECS_16M；切换容量时必须同时核对硬件容量、target 宏和分区表。

Nor Flash的分区表可根据需要修改，约束和修改方式如下：

当前分区表位于：

• /src/build/config/target_config/3322/param_sector/param_8m_sector.json
• /src/build/config/target_config/3322/param_sector/param_16m_sector.json

SSB、SSB backup、recovery、seliteos 等启动链组件应使用发布配置，不直接修改大小。当前 JSON 同时规定了固定 item ID；如确需改变启动链分区，必须联动检查签名、升级和打包脚本，不能只改一处数值。

剩余组件可灵活修改，包括app、fota_data、dfx_data等组件调整大小和顺序。修改如下所示：

1. 参照下图路径根据所用的target选择合适的配置文件。

   图 1 不同的配置文件图示

   

2. 修改分区表配置文件：

   图 2 分区表配置文件图示

   

   除启动链受约束组件外，其余组件可按产品需要调整顺序和大小。修改后由 /src/tools/pkg/chip_packet/3322/packet.py 在打包阶段解析；因此必须按快速入门完成整包构建，不能只生成 application.bin。

3. 修改代码中的宏控，保证代码正常运行。

   图 3 NORFLASH宏定义配置文件图示

   

   图 4 分区配置组件页配置选项

   

   当前两份 JSON 的分区起始地址和大小均按 0x1000（4 KiB）边界组织。新增或调整分区时继续保持 4 KiB 对齐，并检查相邻分区无重叠、末地址不超过实际 Flash 容量；打包成功后再以生成的 .fwpkg 做烧录验证。

系统适配对接

系统启动适配

系统启动适配主要是 APPLICATION 的适配。当前入口文件为 /src/application/3322/3322_app_standard/main.c，main() 按以下顺序完成初始化并启动任务调度：

1. kernel_init()：OS kernel 初始化。
2. chip_init()：初始化芯片内部 IP 模块。
3. board_init()：板级总线、外设初始化。
4. service_init()：服务初始化，包括 DFX 等。
5. thread_pri_init()：任务初始化。
6. osKernelStart()：触发任务调度。

进行系统启动适配时，在 board_init() 增加板级器件初始化，在 service_init() 增加服务初始化，并在 thread_pri_init() 注册任务。修改前先在对应源文件中确认函数扩展点；不要自行新增与现有启动入口重名的函数。

烧录、部署与调试

完成构建后，可通过串口或 RTT 观察系统状态，并根据产品部署方案烧录完整固件包或调整代码段布局。

调试环境

默认 diting-community 在 config.py 中启用 SW_UART_DEBUG，优先使用串口观察启动和业务日志。需要更完整的诊断能力时，参见《DFX软件 开发指南》；需要 J-Link RTT 时，参见本指南的 RTT 调试使用指导。切换日志后端后应重新完整构建，并确认没有同时启用相互冲突的输出宏。

烧录

烧录前先完成应用与整包构建。具体设备连接、端口选择和烧录方法以开发环境快速入门的烧录章节为准。烧录失败时先核对设备连接、驱动、目标选择和 .fwpkg 时间戳，不要用旧包判断本次修改。

代码部署

基于 SDK 开发时，客户代码加入 SDK 框架编译，除了正确书写组件式 CMake，还需规划代码段的运行地址和存储地址。当前 A 核 normal 配置的链接脚本为 /src/drivers/boards/3322_evb/linker/standard/acore/normal/acore.prelds，应使用该文件进行配置。

客户代码的运行地址和存储地址建议放在Flash中，正则表达式的写法有两种：

• 基于 .a 维度，参考图 1中的 1。
• 基于文件路径维度，参考图 1中的 2。

图 1 代码示例

RTT 调试

RTT（Real-Time Transfer）是 J-Link 提供的实时数据传输机制，可通过 J-Link 在目标板与主机之间传输日志，不占用 UART。SDK 在 /src/middleware/utils/common_headers/debug_print.h 和 /src/kernel/osal/adapt/liteos/osal_debug_adapt.c 中声明了 SW_RTT_DEBUG 接口，但未提供 SEGGER_RTT.c、SEGGER_RTT_printf.c 和对应头文件。必须先取得合法的 SEGGER 源码再执行本节流程；缺少这些文件时不能完成构建。

RTT 源码获取

RTT 源码不包含在 SDK 中，需要遵守 SEGGER 的许可条款自行获取。J-Link 安装目录的 SEGGER\JLink\Samples\RTT 下通常包含 RTT 示例压缩包，例如 SEGGER_RTT_V698c.zip；不同 J-Link 版本的压缩包名称可能变化。至少需要 SEGGER_RTT.c、SEGGER_RTT_printf.c、SEGGER_RTT.h 和 SEGGER_RTT_Conf.h，文件列表见图 1，具体以实际安装包为准。

图 1 文件列表

RTT 模块添加

1. 在源码仓的供应商扩展区新建 RTT 目录，放入取得许可的 RTT 源文件和 CMakeLists.txt；目录名及上级构建引用保持一致。

   

2. 在步骤 1 新建的 vendor 目录根级创建 CMakeLists.txt，并增加以下编译引用：

   add_subdirectory_if_exist(rtt)
   

   

   SDK 根目录的 /src/CMakeLists.txt 已包含 add_subdirectory_if_exist(vendor)，因此创建上述文件后可按组件方式加载 RTT 模块。

3. 编译配置文件中添加RTT模块。

   在 /src/build/config/target_config/3322/config.py 的目标配置中把 rtt 加入 ram_component，并将该目标的 SW_UART_DEBUG 替换为 SW_RTT_DEBUG。只修改需要 RTT 的 target；例如应用侧修改 diting-community，若 SSB 也需要 RTT，则还要单独修改 3322-ssb。

   图 1 APP target修改

   

   图 2 SSB target修改

   

4. 在步骤 1 新增的 RTT 目录创建 CMakeLists.txt。以下模板沿用 SDK 的 build_component() 组件格式；文件名必须与实际取得的 SEGGER 源码一致：

   # RTT component
   set(COMPONENT_NAME "rtt")
   
   set(SOURCES
       ${CMAKE_CURRENT_SOURCE_DIR}/SEGGER_RTT.c
       ${CMAKE_CURRENT_SOURCE_DIR}/SEGGER_RTT_printf.c
   )
   
   set(PUBLIC_HEADER
       ${CMAKE_CURRENT_SOURCE_DIR}/
   )
   
   set(PRIVATE_HEADER
   )
   
   set(PRIVATE_DEFINES
   )
   
   set(PUBLIC_DEFINES
   )
   
   # use this when you want to add ccflags like -include xxx
   set(COMPONENT_PUBLIC_CCFLAGS
   )
   
   set(COMPONENT_CCFLAGS
   )
   
   set(WHOLE_LINK
       true
   )
   
   set(MAIN_COMPONENT
       false
   )
   
   build_component()
   

5. 按开发环境快速入门重新构建并打包目标。构建后应在 map 文件中确认 SEGGER_RTT.c 和 SEGGER_RTT_printf.c 已链接。如果编译器报告缺少 SEGGER_RTT.h，应修正 PUBLIC_HEADER 或文件布局，不能用空声明绕过。

说明： 使用 RTT 作为输入输出时应关闭低功耗。具体方法参见《低功耗软件开发指南》中的“特性配置”章节；完成调试后应恢复 UART/量产日志配置并复测功耗。

RTT Viewer 设置

1. RTT链接配置：

   • Connection to J-Link：USB
   • Specify Target Device：RISC-V
   • Script file：选择配套 DevTools 工具包中的 ConnectCore1.JLinkScript，示例路径为 customer\tools\DevEco\DevTools_CFBB_V1.0.3\jlink_script\ConnectCore1.JLinkScript
   • RTT Control block：从本次构建的 map 文件或 J-Link 自动搜索结果确认；仅当结果一致时填写 0x2006FF00

   图 1 RTT链接配置示意图

   

2. 版本运行后，配置RTT Viewer，日志信息会在RTT界面打印。

   图 2 RTT界面打印信息

   

说明： RTT Control Block 地址取决于实际集成结果，应从本次构建生成的 map 文件或 J-Link 自动搜索结果确认；只有确认地址为 0x2006FF00 时才手动填写该值。

问题处理与相关资料

问题处理

现象	处理方法
开发环境不可用或环境检查失败	按开发环境快速入门检查并恢复开发环境。
环境检查报 uv trampoline failed to canonicalize script path	按开发环境快速入门重新完成 CLI 安装或激活，并在新终端中再次检查。
构建日志指向另一份 SDK	停止构建并重新激活目标 SDK 的 CLI 环境，确认 CMake 输出目录位于 <FBB_SDK_DIR>/output。
目标列表中找不到所需目标	确认当前目录和 SDK 路径，并按快速入门重新选择目标。
Windows 下补丁失败并出现 LiteOS 类型冲突	确认当前终端使用可正常运行的 patch.exe，并检查系统 PATH 中同名工具的优先级。
构建成功但没有 .fwpkg	A 核目标只生成应用镜像；按快速入门执行完整固件打包流程。
烧录端口无法打开	检查端口号、串口占用、驱动和访问权限，再重新连接开发板。
修改宏后行为没有变化	确认修改的是当前 target 的配置，重新构建；配置或依赖变化较大时执行清理构建。

变更验证流程

修改 target、组件、分区、驱动或链接脚本后，按以下流程验证：

1. 按开发环境快速入门完成目标选择、清理构建和整包打包。
2. 确认 output/3322/acore/diting-community/application.bin 和 output/3322/fwpkg/diting-community.fwpkg 已更新。
3. 检查构建日志和 .map 文件，确认新增组件已链接且 Flash、RAM 未越界。
4. 烧录目标板，核对启动日志、业务功能、复位或升级路径以及功耗表现。

硬件相关配置还需结合产品原理图和实板结果确认。使用第三方源码或二进制时，应同时确认授权、版本和目标 ABI。

业务应用工具

• 音频工具：提供音频源格式转换等功能，集成在 DebugKits 工具中。详情参见《DebugKits 工具使用指南》。
• 图形压缩工具：用于压缩、打包 UIKIT 图形资源。详情参见《图形工具使用指南》。
• UIKIT 模拟器：用于在 PC 端预览和调试 UIKIT 图形效果，在 HiSpark Studio for VS Code 使用指南的“GUI 工程创建与使用”章节 中查看“模拟器效果展示方法”。
• 可视化布局工具：通过拖拽控件、配置属性和事件生成 UIKIT C++ 图形代码，在 HiSpark Studio for VS Code 使用指南的“GUI 工程创建与使用”章节 中查看“GUI 拖拽界面介绍”。

相关资料

• 开发环境快速入门
• 《DFX软件 开发指南》
• API 参考
• Samples 示例代码