rt-thread/bsp/phytium/libraries/standalone/doc/reference/driver/fsemaphore.md

FSemaphore 驱动程序

1. 概述

硬件信号量（Semaphore）是E2000提供的一个二值信号量模块，支持 32 个硬件信号量。每个信号量包括 UNLOCK 和 LOCKED 两个状态

2. 功能

FSemaphore 驱动程序主要完成 Semaphore 模块的初始化，锁的分配、获取与释放， 相关源文件为：

fsemaphore
    .
    ├── fsemaphore.c
    ├── fsemaphore.h
    ├── fsemaphore_g.c
    ├── fsemaphore_hw.h
    └── fsemaphore_sinit.c

3. 配置方法

以下部分将指导您完成 FSemaphore 驱动的软件配置:

• 初始化 Semaphore 控制器
• 获取 Semaphore 锁
• 加锁/解锁操作

4. 应用示例

Semaphore加锁解锁测试

5. API参考

5.1. 用户数据结构

FSemaConfig

• Semaphore控制器配置

typedef struct 
{
    u32 id;             /* Semaphore控制器id */
    uintptr base_addr;  /* Semaphore控制器基地址 */
} FSemaConfig; /* Semaphore控制器配置 */

FSemaLocker

• Semaphore锁实例

typedef struct
{
    u32 index;                              /* Semaphore锁id */
#define FSEMA_LOCKER_NAME_LEN       32U
    char name[FSEMA_LOCKER_NAME_LEN];       /* Semaphore锁的名字 */
    u32 owner;                              /* Semaphore锁的拥有者 */
    FSema *sema;                            /* Semaphore控制器实例 */
} FSemaLocker; /* Semaphore锁实例 */

FSema

• Semaphore控制器实例

typedef struct _FSema
{
    FSemaConfig config;                       /* Semaphore控制器配置 */
    u32 is_ready;                             /* Semaphore控制器初始化是否完成 */
    FSemaLocker *locker[FSEMA_NUM_OF_LOCKER]; /* Semaphore锁实例，locker[i] == NULL 表示锁尚未分配 */
} FSema; /* Semaphore控制器实例 */

5.2 错误码定义

FSEMA_SUCCESS ：成功 FSEMA_ERR_NOT_INIT ：控制器未初始化 FSEMA_ERR_NO_AVAILABLE_LOCKER ：没有空闲的锁可以分配 FSEMA_ERR_LOCK_TIMEOUT ：锁被占用，获取锁失败 FSEMA_ERR_NO_PERMISSION ：当前角色没有权限操作

5.3. 用户API接口

FSemaLoopkupConfig

const FSemaConfig *FSemaLoopkupConfig(u32 instance_id)

Note:

• 获取Semaphore的默认配置

Input:

• {u32} instance_id, Semaphore的实例id

Return:

• {const FSemaConfig *} Semaphore的默认配置

FSemaCfgInitialize

FError FSemaCfgInitialize(FSema *const instance, const FSemaConfig *input_config)

Note:

• 初始化Semaphore控制器

Input:

• {FSema} *instance, Semaphore控制器实例
• {FSemaConfig} *input_config, Semaphore控制器配置

Return:

• {FError} FSEMA_SUCCESS 表示初始化成功

FSemaDeInitialize

void FSemaDeInitialize(FSema *const instance)

Note:

• 去初始化Semaphore控制器

Input:

• {FSema} *instance, Semaphore控制器实例

Return:

• 无

FSemaCreateLocker

FError FSemaCreateLocker(FSema *const instance, FSemaLocker *const locker)

Note:

• 分配和创建Semaphore锁

Input:

• {FSema} *instance, Semaphore控制器实例
• {FSemaLocker} *locker, Semaphore锁的实例

Return:

• {FError} FSEMA_SUCCESS 表示分配成功

FSemaDeleteLocker

FError FSemaDeleteLocker(FSemaLocker *const locker)

Note:

• 强制解除Semaphore锁并删除锁实例

Input:

• {FSemaLocker} *locker, Semaphore锁实例

Return:

• {FError} FSEMA_SUCCESS 表示删除锁成功

FSemaTryLock

FError FSemaTryLock(FSemaLocker *const locker, u32 owner, u32 try_times, FSemaRelaxHandler relax_handler)

Note:

• 尝试获取Semaphore锁

Input:

• {FSemaLocker} *locker, Semaphore锁的实例
• {u32} owner, 当前尝试获取锁的是谁
• {u32} try_times, 尝试获取的次数
• {FSemaRelaxHandler} relax_handler, 每次尝试获取锁失败后的relax函数

Return:

• {FError} FSEMA_SUCCESS 表示成功获取锁，FSEMA_ERR_LOCK_TIMEOUT 表示锁已经被占用

FSemaUnlock

FError FSemaUnlock(FSemaLocker *const locker, u32 owner)

Note:

• 尝试释放Semaphore锁

Input:

• {FSemaLocker} *locker, Semaphore锁实例
• {u32} owner, 当前尝试释放锁的身份

Return:

• {FError} FSEMA_SUCCESS释放锁成功

FSemaUnlockAll

FError FSemaUnlockAll(FSema *const instance)

Note:

• 强制解除所有Semaphore锁

Input:

• {FSema} *instance, Semaphore控制器实例

Return:

• {FError} FSEMA_SUCCESS表示强制解锁成功

FSemaIsLocked

boolean FSemaIsLocked(FSemaLocker *locker)

Note:

• 检查指定Semaphore锁是否处于锁定状态

Input:

• {FSemaLocker} *locker, Semaphore锁实例

Return:

• {boolean} TRUE: 处于锁定状态