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 );
}