4、算子内核的公共头文件：common.h、kernel_util.h等关键头文件的作用与内容

TFLite Micro 的算子内核实现并非各自为政，而是构建在一组精心设计的公共头文件之上。这些头文件定义了内核与框架之间的接口契约、张量访问的安全封装、以及内存与状态管理的通用工具。理解 common.h、kernel_util.h、op_micro.h 等文件，是阅读具体算子源码（如 Conv、DepthwiseConv、FullyConnected）的前提。本章将深入剖析这些公共头文件的结构、核心宏与内联函数，帮助你建立“框架-内核-张量”三者之间的清晰映射关系。

上图展示了 TFLite Micro 算子内核的依赖关系：算子内核（右侧）通过公共头文件（中间）访问框架层（左侧）提供的上下文与内存分配接口。公共头文件是连接框架与内核的桥梁，所有算子实现都直接或间接依赖这些头文件。

4.1 核心原理：公共头文件的设计哲学

TFLite Micro 的公共头文件设计遵循三个核心原则：最小依赖、显式内存管理和编译期多态。与 TFLite 桌面版本不同，Micro 版本运行在资源受限的 MCU 上，无法使用动态内存分配和 RTTI，因此所有接口都围绕静态分配和 C 风格回调展开。

common.h 定义了 TFLite Micro 特有的数据结构，如 TfLiteContext 和 TfLiteNode 的 Micro 扩展。这些结构体在标准 TFLite 基础上增加了 Micro 特有的字段，例如 GetScratchBuffer 函数指针和 AllocateTempTensor 回调。内核开发者通过 TfLiteContext 获取输入输出张量、申请临时内存、注册 scratch buffer，而无需关心底层分配器的具体实现。

kernel_util.h 则提供了一系列内联工具函数，封装了张量访问、维度计算、量化参数提取等高频操作。这些函数全部声明为 inline 或 static inline，在编译时直接展开，避免函数调用开销。例如 GetTensorData<T>(tensor) 返回张量数据指针，内部通过 reinterpret_cast 将 void* 转换为具体类型指针，同时进行空指针检查。

4.2 判断方法：如何快速定位关键定义

阅读公共头文件时，建议按照以下路径进行：

1. 从 common.h 开始：查看 TfLiteContext 和 TfLiteNode 的 Micro 扩展字段，理解框架如何与内核交互。
2. 进入 kernel_util.h：浏览所有内联函数，重点关注 GetInput、GetOutput、GetTensorData、GetTensorShape 的签名和实现。
3. 查看 op_micro.h：了解 MicroOpResolver 和 MicroContext 的接口，这是算子注册和调用的入口。
4. 对照具体算子源码：以 conv.cc 为例，跟踪其 Prepare() 和 Eval() 函数中调用了哪些公共头文件中的工具。

下表总结了关键头文件的核心内容与典型使用场景：

4.3 案例拆解：以 Conv 算子为例的公共头文件使用

我们以 conv.cc 中的 Prepare() 函数为例，展示公共头文件如何被实际调用。假设输入张量为 input，滤波器为 filter，输出为 output：

TfLiteStatus Prepare(TfLiteContext* context, TfLiteNode* node) {
  // 1. 通过宏获取输入输出张量
  MicroContext* micro_context = GetMicroContext(context);
  TfLiteTensor* input = micro_context->AllocateTempInputTensor(node, 0);
  TfLiteTensor* filter = micro_context->AllocateTempInputTensor(node, 1);
  TfLiteTensor* output = micro_context->AllocateTempOutputTensor(node, 0);

  // 2. 使用 kernel_util.h 中的工具检查维度
  TF_LITE_ENSURE_EQ(context, NumDimensions(input), 4);
  TF_LITE_ENSURE_EQ(context, NumDimensions(filter), 4);

  // 3. 获取量化参数
  auto* conv_params = reinterpret_cast<TfLiteConvParams*>(node->builtin_data);
  const int input_channels = SizeOfDimension(input, 3);
  const int output_channels = SizeOfDimension(filter, 3);

  // 4. 申请 scratch buffer 用于 im2col 转换
  TfLiteStatus status = context->RequestScratchBufferInArena(
      context, input_channels * output_channels * sizeof(int32_t), &scratch_index);
  
  // 5. 释放临时张量
  micro_context->DeallocateTempTensors();
  return kTfLiteOk;
}

这段代码展示了公共头文件的三个关键作用：张量获取（通过 AllocateTempInputTensor）、维度校验（通过 NumDimensions 和 SizeOfDimension）、内存申请（通过 RequestScratchBufferInArena）。所有操作都经过公共接口，不直接操作底层内存。

4.4 实战场景：自定义算子接入公共头文件

假设我们需要在 TFLite Micro 中实现一个自定义的 LayerNorm 算子。接入流程如下：

1. 定义参数结构体：在头文件中声明 struct TfLiteLayerNormParams { float epsilon; };
2. 实现 Prepare 函数：使用 GetMicroContext(context) 获取输入输出张量，校验维度，申请临时内存。
3. 实现 Eval 函数：通过 GetTensorData<float>(input) 获取数据指针，执行归一化计算。
4. 注册算子：在 op_micro.h 的 MicroOpResolver 中添加 AddCustom("LayerNorm", ...)。

关键代码片段：

// 在 Eval 中获取张量数据
const float* input_data = tflite::micro::GetTensorData<float>(input);
float* output_data = tflite::micro::GetTensorData<float>(output);
const int num_elements = tflite::micro::NumElements(input);

// 计算均值与方差
float mean = 0.0f, variance = 0.0f;
for (int i = 0; i < num_elements; ++i) { mean += input_data[i]; }
mean /= num_elements;
for (int i = 0; i < num_elements; ++i) {
  float diff = input_data[i] - mean;
  variance += diff * diff;
}
variance /= num_elements;

// 归一化输出
const float inv_std = 1.0f / sqrtf(variance + params->epsilon);
for (int i = 0; i < num_elements; ++i) {
  output_data[i] = (input_data[i] - mean) * inv_std;
}

这个案例展示了公共头文件如何让自定义算子开发变得高效：开发者无需关心张量内存布局、对齐方式或量化细节，只需专注于算法实现。

4.5 常见误区与总结复盘

在阅读和使用公共头文件时，开发者常犯以下错误：

• 混淆临时张量与持久张量：AllocateTempTensor 分配的张量在 DeallocateTempTensors 后立即失效，不能跨函数保存。
• 忽略维度检查：在 MCU 上，越界访问不会触发异常，而是静默破坏内存，导致难以排查的随机故障。
• 错误使用 GetTensorData 的类型参数：必须与实际张量类型完全匹配，否则 reinterpret_cast 会产生未定义行为。
• 忘记释放 scratch buffer：虽然 arena 分配器会自动回收，但显式释放有助于内存复用。

总结复盘：公共头文件是 TFLite Micro 算子开发的“标准库”。掌握 common.h 中的上下文接口、kernel_util.h 中的张量工具、op_micro.h 中的注册机制，是阅读和编写算子内核的基础。建议读者在阅读具体算子源码前，先花 30 分钟通读这三个头文件，建立整体认知框架。