信号量 Semaphore / Counting Synchronization

信号量通过初始化、等待和释放三个主要操作完成协作。 以下接口按本页提供的 HRTOS 声明整理，参数类型和返回值语义应以当前版本头文件为准。

char os_sem_init(u8 sid, char init_val);
char os_sem_post(char sid);
u8 os_sem_wait(u8 sid);

• os_sem_init()：初始化指定信号量的计数状态。
• os_sem_wait()：请求获取一个信号量计数；当前无法获取时的行为由实现决定。
• os_sem_post()：释放信号量或通知等待任务，具体处理顺序以实现为准。

按本页所描述的 HRTOS 实现，信号量使用通用资源管理结构中的计数与等待状态， 而不是必须为信号量单独创建一套独立对象布局。

OS_RESOURCE
{
    value       // 资源计数或可用状态
    owner       // 通用资源结构中的所有者相关字段
    wait_mask   // 等待任务位图
    wait_cnt    // 等待计数或预留字段，依实现而定
}

• value：表示信号量计数状态，是计数型同步的关键字段。
• wait_mask：记录等待该资源的任务集合，具体位定义由内核实现决定。
• owner：通用资源结构中可能存在的所有者相关字段；信号量不应因此被理解为互斥量。
• wait_cnt：其实际用途应根据当前结构体定义和使用位置确认。

等待操作首先检查信号量当前是否可获取。 当计数大于零时，常见实现会直接消耗一个计数；计数不可用时， 则可能登记当前任务并进入等待状态。

os_sem_wait()
    │
    ▼
检查 value
    ├─ value > 0
    │      └─ 消耗计数并返回
    │
    └─ value 不可获取
           └─ 按内核机制登记等待并处理任务阻塞

原实现说明提到 WAIT_SEM 与 wait_mask。 具体的任务状态切换顺序、等待登记细节和返回路径， 应以当前版本源码为准。

释放信号量时，需要处理当前等待任务和计数状态之间的关系。 原页面描述的实现策略是：优先检查是否存在等待任务；有等待任务时尝试唤醒， 否则在计数范围允许时增加计数。

os_sem_post()
    │
    ▼
检查 wait_mask
    ├─ 存在等待任务
    │      └─ 按实现选择并唤醒等待任务
    │
    └─ 没有等待任务
           └─ 检查计数边界并按规则增加 value

原页面指出，等待任务按优先级选择，且计数存在上限。 这两点属于具体实现策略：应进一步核对当前版本的任务选择代码、 计数类型以及溢出处理，不能只根据伪代码推断所有边界行为。

这里描述的是信号量常见的同步模型，并结合了原页面提供的 HRTOS 行为说明。 具体执行顺序、返回时机和错误情况仍应以当前版本实现为准。

• 计数同步：适用于资源数量管理或记录待处理通知的场景。
• 无互斥所有权语义：信号量与互斥量的设计目的不同，不应将其自动视为共享资源的所有权锁。
• 等待任务管理：当前页面描述的实现使用 wait_mask 记录等待关系，具体位图规则以源码为准。
• 优先级相关行为：若实现按优先级选择等待任务，应在文档中明确选择规则和调度边界。
• 计数边界：计数类型及上限决定最大可累积数量，应用应避免无限制地重复释放。

• Semaphore：重点是计数、同步和资源数量管理。
• Mutex：重点是共享资源的互斥访问及相应的所有权规则。
• Event：重点是表达事件或条件状态，适合任务按状态进行协作。
• Message Queue：重点是按队列规则缓存并传递有序数据。
• Mailbox：重点是实现所定义的邮箱消息传递语义。

需要表示可用数量或同步次数  → Semaphore
需要保护共享资源            → Mutex
需要表达事件或条件状态      → Event
需要缓存并顺序传递数据      → Message Queue
需要邮箱式消息传递          → Mailbox

以上是按常见设计语义进行的选型参考。实际工程中仍应检查 HRTOS 对应接口的真实能力、 调用约束和资源开销，再决定采用哪种机制。