3、返回码设计原则：语义、命名规范与错误码分类

TinyML 设备运行在资源极度受限的 MCU 上，通常只有几十 KB 的 RAM 和几百 KB 的 Flash。在这种环境下，异常处理无法依赖操作系统级的异常机制或复杂的日志系统，返回码（Return Code）成为最基础、最可靠的错误传递手段。一个设计良好的返回码体系，不仅能让上层调用者快速定位问题模块，还能在板端日志中形成一致的排查线索。本章将围绕返回码的语义定义、命名规范、分类体系展开，并结合实际工程案例说明如何在 TinyML 项目中落地。

3.1 返回码的核心语义：从“是否成功”到“为何失败”

在 TinyML 场景中，返回码的第一层语义是成功与失败的二元判断。C 语言约定俗成地用 0 表示成功，非零值表示失败。但在嵌入式系统中，仅有二元判断远远不够。一个传感器读取函数可能因为 I2C 总线忙、设备未应答、数据校验失败、缓冲区溢出等多种原因失败，如果只返回 -1，上层代码无法区分具体原因，只能笼统地重试或复位，这会导致调试效率极低。

因此，返回码的第二层语义是错误原因的精确表达。每个返回码应当对应一个明确的失败场景，并且该场景在代码库中是唯一的。例如，SENSOR_ERR_I2C_NACK 表示传感器在 I2C 通信中未应答，而 SENSOR_ERR_CRC_MISMATCH 表示读取到的数据 CRC 校验失败。这种精确性让板端日志可以直接输出错误码对应的字符串，帮助开发者快速定位是通信问题、数据完整性问题还是配置问题。

第三层语义是错误严重级别的区分。TinyML 设备往往没有足够资源进行复杂的异常处理，但可以通过返回码的数值范围来区分“可恢复错误”和“致命错误”。例如，0x10-0x1F 范围的参数错误通常可以通过修正调用参数恢复；0x20-0x2F 的资源不足错误可能需要释放内存或等待资源可用；而 0x40-0x4F 的硬件错误往往意味着设备需要重新初始化或复位。这种分级让上层调度器可以决定是重试、降级还是进入安全模式。

3.2 错误码分类体系：用数值区间划分错误域

一个清晰的错误码分类体系是返回码设计的骨架。建议采用按位划分的方式，将 32 位整数分为多个字段，每个字段表达不同维度的信息。以下是一种适用于 TinyML 项目的分类方案：

错误码范围	类别	典型场景	处理策略
0x0000	成功	操作正常完成	继续执行
0x0001 - 0x0FFF	通用错误	未初始化、无效操作、状态冲突	检查调用顺序或状态机
0x1000 - 0x1FFF	参数错误	空指针、越界索引、非法枚举值	修正调用参数
0x2000 - 0x2FFF	资源不足	内存分配失败、缓冲区满、栈溢出	释放资源或增加容量
0x3000 - 0x3FFF	超时/状态	I2C 超时、等待信号超时、状态机卡死	重试或复位外设
0x4000 - 0x4FFF	硬件/通信	CRC 错误、总线冲突、外设故障	重新初始化硬件
0x5000 - 0x5FFF	算法/模型	输入维度不匹配、量化溢出、推理超时	检查模型配置或输入数据

这种分类方式的优势在于：数值区间即错误类别，开发者看到错误码的高位字节就能快速判断错误类型，无需查阅完整错误码表。同时，每个模块可以在自己的类别区间内定义具体错误码，例如传感器模块使用 0x4100-0x41FF 表示 I2C 通信错误，使用 0x4200-0x42FF 表示数据校验错误，这样既保持了全局分类的一致性，又允许模块内部灵活扩展。

在实际工程中，建议将错误码定义集中在头文件中，并使用枚举或宏定义。例如：

// error_codes.h
typedef enum {
    ERR_OK = 0x0000,
    ERR_GEN_UNINIT = 0x0001,
    ERR_GEN_INVALID_OP = 0x0002,
    ERR_PARAM_NULL_PTR = 0x1001,
    ERR_PARAM_OUT_OF_RANGE = 0x1002,
    ERR_RES_MEM_ALLOC = 0x2001,
    ERR_RES_BUF_FULL = 0x2002,
    ERR_TIMEOUT_I2C = 0x3001,
    ERR_TIMEOUT_ADC = 0x3002,
    ERR_HW_CRC = 0x4001,
    ERR_HW_BUS_CONFLICT = 0x4002,
    ERR_MODEL_INPUT_SIZE = 0x5001,
    ERR_MODEL_QUANT_OVERFLOW = 0x5002
} err_code_t;

3.3 命名规范：让错误码自解释

错误码的命名直接影响代码的可读性和日志的可解析性。在 TinyML 项目中，建议遵循以下命名规范：

• 前缀标识模块：使用模块缩写作为前缀，如 SENSOR_、MEM_、I2C_、MODEL_、FLASH_。这能避免不同模块间的错误码冲突，也让日志中的错误码能直接定位到模块。
• 类别关键词：在模块名后紧跟错误类别，如 ERR_PARAM、ERR_TIMEOUT、ERR_RES。这对应了错误码分类体系中的类别字段。
• 动作或对象描述：最后用简洁的动词或名词描述具体错误，如 INVALID、FAILED、NACK、OVERFLOW。避免使用模糊的 ERROR 或 FAIL 单独作为后缀。
• 全大写 + 下划线：所有错误码宏或枚举值使用全大写字母，单词间用下划线分隔，与普通变量命名区分。
• 统一类型：所有返回码使用 int32_t 类型，避免使用 uint8_t 或 uint16_t，因为 32 位整数可以容纳完整的错误码分类体系，且在不同编译器和平台上行为一致。

以下是一个命名对比示例：

不推荐命名	推荐命名	说明
ERROR	SENSOR_ERR_I2C_NACK	明确模块、类别和具体原因
FAIL	MEM_ERR_ALLOC_FAILED	明确是内存分配失败
BAD_PARAM	MODEL_ERR_INPUT_SIZE	明确是模型输入尺寸不匹配
TIMEOUT	I2C_ERR_TIMEOUT	明确是 I2C 模块超时

3.4 实战案例：传感器数据采集链路的返回码设计

以一个典型的 TinyML 振动监测节点为例，该节点使用 I2C 接口的加速度传感器，采集数据后通过轻量级模型进行故障分类。整个数据采集链路涉及传感器初始化、数据读取、校验、缓存和模型推理五个环节。我们为每个环节设计返回码，并观察它们如何协同工作。

背景与约束：MCU 为 Cortex-M4，主频 80MHz，RAM 仅 64KB，Flash 256KB。传感器为 ADXL345，I2C 地址 0x53。系统要求：当传感器通信失败时，设备不能死机，必须自动重试 3 次后上报错误；当模型推理输入数据异常时，应丢弃当前帧并继续采集。

初始现象：设备在现场运行 2 小时后，偶尔出现数据中断，日志显示 ERR_GEN_UNINIT，但传感器初始化代码明明已经执行过。进一步排查发现，I2C 总线在长时间运行后出现锁死，导致后续读取操作返回未初始化错误。

分析过程：通过查看返回码，发现 ERR_GEN_UNINIT 被多个模块共用，无法区分是传感器未初始化还是 I2C 总线故障。这说明错误码分类不够精细。重新设计后，将 I2C 通信错误单独归类为 I2C_ERR_TIMEOUT 和 I2C_ERR_BUS_LOCK，传感器读取错误归类为 SENSOR_ERR_READ_FAIL。

操作步骤：

1. 重新定义错误码，将 I2C 总线锁死单独编码为 I2C_ERR_BUS_LOCK = 0x3003。
2. 在传感器读取函数中，捕获 I2C 错误后先执行总线释放操作（切换 GPIO 模式并发送 9 个时钟脉冲），再返回错误码。
3. 上层调度器根据返回码决定重试策略：I2C_ERR_BUS_LOCK 执行总线恢复后重试，SENSOR_ERR_READ_FAIL 直接丢弃当前帧。
4. 在板端日志中，将错误码转换为可读字符串输出，例如 [SENSOR] I2C bus locked, recovering...。

结果对比：重新设计后，设备在相同工况下运行 72 小时，数据中断次数从 5 次降为 0 次。即使发生 I2C 总线锁死，系统也能在 2ms 内自动恢复，且日志中能明确看到 I2C_ERR_BUS_LOCK 和恢复动作。

风险与代价：增加错误码分类会增加代码量（约 200 字节 Flash），但换来了更快的故障定位能力。同时，需要为每个错误码编写对应的日志字符串，占用少量 Flash 空间。

3.5 常见误区与设计复盘

在 TinyML 返回码设计中，以下误区值得特别注意：

• 误区一：所有错误都返回 -1。这会让日志失去诊断价值，调试时只能靠猜测。正确做法是至少区分模块和类别。
• 误区二：错误码定义过于细碎。如果每个函数都定义 20 个错误码，维护成本会急剧上升。建议每个模块控制在 10-15 个错误码以内，覆盖主要失败场景即可。
• 误区三：忽略错误码的传递链。底层函数返回错误后，上层函数直接返回 ERR_GEN_UNINIT 而不是透传底层错误码，导致原始错误信息丢失。正确做法是上层函数在返回时保留底层错误码，或至少将底层错误码记录到日志中。
• 误区四：错误码与日志脱节。返回码设计得再好，如果板端日志不输出错误码对应的字符串和上下文信息，仍然难以排查。建议在日志模块中维护一张错误码到字符串的映射表。
• 误区五：使用 uint8_t 作为返回类型。8 位整数最多只能表达 256 种错误，且容易与数据字节混淆。使用 int32_t 可以避免这些问题。

在项目复盘时，建议团队定期审查错误码使用情况：哪些错误码从未被使用？哪些错误码经常出现但定位困难？哪些错误码语义模糊需要拆分？通过这种持续优化，返回码体系会越来越贴合实际工程需求。