ESP32 FreeRTOS-流缓冲区(12)

提示：好记性不如烂笔头。本博客作为学习笔记，有错误的地方希望指正

前言：

  参考资料：FreeRTOS API参考
  这里主要数据流，我们可以实现接收一些流媒体数据，例如音频数据流，视频数据流，只要达到我们接收长度即可触发接收，之后一值会将结束数据区塞满。

一、xStreamBufferCreate()、xStreamBufferCreateWithCallback()

API原型：

StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
                                           size_t xTriggerLevelBytes );
StreamBufferHandle_t xStreamBufferCreateWithCallback( 
                         size_t xBufferSizeBytes,
                         size_t xTriggerLevelBytes
                         StreamBufferCallbackFunction_t pxSendCompletedCallback,
                         StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

  创建一个使用动态分配内存的新流缓冲区。流缓冲区 在完成每个发送和接收操作时执行回调。使用 xStreamBufferCreate()API 创建的流缓冲区 共享相同的发送和接收完成回调函数，这些函数是用 sbSEND_COMPLETED() 和 sbRECEIVE_COMPLETED() 宏定义的 。使用 xStreamBufferCreateWithCallback() API 创建的流缓冲区可以有各自独特的发送和接收完成 回调函数。请参阅 xStreamBufferCreateStatic() 和 xStreamBufferCreateStaticWithCallback() 了解使用动态分配内存（在编译时分配的内存）的对应版本 。
  configSUPPORT_DYNAMIC_ALLOCATION 必须 在 FreeRTOSConfig.h 中设置为 1 或未定义， xStreamBufferCreate () 才可用。此外，configUSE_SB_COMPLETED_CALLBACK 必须在 FreeRTOSConfig.h 中设置为 1，xStreamBufferCreateWithCallback() 才可用。
  将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中即可启用流缓冲区功能。
参数：
  xBufferSizeBytes 流缓冲区在任何时候能够容纳的总字节数。
  xTriggerLevelBytes 在流缓冲区中被阻塞以等待数据的任务离开阻塞状态之前， 流缓冲区中必须包含的字节数。例如，如果一个任务在读取触发等级为 1 的空流缓冲区时被阻塞， 那么当单个字节写入缓冲区或该任务的阻塞时间结束时，该任务将被解除阻塞。 另一个例子是，如果一个任务在读取触发等级为 10 的空流缓冲区时被阻塞， 那么直到流缓冲区至少包含 10 个字节或该任务的阻塞时间结束之前，该任务将不会被解除阻塞。如果 读任务的阻塞时间在达到触发等级之前过期，那么该任务仍将接收实际可用的字节数 。将触发等级设置为 0 将导致使用触发等级 1。指定 一个大于缓冲区大小的触发等级是无效的。
  pxSendCompletedCallback 当对流缓冲区的数据写入导致缓冲区的字节数超过触发等级时调用的回调函数 。如果参数为 NULL，则使用 sbSEND_COMPLETED 宏所提供的默认实现 。发送完成的回调函数必须具有 StreamBufferCallbackFunction_t 定义的原型，即：

void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
                            BaseType_t xIsInsideISR,
                            BaseType_t * const pxHigherPriorityTaskWoken );

  pxReceiveCompletedCallback 当从流缓冲区读取数据（多于 0 字节）时调用的回调函数。如果参数为 NULL， 则使用 sbRECEIVE_COMPLETED 宏所提供的默认实现。接收完成回调函数必须 具有 StreamBufferCallbackFunction_t 定义的原型，即：

void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
                               BaseType_t xIsInsideISR,
                               BaseType_t * const pxHigherPriorityTaskWoken );

返回值：
  如果返回 NULL，则说明因为没有足够的堆内存可供 FreeRTOS 分配流缓冲区的数据结构体和存储区域，所以流缓冲区无法被创建。如果返回的值不是 NULL，则说明流缓冲区已经成功创建 ——返回值应该作为所创建流缓冲区的句柄来存储。
用法示例：

void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
                            BaseType_t xIsInsideISR,
                            BaseType_t * const pxHigherPriorityTaskWoken )
{
   
   
    /* 在此插入代码，当对流缓冲区进行数据写入操作时，该代码被调用。
     * 在此插入代码，当对流缓冲区的数据写入操作导致缓冲区内的字节数
     * 导致缓冲区内的字节数超过了触发水平。
     * 当流缓冲区被用来在多核处理器之间传递数据时，这很有用。
     * 在一个多核处理器上的核心之间传递数据时，这一点非常有用。在这种情况下，这个回调
     * 可以实现在另一个CPU核中产生一个中断。
     * 然后，中断的服务程序可以使用
     * xStreamBufferSendCompletedFromISR() API函数来检查，如果有必要的话
     * 必要时解除对一个正在等待数据的任务的封锁。*/
}

void vReceiveCallbackFunction( StreamBufferHandle_t xStreamBuffer,
                               BaseType_t xIsInsideISR,
                               BaseType_t * const pxHigherPriorityTaskWoken )
{
   
   
    /* 在这里插入代码，当数据从流中读出时被调用。
     * 缓冲区。
     * 当流缓冲区被用来在多核之间传递数据时，这很有用。
     * 这在多核处理器上的核心之间传递数据时非常有用。在这种情况下，这个回调
     * 可以实现在另一个CPU核中产生一个中断。
     * 然后，中断的服务程序可以使用
     * xStreamBufferReceiveCompletedFromISR() API函数来检查，如果有必要的话
     * 必要时解除对一个等待发送数据的任务的封锁。*/
}

void vAFunction( void )
{
   
   
	StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
	const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;

    /* 创建一个可以容纳100字节的流缓冲区，并使用
     * 使用sbSEND_COMPLETED()和
     * sbRECEIVE_COMPLETED() 宏定义的函数作为发送和接收完成的
     * 回调函数。用来保存流的内存
     * 缓冲区结构和流缓冲区中的数据是动态分配的。
     * 动态地分配。*/
    xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes,
                                         xTriggerLevel );
    if( xStreamBuffer == NULL )
    {
   
   
        /* 没有足够的堆内存空间可用于创建流缓冲区。
        流缓冲区。*/
    }
    else
    {
   
   
        /* 流缓冲区已成功创建，现在可以使用。*/
    }
    
    /* 创建一个可以容纳100字节的流缓冲区，并使用
     * 函数vSendCallbackFunction和vReceiveCallbackFunction
     *作为发送和接收完成的回调函数。内存
     * 用于容纳流缓冲区结构和数据的
     *流缓冲区中的数据是动态分配的。*/
    xStreamBufferWithCallback = xStreamBufferCreateWithCallback( 
                                    xStreamBufferSizeBytes,
                                    xTriggerLevel,
                                    vSendCallbackFunction,
                                    vReceiveCallbackFunction );
    if( xStreamBufferWithCallback == NULL )
    {
   
   
        /* 没有足够的堆内存空间可用于创建流缓冲区。*/
    }
    else
    {
   
   
        /* 流缓冲区已成功创建，现在可以使用。*/
    }
}

二、xStreamBufferCreateStatic()、xStreamBufferCreateStaticWithCallback()

API原型：

StreamBufferHandle_t xStreamBufferCreateStatic(
                                    size_t xBufferSizeBytes,
                                    size_t xTriggerLevelBytes,
                                    uint8_t *pucStreamBufferStorageArea,
                                    StaticStreamBuffer_t *pxStaticStreamBuffer );

StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
                                    size_t xBufferSizeBytes,
                                    size_t xTriggerLevelBytes,
                                    uint8_t *pucStreamBufferStorageArea,
                                    StaticStreamBuffer_t *pxStaticStreamBuffer,
                                    StreamBufferCallbackFunction_t pxSendCompletedCallback,
                                    StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

  使用静态分配的内存创建一个新的流缓冲区。流缓冲区 在完成每个发送和接收操作时执行回调。使用 xStreamBufferCreateStatic() API 创建的流缓冲区 共享相同的发送和接收完成回调函数，这些函数是用 sbSEND_COMPLETED() 和 sbRECEIVE_COMPLETED() 宏定义的 。使用 xStreamBufferCreateStaticWithCallback() API 创建的流缓冲区可以有各自独特的发送和接收完成 回调函数。请参阅 xStreamBufferCreate() and xStreamBufferCreateWithCallback() 了解使用动态分配内存的对应版本。
  configSUPPORT_STATIC_ALLOCATION 必须在 FreeRTOSConfig.h 中设置为 1， xStreamBufferCreateStatic() 才可用。此外，configUSE_SB_COMPLETED_CALLBACK 必须在 FreeRTOSConfig.h 中设置为 1，xStreamBufferCreateStaticWithCallback() 才可用。
  将 FreeRTOS/source/stream_buffer.c 源文件包含在构建中即可启用流缓冲区功能。
参数：
  xBufferSizeBytes pucStreamBufferStorageArea 参数所指向的缓冲区的大小（单位：字节）。
  xTriggerLevelBytes 在流缓冲区中被阻塞以等待数据的任务离开阻塞状态之前， 流缓冲区中必须存在的字节数。例如，如果一个任务在读取触发等级为 1 的空流缓冲区时被阻塞， 那么当单个字节写入缓冲区或该任务的阻塞时间结束时，该任务将被解除阻塞。 另一个例子是，如果一个任务在读取触发等级为 10 的空流缓冲区时被阻塞， 那么直到流缓冲区至少包含 10 个字节或该任务的阻塞时间结束之前，该任务将不会被解除阻塞。如果 读取任务的阻塞时间在达到触发等级之前过期，那么该任务仍将接收实际可用的字节数 。将触发等级设置为 0 将导致使用触发等级 1。指定 一个大于缓冲区大小的触发等级是无效的。
  pucStreamBufferStorageArea 必须指向一个大小至少为 xBufferSizeBytes + 1 的 uint8_t 数组。这是一个数组，当将流写入流缓冲区时， 流会被复制到这个数组中。
  pxStaticStreamBuffer 必须指向一个 StaticStreamBuffer_t 类型的变量，它将用于保存流缓冲区的数据结构体。
  pxSendCompletedCallback 当对流缓冲区的数据写入导致缓冲区的字节数超过触发等级时调用的回调函数 。如果参数为 NULL，则使用 sbSEND_COMPLETED 宏所提供的默认实现 。发送完成的回调函数必须具有 StreamBufferCallbackFunction_t 定义的原型，即：

void vSendCallbackFunction( StreamBufferHandle_t xStreamBuffer,
                            BaseType_t xIsInsideISR,