企业官网建设流程全解析

1. 项目概述：为什么一个轻量级关键词唤醒模型值得被“解剖”？

ARM｜边缘AI开源审计｜ML‑KWS‑for‑MCU 源码静态评测与工程架构全景解析——这个标题不是在喊口号，而是实打实的“手术刀式”技术复盘。我用两周时间，把 ML‑KWS‑for‑MCU 这个 GitHub 上星标超 1200 的嵌入式语音唤醒项目，从头到尾扒了一遍：不是跑通 demo 就完事，而是逐行读 C 文件、反汇编关键函数、比对 ARM Compiler 5.06u7 和 GCC 10.3 的生成代码差异、手绘内存布局图、重走整个构建链路。它解决的不是一个“能不能用”的问题，而是一个“能不能在真实产线里长期稳定跑、不烧 Flash、不掉唤醒率、不被客户 QA 打回来”的问题。

核心关键词ARM、边缘AI、ML‑KWS‑for‑MCU、源码静态评测、工程架构，每一个都不是虚词。ARM 是物理载体——你手上那块 STM32H7 或 NXP i.MX RT1064，它的 Cortex-M7 内核、192KB TCM、双 Bank Flash、DMA 通道数，直接决定你能塞多大的模型、跑多快的推理；边缘AI 是场景约束——没有云 API 可调、没有 2GB RAM 可挥霍、功耗必须压在 5mW 待机以下；ML‑KWS‑for‑MCU 是具体落点——它不是 PyTorch Mobile 的移植版，而是为 MCU 量身定制的纯 C 实现，连 malloc 都被禁用，所有内存全靠栈+静态分配；源码静态评测 不是用 SonarQube 点几下就交差，而是看它有没有裸写attribute((section(".ram_code"))) 去把 hot path 搬进 TCM，看它是否规避了 ARMv7-M 的 unaligned access trap，看它中断服务例程里有没有隐式浮点运算；工程架构 则是骨架——Makefile 里是否封装了不同芯片的启动文件路径？CMSIS-NN 的调用是否做了宏开关隔离？量化参数是硬编码在 header 里，还是通过 linker script 动态注入？这些细节，决定了你拿到代码后，是 3 小时完成移植，还是 3 周卡在某个 DMA 传输错位上反复 reboot。

适合谁来读？如果你正在做智能门锁的离线唤醒、工业传感器的声纹触发、或是医疗设备的语音控制按钮，手头只有 512KB Flash 和 192KB RAM，还被要求待机电流 <10μA，那这篇就是你的“避坑地图”。哪怕你只是刚学完《ARM体系架构》课本，也别跳过——我会用“STM32F407 的 FSMC 接 NOR Flash 时序怎么配”这种具体例子，把抽象概念钉死在硬件引脚上。这不是理论课，这是我在给某安防厂商做 KWS 方案时，踩过坑、改过 bug、最终量产交付的真实记录。

2. 整体设计思路拆解：为什么放弃 TensorFlow Lite Micro，坚持手写 C 层？

2.1 架构选型背后的三重现实枷锁

ML‑KWS‑for‑MCU 没有选择当时更火的 TensorFlow Lite Micro（TFLM），这个决策背后是三个无法绕开的硬约束：

第一是Flash 空间极限。TFLM 的最小可裁剪镜像（仅含 int8 quantized conv + fully connected）在 ARM Compiler 5.06u7 下仍需 180KB+，而目标芯片（如 NXP LPC55S69）可用 Flash 仅 320KB，还要留给 Bootloader、OTA、应用逻辑。ML‑KWS‑for‑MCU 全部 C 实现，核心推理引擎（含 Mel-spectrogram 计算、卷积、池化、Softmax）压缩后仅 42KB，剩余空间足够塞进 AES 加密和 OTA 回滚区。我实测过：把 TFLM 的 model.c 替换进去，Linker 报错region 'FLASH' overflowed by 124KB，根本连编译都过不去。

第二是确定性执行时间。TFLM 的 Op 注册机制依赖函数指针表，在 Cortex-M4 上每次调用都要查表跳转，最坏路径延迟波动达 ±15%。而 ML‑KWS‑for‑MCU 的卷积层完全展开为固定循环（unroll=4），所有地址计算在编译期确定，用__builtin_arm_dsb(0xF)强制刷写 D-Cache 后，单次推理耗时稳定在 8.3ms±0.1ms（@150MHz），满足实时音频流处理的 jitter 要求。这直接关系到唤醒词“Alexa”的首音节能否被完整捕获——延迟抖动大，前端 VAD 就可能切掉开头的 /æ/ 音。

第三是调试可见性。TFLM 的 tensor buffer 分配藏在 arena 里，出错时只能看到Invoke() failed with status 1。而 ML‑KWS‑for‑MCU 的每一帧输入（16-bit PCM）、MFCC 特征（float32[10][13]）、卷积中间结果（int16_t[32][8][8]）全部定义为全局 static 数组，J-Link 调试时直接 Memory View 查看，连第 3 帧第 5 个 MFCC 系数都能实时对比。客户 QA 提出“唤醒率在低温下下降”，我直接抓取 -20℃ 环境舱里的 RAM dump，发现 float32 到 int16 的量化偏移量没做温度补偿——这种问题，TFLM 的黑盒里根本找不到入口。

2.2 工程分层逻辑：从硬件寄存器到 AI 模型的四层映射

它的架构不是简单的“驱动→算法→应用”，而是严格按 ARM 嵌入式开发范式分四层，每层接口契约清晰：

• Hardware Abstraction Layer（HAL）：只做三件事——初始化 ADC（配置采样率 16kHz、12-bit、DMA 循环缓冲区）、配置 GPIO（唤醒 LED 控制）、读取低功耗模式状态。所有寄存器操作用 CMSIS 定义的LPC_ADC->CR = ...，绝不直写*(volatile uint32_t*)0x40012000 = ...。这里有个关键设计：ADC DMA 缓冲区大小设为 256 字节（128 个采样点），恰好是模型输入窗口（16ms @16kHz = 256 samples）的整数倍，避免软件搬移数据。

• Signal Processing Layer（SPL）：核心是mfcc_compute()函数。它不调用任何外部库，所有 FFT 用基 2 蝶形手写（长度 256），Mel 滤波器组系数预计算成 const 数组存 Flash。重点在于内存布局：输入 PCM 放在 SRAM1（非 cacheable），MFCC 特征矩阵放 TCM（cacheable + zero-wait-state），这样 FFT 过程中数据搬运不触发 cache miss。我反汇编发现，Compiler 5.06u7 对for (i=0; i<13; i++) { out[i] = ... }自动向量化成了vmla.f32 q0, q1, q2，但 GCC 10.3 却生成了 13 条独立vmov.f32，性能差 2.3 倍。

• Neural Network Layer（NNL）：模型结构固化为 3 层：Conv1D（16 filters, kernel=3）、MaxPool（size=2）、Fully Connected（16→2）。权重和 bias 全部用__attribute__((section(".kws_weights")))放到特定 Flash 区域，Linker Script 里明确指定.kws_weights (NOLOAD) : { *(.kws_weights) } > FLASH，确保 OTA 升级时能单独擦除重写。量化方案是 asymmetric int8：激活值范围 [-128,127]，权重范围 [-100,100]，bias 用 int32 补偿——这个选择让模型在 8-bit MCU 上准确率只降 0.7%，而 symmetric quantization 会掉 3.2%。

• Application Layer（APL）：只暴露两个 API：kws_init()初始化所有层，kws_run_frame(int16_t* pcm_buf)处理一帧数据并返回KWS_DETECTED或KWS_IDLE。没有回调函数，没有事件队列，状态全靠static kws_state_t state管理。这种极简设计，让客户工程师能在 1 小时内把唤醒逻辑集成进他们已有的 FreeRTOS 任务里，而不是被迫重构整个音频处理流水线。

2.3 构建系统设计：为什么 Makefile 比 CMake 更适合 MCU？

项目用纯 Makefile，而非当时更主流的 CMake。这不是守旧，而是针对 MCU 开发的精准选择：

• 芯片型号绑定：Makefile 里MCU ?= lpc55s69，自动包含$(MCU)_config.h，其中定义#define FLASH_SIZE_KB 320、#define TCM_SIZE_KB 192。CMake 的find_package()在 MCU 场景下反而冗余——你不会动态加载不同芯片的驱动，而是明确知道用哪颗料。

• 编译器版本强控：CC = arm-none-eabi-gcc被注释掉，实际使用CC = armclang（ARM Compiler 5.06u7）。因为 ARM Compiler 对 Cortex-M 的 intrinsic 优化更激进，比如__builtin_arm_rbit()生成单条rbit指令，而 GCC 需要 5 条 ARM 指令模拟。Makefile 里ifeq ($(shell $(CC) --version | grep -c "5.06"), 1)做版本校验，避免工程师误用 GCC 导致性能暴跌。

• 内存布局精确控制：Linker Script 不是自动生成的，而是手写sections.ld：

  MEMORY { FLASH (rx) : ORIGIN = 0x00000000, LENGTH = 320K RAM (rwx) : ORIGIN = 0x20000000, LENGTH = 256K } SECTIONS { .text : { *(.text) } > FLASH .kws_weights : { *(.kws_weights) } > FLASH .data : { *(.data) } > RAM AT > FLASH .bss : { *(.bss) } > RAM }

  这样.kws_weights段能被 OTA 工具单独定位擦除，而 CMake 的target_link_libraries()无法做到这种颗粒度。

提示：很多团队用 CMake 生成 Makefile，但在 MCU 场景下，这层抽象反而增加调试成本。当你在 J-Link 中看到0x0000A124地址报 data abort，直接查sections.ld就知这是.kws_weights段越界，而不用在 CMake 的add_executable()里层层追溯。

3. 核心细节解析与实操要点：从源码到硅片的 7 个生死关

3.1 MFCC 计算中的定点数陷阱：为什么 float32 在 MCU 上是奢侈品？

mfcc_compute()函数里，Mel 滤波器组的系数本该是 float32，但项目强制用 int32_t 存储，乘法后右移 15 位还原。原因很现实：Cortex-M4 的 FPU 虽支持 float32，但开启 FPU 会增加 context switch 时间（保存/恢复 32 个浮点寄存器），而 KWS 是高频调用（每 10ms 一帧），FPU 切换开销占到总耗时的 18%。更致命的是，某些低成本 MCU（如 GD32E230）根本没 FPU，float32 全靠软件模拟，一帧 MFCC 直接干到 45ms。

我实测对比了三种方案：

最终选 Q15：精度损失仅 0.6%，但耗时从 38ms 压到 12.7ms，且兼容无 FPU 芯片。关键技巧是滤波器系数预计算时，用 Python 脚本做round(x * 32768)，再存入 const 数组：

// gen_mel_filters.py import numpy as np mel_filters = np.array([...]) # float32 coefficients q15_filters = np.round(mel_filters * 32768).astype(np.int32) np.savetxt("mel_filters_q15.h", q15_filters, fmt="%d", delimiter=",")

这样生成的头文件，编译时直接进 Flash，运行时零计算开销。

3.2 卷积层的手动展开：为什么 for-loop 比 CMSIS-NN 更快？

项目没用 ARM 官方的 CMSIS-NN 库，而是手写卷积：

for (int f = 0; f < 16; f++) { int32_t sum = bias[f]; for (int k = 0; k < 3; k++) { sum += (int32_t)input[i+k] * weight[f][k]; } output[f] = (int16_t)__SSAT(sum >> 6, 16); // Q15 -> Q9 }

CMSIS-NN 的arm_conv_1d_fast_q15()函数在相同条件下慢 2.1 倍。原因有三：

• 内存访问模式：CMSIS-NN 为通用性，weight 按f,k顺序存储，导致weight[f][k]访问时 cache line 不连续。而手写版本把 weight 按k,f重排（weight[3][16]），使每次k循环都在同一 cache line 内。

• 指令流水线填充：手写代码中sum += ...被 Compiler 5.06u7 优化成smlabb r0, r1, r2, r0（带符号乘加），而 CMSIS-NN 的宏展开引入额外分支预测失败。

• 量化位宽匹配：CMSIS-NN 默认 Q7 输入，需额外做 Q15→Q7 转换；手写版本直接用 Q15 输入，省去 2 次 shift 操作。

注意：这个优化只在 input channel=1（单声道）时成立。如果要做双声道唤醒，必须重写为arm_conv_1d_fast_q15()，否则性能崩塌。我在某项目中吃过亏——客户临时要求支持双麦波束成形，硬改手写卷积花了 3 天，而 CMSIS-NN 只需改一行参数。

3.3 中断安全的音频采集：DMA+双缓冲的临界区设计

ADC 采集用 DMA 循环模式，但kws_run_frame()在主循环调用，如何保证不读到半更新的缓冲区？项目用经典的双缓冲+标志位：

#define AUDIO_BUF_SIZE 256 static int16_t audio_buf[2][AUDIO_BUF_SIZE]; static volatile uint8_t buf_idx = 0; static volatile uint8_t buf_full[2] = {0}; void ADC_IRQHandler(void) { if (DMA_GetITStatus(DMA0, DMA_INT_MAJOR) == SET) { buf_full[buf_idx] = 1; buf_idx ^= 1; // 切换缓冲区 DMA_ClearITPendingBit(DMA0, DMA_INT_MAJOR); } } // 主循环 if (buf_full[buf_idx^1]) { kws_run_frame(audio_buf[buf_idx^1]); buf_full[buf_idx^1] = 0; }

关键点在于buf_idx切换和buf_full置位必须原子。ARM Cortex-M 的ldrex/strex指令太重，这里用更轻量的__disable_irq()关中断 3 条指令：

__disable_irq(); buf_full[buf_idx^1] = 0; buf_idx ^= 1; __enable_irq();

实测关中断时间仅 12ns，远低于 ADC 采样间隔（62.5μs），完全不影响实时性。若用 FreeRTOS 的xSemaphoreTake()，上下文切换开销达 1.8μs，会吃掉 3% 的 CPU 时间。

3.4 Flash 分区的 OTA 可靠性：为什么 .kws_weights 必须 NOLOAD？

Linker Script 中.kws_weights (NOLOAD)的设计，是为 OTA 升级留的后门。NOLOAD 意味着该段内容不写入最终 bin 文件，但保留地址和大小信息。OTA 工具（如 MCUboot）升级时，只擦除.kws_weights区域（起始地址0x00020000，长度0x4000），然后把新权重烧进去，其他代码段不动。这样做的好处：

• 升级速度：擦除 16KB 比擦除整个 320KB Flash 快 12 倍（NOR Flash 擦除时间约 100ms/sector）。
• 失败回滚：如果新权重校验失败，直接跳回旧权重区域，无需整机重启。
• 版本管理：每个权重文件带 CRC32 校验和，存放在.kws_weights段末尾，kws_init()时验证。

我曾遇到客户现场 OTA 失败：新权重文件 CRC 错，但 boot loader 没校验直接跳转，结果模型输出全乱。补丁很简单——在kws_init()加两行：

uint32_t *crc_ptr = (uint32_t*)((uint8_t*)&kws_weights_start + WEIGHTS_SIZE - 4); if (crc32(&kws_weights_start, WEIGHTS_SIZE - 4) != *crc_ptr) { return KWS_ERR_WEIGHTS_CORRUPT; }

3.5 低功耗模式下的唤醒延迟：从 STOP 模式到 IRQ 的 12μs 路径

为满足待机功耗 <10μA，主芯片进入 STOP 模式，但 ADC 需保持运行。项目用 LPC55S69 的特殊设计：ADC 可在 STOP 模式下继续采样，DMA 触发后唤醒 CPU。实测从 STOP 到ADC_IRQHandler第一行代码执行，耗时 12μs——这决定了唤醒词首音节能否被捕获。

关键配置：

• POWER_DisablePD(kPDRUNCFG_PD_ACOMP);// 保持模拟比较器供电
• ADC_EnableTrigger(ADC0, true);// 使能硬件触发
• SYSCON_SetADC0ClockRate(12000000);// ADC 时钟独立于 CPU 时钟
• NVIC_EnableIRQ(ADC0_IRQn);// 中断优先级设为最高（0）

注意：很多工程师误以为 STOP 模式下所有外设都停，其实 ARM Cortex-M 的 PDRUNCFG 寄存器可以精细控制每个模块供电。ADC 的PD_ADC位必须清零，否则唤醒后 ADC 无法初始化。

3.6 模型量化参数的跨平台一致性：为什么不能用训练框架直接导出？

训练用 TensorFlow，但量化参数（scale、zero_point）不能直接用 tf.quantization.fake_quant_with_min_max_vars 导出，因为 MCU 的 int8 乘法会溢出。项目用 Python 脚本做后处理：

# quantize_weights.py def quantize_weight(weight_tensor): w_min, w_max = weight_tensor.min(), weight_tensor.max() scale = (w_max - w_min) / 255.0 zero_point = int(round(-w_min / scale)) # clamp to int8 range q_weight = np.clip(np.round(weight_tensor / scale + zero_point), 0, 255).astype(np.uint8) return q_weight, scale, zero_point

重点在clamping：TensorFlow 的 fake_quant 可能生成 256，但 int8 最大是 255，必须截断。我在某次量产中发现，未 clamp 的权重导致__SSAT(sum, 16)溢出，唤醒率骤降 40%。补丁就是加一行q_weight = np.clip(q_weight, 0, 255)。

3.7 构建产物的可追溯性：如何用 git hash 绑定固件版本？

Makefile 里加入：

GIT_HASH := $(shell git rev-parse --short HEAD) CFLAGS += -DGIT_HASH=\"$(GIT_HASH)\"

然后在kws_init()打印：

printf("KWS firmware v1.2.0-%s\n", GIT_HASH);

这样每台设备烧录的固件，都能精确对应到 GitHub 的某次 commit。当客户反馈“某批次设备唤醒失灵”，直接查 git log 就知是哪次修改引入的问题——比如某次为了减小 Flash，把 MFCC 的 FFT 点数从 256 改成 128，导致高频特征丢失。

4. 实操过程与核心环节实现：从零搭建可复现的评测环境

4.1 环境搭建：ARM Compiler 5.06u7 的安装与验证

ARM Compiler 5.06u7（Build 960）是官方最后支持 Cortex-M0/M3/M4 的经典版本，比 ARM Compiler 6 更适合 MCU。下载地址已归档，需从 ARM Developer Community 获取。安装步骤：

1. 解压arm_compiler_5.06u7_linux.tar.gz到/opt/arm/gcc-arm-none-eabi-5_06u7
2. 创建软链接：sudo ln -sf /opt/arm/gcc-arm-none-eabi-5_06u7 /opt/arm/gcc-arm-none-eabi
3. 添加环境变量：

   echo 'export ARM_TOOLCHAIN=/opt/arm/gcc-arm-none-eabi' >> ~/.bashrc echo 'export PATH=$ARM_TOOLCHAIN/bin:$PATH' >> ~/.bashrc source ~/.bashrc

4. 验证版本：

   armclang --version # 输出应为：ARM C/C++ Compiler, 5.06 update 7 (build 960)

注意：不要用arm-none-eabi-gcc替代。我测试过 GCC 10.3 编译的固件，在 LPC55S69 上跑kws_run_frame()耗时 14.2ms，而 armclang 是 12.7ms——1.5ms 的差距，在 10ms 帧周期里就是 15% 的 margin 损失。

4.2 静态评测工具链：Cppcheck + custom regex 的组合拳

源码静态评测不是只跑 Cppcheck，而是三层过滤：

• Cppcheck 基础扫描：

  cppcheck --enable=all --inconclusive --platform=unix64 \ --suppress=unusedFunction \ --suppress=missingInclude \ src/ > cppcheck_report.txt

  关键 suppress：unusedFunction（MCU 项目常有未调用的 HAL 函数预留）、missingInclude（CMSIS 头文件路径由 Makefile 指定，Cppcheck 找不到）。

• 正则表达式深度扫描：写 Python 脚本查危险模式：

  import re patterns = [ (r'malloc\(|calloc\(|realloc\(', "禁止动态内存分配"), (r'printf\(|sprintf\(', "禁止格式化输出，占用大量 Flash"), (r'float\s+\w+', "禁止 float 变量声明，除非在 #ifdef FLOAT_DEBUG 内"), (r'while\(1\)\s*{', "无限循环必须有 watchdog feed 或 sleep") ] for pattern, msg in patterns: for file in glob.glob("src/*.c"): with open(file) as f: for i, line in enumerate(f, 1): if re.search(pattern, line): print(f"{file}:{i} {msg}")

• 汇编层验证：用armclang -O3 -S生成汇编，grep 查关键指令：

  armclang -O3 -S src/kws_engine.c -o kws_engine.s grep -n "rbit\|ssat\|dsb" kws_engine.s # 确保有 rbit（位反转加速 FFT）、ssat（饱和运算防溢出）、dsb（内存屏障）

4.3 内存布局可视化：用 objdump 和 python 绘制 RAM/Flash 占用图

Linker Script 定义了内存分区，但实际占用需验证。步骤：

1. 编译后生成 map 文件：

   armclang -O3 --map --list=kws.map src/main.c -o kws.elf

2. 解析 map 文件提取各段大小：

   # parse_map.py import re with open('kws.map') as f: content = f.read() sections = re.findall(r'(\.\w+)\s+0x[0-9a-f]+\s+0x([0-9a-f]+)', content) for name, size in sections: if int(size, 16) > 0x100: # 过滤小于 256 字节的段 print(f"{name}: {int(size, 16)} bytes")

3. 生成饼图（需 matplotlib）：

   sizes = [flash_text, flash_weights, ram_data, ram_bss] labels = ['TEXT', 'WEIGHTS', 'DATA', 'BSS'] plt.pie(sizes, labels=labels, autopct='%1.1f%%') plt.title('Memory Usage') plt.savefig('memory_pie.png')

实测某次编译结果：.text32KB、.kws_weights16KB、.data4KB、.bss8KB，总 Flash 占用 52KB，RAM 占用 12KB——远低于 320KB/256KB 限额，留出充足余量。

4.4 性能基准测试：用 DWT（Data Watchpoint and Trace）计时

ARM Cortex-M3/M4 内置 DWT 模块，可高精度计时。在kws_run_frame()前后加：

// 启用 DWT CoreDebug->DEMCR |= CoreDebug_DEMCR_TRCENA_Msk; DWT->CTRL |= DWT_CTRL_CYCCNTENA_Msk; DWT->CYCCNT = 0; kws_run_frame(pcm_buf); uint32_t cycles = DWT->CYCCNT; float ms = (float)cycles / SystemCoreClock * 1000.0f; printf("KWS time: %.2f ms\n", ms);

SystemCoreClock 为 150MHz，1 cycle = 6.67ns，精度远超 SysTick。实测值 12.7ms 对应 1905000 cycles，误差 <0.1%。

4.5 唤醒率实测：用 Audacity 生成标准测试集

准确率不能只信训练集报告，必须用真实音频测试。方法：

1. 用 Audacity 录制 1000 条唤醒词（“Hi Robot”）和 1000 条干扰语音（新闻播报、音乐、咳嗽声）。
2. 导出为 16-bit PCM，采样率 16kHz，单声道。
3. 写 Python 脚本批量喂给固件：

   import serial ser = serial.Serial('/dev/ttyACM0', 115200) for wav_file in test_wavs: with open(wav_file, 'rb') as f: pcm_data = f.read() ser.write(pcm_data) response = ser.readline().decode().strip() if 'DETECTED' in response: result.append(1) else: result.append(0) print(f"Accuracy: {sum(result)/len(result)*100:.1f}%")

实测某次：唤醒词识别率 91.3%，误唤醒率 0.8%（即 1000 条干扰语音中错误触发 8 次），满足工业级要求（误唤醒 <1%）。

4.6 交叉编译适配：从 x86 Linux 到 ARM MCU 的迁移要点

项目在 Ubuntu 22.04 x86_64 上开发，但目标是 ARM Cortex-M。关键迁移点：

• 头文件路径：CMSIS 头文件不能用系统默认路径，Makefile 中显式指定：

  INC_DIRS += $(ARM_TOOLCHAIN)/include INC_DIRS += $(ARM_TOOLCHAIN)/include/cmsis INC_DIRS += $(ARM_TOOLCHAIN)/include/cmsis_device

• 链接脚本路径：-T sections.ld必须用绝对路径，否则在 CI 环境中易出错：

  LDFLAGS += -T $(abspath sections.ld)

• 符号大小写：ARM Compiler 默认函数名小写，而某些旧版 GCC 生成大写。用armclang --cpu=Cortex-M4 --fpu=vfpv4显式指定，避免main和Main混淆。

• 浮点 ABI：-mfloat-abi=hard（硬浮点）比softfp快 3.2 倍，但需确认芯片支持 VFPv4。LPC55S69 支持，故启用。

4.7 工程架构文档化：用 Doxygen 自动生成 API 参考

虽然项目小，但 API 文档必不可少。Doxyfile 配置关键项：

PROJECT_NAME = "ML-KWS-for-MCU" INPUT = src/ FILE_PATTERNS = *.c *.h RECURSIVE = YES GENERATE_HTML = YES GENERATE_LATEX = NO EXTRACT_ALL = YES EXTRACT_STATIC = YES

然后doxygen Doxyfile生成 HTML 文档。重点在函数注释：

/** * @brief Run one frame of keyword spotting * @param pcm_buf Pointer to 256 samples of 16-bit PCM data * @return KWS_DETECTED if keyword found, KWS_IDLE otherwise * @note Must be called every 10ms. Buffer must be aligned to 4-byte boundary. */ kws_status_t kws_run_frame(int16_t* pcm_buf);

这样客户工程师查文档就知道pcm_buf必须 4 字节对齐，避免因未对齐访问导致 HardFault。

5. 常见问题与排查技巧实录：那些让工程师熬夜的典型故障

5.1 故障速查表：从现象到根因的快速定位