📚 课程目录第4章源码工程结构解析

4、源码工程结构解析：理解Nordic nRF项目的目录组织、CMakeLists.txt、Kconfig配置、设备树（devicetree）与链接脚本

在Nordic nRF TinyML交付物中，源码工程结构是连接算法模型与硬件实体的桥梁。一个规范的nRF Connect SDK（NCS）工程，其目录组织、构建系统配置、内核裁剪参数以及硬件描述方式，直接决定了固件能否高效运行、功耗是否可控以及后续维护是否顺畅。本章将深入拆解nRF项目的四大核心支柱：目录组织、CMakeLists.txt构建脚本、Kconfig配置体系以及设备树（Devicetree）与链接脚本的协同机制。理解这些内容，是进行源码级功耗优化、外设驱动定制和TinyML算子部署的前提。

4.1 目录组织：从顶层到底层的模块化布局

一个典型的Nordic nRF TinyML工程，其目录结构遵循NCS（nRF Connect SDK）的标准化约定。顶层目录通常包含src/（用户源码）、include/（头文件）、boards/（板级定制）、CMakeLists.txt（构建入口）、prj.conf（Kconfig配置入口）以及Kconfig文件。这种布局的核心目的是将应用逻辑与SDK基础设施分离，使得开发者可以专注于TinyML模型的推理代码，而不必关心Zephyr RTOS内核的底层实现。

在src/目录下，常见的子模块包括main.c（入口函数）、model/（存放TFLite Micro或自定义推理引擎）、sensors/（传感器驱动封装）、power/（功耗管理策略）。每个子模块应当保持独立编译单元，通过头文件暴露接口。例如，sensors/模块应提供sensor_init()和sensor_read()函数，而model/模块则提供model_init()和model_predict()。这种模块化设计不仅便于单元测试，还能在后续功耗优化时快速定位瓶颈。

工程目录示例（精简版）：

my_tinyml_app/
├── CMakeLists.txt          # 顶层构建脚本
├── prj.conf                # Kconfig配置（使能TinyML相关选项）
├── Kconfig                 # 自定义Kconfig扩展
├── src/
│   ├── main.c              # 主逻辑
│   ├── model/
│   │   ├── model_data.c    # 模型权重数组
│   │   └── inference.c     # 推理调用封装
│   ├── sensors/
│   │   ├── imu.c           # IMU传感器驱动
│   │   └── battery.c       # 电量监测
│   └── power/
│       └── pm_handler.c    # 电源状态机
├── include/
│   ├── model.h
│   ├── sensors.h
│   └── power.h
└── boards/
    └── my_custom_board.dts # 自定义设备树覆盖

对于TinyML项目，目录组织的关键考量是模型文件的大小。一个量化后的模型可能占用100-300KB的Flash，因此建议将模型数据放在独立的.c文件中，并通过链接脚本将其放置在特定的Flash分区（如外部Flash或专用存储区），避免与代码段争抢空间。

4.2 CMakeLists.txt：构建系统的核心编排者

CMakeLists.txt是nRF工程的构建蓝图。它负责定义目标（target）、收集源文件、指定头文件路径、链接库以及设置编译选项。在NCS环境中，顶层CMakeLists.txt通常非常简洁，主要调用find_package(Zephyr)来引入Zephyr的构建系统，然后通过target_sources和target_include_directories添加应用代码。

一个典型的TinyML工程CMakeLists.txt包含以下关键部分：

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_tinyml_app)

# 添加应用源码
target_sources(app PRIVATE
    src/main.c
    src/model/inference.c
    src/sensors/imu.c
    src/power/pm_handler.c
)

# 指定头文件路径
target_include_directories(app PRIVATE include)

# 链接TFLite Micro库（如果使用）
find_package(TensorFlowLiteMicro REQUIRED)
target_link_libraries(app PRIVATE TensorFlowLiteMicro)

# 可选：添加自定义链接脚本
zephyr_linker_sources(ROM_START SORT_KEY 0 model_data.c)

在TinyML场景中，CMakeLists.txt的优化重点在于内存布局控制。例如，通过zephyr_linker_sources()可以将模型数据放置在特定的内存区域。此外，对于功耗敏感的设备，可能需要通过CMake选项禁用某些不需要的驱动（如USB或显示），这通常通过Kconfig完成，但CMake可以传递编译宏来进一步优化。

经验提示：在调试内存溢出时，可以在CMakeLists.txt中添加-Wl,--print-memory-usage链接选项，编译后会在终端输出详细的RAM/Flash占用情况。这是定位TinyML模型内存超限的最直接手段。

4.3 Kconfig配置：内核与驱动的开关面板

Kconfig是Zephyr（以及NCS）的配置系统，它通过prj.conf文件或menuconfig图形界面来裁剪内核功能。对于TinyML应用，Kconfig配置直接决定了固件的体积和运行功耗。一个常见的误区是直接使用默认配置，导致大量未使用的驱动被编译进固件，既浪费Flash又增加静态功耗。

关键的Kconfig选项包括：

CONFIG_TINYML_MODEL_SIZE：自定义选项，用于告知编译器模型数组的大小，以便优化内存对齐。
CONFIG_SPI=y / CONFIG_I2C=y：按需使能传感器总线。
CONFIG_PM_DEVICE=y：使能设备电源管理，允许在推理间隙关闭外设电源。
CONFIG_THREAD_MONITOR=n：禁用线程监控以节省RAM。
CONFIG_PRINTK=y：在调试阶段保留日志，量产时关闭。

在TinyML项目中，建议使用prj.conf配合boards/<board_name>_defconfig进行分层配置。板级配置存放硬件相关的固定选项（如时钟频率、Flash大小），而prj.conf存放应用相关的可裁剪选项。例如，对于nRF5340芯片，可以在板级配置中固定CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC=128000000，而在应用配置中决定是否启用BLE。

4.4 设备树（Devicetree）与链接脚本：硬件描述与内存映射

设备树是描述硬件拓扑的声明式语言，在NCS中用于替代传统的板级头文件。它定义了CPU、内存、外设（如UART、SPI、GPIO）的地址和中断号。对于TinyML应用，设备树的主要作用是配置传感器接口和定义内存分区。例如，在.dts文件中可以这样定义一个SPI接口的IMU传感器：

&spi3 {
    status = "okay";
    imu: lsm6dso@0 {
        compatible = "st,lsm6dso";
        reg = <0>;
        spi-max-frequency = <10000000>;
        irq-gpios = <&gpio0 13 GPIO_ACTIVE_HIGH>;
    };
};

链接脚本（.ld文件）则负责将编译产物映射到具体的物理地址。在NCS中，链接脚本通常由Zephyr自动生成，但开发者可以通过zephyr_linker_sources()或自定义.ld文件来调整内存布局。对于TinyML，一个常见的需求是将模型数据放在外部Flash（如QSPI NOR Flash）中，以节省内部Flash空间。这需要在链接脚本中定义一个新的内存区域，并将模型段指向该区域。

配置项	作用	TinyML典型设置
设备树节点	描述外设地址、中断、GPIO	定义IMU、麦克风等传感器接口
内存区域（<ram> / <flash>）	定义RAM和Flash的起始地址与大小	为模型数据划分独立Flash分区
链接脚本段（SECTIONS）	控制代码、数据、BSS的放置位置	将模型数组放入外部Flash段
Kconfig（CONFIG_*）	裁剪内核功能、驱动使能	关闭蓝牙、禁用日志、使能PM

4.5 案例拆解：基于nRF5340的异常检测固件内存优化

假设我们需要交付一个基于nRF5340的振动异常检测固件，模型为一个50KB的量化TFLite模型，系统要求RAM占用不超过256KB，Flash占用不超过1MB。初始构建时，发现Flash占用高达1.2MB，RAM占用300KB，超出规格。

分析过程：首先通过west build -t menuconfig检查配置，发现CONFIG_BT=y（蓝牙被意外启用）、CONFIG_NVS=y（非易失性存储）以及CONFIG_LOG_MODE_IMMEDIATE=y。这些功能占用了约200KB的Flash和50KB的RAM。此外，设备树中定义了多个未使用的UART和SPI节点，导致驱动被编译。

优化步骤：

在prj.conf中设置CONFIG_BT=n、CONFIG_NVS=n，并将日志模式改为CONFIG_LOG_MODE_MINIMAL=y。
在设备树中，将未使用的外设节点状态设为status = "disabled"，例如&uart2 { status = "disabled"; };。
通过链接脚本将模型数据重定向到外部QSPI Flash：在CMakeLists.txt中添加zephyr_linker_sources(ROM_START SORT_KEY 0 model_data.c)，并在.dts中定义model_partition分区。
启用CONFIG_PM_DEVICE=y，并在代码中调用pm_device_action_run()在推理间隙关闭传感器电源。

结果对比：优化后Flash占用降至780KB，RAM占用降至210KB，静态功耗从12mW降至6mW。代价是外部Flash的读取延迟增加了约2ms，但通过双缓冲机制（预取下一帧数据）掩盖了该延迟。

风险提示：在修改链接脚本时，务必确认外部Flash的初始化代码在模型数据访问之前执行。否则，系统在启动阶段访问未初始化的QSPI控制器会导致HardFault。建议在main()早期调用qspi_flash_init()。

4.6 常见误区与总结复盘

在解析nRF工程结构时，开发者常犯以下错误：

混淆Kconfig与设备树：Kconfig控制软件功能（如是否编译某个驱动），设备树描述硬件连接（如SPI片选引脚）。两者不能互相替代。
忽略链接脚本的默认行为：Zephyr默认将所有只读数据放在内部Flash，如果模型数组过大，会导致链接失败。需要主动使用zephyr_linker_sources()或自定义段。
过度裁剪Kconfig导致功能缺失：例如禁用CONFIG_MULTITHREADING会导致Zephyr内核无法调度，TinyML推理线程无法运行。
设备树别名使用不当：在代码中应使用DEVICE_DT_GET(DT_NODELABEL(imu))获取设备指针，而不是硬编码设备名，否则在板级变更时无法适配。

总结而言，源码工程结构的解析是TinyML交付的基石。目录组织决定了代码的可维护性，CMakeLists.txt控制了构建流程，Kconfig裁剪了系统资源，而设备树与链接脚本则完成了从逻辑到物理的映射。在实际项目中，建议建立一份工程配置清单，记录每个关键Kconfig选项的修改原因、设备树节点的状态以及链接脚本的内存分配表。这份文档将成为后续功耗调优和固件迭代的重要参考。