10 KiB
任务通信
XiUOS提供多种任务间通信机制，包括消息队列、信号量、互斥量与事件集。
消息队列
消息队列（message queue）提供可供多个任务读或写的消息缓冲区，其中消息指固定长度的任意数据块。消息队列的容量有限。当消息队列满时，向消息队列写入的任务会被挂起；当消息队列空时，从消息队列读取的任务会被挂起。
消息队列结构定义
struct xs_MsgQueue
{
xs_uint16 id;
void *msg_buf;
xs_uint16 index;
xs_uint16 num_msgs;
xs_uint16 each_len;
xs_uint16 max_msgs;
XS_DOUBLE_LINKLIST send_pend_list;
XS_DOUBLE_LINKLIST recv_pend_list;
XS_DOUBLE_LINKLIST link;
};
| 成员 | 描述 |
|---|---|
| id | 消息队列ID，用于唯一标识一个消息队列 |
| msg_buf | 用于存储消息的缓冲区的首地址 |
| index | 当前缓冲区中第一个消息的序号 |
| num_msgs | 当前缓冲区中的消息数量 |
| each_len | 每条消息的大小，单位为字节 |
| max_msgs | 缓冲区中最多能存放的消息数量 |
| send_pend_list | 被挂起的发送任务链表 |
| recv_pend_list | 被挂起的接收任务链表 |
| link | 系统中所有消息队列构成的链表 |
消息队列函数接口
xs_int32 xs_UserMsgQueueCreate(xs_uint16 msg_len, xs_uint16 max_msgs);
该函数用于创建一个消息队列。创建成功后，新的消息队列会被加入内核的消息队列管理链表，并返回该消息队列的ID，ID默认范围0-255，可配置。
| 参数 | 描述 |
|---|---|
| msg_len | 每条消息的长度，单位为字节 |
| max_msgs | 缓冲区中最多存放的消息数量 |
void xs_UserMsgQueueDelete(xs_uint16 id);
该函数用于删除一个已创建的消息队列。
| 参数 | 描述 |
|---|---|
| id | 待删除的消息队列ID |
xs_int32 xs_UserMsgQueueSend(xs_uint16 id, const void *msg, xs_uint16 size, xs_ticks_x wait_time);
该函数用于向消息队列发送一个消息。若消息发送成功则返回XS_EOK，若不成功（等待超时）则返回-XS_ETIMEOUT。
| 参数 | 描述 |
|---|---|
| id | 目标消息队列ID |
| msg | 消息数据首地址 |
| size | 消息长度 |
| wait_time | 等待时间上限，单位ticks；若为0，则不等待 |
xs_int32 xs_UserMsgQueueRecv(xs_uint16 id, void *buf, xs_uint16 size, xs_ticks_x wait_time);
该函数用于从消息队列接收一个消息。若消息接收成功则返回XS_EOK，若不成功（等待超时）则返回-XS_ETIMEOUT。
| 参数 | 描述 |
|---|---|
| id | 来源消息队列ID |
| buf | 用于接收消息数据的缓冲区 |
| size | 缓冲区大小 |
| wait_time | 等待时间上限，单位ticks；若为0，则不等待 |
xs_int32 xs_UserMsgQueueReinit(xs_uint16 id);
该函数用于将一个消息队列复位。
| 参数 | 描述 |
|---|---|
| id | 来源消息队列ID |
信号量
信号量（semaphore）具有一个给定的初值。任务可以获取或释放一个信号量。当任务获取信号量时信号量的值递减，释放信号量时值递增。当信号量值递减至0时，后续尝试获取信号量的任务会被挂起。每当一个已获取信号量的任务释放信号量时，内核会从信号量挂起队列上唤醒一个任务。信号量可以用于实现任务间的同步与互斥。
信号量结构定义
struct xs_Semaphore
{
xs_uint16 id;
xs_uint16 value;
XS_DOUBLE_LINKLIST pend_list;
XS_DOUBLE_LINKLIST link;
};
| 成员 | 描述 |
|---|---|
| id | 信号量ID，用于唯一标识一个信号量 |
| value | 信号量的当前值 |
| pend_link | 挂起任务链表 |
| link | 系统中所有信号量构成的链表 |
信号量函数接口
xs_int32 xs_UserSemaphoreCreate(xs_uint16 val);
该函数用于创建一个信号量。创建成功后，新的信号量会被加入内核的信号量管理链表，并返回该信号量的ID，ID默认范围0-255，可配置。
| 参数 | 描述 |
|---|---|
| val | 信号量的初值 |
void xs_UserSemaphoreDelete(xs_uint16 id);
该函数用于删除一个已创建的信号量。
| 参数 | 描述 |
|---|---|
| id | 待删除的信号量的ID |
xs_int32 xs_UserSemaphoreObtain(xs_uint16 id, xs_ticks_x wait_time);
该函数用于获取一个信号量。若获取成功则返回XS_EOK，若不成功（等待超时）则返回-XS_ETIMEOUT。
| 参数 | 描述 |
|---|---|
| id | 欲获取的信号量的ID |
| wait_time | 等待时间上限，单位ticks；若为0，则不等待 |
xs_int32 xs_UserSemaphoreAbandon(xs_uint16 id);
该函数用于释放一个信号量。
| 参数 | 描述 |
|---|---|
| id | 待释放的信号量的ID |
xs_int32 xs_UserSemaphoreSetValue(xs_uint16 id, xs_uint16 val);
该函数用于将一个信号量的值进行重置。
| 参数 | 描述 |
|---|---|
| id | 来源消息队列ID |
| val | 重置的信号量的值 |
互斥量
互斥量（mutex）可以视作一个初值为1的信号量，同样有获取和释放操作。互斥量一般用于任务间的互斥。
互斥量结构定义
struct xs_Mutex { xs_uint16 id;
xs_uint8 origin_prio;
xs_uint8 recursive_cnt;
struct task_descriptor *holder;
XS_DOUBLE_LINKLIST pend_list;
XS_DOUBLE_LINKLIST link;
};
| 成员 | 描述 |
|---|---|
| id | 互斥量ID，用于唯一标识一个互斥量 |
| origin_prio | 持有互斥量的任务的原优先级，用于避免优先级反转 |
| recursive_cnt | 持有互斥量的任务获取互斥量的次数，用于实现递归锁 |
| holder | 持有互斥量的任务 |
| pend_list | 挂起任务链表 |
| link | 系统中所有互斥量构成的链表 |
互斥量函数接口
xs_int32 xs_UserMutexCreate(void);
该函数用于创建一个互斥量。创建成功后，新的互斥量会被加入内核的互斥量管理链表，并返回该互斥量的ID，ID默认范围0-255，可配置。
void xs_UserMutexDelete(xs_uint16 id);
该函数用于删除一个已创建的互斥量。
| 参数 | 描述 |
|---|---|
| id | 待删除的互斥量的ID |
xs_int32 xs_UserMutexObtain(xs_uint16 id, xs_ticks_x wait_time);
该函数用于获取一个互斥量。若获取成功则返回XS_EOK，若不成功（等待超时）则返回-XS_ETIMEOUT。
| 参数 | 描述 |
|---|---|
| id | 欲获取的互斥量的ID |
| wait_time | 等待时间上限，单位ticks；若为0，则不等待 |
xs_int32 xs_UserMutexAbandon(xs_uint16 id);
该函数用于释放一个互斥量。
| 参数 | 描述 |
|---|---|
| id | 待释放的互斥量的ID |
事件集
事件集（event set）允许用户定义一个事件集合，集合中的每个事件都可以被任务触发或等待。任务可以同时等待多个事件，此时等待触发的条件可以配置为AND或者OR：当等待触发条件配置为AND时，只有所有被等待的事件均被触发才视作等待结束；当等待触发条件配置为OR时，任意一个被等待的事件触发即视作等待结束。使用事件集可以实现多对多的任务间同步与互斥。
事件集结构定义
#define XS_EVENT_AND (1 << 29)
#define XS_EVENT_OR (1 << 30)
#define XS_EVENT_AUTOCLEAN (1 << 31)
#define XS_EVENTS(x) (1 << x)
struct xs_event
{
xs_uint16 id;
xs_uint32 trigge_way;
XS_DOUBLE_LINKLIST pend_list;
XS_DOUBLE_LINKLIST link;
};
| 成员 | 描述 |
|---|---|
| id | 事件集ID，用于唯一标识一个事件集 |
| trigge_way | 高3位用于记录事件集属性（等待触发条件、是否自动清空），低29位用于表示至多29个事件 |
| pend_list | 等待任务链表 |
| link | 系统中所有事件集构成的链表 |
事件集函数接口
xs_int32 xs_UserEventCreate(xs_uint32 options);
该函数用于创建一个事件集。options参数用于配置事件集的属性。可配置的属性有等待触发方式（XS_EVENT_AND或XS_EVENT_OR）及等待触发后是否自动清空其他已触发的事件（XS_EVENT_AUTOCLEAN）。创建成功后，新的事件集会被加入内核的事件集管理链表，并返回该事件集的ID，ID默认范围0-255，可配置。
| 参数 | 描述 |
|---|---|
| options | 事件集配置选项，须在XS_EVENT_AND及XS_EVENT_OR中指定其一，并可以按位或上XS_EVENT_AUTOCLEAN |
void xs_UserEventDelete(xs_uint16 id);
该函数用于删除一个已创建的事件集。
| 参数 | 描述 |
|---|---|
| id | 待删除的事件集的ID |
xs_int32 xs_UserEventTrigger(xs_uint16 id, xs_uint32 events);
该函数用于触发事件集中的一组事件。
| 参数 | 描述 |
|---|---|
| id | 事件集ID |
| events | 欲触发的事件，其中被置1的位标识被触发的事件 ,可以使用XS_EVENTS宏按位或发送事件类型 |
xs_int32 xs_UserEventProcess(xs_uint16 id, xs_uint32 events, xs_ticks_x wait_time);
该函数用于等待事件集中的一组事件。若等待成功则返回XS_EOK，此时若XS_EVENT_AUTOCLEAN被打开则事件集中所有已触发事件会被清空；若等待失败（超时）则返回-XS_ETIMEOUT。
| 参数 | 描述 |
|---|---|
| id | 事件集ID |
| events | 欲等待的事件，其中被置1的位标识被等待的事件，可以使用XS_EVENTS宏按位或接收事件类型 |
| wait_time | 等待时间上限，单位ticks；若为0，则不等待 |
xs_int32 xs_UserEventConfig(xs_uint16 id, xs_uint32 options);
该函数用于配置事件集中的一种事件类型。若等配置成功则返回XS_EOK，options参数用于配置事件集的属性。可配置的属性有等待触发方式（XS_EVENT_AND或XS_EVENT_OR）及等待触发后是否自动清空其他已触发的事件（XS_EVENT_AUTOCLEAN）。
| 参数 | 描述 |
|---|---|
| id | 事件集ID |
| options | 事件集配置选项，须在XS_EVENT_AND及XS_EVENT_OR中指定其一，并可以按位或上XS_EVENT_AUTOCLEAN |
xs_int32 xs_UserEventReinit(xs_uint16 id);
该函数用于将一个事件的值进行重置。
| 参数 | 描述 |
|---|---|
| id | 来源消息队列ID |