FreeRTOS api库函数之Stream Buffers(流缓冲区)

xStreamBufferCreate（）
StreamBufferHandle_t xStreamBufferCreate（size_t xBufferSizeBytes，size_t xTriggerLevelBytes）;
使用动态分配的内存创建新的流缓冲区。
必须在FreeRTOSConfig.h中将configSUPPORT_DYNAMIC_ALLOCATION设置为1或未定义，才能使xStreamBufferCreate（）可用。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xBufferSizeBytes 流缓冲区在任何时候都能够保存的总字节数。
    xTriggerLevelBytes 在流缓冲区上阻塞以等待数据的任务移出阻塞状态之前，流缓冲区中必须包含的字节数。例如，如果在读取具有触发级别1的空流缓冲区时阻止任务，则当将单个字节写入缓冲区或任务的块时间到期时，将取消阻止该任务。作为另一示例，如果在读取具有触发级别10的空流缓冲器时阻止任务，则在流缓冲器包含至少10个字节或任务的块时间到期之前不会解除对任务的阻塞。如果读取任务的阻塞时间在达到触发级别之前到期，则任务仍将接收，但实际可用的字节数很多。将触发电平设置为0将导致使用触发电平1。指定大于缓冲区大小的触发器级别无效。
返回：
    如果返回NULL，则无法创建流缓冲区，因为FreeRTOS没有足够的堆内存来分配流缓冲区数据结构和存储区域。返回的非NULL值表示已成功创建流缓冲区 - 返回的值应存储为创建的流缓冲区的句柄。

xStreamBufferCreateStatic（）
StreamBufferHandle_t xStreamBufferCreateStatic（size_t xBufferSizeBytes，size_t xTriggerLevelBytes，uint8_t * pucStreamBufferStorageArea，StaticStreamBuffer_t * pxStaticStreamBuffer）;
使用静态分配的内存创建新的流缓冲区。
FreeRTOSConfig.h中的configSUPPORT_STATIC_ALLOCATION必须设置为1才能使xStreamBufferCreateStatic（）可用。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xBufferSizeBytes  pucStreamBufferStorageArea参数指向的缓冲区的大小（以字节为单位）。
    xTriggerLevelBytes 在流缓冲区上阻塞以等待数据的任务移出阻塞状态之前，流缓冲区中必须包含的字节数。例如，如果在读取具有触发级别1的空流缓冲区时阻止任务，则当将单个字节写入缓冲区或任务的块时间到期时，将取消阻止该任务。作为另一示例，如果在读取具有触发级别10的空流缓冲器时阻止任务，则在流缓冲器包含至少10个字节或任务的块时间到期之前不会解除对任务的阻塞。如果读取任务的阻塞时间在达到触发级别之前到期，则任务仍将接收，但实际可用的字节数很多。将触发电平设置为0将导致使用触发电平1。指定大于缓冲区大小的触发器级别无效。
    pucStreamBufferStorageArea必须指向至少xBufferSizeBytes + 1大的uint8_t数组。这是在将流写入流缓冲区时将流复制到的数组。
    pxStaticStreamBuffer必须指向StaticStreamBuffer_t类型的变量，该变量将用于保存流缓冲区的数据结构。
返回：
    如果成功创建了流缓冲区，则返回创建的流缓冲区的句柄。如果pucStreamBufferStorageArea或pxStaticstreamBuffer为NULL，则返回NULL。

xStreamBufferSend（）
size_t xStreamBufferSend（StreamBufferHandle_t xStreamBuffer，const void * pvTxData，size_t xDataLengthBytes，TickType_t xTicksToWait）;
将字节发送到流缓冲区。字节被复制到流缓冲区中。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xStreamBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xStreamBufferRead（））中，并使用接收块时间为0。
使用xStreamBufferSend（）从任务写入流缓冲区。使用xStreamBufferSendFromISR（）从中断服务例程（ISR）写入流缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xStreamBuffer 正在向其发送流的流缓冲区的句柄。
    pvTxData 指向缓冲区的指针，该缓冲区保存要复制到流缓冲区中的字节。
    xDataLengthBytes 从pvTxData复制到流缓冲区的最大字节数。
    xTicksToWait 如果流缓冲区包含的空间太小而无法容纳另一个xDataLengthBytes字节，则任务应保持在阻塞状态以等待流缓冲区中有足够空间可用的最长时间。块时间在滴答周期中指定，因此它表示的绝对时间取决于滴答频率。宏pdMS_TO_TICKS（）可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。如果在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1，则将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时）。如果一个任务超时，它可以将所有xDataLengthBytes写入缓冲区，它仍将写入尽可能多的字节。任务在处于阻塞状态时不使用任何CPU时间。
返回：
    写入流缓冲区的字节数。如果一个任务超时，它可以将所有xDataLengthBytes写入缓冲区，它仍将写入尽可能多的字节。

xStreamBufferSendFromISR（）
size_t xStreamBufferSendFromISR（StreamBufferHandle_t xStreamBuffer，const void * pvTxData，size_t xDataLengthBytes，BaseType_t * pxHigherPriorityTaskWoken）;
中断安全版本的API函数，它将字节流发送到流缓冲区。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xStreamBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xStreamBufferRead（））中，并使用接收块时间为0。
使用xStreamBufferSend（）从任务写入流缓冲区。使用xStreamBufferSendFromISR（）从中断服务例程（ISR）写入流缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xStreamBuffer 正在向其发送流的流缓冲区的句柄。
    pvTxData 指向缓冲区的指针，该缓冲区保存要复制到流缓冲区中的字节。
    xDataLengthBytes 从pvTxData复制到流缓冲区的最大字节数。
    pxHigherPriorityTaskWoken 流缓冲区可能会阻塞任务等待数据。调用xStreamBufferSendFromISR（）可以使数据可用，从而导致正在等待数据离开阻塞状态的任务。如果调用xStreamBufferSendFromISR（）导致任务离开阻塞状态，并且未阻塞任务的优先级高于当前正在执行的任务（被中断的任务），则在内部，xStreamBufferSendFromISR（）将* pxHigherPriorityTaskWoken设置为pdTRUE。如果xStreamBufferSendFromISR（）将此值设置为pdTRUE，则通常应在退出中断之前执行上下文切换。这将确保中断直接返回到最高优先级的就绪状态任务。 * pxHigherPriorityTaskWoken在传递给函数之前应该设置为pdFALSE。有关示例，请参阅下面的示例代码。
返回：
    写入流缓冲区的字节数。如果一个任务超时，它可以将所有xDataLengthBytes写入缓冲区，它仍将写入尽可能多的字节。

xStreamBufferReceive（）
size_t xStreamBufferReceive（StreamBufferHandle_t xStreamBuffer，void * pvRxData，size_t xBufferLengthBytes，TickType_t xTicksToWait）;
从流缓冲区接收字节。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xStreamBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xStreamBufferRead（））中，并使用接收块时间为0。
使用xStreamBufferReceive（）从任务中读取流缓冲区。使用xStreamBufferReceiveFromISR（）从中断服务例程（ISR）读取流缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xStreamBuffer 要从中接收字节的流缓冲区的句柄。
    pvRxData 指向将要复制接收字节的缓冲区的指针。
    xBufferLengthBytes  pvRxData参数指向的缓冲区长度。这设置了一次调用中要接收的最大字节数。 xStreamBufferReceive将返回尽可能多的字节，直到xBufferLengthBytes设置的最大值。
    xTicksToWait 如果流缓冲区为空，任务应保持在阻止状态以等待数据变为可用的最长时间。如果xTicksToWait为零，xStreamBufferReceive（）将立即返回。块时间在滴答周期中指定，因此它表示的绝对时间取决于滴答频率。宏pdMS_TO_TICKS（）可用于将以毫秒为单位指定的时间转换为刻度中指定的时间。如果在FreeRTOSConfig.h中将INCLUDE_vTaskSuspend设置为1，则将xTicksToWait设置为portMAX_DELAY将导致任务无限期地等待（没有超时）。任务在处于阻止状态时不使用任何CPU时间。
返回：
    实际从流缓冲区读取的字节数，如果在xBufferLengthBytes可用之前对xStreamBufferReceive（）的调用超时，则该字节数将小于xBufferLengthBytes。

xStreamBufferReceiveFromISR（）
size_t xStreamBufferReceiveFromISR（StreamBufferHandle_t xStreamBuffer，void * pvRxData，size_t xBufferLengthBytes，BaseType_t * pxHigherPriorityTaskWoken）;
API函数的中断安全版本，它从流缓冲区接收字节。
注意：在FreeRTOS对象中，流缓冲区实现（以及消息缓冲区实现，因为消息缓冲区构建在流缓冲区之上）假设只有一个任务或中断将写入缓冲区（写入程序），并且只有一个任务或中断将从缓冲区（阅读器）读取。作者和读者可以安全地处理不同的任务或中断，但与其他FreeRTOS对象不同，拥有多个不同的编写器或多个不同的读取器是不安全的。如果要有多个不同的编写器，那么应​​用程序编写者必须将每个调用放在一个临界区内的写API函数（例如xStreamBufferSend（））中，并使用0的发送块时间。同样，如果有多个不同的然后，应用程序编写者必须将每个调用放在一个关键部分内的读取API函数（例如xStreamBufferRead（））中，并使用接收块时间为0。
使用xStreamBufferReceive（）从任务中读取流缓冲区。使用xStreamBufferReceiveFromISR（）从中断服务例程（ISR）读取流缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xStreamBuffer 要从中接收字节的流缓冲区的句柄。
    pvRxData 指向将要复制接收字节的缓冲区的指针。
    xBufferLengthBytes  pvRxData参数指向的缓冲区长度。这设置了一次调用中要接收的最大字节数。 xStreamBufferReceive将返回尽可能多的字节，直到xBufferLengthBytes设置的最大值。
    pxHigherPriorityTaskWoken 流缓冲区可能会阻塞任务，等待空间可用。调用xStreamBufferReceiveFromISR（）可以使空间可用，从而导致等待空间的任务离开阻塞状态。如果调用xStreamBufferReceiveFromISR（）导致任务退出阻塞状态，并且未阻塞任务的优先级高于当前正在执行的任务（被中断的任务），则在内部，xStreamBufferReceiveFromISR（）将* pxHigherPriorityTaskWoken设置为pdTRUE。如果xStreamBufferReceiveFromISR（）将此值设置为pdTRUE，则通常应在退出中断之前执行上下文切换。这将确保中断直接返回到最高优先级的就绪状态任务。 * pxHigherPriorityTaskWoken在传递给函数之前应该设置为pdFALSE。有关示例，请参阅下面的代码示例。
返回：
    从流缓冲区读取的字节数（如果有）。

vStreamBufferDelete（）
void vStreamBufferDelete（StreamBufferHandle_t xStreamBuffer）;
删除先前使用xStreamBufferCreate（）或xStreamBufferCreateStatic（）调用创建的流缓冲区。 如果使用动态内存（即xStreamBufferCreate（））创建了流缓冲区，则释放分配的内存。
删除流缓冲区后，不得使用流缓冲区句柄。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 要删除的流缓冲区的句柄。

xStreamBufferBytesAvailable（）
size_t xStreamBufferBytesAvailable（StreamBufferHandle_t xStreamBuffer）;
查询流缓冲区以查看它包含多少数据，这等于在流缓冲区为空之前可以从流缓冲区读取的字节数。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 正在查询的流缓冲区的句柄。
返回：
     在流缓冲区为emtpy之前可以从流缓冲区读取的字节数。

xStreamBufferSpacesAvailable（）
size_t xStreamBufferSpacesAvailable（StreamBufferHandle_t xStreamBuffer）;
查询流缓冲区以查看它包含多少可用空间，这等于在流缓冲区满之前可以发送到流缓冲区的数据量。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 正在查询的流缓冲区的句柄。
返回：
     在流缓冲区满之前可以写入流缓冲区的字节数。

xStreamBufferSetTriggerLevel（）
BaseType_t xStreamBufferSetTriggerLevel（StreamBufferHandle_t xStreamBuffer，size_t xTriggerLevel）;
流缓冲区的触发级别是在流缓冲区上阻塞以等待数据的任务移出阻塞状态之前必须在流缓冲区中的字节数。例如，如果在读取具有触发级别1的空流缓冲区时阻止任务，则当将单个字节写入缓冲区或任务的块时间到期时，将取消阻止该任务。作为另一示例，如果在读取具有触发级别10的空流缓冲器时阻止任务，则在流缓冲器包含至少10个字节或任务的块时间到期之前不会解除对任务的阻塞。如果读取任务的阻塞时间在达到触发级别之前到期，则任务仍将接收，但实际可用的字节数很多。将触发电平设置为0将导致使用触发电平1。指定大于缓冲区大小的触发器级别无效。
创建流缓冲区时会设置触发器级别，并且可以使用xStreamBufferSetTriggerLevel（）进行修改。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
    xStreamBuffer 正在更新的流缓冲区的句柄。
    xTriggerLevel 流缓冲区的新触发器级别。
返回：
    如果xTriggerLevel小于或等于蒸汽缓冲区的长度，则将更新触发级别并返回pdTRUE。否则返回pdFALSE。

xStreamBufferReset（）
BaseType_t xStreamBufferReset（StreamBufferHandle_t xStreamBuffer）;
将流缓冲区重置为其初始的空状态。 流缓冲区中的任何数据都将被丢弃。 如果没有任何任务被阻止等待发送到流缓冲区或从流缓冲区接收，则只能重置流缓冲区。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 正在重置的流缓冲区的句柄。
返回：
     如果重置流缓冲区，则返回pdPASS。 如果有任务被阻止等待发送到流缓冲区或从流缓冲区读取，则不会重置流缓冲区并返回pdFAIL。

xStreamBufferIsEmpty（）
BaseType_t xStreamBufferIsEmpty（StreamBufferHandle_t xStreamBuffer）;
查询流缓冲区以查看它是否为空。 如果流缓冲区不包含任何数据，则它是空的。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 正在查询的流缓冲区的句柄。
返回：
     如果流缓冲区为空，则返回pdTRUE。 否则返回pdFALSE。

xStreamBufferIsFull（）
BaseType_t xStreamBufferIsFull（StreamBufferHandle_t xStreamBuffer）;
查询流缓冲区以查看它是否已满。 如果流缓冲区没有任何可用空间，则它已满，因此无法再接受任何数据。
通过在构建中包含FreeRTOS / source / stream_buffer.c源文件来启用流缓冲区功能。
参数：
     xStreamBuffer 正在查询的流缓冲区的句柄。
返回：
     如果流缓冲区已满，则返回pdTRUE。 否则返回pdFALSE。