OpenHarmony轻量系统（Hi3861）RTOS API开发详解

鸿蒙小白龙2026-01-04 10:29

目录

  1. 内核管理函数
  2. 任务管理函数
  3. 消息队列函数
  4. 信号量函数
  5. 互斥锁函数
  6. 事件标志函数
  7. 定时器函数
  8. 实际应用示例
  9. 配置参数说明

1. 内核管理函数

1.1 osKernelInitialize

函数原型：

c 复制代码 
osStatus_t osKernelInitialize (void);

功能描述：

初始化RTOS内核。该函数在使用任何CMSIS-RTOS2功能之前必须被调用。

返回值：

  • osOK：内核初始化成功
  • osError：内核初始化失败

说明：

  • 该函数通常在系统启动时自动调用
  • 在OpenHarmony轻量系统中，内核初始化由系统框架自动完成
  • 应用开发者通常不需要直接调用此函数

1.2 osKernelStart

函数原型：

c 复制代码 
osStatus_t osKernelStart (void);

功能描述：

启动RTOS内核，开始任务调度。

返回值：

  • osOK：内核启动成功
  • osError：内核启动失败

说明：

  • 内核启动后，系统开始执行最高优先级的就绪任务
  • 内核只能启动一次，重复调用会返回错误
  • 在OpenHarmony轻量系统中，该函数由系统框架调用

1.3 osKernelGetState

函数原型：

c 复制代码 
osKernelState_t osKernelGetState (void);

功能描述：

获取内核当前状态。

返回值：

  • osKernelInactive：内核未激活
  • osKernelReady：内核已就绪
  • osKernelRunning：内核正在运行
  • osKernelLocked：内核已锁定
  • osKernelSuspended：内核已挂起
  • osKernelError：内核异常

内核状态枚举定义：

c 复制代码 
typedef enum {
    osKernelInactive        =  0,
    osKernelReady           =  1,
    osKernelRunning         =  2,
    osKernelLocked          =  3,
    osKernelSuspended       =  4,
    osKernelError           = -1,
    osKernelReserved        = 0x7FFFFFFFU
} osKernelState_t;

1.4 osKernelGetTickCount

函数原型：

c 复制代码 
uint32_t osKernelGetTickCount (void);

功能描述：

获取内核当前的系统滴答计数。

返回值：

  • 返回当前的系统滴答计数值（uint32_t类型）

说明：

  • 系统滴答是内核的基本时间单位
  • 可用于计算时间间隔
  • 滴答频率由LOSCFG_BASE_CORE_TICK_PER_SECOND配置决定

1.5 osKernelGetTickFreq

函数原型：

c 复制代码 
uint32_t osKernelGetTickFreq (void);

功能描述：

获取内核滴答频率（每秒的滴答数）。

返回值：

  • 返回每秒的滴答数

说明：

  • 典型值为100（10ms一个滴答）或1000（1ms一个滴答）
  • 用于将滴答数转换为实际时间

1.6 osKernelLock

函数原型：

c 复制代码 
int32_t osKernelLock (void);

功能描述：

锁定内核调度，禁止任务切换。

返回值：

  • 1：内核锁定成功
  • 0：内核已经被锁定
  • 负值：锁定失败

说明：

  • 锁定后，当前任务不会被其他任务抢占
  • 必须配对使用osKernelUnlock解锁
  • 支持嵌套锁定

1.7 osKernelUnlock

函数原型：

c 复制代码 
int32_t osKernelUnlock (void);

功能描述：

解锁内核调度，恢复任务切换。

返回值：

  • 1：内核解锁成功
  • 0：内核未被锁定
  • 负值：解锁失败

说明：

  • 必须与osKernelLock配对使用
  • 嵌套锁定时，只有最后一次解锁才会真正恢复调度

2. 任务管理函数

2.1 osThreadNew

函数原型：

c 复制代码 
osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);

功能描述：

创建一个新的任务并使其进入就绪状态。

参数说明：

  • func：任务函数指针，任务入口函数
  • argument：传递给任务的参数指针
  • attr：任务属性结构体指针

返回值：

  • 成功：返回任务ID（osThreadId_t类型）
  • 失败：返回NULL

任务属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 任务名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 任务控制块内存地址
    uint32_t        cb_size;      // 任务控制块内存大小
    void            *stack_mem;   // 栈内存地址
    uint32_t        stack_size;   // 栈大小（字节）
    osPriority_t    priority;     // 任务优先级
    TZ_ModuleId_t   tz_module;    // TrustZone模块ID
    uint32_t        reserved;     // 保留字段
} osThreadAttr_t;

任务优先级定义：

c 复制代码 
typedef enum {
    osPriorityNone          =  0,
    osPriorityIdle          =  1,   // 空闲任务优先级
    osPriorityLow           =  8,   // 低优先级
    osPriorityLow1          =  9,
    osPriorityLow2          =  10,
    osPriorityLow3          =  11,
    osPriorityLow4          =  12,
    osPriorityLow5          =  13,
    osPriorityLow6          =  14,
    osPriorityLow7          =  15,
    osPriorityBelowNormal   =  16,  // 低于正常优先级
    osPriorityBelowNormal1  =  17,
    osPriorityBelowNormal2  =  18,
    osPriorityBelowNormal3  =  19,
    osPriorityBelowNormal4  =  20,
    osPriorityBelowNormal5  =  21,
    osPriorityBelowNormal6  =  22,
    osPriorityBelowNormal7  =  23,
    osPriorityNormal        =  24,  // 正常优先级（推荐使用）
    osPriorityNormal1       =  25,
    osPriorityNormal2       =  26,
    osPriorityNormal3       =  27,
    osPriorityNormal4       =  28,
    osPriorityNormal5       =  29,
    osPriorityNormal6       =  30,
    osPriorityNormal7       =  31,
    osPriorityAboveNormal   =  32,  // 高于正常优先级
    osPriorityAboveNormal1  =  33,
    osPriorityAboveNormal2  =  34,
    osPriorityAboveNormal3  =  35,
    osPriorityAboveNormal4  =  36,
    osPriorityAboveNormal5  =  37,
    osPriorityAboveNormal6  =  38,
    osPriorityAboveNormal7  =  39,
    osPriorityHigh          =  40,  // 高优先级
    osPriorityHigh1         =  41,
    osPriorityHigh2         =  42,
    osPriorityHigh3         =  43,
    osPriorityHigh4         =  44,
    osPriorityHigh5         =  45,
    osPriorityHigh6         =  46,
    osPriorityHigh7         =  47,
    osPriorityRealtime      =  48,  // 实时优先级
    osPriorityRealtime1     =  49,
    osPriorityRealtime2     =  50,
    osPriorityRealtime3     =  51,
    osPriorityRealtime4     =  52,
    osPriorityRealtime5     =  53,
    osPriorityRealtime6     =  54,
    osPriorityRealtime7     =  55,
    osPriorityISR           =  56,  // ISR延迟任务优先级
    osPriorityError         = -1,
    osPriorityReserved      = 0x7FFFFFFF
} osPriority_t;

使用示例：

c 复制代码 
void MyTask(void *argument)
{
    while (1) {
        printf("Task running...\n");
        sleep(1);
    }
}

void create_task_example(void)
{
    osThreadAttr_t attr = {0};
    attr.name = "MyTask";
    attr.stack_size = 1024;        // 栈大小1024字节
    attr.priority = osPriorityNormal;  // 正常优先级
    
    osThreadId_t task_id = osThreadNew((osThreadFunc_t)MyTask, NULL, &attr);
    if (task_id != NULL) {
        printf("Task created successfully, ID = %d\n", task_id);
    }
}

说明：

  • 优先级范围：9-38（Hi3861平台实际支持范围）
  • 最大任务数由LOSCFG_BASE_CORE_TSK_LIMIT配置决定
  • 栈大小建议：简单任务1024字节，复杂任务2048-4096字节
  • 任务名称用于调试和日志输出

2.2 osThreadGetName

函数原型：

c 复制代码 
const char *osThreadGetName (osThreadId_t thread_id);

功能描述：

获取指定任务的名称。

参数说明：

  • thread_id：任务ID

返回值：

  • 成功：返回任务名称字符串
  • 失败：返回NULL

2.3 osThreadGetId

函数原型：

c 复制代码 
osThreadId_t osThreadGetId (void);

功能描述：

获取当前运行任务的ID。

返回值：

  • 成功：返回当前任务ID
  • 失败：返回NULL

说明：

  • 可在任务函数内部调用，获取自身ID
  • 可用于任务间的通信和同步

2.4 osThreadGetState

函数原型：

c 复制代码 
osThreadState_t osThreadGetState (osThreadId_t thread_id);

功能描述：

获取指定任务的状态。

参数说明：

  • thread_id：任务ID

返回值：

  • osThreadInactive：任务未激活
  • osThreadReady：任务就绪
  • osThreadRunning：任务正在运行
  • osThreadBlocked：任务被阻塞
  • osThreadTerminated：任务已终止
  • osThreadError：任务异常

任务状态枚举定义：

c 复制代码 
typedef enum {
    osThreadInactive        =  0,
    osThreadReady           =  1,
    osThreadRunning         =  2,
    osThreadBlocked         =  3,
    osThreadTerminated      =  4,
    osThreadError           = -1,
    osThreadReserved        = 0x7FFFFFFF
} osThreadState_t;

2.5 osThreadGetStackSize

函数原型：

c 复制代码 
uint32_t osThreadGetStackSize (osThreadId_t thread_id);

功能描述：

获取指定任务的栈大小。

参数说明：

  • thread_id：任务ID

返回值：

  • 成功：返回栈大小（字节）
  • 失败：返回0

2.6 osThreadSetPriority

函数原型：

c 复制代码 
osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);

功能描述：

修改指定任务的优先级。

参数说明：

  • thread_id：任务ID
  • priority：新的优先级

返回值：

  • osOK：优先级设置成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

2.7 osThreadGetPriority

函数原型：

c 复制代码 
osPriority_t osThreadGetPriority (osThreadId_t thread_id);

功能描述：

获取指定任务的优先级。

参数说明：

  • thread_id：任务ID

返回值：

  • 成功：返回任务优先级
  • 失败：返回osPriorityError

2.8 osThreadYield

函数原型：

c 复制代码 
osStatus_t osThreadYield (void);

功能描述：

主动让出CPU，使当前任务从运行状态切换到就绪状态。

返回值：

  • osOK：让出CPU成功
  • osError：让出CPU失败

说明：

  • 系统会调度同优先级的其他就绪任务运行
  • 如果没有同优先级的就绪任务，当前任务继续运行
  • 常用于时间片轮转或协作式调度

使用示例：

c 复制代码 
void CooperativeTask(void)
{
    while (1) {
        // 执行一些工作
        do_some_work();
        
        // 让出CPU，让其他同优先级任务运行
        osThreadYield();
    }
}

2.9 osThreadSuspend

函数原型：

c 复制代码 
osStatus_t osThreadSuspend (osThreadId_t thread_id);

功能描述：

挂起指定任务，使其进入阻塞状态。

参数说明：

  • thread_id：任务ID

返回值：

  • osOK：任务挂起成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 挂起的任务不会参与调度，直到被恢复
  • 可以挂起其他任务，也可以挂起自己
  • 挂起的任务需要调用osThreadResume恢复

使用示例：

c 复制代码 
void Task2(void)
{
    while (1) {
        printf("Task 2, 开始挂起任务1\n");
        osThreadSuspend(Task1_ID);  // 挂起任务1
        sleep(5);
        
        printf("Task 2, 开始恢复任务1\n");
        osThreadResume(Task1_ID);   // 恢复任务1
        sleep(5);
    }
}

2.10 osThreadResume

函数原型：

c 复制代码 
osStatus_t osThreadResume (osThreadId_t thread_id);

功能描述：

恢复被挂起的任务，使其进入就绪状态。

参数说明：

  • thread_id：任务ID

返回值：

  • osOK：任务恢复成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 只能恢复被挂起的任务
  • 恢复后，任务会根据优先级参与调度
  • 如果优先级高于当前任务，会立即抢占

2.11 osThreadTerminate

函数原型：

c 复制代码 
osStatus_t osThreadTerminate (osThreadId_t thread_id);

功能描述：

终止指定任务，释放其占用的资源。

参数说明：

  • thread_id：任务ID

返回值：

  • osOK：任务终止成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 终止的任务不能再被恢复
  • 任务占用的栈和资源会被释放
  • 可以终止其他任务，也可以终止自己

2.12 osThreadGetCount

函数原型：

c 复制代码 
uint32_t osThreadGetCount (void);

功能描述：

获取当前系统中活跃任务的数量。

返回值：

  • 成功：返回活跃任务数
  • 失败：返回0

3. 消息队列函数

3.1 osMessageQueueNew

函数原型：

c 复制代码 
osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);

功能描述：

创建并初始化一个消息队列。

参数说明：

  • msg_count：消息队列中可容纳的消息数量
  • msg_size：每条消息的大小（字节）
  • attr：消息队列属性结构体指针（通常为NULL）

返回值：

  • 成功：返回消息队列ID
  • 失败：返回NULL

消息队列属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 消息队列名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 控制块内存地址
    uint32_t        cb_size;      // 控制块内存大小
    void            *mq_mem;      // 消息存储内存地址
    uint32_t        mq_size;      // 消息存储内存大小
} osMessageQueueAttr_t;

使用示例：

c 复制代码 
typedef struct {
    uint8_t id;
    uint8_t age;
    char *name;
} msg_people_t;

osMessageQueueId_t MsgQueue_ID;

void create_message_queue(void)
{
    // 创建消息队列：16条消息，每条消息大小为msg_people_t结构体大小
    MsgQueue_ID = osMessageQueueNew(16, sizeof(msg_people_t), NULL);
    if (MsgQueue_ID != NULL) {
        printf("Message queue created successfully, ID = %d\n", MsgQueue_ID);
    }
}

说明：

  • 消息队列用于任务间的异步通信
  • 消息按照FIFO（先进先出）原则处理
  • 队列满时，发送操作会阻塞或超时
  • 队列空时，接收操作会阻塞或超时

3.2 osMessageQueuePut

函数原型：

c 复制代码 
osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);

功能描述：

向消息队列发送一条消息。

参数说明：

  • mq_id：消息队列ID
  • msg_ptr：指向要发送的消息数据的指针
  • msg_prio：消息优先级（Hi3861平台未使用，设为0）
  • timeout：超时时间（单位：滴答数）

返回值：

  • osOK：消息发送成功
  • osErrorTimeout：发送超时
  • osErrorResource：队列已满
  • osErrorParameter：参数错误

超时时间常量：

c 复制代码 
#define osWaitForever    0xFFFFFFFFU  // 永久等待
#define osNoWait         0x0U         // 不等待

使用示例：

c 复制代码 
void Task1(void)
{
    msg_people_t msg_people;
    
    while (1) {
        msg_people.id = 0;
        msg_people.age = 16;
        msg_people.name = "xiao_ming";
        
        osStatus_t status = osMessageQueuePut(MsgQueue_ID, &msg_people, 0, osWaitForever);
        if (status == osOK) {
            printf("Message sent successfully\n");
        }
        
        sleep(1);
    }
}

3.3 osMessageQueueGet

函数原型：

c 复制代码 
osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout);

功能描述：

从消息队列接收一条消息。

参数说明：

  • mq_id：消息队列ID
  • msg_ptr：指向接收消息缓冲区的指针
  • msg_prio：接收消息优先级的指针（Hi3861平台未使用，设为NULL）
  • timeout：超时时间（单位：滴答数）

返回值：

  • osOK：消息接收成功
  • osErrorTimeout：接收超时
  • osErrorResource：队列为空
  • osErrorParameter：参数错误

使用示例：

c 复制代码 
void Task2(void)
{
    msg_people_t msg_people;
    
    while (1) {
        osStatus_t status = osMessageQueueGet(MsgQueue_ID, &msg_people, NULL, osWaitForever);
        if (status == osOK) {
            printf("Received: id=%d, age=%d, name=%s\n", 
                   msg_people.id, msg_people.age, msg_people.name);
        }
    }
}

3.4 osMessageQueueGetCapacity

函数原型：

c 复制代码 
uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);

功能描述：

获取消息队列的最大容量（可容纳的消息数量）。

参数说明：

  • mq_id：消息队列ID

返回值：

  • 成功：返回消息队列的最大容量
  • 失败：返回0

3.5 osMessageQueueGetMsgSize

函数原型：

c 复制代码 
uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);

功能描述：

获取消息队列中单条消息的最大大小。

参数说明：

  • mq_id：消息队列ID

返回值：

  • 成功：返回单条消息的最大大小
  • 失败：返回0

3.6 osMessageQueueGetCount

函数原型：

c 复制代码 
uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);

功能描述：

获取消息队列中当前的消息数量。

参数说明：

  • mq_id：消息队列ID

返回值：

  • 成功：返回当前消息数量
  • 失败：返回0

3.7 osMessageQueueGetSpace

函数原型：

c 复制代码 
uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);

功能描述：

获取消息队列中可用的消息槽位数量。

参数说明：

  • mq_id：消息队列ID

返回值：

  • 成功：返回可用槽位数量
  • 失败：返回0

3.8 osMessageQueueDelete

函数原型：

c 复制代码 
osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);

功能描述：

删除消息队列，释放其占用的资源。

参数说明：

  • mq_id：消息队列ID

返回值：

  • osOK：删除成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 删除后，消息队列不能再被使用
  • 队列中的所有消息都会被丢弃
  • 正在等待该队列的任务会被唤醒并返回错误

4. 信号量函数

4.1 osSemaphoreNew

函数原型：

c 复制代码 
osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);

功能描述：

创建并初始化一个信号量。

参数说明：

  • max_count：信号量的最大计数值
  • initial_count：信号量的初始计数值
  • attr：信号量属性结构体指针（通常为NULL）

返回值：

  • 成功：返回信号量ID
  • 失败：返回NULL

信号量属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 信号量名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 控制块内存地址
    uint32_t        cb_size;      // 控制块内存大小
} osSemaphoreAttr_t;

使用示例：

c 复制代码 
osSemaphoreId_t Semaphore_ID;

void create_semaphore(void)
{
    // 创建二值信号量：最大值1，初始值1
    Semaphore_ID = osSemaphoreNew(1, 1, NULL);
    if (Semaphore_ID != NULL) {
        printf("Semaphore created successfully, ID = %d\n", Semaphore_ID);
    }
}

说明：

  • 二值信号量：max_count=1, initial_count=1
  • 计数信号量：max_count>1, initial_count可自定义
  • 信号量用于任务间的同步和互斥

4.2 osSemaphoreAcquire

函数原型：

c 复制代码 
osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout);

功能描述：

获取信号量（信号量计数值减1）。

参数说明：

  • semaphore_id：信号量ID
  • timeout：超时时间（单位：滴答数）

返回值：

  • osOK：获取信号量成功
  • osErrorTimeout：获取超时
  • osErrorResource：信号量不可用
  • osErrorParameter：参数错误

使用示例：

c 复制代码 
void Task1(void)
{
    while (1) {
        // 请求信号量（阻塞等待）
        osSemaphoreAcquire(Semaphore_ID, osWaitForever);
        
        // 访问共享资源
        printf("Task1 accessing shared resource\n");
        // ... 临界区代码 ...
        
        // 释放信号量
        osSemaphoreRelease(Semaphore_ID);
        
        sleep(1);
    }
}

说明：

  • 如果信号量计数值>0，立即获取成功，计数值减1
  • 如果信号量计数值=0，任务阻塞等待
  • 超时后，如果仍未获取成功，返回超时错误

4.3 osSemaphoreRelease

函数原型：

c 复制代码 
osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);

功能描述：

释放信号量（信号量计数值加1）。

参数说明：

  • semaphore_id：信号量ID

返回值：

  • osOK：释放信号量成功
  • osErrorResource：信号量已达到最大值
  • osErrorParameter：参数错误

使用示例：

c 复制代码 
void Task2(void)
{
    while (1) {
        // 请求信号量
        osSemaphoreAcquire(Semaphore_ID, osWaitForever);
        
        // 访问共享资源
        printf("Task2 accessing shared resource\n");
        // ... 临界区代码 ...
        
        // 释放信号量
        osSemaphoreRelease(Semaphore_ID);
        
        sleep(1);
    }
}

说明：

  • 释放信号量后，如果有任务在等待该信号量，会唤醒一个任务
  • 信号量计数值不能超过max_count
  • 必须与osSemaphoreAcquire配对使用

4.4 osSemaphoreGetCount

函数原型：

c 复制代码 
uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);

功能描述：

获取信号量的当前计数值。

参数说明：

  • semaphore_id：信号量ID

返回值：

  • 成功：返回信号量的当前计数值
  • 失败：返回0

4.5 osSemaphoreDelete

函数原型：

c 复制代码 
osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);

功能描述：

删除信号量，释放其占用的资源。

参数说明：

  • semaphore_id：信号量ID

返回值：

  • osOK：删除成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 删除后，信号量不能再被使用
  • 正在等待该信号量的任务会被唤醒并返回错误

5. 互斥锁函数

5.1 osMutexNew

函数原型：

c 复制代码 
osMutexId_t osMutexNew (const osMutexAttr_t *attr);

功能描述：

创建并初始化一个互斥锁。

参数说明：

  • attr：互斥锁属性结构体指针（通常为NULL）

返回值：

  • 成功：返回互斥锁ID
  • 失败：返回NULL

互斥锁属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 互斥锁名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 控制块内存地址
    uint32_t        cb_size;      // 控制块内存大小
} osMutexAttr_t;

互斥锁属性位定义：

c 复制代码 
#define osMutexRecursive      0x00000001U  // 支持递归锁
#define osMutexPrioInherit    0x00000002U  // 优先级继承
#define osMutexRobust         0x00000008U  // 健壮锁

使用示例：

c 复制代码 
osMutexId_t Mutex_ID;

void create_mutex(void)
{
    Mutex_ID = osMutexNew(NULL);
    if (Mutex_ID != NULL) {
        printf("Mutex created successfully, ID = %d\n", Mutex_ID);
    }
}

说明：

  • 互斥锁用于保护共享资源，确保同一时间只有一个任务访问
  • 互斥锁具有所有权概念，只有获取锁的任务才能释放锁
  • 支持优先级继承，防止优先级反转

5.2 osMutexAcquire

函数原型：

c 复制代码 
osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout);

功能描述：

获取互斥锁。

参数说明：

  • mutex_id：互斥锁ID
  • timeout：超时时间（单位：滴答数）

返回值：

  • osOK：获取互斥锁成功
  • osErrorTimeout：获取超时
  • osErrorResource：互斥锁已被其他任务持有
  • osErrorParameter：参数错误

使用示例：

c 复制代码 
void Task1(void)
{
    while (1) {
        // 获取互斥锁
        osMutexAcquire(Mutex_ID, osWaitForever);
        
        // 访问共享资源
        printf("Task1 accessing shared resource\n");
        // ... 临界区代码 ...
        
        // 释放互斥锁
        osMutexRelease(Mutex_ID);
        
        sleep(1);
    }
}

说明：

  • 如果互斥锁未被持有，立即获取成功
  • 如果互斥锁已被其他任务持有，当前任务阻塞等待
  • 如果当前任务已经持有该互斥锁（递归锁），可以重复获取
  • 获取次数必须与释放次数匹配

5.3 osMutexRelease

函数原型：

c 复制代码 
osStatus_t osMutexRelease (osMutexId_t mutex_id);

功能描述：

释放互斥锁。

参数说明：

  • mutex_id：互斥锁ID

返回值：

  • osOK：释放互斥锁成功
  • osErrorResource：互斥锁未被当前任务持有
  • osErrorParameter：参数错误

使用示例：

c 复制代码 
void Task2(void)
{
    while (1) {
        // 获取互斥锁
        osMutexAcquire(Mutex_ID, osWaitForever);
        
        // 访问共享资源
        printf("Task2 accessing shared resource\n");
        // ... 临界区代码 ...
        
        // 释放互斥锁
        osMutexRelease(Mutex_ID);
        
        sleep(1);
    }
}

说明：

  • 只有持有互斥锁的任务才能释放它
  • 释放后，如果有任务在等待该互斥锁，会唤醒一个任务
  • 必须与osMutexAcquire配对使用

5.4 osMutexGetOwner

函数原型：

c 复制代码 
osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);

功能描述：

获取当前持有互斥锁的任务ID。

参数说明：

  • mutex_id：互斥锁ID

返回值：

  • 成功：返回持有互斥锁的任务ID
  • 失败：返回NULL

5.5 osMutexDelete

函数原型：

c 复制代码 
osStatus_t osMutexDelete (osMutexId_t mutex_id);

功能描述：

删除互斥锁，释放其占用的资源。

参数说明：

  • mutex_id：互斥锁ID

返回值：

  • osOK：删除成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 删除后，互斥锁不能再被使用
  • 正在等待该互斥锁的任务会被唤醒并返回错误

6. 事件标志函数

6.1 osEventFlagsNew

函数原型：

c 复制代码 
osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);

功能描述：

创建并初始化一个事件标志对象。

参数说明：

  • attr：事件标志属性结构体指针（通常为NULL）

返回值：

  • 成功：返回事件标志ID
  • 失败：返回NULL

事件标志属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 事件标志名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 控制块内存地址
    uint32_t        cb_size;      // 控制块内存大小
} osEventFlagsAttr_t;

使用示例：

c 复制代码 
osEventFlagsId_t EventFlags_ID;

void create_event_flags(void)
{
    EventFlags_ID = osEventFlagsNew(NULL);
    if (EventFlags_ID != NULL) {
        printf("Event flags created successfully, ID = %d\n", EventFlags_ID);
    }
}

说明：

  • 事件标志用于任务间的同步
  • 每个事件标志对象包含32个标志位
  • 可以等待单个或多个标志位

6.2 osEventFlagsSet

函数原型：

c 复制代码 
uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags);

功能描述：

设置事件标志。

参数说明：

  • ef_id：事件标志ID
  • flags：要设置的标志位（位掩码）

返回值：

  • 成功：返回设置后的标志值
  • 失败：返回osFlagsErrorParameter

使用示例：

c 复制代码 
void Task1(void)
{
    while (1) {
        // 设置事件标志
        osEventFlagsSet(EventFlags_ID, 0x01);  // 设置第0位
        
        sleep(1);
    }
}

说明：

  • 可以设置多个标志位（使用位或操作）
  • 设置标志位会唤醒等待这些标志位的任务
  • 标志位是累积的，不会自动清除

6.3 osEventFlagsClear

函数原型：

c 复制代码 
uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags);

功能描述：

清除事件标志。

参数说明：

  • ef_id：事件标志ID
  • flags：要清除的标志位（位掩码）

返回值：

  • 成功：返回清除前的标志值
  • 失败：返回osFlagsErrorParameter

使用示例：

c 复制代码 
void Task2(void)
{
    while (1) {
        // 清除事件标志
        osEventFlagsClear(EventFlags_ID, 0x01);  // 清除第0位
        
        sleep(1);
    }
}

说明：

  • 可以清除多个标志位（使用位或操作）
  • 通常在等待事件后清除标志位
  • 清除操作不会影响其他任务

6.4 osEventFlagsGet

函数原型：

c 复制代码 
uint32_t osEventFlagsGet (osEventFlagsId_t ef_id);

功能描述：

获取当前事件标志的值。

参数说明：

  • ef_id：事件标志ID

返回值：

  • 成功：返回当前事件标志的值
  • 失败：返回0

6.5 osEventFlagsWait

函数原型：

c 复制代码 
uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout);

功能描述：

等待事件标志。

参数说明：

  • ef_id：事件标志ID
  • flags：要等待的标志位（位掩码）
  • options：等待选项
  • timeout：超时时间（单位：滴答数）

返回值：

  • 成功：返回触发的事件标志值
  • 超时：返回osFlagsErrorTimeout
  • 参数错误：返回osFlagsErrorParameter

等待选项定义：

c 复制代码 
#define osFlagsWaitAny        0x00000000U  // 等待任意标志位
#define osFlagsWaitAll        0x00000001U  // 等待所有标志位
#define osFlagsNoClear        0x00000002U  // 不清除标志位

使用示例：

c 复制代码 
void Task3(void)
{
    while (1) {
        // 等待第0位标志，等待任意标志，自动清除
        uint32_t flags = osEventFlagsWait(EventFlags_ID, 0x01, osFlagsWaitAny, osWaitForever);
        
        if (flags & 0x01) {
            printf("Event flag 0x01 received\n");
        }
    }
}

说明：

  • osFlagsWaitAny：任意指定的标志位被设置即返回
  • osFlagsWaitAll：所有指定的标志位都被设置才返回
  • osFlagsNoClear：等待后不清除标志位
  • 默认情况下，等待后会清除标志位

6.6 osEventFlagsDelete

函数原型：

c 复制代码 
osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);

功能描述：

删除事件标志对象，释放其占用的资源。

参数说明：

  • ef_id：事件标志ID

返回值：

  • osOK：删除成功
  • osErrorParameter：参数错误
  • osErrorResource：资源错误

说明：

  • 删除后，事件标志不能再被使用
  • 正在等待该事件标志的任务会被唤醒并返回错误

7. 定时器函数

7.1 osTimerNew

函数原型：

c 复制代码 
osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);

功能描述：

创建并初始化一个定时器。

参数说明：

  • func：定时器回调函数指针
  • type：定时器类型
  • argument：传递给回调函数的参数
  • attr：定时器属性结构体指针（通常为NULL）

返回值：

  • 成功：返回定时器ID
  • 失败：返回NULL

定时器类型定义：

c 复制代码 
typedef enum {
    osTimerOnce       = 0,  // 单次定时器
    osTimerPeriodic   = 1   // 周期定时器
} osTimerType_t;

定时器属性结构体定义：

c 复制代码 
typedef struct {
    const char      *name;        // 定时器名称
    uint32_t        attr_bits;    // 属性位
    void            *cb_mem;      // 控制块内存地址
    uint32_t        cb_size;      // 控制块内存大小
} osTimerAttr_t;

使用示例：

c 复制代码 
void TimerCallback(void *argument)
{
    printf("Timer callback executed\n");
}

osTimerId_t Timer_ID;

void create_timer(void)
{
    // 创建周期定时器，每1000个滴答触发一次
    Timer_ID = osTimerNew(TimerCallback, osTimerPeriodic, NULL, NULL);
    if (Timer_ID != NULL) {
        printf("Timer created successfully, ID = %d\n", Timer_ID);
    }
}

说明：

  • 单次定时器：触发一次后自动停止
  • 周期定时器：周期性触发，直到手动停止
  • 定时器精度为1000 / LOSCFG_BASE_CORE_TICK_PER_SECOND毫秒
  • 定时器回调函数在定时器任务上下文中执行

7.2 osTimerStart

函数原型：

c 复制代码 
osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks);

功能描述：

启动或重启定时器。

参数说明：

  • timer_id：定时器ID
  • ticks：定时器周期（单位：滴答数）

返回值：

  • osOK：启动成功
  • osErrorParameter：参数错误
  • osErrorResource：定时器正在运行

使用示例：

c 复制代码 
void start_timer(void)
{
    // 启动定时器，周期为1000个滴答
    osStatus_t status = osTimerStart(Timer_ID, 1000);
    if (status == osOK) {
        printf("Timer started successfully\n");
    }
}

说明：

  • 如果定时器正在运行，会先停止再重新启动
  • 周期时间从调用时刻开始计算
  • 周期定时器会周期性触发回调函数

7.3 osTimerStop

函数原型：

c 复制代码 
osStatus_t osTimerStop (osTimerId_t timer_id);

功能描述：

停止定时器。

参数说明：

  • timer_id：定时器ID

返回值：

  • osOK：停止成功
  • osErrorParameter：参数错误
  • osErrorResource：定时器未运行

使用示例：

c 复制代码 
void stop_timer(void)
{
    osStatus_t status = osTimerStop(Timer_ID);
    if (status == osOK) {
        printf("Timer stopped successfully\n");
    }
}

说明：

  • 停止后，定时器不再触发回调函数
  • 可以重新启动定时器
  • 停止未运行的定时器会返回错误

7.4 osTimerIsRunning

函数原型：

c 复制代码 
uint32_t osTimerIsRunning (osTimerId_t timer_id);

功能描述：

检查定时器是否正在运行。

参数说明：

  • timer_id：定时器ID

返回值：

  • 1：定时器正在运行
  • 0：定时器未运行

7.5 osTimerDelete

函数原型：

c 复制代码 
osStatus_t osTimerDelete (osTimerId_t timer_id);

功能描述：

删除定时器，释放其占用的资源。

参数说明：

  • timer_id：定时器ID

返回值：

  • osOK：删除成功
  • osErrorParameter：参数错误
  • osErrorResource：定时器正在运行

说明：

  • 删除前必须先停止定时器
  • 删除后，定时器不能再被使用
  • 正在触发的回调函数会继续执行完毕

8. 实际应用示例

8.1 多任务LED闪烁示例

场景描述：

创建两个任务，一个任务控制LED闪烁，另一个任务执行其他功能。

代码示例：

c 复制代码 
#include "ohos_init.h"
#include "cmsis_os2.h"
#include "bsp_led.h"

osThreadId_t LED_Task_ID;
osThreadId_t Other_Task_ID;

/* LED闪烁任务 */
void LED_Task(void)
{
    led_init();
    while (1) {
        LED(1);
        usleep(200 * 1000);  // 200ms
        LED(0);
        usleep(200 * 1000);  // 200ms
    }
}

/* 其他功能任务 */
void Other_Task(void)
{
    while (1) {
        printf("Other task running...\n");
        sleep(1);
    }
}

/* 创建任务 */
void create_tasks(void)
{
    osThreadAttr_t attr = {0};
    
    // 创建LED任务
    attr.name = "LEDTask";
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    LED_Task_ID = osThreadNew((osThreadFunc_t)LED_Task, NULL, &attr);
    
    // 创建其他任务
    attr.name = "OtherTask";
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    Other_Task_ID = osThreadNew((osThreadFunc_t)Other_Task, NULL, &attr);
}

8.2 任务挂起与恢复示例

场景描述：

任务2控制任务1的挂起和恢复，实现任务的动态控制。

代码示例：

c 复制代码 
#include "ohos_init.h"
#include "cmsis_os2.h"

osThreadId_t Task1_ID;
osThreadId_t Task2_ID;

/* 任务1 */
void Task1(void)
{
    while (1) {
        printf("Task 1 running...\n");
        sleep(1);
    }
}

/* 任务2 */
void Task2(void)
{
    while (1) {
        printf("Task 2: Suspending Task 1\n");
        osThreadSuspend(Task1_ID);
        sleep(5);
        
        printf("Task 2: Resuming Task 1\n");
        osThreadResume(Task1_ID);
        sleep(5);
    }
}

/* 创建任务 */
void create_tasks(void)
{
    osThreadAttr_t attr = {0};
    
    // 创建任务1
    attr.name = "Task1";
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    Task1_ID = osThreadNew((osThreadFunc_t)Task1, NULL, &attr);
    
    // 创建任务2
    attr.name = "Task2";
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal1;
    Task2_ID = osThreadNew((osThreadFunc_t)Task2, NULL, &attr);
}

8.3 消息队列通信示例

场景描述：

任务1发送消息，任务2接收消息，实现任务间的数据传递。

代码示例：

c 复制代码 
#include "ohos_init.h"
#include "cmsis_os2.h"

osThreadId_t Task1_ID;
osThreadId_t Task2_ID;
osMessageQueueId_t MsgQueue_ID;

typedef struct {
    uint8_t id;
    uint8_t age;
    char *name;
} msg_people_t;

/* 任务1：发送消息 */
void Task1(void)
{
    msg_people_t msg;
    
    while (1) {
        msg.id = 0;
        msg.age = 16;
        msg.name = "xiao_ming";
        
        osStatus_t status = osMessageQueuePut(MsgQueue_ID, &msg, 0, osWaitForever);
        if (status == osOK) {
            printf("Message sent: id=%d, age=%d, name=%s\n", 
                   msg.id, msg.age, msg.name);
        }
        
        sleep(1);
    }
}

/* 任务2：接收消息 */
void Task2(void)
{
    msg_people_t msg;
    
    while (1) {
        osStatus_t status = osMessageQueueGet(MsgQueue_ID, &msg, NULL, osWaitForever);
        if (status == osOK) {
            printf("Message received: id=%d, age=%d, name=%s\n", 
                   msg.id, msg.age, msg.name);
        }
    }
}

/* 初始化 */
void init_example(void)
{
    // 创建消息队列
    MsgQueue_ID = osMessageQueueNew(16, sizeof(msg_people_t), NULL);
    
    // 创建任务
    osThreadAttr_t attr = {0};
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    
    attr.name = "Task1";
    Task1_ID = osThreadNew((osThreadFunc_t)Task1, NULL, &attr);
    
    attr.name = "Task2";
    Task2_ID = osThreadNew((osThreadFunc_t)Task2, NULL, &attr);
}

8.4 信号量互斥示例

场景描述：

使用二值信号量保护共享资源，确保同一时间只有一个任务访问。

代码示例：

c 复制代码 
#include "ohos_init.h"
#include "cmsis_os2.h"

osThreadId_t Task1_ID;
osThreadId_t Task2_ID;
osSemaphoreId_t Semaphore_ID;
uint8_t shared_buffer[20];

/* 任务1：写数据 */
void Task1(void)
{
    int i;
    
    while (1) {
        // 获取信号量
        osSemaphoreAcquire(Semaphore_ID, osWaitForever);
        
        // 写入共享数据
        printf("Task1 writing data:\n");
        for (i = 0; i < sizeof(shared_buffer); i++) {
            shared_buffer[i] = i;
            printf("%d ", shared_buffer[i]);
        }
        printf("\n");
        
        // 释放信号量
        osSemaphoreRelease(Semaphore_ID);
        
        sleep(1);
    }
}

/* 任务2：读数据 */
void Task2(void)
{
    int i;
    
    while (1) {
        // 获取信号量
        osSemaphoreAcquire(Semaphore_ID, osWaitForever);
        
        // 读取共享数据
        printf("Task2 reading data:\n");
        for (i = 0; i < sizeof(shared_buffer); i++) {
            printf("%d ", shared_buffer[i]);
        }
        printf("\n");
        
        // 释放信号量
        osSemaphoreRelease(Semaphore_ID);
        
        sleep(1);
    }
}

/* 初始化 */
void init_example(void)
{
    // 创建二值信号量
    Semaphore_ID = osSemaphoreNew(1, 1, NULL);
    
    // 创建任务
    osThreadAttr_t attr = {0};
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    
    attr.name = "Task1";
    Task1_ID = osThreadNew((osThreadFunc_t)Task1, NULL, &attr);
    
    attr.name = "Task2";
    Task2_ID = osThreadNew((osThreadFunc_t)Task2, NULL, &attr);
}

8.5 定时器应用示例

场景描述：

使用周期定时器定期执行任务，实现定时功能。

代码示例：

c 复制代码 
#include "ohos_init.h"
#include "cmsis_os2.h"

osTimerId_t Timer_ID;

/* 定时器回调函数 */
void TimerCallback(void *argument)
{
    printf("Timer callback: Periodic task executed\n");
}

/* 主任务 */
void Main_Task(void)
{
    // 启动定时器，周期为1000个滴答
    osTimerStart(Timer_ID, 1000);
    
    while (1) {
        printf("Main task running...\n");
        sleep(5);
    }
}

/* 初始化 */
void init_example(void)
{
    // 创建周期定时器
    Timer_ID = osTimerNew(TimerCallback, osTimerPeriodic, NULL, NULL);
    
    // 创建主任务
    osThreadAttr_t attr = {0};
    attr.name = "MainTask";
    attr.stack_size = 1024;
    attr.priority = osPriorityNormal;
    osThreadNew((osThreadFunc_t)Main_Task, NULL, &attr);
}

9. 配置参数说明

9.1 任务栈大小配置

推荐配置：

  • 简单任务：1024字节
  • 中等复杂任务：2048字节
  • 复杂任务：4096字节
  • 包含浮点运算的任务：建议增加512-1024字节

配置示例：

c 复制代码 
osThreadAttr_t attr = {0};
attr.stack_size = 1024;  // 栈大小1024字节

9.2 任务优先级配置

优先级范围：

  • Hi3861平台支持范围：9-38
  • 推荐使用范围：24-32（osPriorityNormal到osPriorityAboveNormal）

优先级分配原则：

  • 空闲任务：osPriorityIdle (1)
  • 低优先级任务：osPriorityLow (8-15)
  • 普通任务：osPriorityNormal (24-31)
  • 高优先级任务：osPriorityAboveNormal (32-39)

配置示例：

c 复制代码 
osThreadAttr_t attr = {0};
attr.priority = osPriorityNormal;  // 正常优先级

9.3 消息队列配置

配置参数：

  • 消息数量：根据实际需求设置（如16、32、64）
  • 消息大小：根据消息结构体大小设置

配置示例：

c 复制代码 
typedef struct {
    uint8_t id;
    uint8_t age;
    char *name;
} msg_people_t;

// 创建消息队列：16条消息，每条消息大小为msg_people_t结构体大小
osMessageQueueId_t MsgQueue_ID = osMessageQueueNew(16, sizeof(msg_people_t), NULL);

9.4 信号量配置

二值信号量配置：

c 复制代码 
// 最大值1，初始值1
osSemaphoreId_t Semaphore_ID = osSemaphoreNew(1, 1, NULL);

计数信号量配置：

c 复制代码 
// 最大值10，初始值5
osSemaphoreId_t CountingSemaphore_ID = osSemaphoreNew(10, 5, NULL);

9.5 定时器配置

单次定时器配置：

c 复制代码 
osTimerId_t Timer_ID = osTimerNew(TimerCallback, osTimerOnce, NULL, NULL);

周期定时器配置：

c 复制代码 
osTimerId_t Timer_ID = osTimerNew(TimerCallback, osTimerPeriodic, NULL, NULL);

附录

A. 返回值枚举定义

c 复制代码 
typedef enum {
    osOK                      =  0,   // 操作成功
    osError                   = -1,   // 未指定错误
    osErrorTimeout            = -2,   // 超时
    osErrorResource           = -3,   // 资源错误
    osErrorParameter          = -4,   // 参数错误
    osErrorNoMemory           = -5,   // 内存不足
    osErrorISR                = -6,   // ISR错误
    osStatusReserved          = 0x7FFFFFFF
} osStatus_t;

B. 常用宏定义

c 复制代码 
// 超时时间
#define osWaitForever    0xFFFFFFFFU  // 永久等待
#define osNoWait         0x0U         // 不等待

// 事件标志选项
#define osFlagsWaitAny        0x00000000U  // 等待任意标志位
#define osFlagsWaitAll        0x00000001U  // 等待所有标志位
#define osFlagsNoClear        0x00000002U  // 不清除标志位

// 互斥锁属性
#define osMutexRecursive      0x00000001U  // 支持递归锁
#define osMutexPrioInherit    0x00000002U  // 优先级继承
#define osMutexRobust         0x00000008U  // 健壮锁

--

相关推荐
IT陈图图13 小时前
Flutter × OpenHarmony 跨端实践：从零构建一个轻量级视频播放器
flutter·音视频·鸿蒙·openharmony
时光慢煮19 小时前
Flutter × OpenHarmony 跨端开发实战：动态显示菜单详解
flutter·华为·开源·openharmony
时光慢煮20 小时前
Flutter × OpenHarmony：构建高效文章列表界面实践
flutter·华为·开源·openharmony
IT陈图图1 天前
Flutter × OpenHarmony 实战：从 0 构建视频播放器的分类导航模块
flutter·华为·音视频·openharmony
时光慢煮1 天前
Flutter × OpenHarmony 文件管家-构建文件管理器主界面与存储设备卡片
flutter·华为·开源·openharmony
A懿轩A1 天前
【2026 最新】Kuikly 编译开发 OpenHarmony 项目逐步详细教程带图操作Android Studio编译（Windows）
windows·harmonyos·鸿蒙·openharmony·kuikly
时光慢煮1 天前
打造跨端浮动操作按钮：Flutter × OpenHarmony 实战
flutter·华为·开源·openharmony
IT陈图图1 天前
基于 Flutter × OpenHarmony 的跨端视频播放器数据模型设计实践
flutter·开源·鸿蒙·openharmony
时光慢煮1 天前
Flutter × OpenHarmony 跨端开发：实现排序与创建选项功能
flutter·华为·开源·openharmony
IT陈图图1 天前
构建跨端视频播放器中的“推荐视频”模块：Flutter × OpenHarmony 实战解析
flutter·音视频·鸿蒙·openharmony
热门推荐
01GitHub 镜像站点02OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)03Linux下V2Ray安装配置指南04Claude Code Skills 实用使用手册05Open Code教程（四）| 高级配置与集成06UV安装并设置国内源07BongoCat - 跨平台键盘猫动画工具08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）10MC.JS 网页版《我的世界》 免安装中文版