CMSIS-RTOS2 文档翻译之参考（CMSIS-RTOS2 API 之消息队列）

最新推荐文章于 2024-08-11 19:47:39 发布

XinLiBK

最新推荐文章于 2024-08-11 19:47:39 发布

阅读量8.2k

点赞数 6

分类专栏： CMSIS CMSIS-RTOS2 文档翻译文章标签： ARM CMSIS RTOS RTOS2 RTX

CMSIS 同时被 2 个专栏收录

42 篇文章 31 订阅

订阅专栏

CMSIS-RTOS2 文档翻译

42 篇文章 102 订阅

订阅专栏

在类似 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

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

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

osMessageQueueAttr_t::cb_mem
osMessageQueueAttr_t::cb_size
osMessageQueueAttr_t::mq_mem
osMessageQueueAttr_t::mq_size

数据字段
const char *	name	消息队列的名称指向具有人类可读名称的消息队列对象的字符串。默认值：NULL 。
uint32_t	attr_bits	属性位保留以供将来使用（设为 '0'）。默认值：0 。
void *	cb_mem	内存控制块指向消息队列控制块对象的内存位置。这可以选择用于定制内存管理系统。默认值：NULL（使用内核内存管理）。
uint32_t	cb_size	为控制块提供的内存大小内存块的大小与 cb_mem 一起传递。必须是消息队列控制块对象的大小或更大。
void *	mq_mem	内存数据存储指向消息队列对象数据的内存位置。默认值：NULL 。
uint32_t	mq_size	为数据存储提供的内存大小通过 mq_mem 传递的内存大小。

函数文档

osMessageQueueId_t osMessageQueueNew	(	uint32_t	msg_count,
		uint32_t	msg_size,
		const osMessageQueueAttr_t *	attr
	)

参数

[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 在没有超时的情况下。