TFLM MobileNet V2 Luna 推理示例
===============================

功能说明
--------

本示例在 ``arcs_evb`` 或 ``venusa_rd_evb`` 的 CPU0 上运行 MobileNet V2
W8A8 模型，通过 TensorFlow Lite for Microcontrollers 调用 Luna NPU 版本的
``CONV_2D``、``DEPTHWISE_CONV_2D`` 和 ``FULLY_CONNECTED`` 算子。示例记录
整网推理周期、输出校验和、Top-1 索引以及各 Luna kernel 的调用次数和分阶段
周期，用于验证 TFLM 与 Luna 的整网适配链路并定位性能热点。

示例将模型输入全部填充为 ``128``，目的是提供稳定、可重复的推理冒烟测试，
不执行图片预处理。因此日志中的 Top-1 索引不代表真实图片的分类结果。

硬件连接
--------

无需外部连接，示例使用 LS2684 或 CSK7004J8U 内置 Luna NPU。

模型与内存
----------

- 模型文件：``models/mobilenet_v2.tflite``，大小约 3.84 MiB。
- 输入：``UINT8`` 张量，示例将所有输入元素填充为 ``128``。
- 输出：1000 个 ``UINT8`` 分类分数。
- Tensor arena：位于 PSRAM；ARCS 性能配置为 6 MiB，其他平台默认 4 MiB。
- Conv2D 预打包权重：ARCS 预留最多 4 MiB tensor arena 空间，以消除推理期间的
  权重转换和打包；其他平台默认预算为 1 MiB。
- 推理任务栈：1024 个 ``StackType_t``，在当前 RV32 ABI 下为 4 KiB，固定在
  内部 SRAM 的 ``.fast.data`` 段。
- Luna workspace：由目标板型的 APRAM 配置提供。

构建时，CMake 将 ``mobilenet_v2.tflite`` 转换为 C 数组并链接进固件。需要使用
其他兼容模型时，可通过 ``TFLM_MOBILENET_MODEL`` 覆盖默认路径。

示例步骤
--------

1. 初始化 Luna 时钟和运行时；ARCS 保持硬件一致性 DCache 开启，以加速 PSRAM
   张量访问。
2. 读取随示例提供的 MobileNet V2 W8A8 模型并检查 TFLite schema 版本。
3. 注册模型需要的 10 个算子，其中卷积、深度卷积和全连接使用 Luna kernel。
4. 在 PSRAM tensor arena 中分配模型张量和预打包卷积权重。
5. 使用常量输入执行一次推理，计算输出校验和与 Top-1 索引。
6. 输出 tensor arena 使用量、推理周期、Luna kernel 分阶段统计、调用计数和
   推理任务剩余栈空间。

性能与内存配置
----------------

``prj_arcs.conf`` 默认启用 ``-O3``，并使用下列两个 Kconfig 选项：

.. list-table::
   :header-rows: 1

   * - 选项
     - ARCS 默认值
     - 说明
   * - ``CONFIG_TFLM_MOBILENET_V2_TENSOR_ARENA_SIZE``
     - 6291456（6 MiB）
     - PSRAM tensor arena 容量
   * - ``CONFIG_TFLM_MOBILENET_V2_CONV_PREPARED_FILTER_BUDGET``
     - 4194304（4 MiB）
     - Conv2D 持久化预打包权重预算

增大预打包预算会降低推理耗时，但必须同时保证 tensor arena 能容纳激活张量。
替换模型后应检查 ``tensor arena: used=... capacity=...``；若出现
``Failed to resize buffer``，应增大 arena 或减小预打包预算。

编译
----

模型已随示例提供，但 TFLM 运行时源码仍来自子模块。首次使用时初始化子模块：

.. code-block:: bash

   git submodule update --init modules/tflite-micro

构建 ``arcs_evb`` 固件：

.. code-block:: bash

   ./build.sh -C -S labs/tflite_micro/mobilenet_v2 -DBOARD=arcs_evb

构建 ``venusa_rd_evb`` 固件：

.. code-block:: bash

   ./build.sh -C -S labs/tflite_micro/mobilenet_v2 -DBOARD=venusa_rd_evb

烧录
----

烧录 ARCS CPU0 固件，将 ``<串口设备>`` 替换为实际设备：

.. code-block:: bash

   ./tools/burn/cskburn -C arcs -s <串口设备> -b 3000000 \
       --verify-all 0x0 build/tflite_micro_mobilenet_v2.bin

烧录 VenusA CPU0 固件：

.. code-block:: bash

   ./tools/burn/cskburn -C venusa -s <串口设备> -b 3000000 \
       --verify-all 0x0 build/tflite_micro_mobilenet_v2.bin

预期输出
--------

推理周期和剩余栈空间会随平台及构建配置变化。使用随示例提供的模型时，日志格式如下：

.. code-block:: text

   I/tflm_mobilenet_v2 ... mobilenet_v2 passed: output=1000 checksum=62994 top1=892 invoke=... cycles conv_luna=35 depthwise_luna=17 fc_luna=1
   I/tflm_mobilenet_v2 ... profile conv inner: ...
   I/tflm_mobilenet_v2 ... mobilenet_v2 result=0 stack_free=...

``mobilenet_v2 passed`` 表示模型解析、张量分配和 ``Invoke()`` 均成功。确认 Luna
加速链路时，还应检查 ``conv_luna``、``depthwise_luna`` 和 ``fc_luna`` 均大于零。

核心 API
--------

.. list-table::
   :header-rows: 1

   * - API
     - 说明
   * - ``tflite::GetModel()``
     - 读取 FlatBuffer 模型描述
   * - ``tflite::MicroMutableOpResolver``
     - 仅注册 MobileNet V2 所需算子
   * - ``tflite::luna::Register_CONV_2D_INT8()``
     - 注册 Luna NPU int8 卷积算子
   * - ``tflite::luna::Register_DEPTHWISE_CONV_2D_INT8()``
     - 注册 Luna NPU int8 深度卷积算子
   * - ``tflite::luna::Register_FULLY_CONNECTED_INT8()``
     - 注册 Luna NPU int8 全连接算子
   * - ``tflite::MicroInterpreter::AllocateTensors()``
     - 在 PSRAM tensor arena 中规划张量内存
   * - ``tflite::MicroInterpreter::Invoke()``
     - 执行一次整网推理
   * - ``xTaskCreateStatic()``
     - 使用内部 SRAM 静态栈创建推理任务

核心文件
--------

.. list-table::
   :header-rows: 1

   * - 文件
     - 说明
   * - ``models/mobilenet_v2.tflite``
     - MobileNet V2 W8A8 模型
   * - ``src/main.cc``
     - 算子注册、张量分配、推理及结果检查
   * - ``src/luna_platform.c``
     - Luna 时钟、Cache 和运行时初始化
   * - ``src/model_data.cc.in``
     - 将模型字节生成固件内 C 数组的模板
   * - ``prj_arcs.conf`` / ``prj_venusa.conf``
     - ARCS 与 VenusA 的 CPU0 平台配置

注意事项
--------

1. **分类语义**：示例使用常量输入，只验证推理链路；Top-1 索引不能作为图片
   分类结果。接入真实图片时需要按模型要求完成尺寸、通道顺序和量化预处理。
2. **Flash 容量**：模型会直接链接进固件，当前配置为固件预留 8 MiB Flash 空间。
3. **模型兼容性**：替换模型时必须保持输入类型、输出类型和算子集合兼容；否则需
   同步修改 ``src/main.cc`` 的张量检查与算子注册。
4. **推理任务栈**：调用 Luna 的完整推理任务栈必须位于内部 SRAM，避免命令参数
   落入 Luna 无法访问的内存。
5. **ARCS Cache**：当前 ARCS 板级配置启用硬件一致性 DCache；Luna 命令数据位于
   APRAM，模型张量位于 PSRAM。若移植到非一致性 Cache 平台，必须补充显式的
   clean/invalidate 操作，不能直接沿用本配置。
6. **成功判据**：除 ``result=0`` 外，还应确认三类 Luna kernel 调用计数均大于零。