4.6.7 最佳实践

📚 本节导读

学习时长: 约 15 分钟
难度级别: ⭐⭐☆☆☆
前置知识: 错误处理三层的全部内容

🎯 学习目标

• 掌握 OneOS 错误处理的最佳实践总结
• 了解开发和生产环境的不同配置策略
• 建立规范的错误处理编码习惯

一、错误处理最佳实践

1.1 始终检查返回值

永远不要忽略 API 的返回值。即使确信"不会出错"，也应检查返回值——因为在嵌入式系统中，由于内存碎片、中断竞争、资源耗尽等原因，很多"不可能"的错误确实会发生。

/* 错误做法 */
os_sem_wait(sem, OS_WAIT_FOREVER);
/* 直接使用资源，假设信号量一定获取成功 */

/* 正确做法 */
os_err_t ret = os_sem_wait(sem, OS_WAIT_FOREVER);
if (ret != OS_SUCCESS)
{
    os_kprintf("sem_wait failed: %d\r\n", ret);
    return;
}

1.2 使用断言检查"不可能"的条件

用断言验证编程逻辑中的不变量，在开发阶段尽早暴露问题：

void process_data(void *buffer, size_t size)
{
    /* 这些条件在逻辑上不应该为假 */
    OS_ASSERT(buffer != OS_NULL);
    OS_ASSERT(size > 0);
    OS_ASSERT(size <= MAX_BUFFER_SIZE);

    /* 正常处理 */
}

1.3 使用错误码处理可恢复的错误

对于可能发生但可以恢复的运行时错误，使用错误码返回：

os_err_t send_message(const char *msg)
{
    if (msg == OS_NULL)
    {
        return OS_INVAL;  /* 参数无效，可恢复的错误 */
    }

    if (queue_is_full())
    {
        return OS_FULL;   /* 队列满，调用者可稍后重试 */
    }

    /* 正常发送 */
    return OS_SUCCESS;
}

1.4 区分断言和错误码的使用场景

场景	使用	示例
空指针参数（不应发生）	断言	OS_ASSERT(ptr != OS_NULL)
用户输入无效	错误码	return OS_INVAL
内存分配失败	取决于策略	关键系统用断言，普通系统用错误码
内部状态不一致	断言	OS_ASSERT(state == EXPECTED)
通信超时	错误码	return OS_TIMEOUT
资源临时不可用	错误码	return OS_BUSY

二、环境配置策略

2.1 开发阶段配置

/* 开发阶段：启用所有调试和检查功能 */
#define OS_USING_ASSERT                /* 启用断言 */
#define OS_USING_SAFETY_MECHANISM      /* 启用安全机制 */
#define OS_USING_MEM_TRACE             /* 启用内存追踪 */
#define OS_USING_CPU_MONITOR           /* 启用 CPU 监控 */
#define OS_USING_SPINLOCK_CHECK        /* 启用自旋锁检查 */
#define OS_USING_MEMPOOL_CHECK_TAG     /* 启用内存池标签检查 */
#define OS_USING_KERNEL_DEBUG          /* 启用内核调试日志 */
#define OS_TICK_PER_SECOND 100         /* 适当的 tick 频率 */

2.2 生产阶段配置

/* 生产阶段：平衡安全性和性能 */
// #define OS_USING_ASSERT             /* 可禁用断言减小体积 */
#define OS_USING_SAFETY_MECHANISM      /* 保留安全机制 */
// #define OS_USING_MEM_TRACE          /* 禁用内存追踪 */
// #define OS_USING_CPU_MONITOR        /* 禁用 CPU 监控 */
// #define OS_USING_SPINLOCK_CHECK     /* 禁用自旋锁检查 */
// #define OS_USING_MEMPOOL_CHECK_TAG  /* 可选保留 */
// #define OS_USING_KERNEL_DEBUG       /* 禁用内核调试日志 */
#define OS_TICK_PER_SECOND 100         /* 根据实时性需求调整 */

2.3 安全关键系统配置

/* 安全关键系统：最大化安全保护 */
#define OS_USING_ASSERT                /* 保留断言 */
#define OS_USING_SAFETY_MECHANISM      /* 必须启用 */
#define OS_USING_MEMPOOL_CHECK_TAG     /* 保留标签检查 */
#define OS_TICK_PER_SECOND 200         /* 更高的实时性 */

三、栈空间配置

3.1 栈大小确定方法

1. 初始分配一个较大的栈（如 2048 字节）
2. 在典型负载下运行系统
3. 使用 os_task_get_stack_top/begin/end 检查实际使用量
4. 将栈大小调整为实际使用量的 1.3-1.5 倍
5. 在边界条件下验证

3.2 栈使用监控

/* 定期检查栈使用情况的监控任务 */
void stack_monitor_task(void *arg)
{
    while (1)
    {
        check_all_tasks_stack();
        os_task_msleep(5000);  /* 每 5 秒检查一次 */
    }
}

3.3 栈大小建议

任务类型	最小	推荐	安全余量
空闲任务	128	256	128
简单任务	256	512	256
中等任务	512	1024	512
复杂任务	1024	2048	1024
网络/文件系统任务	2048	4096	2048

四、ISR 上下文注意事项

4.1 禁止在 ISR 中阻塞

/* 错误：在 ISR 中调用可能阻塞的 API */
void my_isr_handler(void)
{
    os_sem_wait(sem, OS_WAIT_FOREVER);  /* 绝对禁止！ */
    os_task_msleep(100);                /* 绝对禁止！ */
    os_mutex_lock(mutex, OS_WAIT_FOREVER); /* 绝对禁止！ */
}

4.2 ISR 中安全使用的 API

/* ISR 中安全使用的 API */
void my_isr_handler(void)
{
    os_sem_post(sem);           /* 安全：释放信号量 */
    os_event_post(event, flags); /* 安全：发送事件 */
    os_timer_start(timer);      /* 安全：启动定时器（硬件定时器在 ISR 中执行） */
}

4.3 使用自旋锁进行短临界区保护

/* ISR 和任务共享数据的保护 */
os_spinlock_t g_spinlock;

void isr_handler(void)
{
    os_ubase_t level;

    /* 自旋锁保护极短临界区 */
    level = os_spinlock_lock(&g_spinlock);
    g_shared_data++;
    os_spinlock_unlock(&g_spinlock, level);
}

void task_function(void)
{
    os_ubase_t level;

    /* 任务中也使用自旋锁保护同一共享数据 */
    level = os_spinlock_lock(&g_spinlock);
    g_shared_data++;
    os_spinlock_unlock(&g_spinlock, level);
}

原则：自旋锁用于极短（微秒级）的临界区保护，互斥锁用于较长（毫秒级）的临界区保护。ISR 中只能使用自旋锁，不能使用互斥锁。

五、安全机制配置

5.1 注册故障钩子

void init_safety_handlers(void)
{
    /* 在生产环境中注册故障处理钩子 */
    #ifdef OS_USING_SAFETY_MECHANISM
    os_safety_assert_set_hook(safety_fault_hook);
    os_safety_task_stack_overflow_set_hook(safety_fault_hook);
    os_safety_exception_set_hook(safety_fault_hook);
    #endif
}

static void safety_fault_hook(void)
{
    /* 1. 将系统置于安全状态 */
    set_safe_outputs();

    /* 2. 记录故障信息 */
    save_fault_record();

    /* 3. 执行复位（或停止，取决于应用需求） */
    os_hw_reboot();
}

5.2 故障记录

建议在故障钩子中记录以下信息：

• 故障类型（断言/堆栈溢出/异常）
• 故障任务名称
• 系统 tick 值
• 故障时的寄存器状态（对于异常）
• 故障时间戳（如果有 RTC）

六、调试追踪策略

6.1 开发阶段

• 启用所有调试追踪工具
• 定期输出内存追踪报告，检查内存泄漏
• 使用 CPU 监控分析任务 CPU 使用率
• 使用 os_kprintf 输出关键路径的调试信息
• 保留断言以捕获逻辑错误

6.2 测试阶段

• 保留内存追踪和内存池标签检查
• 在边界条件下运行压力测试
• 检查栈使用情况，确保有足够余量
• 使用故障注入测试安全机制和异常处理

6.3 生产阶段

• 仅保留必要的安全机制
• 禁用性能开销大的调试工具
• 保留关键的故障处理钩子
• 考虑实现简单的看门狗机制

七、配置选项汇总

配置宏	开发	测试	生产	安全关键
OS_USING_ASSERT	✅	✅	❌/✅	✅
OS_USING_SAFETY_MECHANISM	✅	✅	✅	✅
OS_USING_MEM_TRACE	✅	✅	❌	❌
OS_USING_CPU_MONITOR	✅	✅	❌	❌
OS_USING_SPINLOCK_CHECK	✅	✅	❌	❌
OS_USING_MEMPOOL_CHECK_TAG	✅	✅	❌/✅	✅
OS_USING_KERNEL_DEBUG	✅	❌	❌	❌

📝 本节小结

错误处理是嵌入式系统可靠性的基石。在 OneOS 开发中，应遵循以下核心原则：始终检查 API 返回值，用断言验证逻辑不变量，用错误码处理可恢复的运行时错误，合理配置栈空间并预留安全余量，在 ISR 中避免阻塞操作，使用自旋锁保护极短临界区而用互斥锁保护较长临界区。开发阶段应启用所有调试工具，生产阶段保留必要的安全机制，安全关键系统应最大化安全保护。这些最佳实践将帮助开发者编写更健壮、更可靠的嵌入式代码。

🔗 相关链接

• 4.6.1 断言机制
• 4.6.2 错误码
• 4.6.3 安全机制
• 4.6.4 堆栈溢出检测
• 4.6.5 异常处理
• 4.6.6 调试追踪