22-RTOS 流缓冲区 API 函数

1StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
2size_t xTriggerLevelBytes );
3
4StreamBufferHandle_t xStreamBufferCreateWithCallback( 
5size_t xBufferSizeBytes,
6size_t xTriggerLevelBytes
7StreamBufferCallbackFunction_t pxSendCompletedCallback,
8StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

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

1void vSendCallbackFunction(StreamBufferHandle_t xStreamBuffer,
 2BaseType_t xIsInsideISR,
 3BaseType_t *const pxHigherPriorityTaskWoken)
 4{
 5/* Insert code here which is invoked when a data write operation
 6* to the stream buffer causes the number of bytes in the buffer
 7* to be more then the trigger level.
 8* This is useful when a stream buffer is used to pass data between
 9* cores on a multicore processor. In that scenario, this callback
10* can be implemented to generate an interrupt in the other CPU core,
11* and the interrupt's service routine can then use the
12* xStreamBufferSendCompletedFromISR() API function to check, and if
13* necessary unblock, a task that was waiting for the data. */
14}
15
16void vReceiveCallbackFunction(StreamBufferHandle_t xStreamBuffer,
17BaseType_t xIsInsideISR,
18BaseType_t *const pxHigherPriorityTaskWoken)
19{
20/* Insert code here which is invoked when data is read from a stream
21* buffer.
22* This is useful when a stream buffer is used to pass data between
23* cores on a multicore processor. In that scenario, this callback
24* can be implemented to generate an interrupt in the other CPU core,
25* and the interrupt's service routine can then use the
26* xStreamBufferReceiveCompletedFromISR() API function to check, and if
27* necessary unblock, a task that was waiting to send the data. */
28}
29
30void vAFunction(void)
31{
32StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
33const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
34
35/* Create a stream buffer that can hold 100 bytes and uses the
36* functions defined using the sbSEND_COMPLETED() and
37* sbRECEIVE_COMPLETED() macros as send and receive completed
38* callback functions. The memory used to hold both the stream
39* buffer structure and the data in the stream buffer is
40* allocated dynamically. */
41xStreamBuffer = xStreamBufferCreate(xStreamBufferSizeBytes,
42xTriggerLevel);
43if (xStreamBuffer == NULL)
44{
45/* There was not enough heap memory space available to create the
46stream buffer. */
47}
48else
49{
50/* The stream buffer was created successfully and can now be used. */
51}
52
53/* Create a stream buffer that can hold 100 bytes and uses the
54* functions vSendCallbackFunction and vReceiveCallbackFunction
55* as send and receive completed callback functions. The memory
56* used to hold both the stream buffer structure and the data
57* in the stream buffer is allocated dynamically. */
58xStreamBufferWithCallback = xStreamBufferCreateWithCallback(
59xStreamBufferSizeBytes,
60xTriggerLevel,
61vSendCallbackFunction,
62vReceiveCallbackFunction);
63if (xStreamBufferWithCallback == NULL)
64{
65/* There was not enough heap memory space available to create the
66* stream buffer. */
67}
68else
69{
70/* The stream buffer was created successfully and can now be used. */
71}
72}

1StreamBufferHandle_t xStreamBufferCreateStatic(
 2size_t xBufferSizeBytes,
 3size_t xTriggerLevelBytes,
 4uint8_t *pucStreamBufferStorageArea,
 5StaticStreamBuffer_t *pxStaticStreamBuffer );
 6
 7StreamBufferHandle_t xStreamBufferCreateStaticWithCallback(
 8size_t xBufferSizeBytes,
 9size_t xTriggerLevelBytes,
10uint8_t *pucStreamBufferStorageArea,
11StaticStreamBuffer_t *pxStaticStreamBuffer,
12StreamBufferCallbackFunction_t pxSendCompletedCallback,
13StreamBufferCallbackFunction_t pxReceiveCompletedCallback );

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

1/* Used to dimension the array used to hold the streams. The available
 2* space will actually be one less than this, so 999. */
 3#define STORAGE_SIZE_BYTES 1000
 4
 5/* Defines the memory that will actually hold the streams within the
 6* stream buffer. */
 7static uint8_t ucStreamBufferStorage[STORAGE_SIZE_BYTES];
 8static uint8_t ucStreamBufferWithCallbackStorage[STORAGE_SIZE_BYTES];
 9
10/* The variable used to hold the stream buffer structure. */
11StaticStreamBuffer_t xStreamBufferStruct;
12StaticStreamBuffer_t xStreamBufferWithCallbackStruct;
13
14void vSendCallbackFunction(StreamBufferHandle_t xStreamBuffer,
15BaseType_t xIsInsideISR,
16BaseType_t *const pxHigherPriorityTaskWoken)
17{
18/* Insert code here which is invoked when a data write operation
19* to the stream buffer causes the number of bytes in the buffer
20* to be more then the trigger level.
21* This is useful when a stream buffer is used to pass data between
22* cores on a multicore processor. In that scenario, this callback
23* can be implemented to generate an interrupt in the other CPU core,
24* and the interrupt's service routine can then use the
25* xStreamBufferSendCompletedFromISR() API function to check, and if
26* necessary unblock, a task that was waiting for the data. */
27}
28
29void vReceiveCallbackFunction(StreamBufferHandle_t xStreamBuffer,
30BaseType_t xIsInsideISR,
31BaseType_t *const pxHigherPriorityTaskWoken)
32{
33/* Insert code here which is invoked when data is read from a stream
34* buffer.
35* This is useful when a stream buffer is used to pass data between
36* cores on a multicore processor. In that scenario, this callback
37* can be implemented to generate an interrupt in the other CPU core,
38* and the interrupt's service routine can then use the
39* xStreamBufferReceiveCompletedFromISR() API function to check, and if
40* necessary unblock, a task that was waiting to send the data. */
41}
42
43void MyFunction(void)
44{
45StreamBufferHandle_t xStreamBuffer, xStreamBufferWithCallback;
46const size_t xTriggerLevel = 1;
47
48/* Create a stream buffer that uses the functions defined
49* using the sbSEND_COMPLETED() and sbRECEIVE_COMPLETED()
50* macros as send and receive completed callback functions. */
51xStreamBuffer = xStreamBufferCreateStatic(sizeof(ucStreamBufferStorage),
52xTriggerLevel,
53ucStreamBufferStorage,
54&xStreamBufferStruct);
55
56/* Create a stream buffer that uses the functions
57* vSendCallbackFunction and vReceiveCallbackFunction as send
58* and receive completed callback functions. */
59xStreamBufferWithCallback = xStreamBufferCreateStaticWithCallback(
60sizeof(ucStreamBufferWithCallbackStorage),
61xTriggerLevel,
62ucStreamBufferWithCallbackStorage,
63&xStreamBufferWithCallbackStruct,
64vSendCallbackFunction,
65vReceiveCallbackFunction);
66
67/* As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
68* parameters were NULL, xStreamBuffer and xStreamBufferWithCallback
69* will not be NULL, and can be used to reference the created stream
70* buffers in other stream buffer API calls. */
71
72/* Other code that uses the stream buffers can go here. */

1size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
2const void *pvTxData,
3size_t xDataLengthBytes,
4TickType_t xTicksToWait );

1void vAFunction( StreamBufferHandle_t xStreamBuffer )
 2{
 3size_t xBytesSent;
 4uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
 5char *pcStringToSend = "String to send";
 6const TickType_t x100ms = pdMS_TO_TICKS( 100 );
 7
 8/* Send an array to the stream buffer, blocking for a maximum of 100ms to
 9wait for enough space to be available in the stream buffer. */
10xBytesSent = xStreamBufferSend( xStreamBuffer,
11( void * ) ucArrayToSend,
12sizeof( ucArrayToSend ),
13x100ms );
14
15if( xBytesSent != sizeof( ucArrayToSend ) )
16{
17/* The call to xStreamBufferSend() times out before there was enough
18space in the buffer for the data to be written, but it did
19successfully write xBytesSent bytes. */
20}
21
22/* Send the string to the stream buffer. Return immediately if there is not
23enough space in the buffer. */
24xBytesSent = xStreamBufferSend( xStreamBuffer,
25( void * ) pcStringToSend,
26strlen( pcStringToSend ), 0 );
27
28if( xBytesSent != strlen( pcStringToSend ) )
29{
30/* The entire string could not be added to the stream buffer because
31there was not enough free space in the buffer, but xBytesSent bytes
32were sent. Could try again to send the remaining bytes. */
33}
34}

1size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
2const void *pvTxData,
3size_t xDataLengthBytes,
4BaseType_t *pxHigherPriorityTaskWoken );

1/* A stream buffer that has already been created. */
 2StreamBufferHandle_t xStreamBuffer;
 3
 4void vAnInterruptServiceRoutine( void )
 5{
 6size_t xBytesSent;
 7char *pcStringToSend = "String to send";
 8BaseType_t xHigherPriorityTaskWoken = pdFALSE; /* Initialised to pdFALSE. */
 9
10/* Attempt to send the string to the stream buffer. */
11xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
12( void * ) pcStringToSend,
13strlen( pcStringToSend ),
14&xHigherPriorityTaskWoken );
15
16if( xBytesSent != strlen( pcStringToSend ) )
17{
18/* There was not enough free space in the stream buffer for the entire
19string to be written, ut xBytesSent bytes were written. */
20}
21
22/* If xHigherPriorityTaskWoken was set to pdTRUE inside
23xStreamBufferSendFromISR() then a task that has a priority above the
24priority of the currently executing task was unblocked and a context
25switch should be performed to ensure the ISR returns to the unblocked
26task. In most FreeRTOS ports this is done by simply passing
27xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
28variables value, and perform the context switch if necessary. Check the
29documentation for the port in use for port specific instructions. */
30taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
31}

1size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
2void *pvRxData,
3size_t xBufferLengthBytes,
4TickType_t xTicksToWait );

1void vAFunction( StreamBuffer_t xStreamBuffer )
 2{
 3uint8_t ucRxData[ 20 ];
 4size_t xReceivedBytes;
 5const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
 6
 7/* Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
 8Wait in the Blocked state (so not using any CPU processing time) for a
 9maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
10available. */
11xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
12( void * ) ucRxData,
13sizeof( ucRxData ),
14xBlockTime );
15
16if( xReceivedBytes > 0 )
17{
18/* A ucRxData contains another xRecievedBytes bytes of data, which can
19be processed here.... */
20}
21}

1size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
2void *pvRxData,
3size_t xBufferLengthBytes,
4BaseType_t *pxHigherPriorityTaskWoken );

1/* A stream buffer that has already been created. */
 2StreamBuffer_t xStreamBuffer;
 3
 4void vAnInterruptServiceRoutine( void )
 5{
 6uint8_t ucRxData[ 20 ];
 7size_t xReceivedBytes;
 8BaseType_t xHigherPriorityTaskWoken = pdFALSE; /* Initialised to pdFALSE. */
 9
10/* Receive the next stream from the stream buffer. */
11xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
12( void * ) ucRxData,
13sizeof( ucRxData ),
14&xHigherPriorityTaskWoken );
15
16if( xReceivedBytes > 0 )
17{
18/* ucRxData contains xReceivedBytes read from the stream buffer.
19Process the stream here.... */
20}
21
22/* If xHigherPriorityTaskWoken was set to pdTRUE inside
23xStreamBufferReceiveFromISR() then a task that has a priority above the
24priority of the currently executing task was unblocked and a context
25switch should be performed to ensure the ISR returns to the unblocked
26task. In most FreeRTOS ports this is done by simply passing
27xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
28variables value, and perform the context switch if necessary. Check the
29documentation for the port in use for port specific instructions. */
30taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
31}

1void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );

1size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );

1size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );

1BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
2size_t xTriggerLevel );

1BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );

1BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );