xMessageBufferSendFromISR()
[RTOS 消息缓冲区 API]
message_buffer.h
size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
const void *pvTxData,
size_t xDataLengthBytes,
BaseType_t *pxHigherPriorityTaskWoken );
中断安全版本的 API 函数,
用于向消息缓冲区发送离散消息。 消息长度只要满足缓冲区可用空间即可,
消息会被复制到缓冲区中。
注意: 与其他 FreeRTOS 对象都不同的是,流缓冲区的实现
(消息缓冲区的实现也是如此,因为消息缓冲区是建立在流缓冲区之上的)
流缓冲区的实现假定只有一个任务或中断将写入缓冲区(写入程序),
缓冲区(写入器),只有一个任务或中断会从
(读取程序)。 写入和读取
不同的任务或中断是安全的,但与其他FreeRTOS对象不同,
有多个不同的写入或多个不同的读取是不安全的。 如果
必须有多个不同的写入,那么应用程序编写者必须
将每个调用放置到临界区中的一个写入 API 函数(如 xStreamBufferSend())中,
并将发送阻塞时间设置为0。 同样,如果有多个不同的读取器,
那么应用程序编写者必须将每个调用放置到临界区中的读取API函数(如xStreamBufferRead())中,
并使用阻塞时间 0。
使用 xMessageBufferSend() 往任务的消息缓冲区写入消息。 xMessageBufferSendFromISR()用于
往中断服务程序 (ISR) 的消息缓冲区写入
数据。
通过在构建中包含 FreeRTOS/source/stream_buffer.c 源文件
来启用消息缓冲区功能(因为消息缓冲区使用流缓冲区)。
-
参数:
-
xMessageBuffer
|
消息发送到的消息缓冲区
的句柄。
|
pvTxData
|
要复制到消息缓冲区中的消息
的指针。
|
xDataLengthBytes
|
消息长度, 即
从pvTxData复制到消息缓冲区的字节数。 当消息
写入消息缓冲区时,还会额外写入 sizeof( size_t ) 字节
用来存储消息的长度。 sizeof( size_t ) 在 32 位架构上通常为 4 字节,
因此在大多数 32 位架构上,
xDataLengthBytes设置为20时,会将消息缓冲区中的可用空间减少24个字节
(其中消息数据占20个字节,4个字节用来保存消息长度)。
|
pxHigherPriorityTaskWoken
|
(此为可选参数,可以设置为 NULL。)
消息缓冲区可能会
阻塞任务等待数据。 调用
xMessageBufferSendFromSISR() 可以使数据可用,从而使
正在等待数据的任务离开阻塞状态。 如果调用
xMessageBufferSendFromSISR() 使任务离开阻止状态,同时
未阻塞任务的优先级高于当前正在执行的任务
(被中断的任务),那么在内部,xMessageBufferSendFromISR()
将* 把pxHigherPriorityTaskWoken设置为pdTRUE。 如果
xMessageBufferSendFromSISR() 将此值设置为 pdTRUE ,
那么通常应在退出中断之前执行上下文切换。 这将
确保中断直接返回到最高优先级的“就绪”
状态任务。 * pxHigherPriorityTaskWoken在传递给函数之前
应该设置为pdFALSE。 有关示例,请参阅下面的代码示例。
|
-
返回:
-
实际写入消息缓冲区的字节数。 如果
消息缓冲区可用空间不足,无法存储消息,
则返回 0,否则返回 xDataLengthBytes。
用法示例:
/* A message buffer that has already been created. */
MessageBufferHandle_t xMessageBuffer;
void vAnInterruptServiceRoutine( void )
{
size_t xBytesSent;
char *pcStringToSend = "String to send";
BaseType_t xHigherPriorityTaskWoken = pdFALSE; /* Initialised to pdFALSE. */
/* Attempt to send the string to the message buffer. */
xBytesSent = xMessageBufferSendFromISR( xMessageBuffer,
( void * ) pcStringToSend,
strlen( pcStringToSend ),
&xHigherPriorityTaskWoken );
if( xBytesSent != strlen( pcStringToSend ) )
{
/* The string could not be added to the message buffer because there was
not enough free space in the buffer. */
}
/* If xHigherPriorityTaskWoken was set to pdTRUE inside
xMessageBufferSendFromISR() then a task that has a priority above the
priority of the currently executing task was unblocked and a context
switch should be performed to ensure the ISR returns to the unblocked
task. In most FreeRTOS ports this is done by simply passing
xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
variables value, and perform the context switch if necessary. Check the
documentation for the port in use for port specific instructions. */
taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.