版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_safe/

一、概述

xt_safe 是 xtiny 平台的中断管理与临界区模块，提供关中断/开中断/查询中断状态三个基础函数，以及一套简洁的临界区宏。在资源竞争敏感的场景中，通过短暂关闭全局中断来保护共享数据的原子性。

设计理念： 最小接口 + 平台可覆写宏 。平台只需实现三个函数，其余通过宏封装。宏全部使用 #if !defined() 模式，允许平台或上层组件注入自定义实现。

1.1 设计原则

全局中断控制 ：关中断是最简单、最快速的临界区保护手段，适用于锁粒度极细的场景
状态保存恢复 ： disable_irq 返回关中断前的状态， enable_irq 按该状态恢复（不是无条件开中断），保证嵌套安全
宏可覆写 ： XT_CRIT_STAT / XT_CRIT_ENTRY / XT_CRIT_EXIT 三个宏均支持外部预定义，平台可替换为更轻量的实现（如仅关某优先级中断）

1.2 依赖

仅依赖 xt_utils.h （基本类型定义）。不依赖任何 OS 原语。

二、核心概念

2.1 临界区三步模式

xt_safe 将临界区拆成三个宏，分别对应声明、加锁、解锁：

XT_CRIT_STAT()    →  声明局部变量 __l_irq_rest （保存中断状态用）
XT_CRIT_ENTRY()   →  关中断并将状态存入 __l_irq_rest
XT_CRIT_EXIT()    →  从 __l_irq_rest 恢复中断状态

这种分离设计让代码结构清晰——声明区、临界区入口、出口各司其职，也避免了 save = disable(); /* ... */ enable(save); 手写变量声明的重复劳动。

2.2 嵌套安全

xt_safe_disable_irq 返回的是 调用前的状态 而非"已关闭"标记。因此以下嵌套是安全的：

XT_CRIT_STAT();
XT_CRIT_ENTRY();    // 关中断，保存状态 A
/* 临界区 1 */
XT_CRIT_ENTRY();    // 此时中断已关，再"关"一次——实际无变化，保存状态 B（已关）
/* 临界区 2 */
XT_CRIT_EXIT();     // 恢复到状态 B（已关），中断不会意外打开
XT_CRIT_EXIT();     // 恢复到状态 A（可能开或关）

2.3 精度权衡

平台	关中断粒度	说明
默认实现	关全局中断	简单可靠，但会延迟所有中断响应
可定制	仅关某优先级中断	通过覆写 XT_CRIT_ENTRY / XT_CRIT_EXIT 实现

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_safe（安全功能）。

3.1 中断控制

函数签名	说明
xt_cpu_base_t xt_safe_disable_irq(void)	关闭全局中断，返回关闭前的中断状态
void xt_safe_enable_irq(xt_cpu_base_t level)	恢复中断到指定状态
xt_cpu_base_t xt_safe_irq_is_enable(void)	查询当前中断是否使能（非 0 为使能，0 为关闭）

3.2 类型

类型签名	说明
xt_cpu_base_t	中断状态保存类型，默认 uint32_t 。定义 XT_SAFE_CPU_BASE_64BITS 后为 uint64_t

3.3 临界区宏

宏	说明
XT_CRIT_STAT()	声明局部变量 __l_irq_rest ，保存中断状态用
XT_CRIT_ENTRY()	关中断并保存状态
XT_CRIT_EXIT()	恢复中断状态
xt_disable_irq()	xt_safe_disable_irq() 的简化别名
xt_enable_irq(level)	xt_safe_enable_irq(level) 的简化别名
xt_irq_is_enable()	xt_safe_irq_is_enable() 的简化别名

四、编译配置

所有宏均采用 #if !defined() 模式，可在 xmake 中覆盖。

宏	默认值	说明
XT_SAFE_CPU_BASE_64BITS	未定义	定义后 xt_cpu_base_t 为 uint64_t
XT_CRIT_STAT	xt_cpu_base_t __l_irq_rest	临界区状态声明，可覆写
XT_CRIT_ENTRY	关中断并保存	临界区入口，可覆写
XT_CRIT_EXIT	恢复中断	临界区出口，可覆写

五、常见模式

5.1 基本临界区

XT_CRIT_STAT()
 
XT_CRIT_ENTRY()
shared_counter++;
XT_CRIT_EXIT()

5.2 带错误处理的临界区

XT_CRIT_STAT()
 
XT_CRIT_ENTRY()
if (resource == NULL) {
    XT_CRIT_EXIT()
    return XT_EINVAL;
}
resource->ref_count++;
XT_CRIT_EXIT()
return XT_EOK;

在 XT_CRIT_ENTRY 和 XT_CRIT_EXIT 之间的任何提前返回路径都必须先调用 XT_CRIT_EXIT ，否则中断永远不会恢复。

5.3 直调函数（不推荐常规使用）

xt_cpu_base_t saved = xt_safe_disable_irq();
/* 临界区 */
xt_safe_enable_irq(saved);

通常建议使用宏而非直调函数——宏名明确表达了临界区的语义边界。

六、反模式

反模式	问题	正确做法
XT_CRIT_ENTRY 后忘记 XT_CRIT_EXIT	中断永久关闭，系统瘫痪	确保所有出口都调用 XT_CRIT_EXIT
不保存返回值直接 xt_safe_disable_irq	无法恢复到原来的中断状态	必须保存返回值并传入 enable_irq
临界区内执行耗时操作	中断延迟大，影响实时性	临界区只做最必要的共享数据访问
XT_CRIT_ENTRY 和 EXIT 不在同一函数	跨函数配对极易遗漏	永远在同一函数内配对