CMSIS-RTOS2 文档翻译 之 参考(CMSIS-RTOS2 API 之 消息队列)

消息队列

在类似 FIFO 的操作中交换线程之间的消息。更多...

数据结构

struct  osMessageQueueAttr_t
 消息队列的属性结构体。更多...
 

函数

osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr)
 创建并初始化消息队列对象。更多...
 
const char * osMessageQueueGetName (osMessageQueueId_t mq_id)
 获取消息队列对象的名称。更多...
 
osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout)
 如果队列已满,请将消息放入队列或超时。更多...
 
osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout)
 如果队列为空,则从队列获取消息或超时。更多...
 
uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id)
 在消息队列中获取最大数量的消息。更多...
 
uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id)
 获取内存池中的最大消息大小。更多...
 
uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id)
 获取消息队列中排队的消息数量。更多...
 
uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id)
 获取消息队列中消息的可用插槽数量。更多...
 
osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id)
 将消息队列重置为初始空状态。更多...
 
osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id)
 删除一个消息队列对象。更多...
 

描述

消息传递是线程之间的另一种基本通信模型。在消息传递模型中,一个线程显式地发送数据,而另一个线程接收它。该操作更像是某种 I/O ,而不是直接访问要共享的信息。在 CMSIS-RTOS 中,这种机制被称为消息队列。数据通过类似 FIFO 的操作从一个线程传递到另一个线程。使用消息队列功能,您可以控制,发送,接收或等待消息。要传递的数据可以是整数或指针类型:

CMSIS-RTOS 消息队列

与内存池相比,消息队列通常效率较低,但解决了更广泛的问题。有时,线程没有共同的地址空间,或者共享内存的使用引发了诸如互斥等问题。

注意
可以从中断服务例程调用osMessageQueuePut,osMessageQueueGet,osMessageQueueGetCapacity,osMessageQueueGetMsgSize,osMessageQueueGetCount,osMessageQueueGetSpace 函数。
有关 RTX5 配置选项,请参阅消息队列配置。

数据结构文档

struct osMessageQueueAttr_t

用于配置消息队列的属性。

有关使用的详细信息,请参阅内存管理

数据字段
const char *name消息队列的名称

指向具有人类可读名称的消息队列对象的字符串。
默认值:NULL 。

uint32_tattr_bits属性位

保留以供将来使用(设为 '0')。
默认值:0 。

void *cb_mem内存控制块

指向消息队列控制块对象的内存位置。这可以选择用于定制内存管理系统。
默认值:NULL(使用内核内存管理)。

uint32_tcb_size为控制块提供的内存大小

内存块的大小与 cb_mem 一起传递。必须是消息队列控制块对象的大小或更大。

void *mq_mem内存数据存储

指向消息队列对象数据的内存位置。
默认值:NULL 。

uint32_tmq_size为数据存储提供的内存大小

通过 mq_mem 传递的内存大小。

函数文档

osMessageQueueId_t osMessageQueueNew(uint32_t msg_count,
  uint32_t msg_size,
  const osMessageQueueAttr_tattr 
 )  
参数
[in]msg_count队列中消息的最大数量。
[in]msg_size最大消息大小以字节为单位
[in]attr消息队列属性; NULL:默认值。
返回
消息队列 ID 以供其他功能参考,或者在发生错误时为 NULL 。

函数 osMessageQueueNew 创建并初始化消息队列对象,并返回指向消息队列对象标识符的指针,或者在发生错误时返回 NULL 。它可以在 RTOS 启动之前(调用 osKernelStart)安全地调用,但不能在它初始化之前(调用 osKernelInitialize)调用

注意
该函数不能从中断服务程序调用。

代码示例

请参阅 osMessageQueuePut

const char * osMessageQueueGetName(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
名称为 NULL 终止的字符串。

osMessageQueueGetName 函数返回指向由参数 mq_id 标识的消息队列的名称字符串的指针,或者在发生错误时返回 NULL 。

注意
该函数不能从中断服务程序调用。

osStatus_t osMessageQueuePut(osMessageQueueId_t mq_id,
  const void * msg_ptr,
  uint8_t msg_prio,
  uint32_t timeout 
 )  
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
[in]msg_ptr指向具有消息的缓冲区以放入队列。
[in]msg_prio消息优先级。
[in]timeout超时值或 0 在没有超时的情况下。
返回
状态代码,指示该功能的执行状态。

阻塞函数 osMessageQueuePut 将 msg_ptr 指向的消息放入由参数 mq_id 指定的消息队列中。参数 msg_prio 用于根据插入的优先级对消息进行排序(较高的数字表示较高的优先级)。

参数超时指定系统等待将消息放入队列的时间。系统等待时,调用此函数的线程将进入 BLOCKED 状态。参数超时可以有以下值:

  • 当超时为 0 时,函数立即返回(即尝试语义)。
  • 当超时设置为 osWaitForever 时,该函数将等待无限的时间直到消息被传递(即等待语义)。
  • 所有其他值都指定了内核中的超时时间(即定时等待语义)。

可能的 osStatus_t 返回值:

  • osOK: 该消息已被放入队列中。
  • osErrorTimeout: 在给定时间内消息不能被放入队列(等待时间语义)。
  • osErrorResource: 队列中没有足够的空间(尝试语义)。
  • osErrorParameter: 参数 mq_id 不正确,在 ISR 中指定的非零超时。
注意
如果参数 timeout 设置为 0,可以从中断服务例程调用。

代码示例:

#include "cmsis_os2.h" // CMSIS RTOS header file
/*----------------------------------------------------------------------------
* Message Queue creation & usage
*---------------------------------------------------------------------------*/
void Thread_MsgQueue1 ( void *argument); // thread function 1
void Thread_MsgQueue2 ( void *argument); // thread function 2
osThreadId_t tid_Thread_MsgQueue1; // thread id 1
osThreadId_t tid_Thread_MsgQueue2; // thread id 2
#define MSGQUEUE_OBJECTS 16 // number of Message Queue Objects
typedef struct { // object data type
uint8_t Buf[32];
uint8_t Idx;
} MSGQUEUE_OBJ_t;
osMessageQueueId_t mid_MsgQueue; // message queue id
int Init_MsgQueue ( void) {
mid_MsgQueue = osMessageQueueNew(MSGQUEUE_OBJECTS, sizeof(MSGQUEUE_OBJ_t), NULL);
if (!mid_MsgQueue) {
; // Message Queue object not created, handle failure
}
tid_Thread_MsgQueue1 = osThreadNew (Thread_MsgQueue1, NULL, NULL);
if (!tid_Thread_MsgQueue1) return(-1);
tid_Thread_MsgQueue2 = osThreadNew (Thread_MsgQueue2, NULL, NULL);
if (!tid_Thread_MsgQueue2) return(-1);
return(0);
}
void Thread_MsgQueue1 ( void *argument) {
MSGQUEUE_OBJ_t msg;
while (1) {
; // Insert thread code here...
msg.Buf[0] = 0x55; // do some work...
msg.Idx = 0;
osMessageQueuePut (mid_MsgQueue, &msg, 0, NULL);
osThreadYield (); // suspend thread
}
}
void Thread_MsgQueue2 ( void *argument) {
MSGQUEUE_OBJ_t msg;
osStatus_t status;
while (1) {
; // Insert thread code here...
status = osMessageQueueGet (mid_MsgQueue, &msg, NULL, NULL); // wait for message
if (status == osOK) {
; // process data
}
}
}

osStatus_t osMessageQueueGet(osMessageQueueId_t mq_id,
  void * msg_ptr,
  uint8_t * msg_prio,
  uint32_t timeout 
 )  
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
[out]msg_ptr指向缓冲区的消息以从队列中获取消息。
[out]msg_prio指向缓冲区的消息优先级或 NULL 。
[in]timeout超时值或 0 在没有超时的情况下。
返回
状态代码,指示该功能的执行状态。

osMessageQueueGet 函数从参数 mq_id 指定的消息队列中检索消息,并将其保存到参数 msg_ptr 所指向的缓冲区中。如果不是令牌{NULL},则消息优先级存储到参数 msg_prio 。

参数 timeout 指定系统等待从队列中检索消息的时间。系统等待时,调用此函数的线程将进入 BLOCKED 状态。参数超时可以有以下值:

  • 当超时为 0 时,函数立即返回(即尝试语义)。
  • 当超时设置为 osWaitForever 时,该函数将等待无限时间,直到检索到消息(即等待语义)。
  • 所有其他值都指定了内核中的超时时间(即定时等待语义)。

可能的 osStatus_t 返回值:

  • osOK: 该消息已从队列中检索出来。
  • osErrorTimeout: 在给定时间内无法从队列中检索消息(定时等待语义)。
  • osErrorResource: 没有什么可以从队列中获得(尝试语义)。
  • osErrorParameter: 参数 mq_id 不正确,在 ISR 中指定的非零超时。
注意
如果参数 timeout 设置为 0 ,可以从中断服务例程调用。

代码示例

请参阅 osMessageQueuePut

uint32_t osMessageQueueGetCapacity(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
消息的最大数量。

函数 osMessageQueueGetCapacity 返回消息队列对象中由参数 mq_id 或 0 指定的最大消息数量,以防出现错误。

注意
这个函数可以从中断服务程序中调用。
uint32_t osMessageQueueGetMsgSize(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
最大消息大小以字节为单位

函数 osMessageQueueGetMsgSize 返回由参数 mq_id 指定的消息队列对象的最大消息大小(以字节为单位)或在出现错误时返回 0 。

注意
这个函数可以从中断服务程序中调用。
uint32_t osMessageQueueGetCount(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
排队的消息数量。

函数 osMessageQueueGetCount 返回由参数 mq_id 或 0 指定的消息队列对象中排队的消息数量,以防出现错误。

注意
这个函数可以从中断服务程序中调用。
uint32_t osMessageQueueGetSpace(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
消息的可用插槽数量。

函数 osMessageQueueGetSpace 返回由参数 mq_id 指定的消息队列对象中的消息的可用槽数量,如果发生错误,则返回 0 。

注意
这个函数可以从中断服务程序中调用。
osStatus_t osMessageQueueReset(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
状态代码,指示该函数的执行状态。

函数 osMessageQueueReset 重置由参数 mq_id 指定的消息队列。

可能的 osStatus_t 返回值:

  • osOK: 消息队列已被重置。
  • osErrorParameter: 参数 mq_id 是 NULL 或无效。
  • osErrorResource: 由参数 mq_id 指定的消息队列处于无效消息队列状态。
  • osErrorISR: osMessageQueueReset 不能从中断服务例程调用。
注意
该函数不能从中断服务程序调用。
osStatus_t osMessageQueueDelete(osMessageQueueId_t mq_id) 
参数
[in]mq_id消息队列 ID 由 osMessageQueueNew 获取。
返回
状态代码,指示该函数的执行状态。

osMessageQueueDelete 函数删除由参数 mq_id 指定的消息队列对象。它释放为消息队列处理而获得的内部内存。在这个调用之后,mq_id 不再有效并且不能使用。消息队列可以使用函数 osMessageQueueNew 再次创建。

可能的 osStatus_t 返回值:

  • osOK: 消息队列对象已被删除。
  • osErrorParameter: 参数 mq_id 是 NULL 或无效。
  • osErrorResource: 由参数 mq_id 指定的消息队列处于无效消息队列状态。
  • osErrorISR: osMessageQueueDelete 不能从中断服务例程调用。
注意
该函数不能从中断服务程序调用。

  • 6
    点赞
  • 22
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
CMSIS-RTOS》是一本PDF文档,本文将以300字回答有关此文档的问题。 《CMSIS-RTOS》是一本关于Cortex微控制器软件接口标准(CMSIS)中的实时操作系统(RTOS)的PDF文档。该文档详细介绍了CMSIS-RTOS的特性、结构、API和使用方法。 CMSIS-RTOS是一种用于嵌入式系统的实时操作系统,它提供了一套标准化的API和接口,用于编写和管理多任务、多线程和中断驱动的应用程序。该文档介绍了如何使用CMSIS-RTOS构建可靠和高效的嵌入式系统。 文档首先介绍了CMSIS-RTOS的基本概念,包括任务、线程、中断和事件。然后,它详细描述了每个概念的特性和用法,包括任务管理、内存管理、同步和互斥机制等。 此外,文档还介绍了CMSIS-RTOS的结构和组件,如内核、调度器和定时器。它说明了每个组件的功能和使用方法,以及它们之间的关系和依赖关系。 最后,文档提供了一些示例代码和实践指南,以帮助读者更好地理解和应用CMSIS-RTOS。它演示了如何创建、启动和管理任务,以及如何使用互斥锁和信号量进行任务间的数据共享和同步。 总而言之,《CMSIS-RTOS》是一本全面且实用的PDF文档,它为开发人员提供了使用CMSIS-RTOS构建嵌入式系统的详细指南和参考资料。无论是初学者还是有经验的开发人员,都能从中获得关于实时操作系统的深入了解和实际应用的指导。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值