2 * FreeRTOS Kernel V10.3.0
\r
3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
\r
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
\r
6 * this software and associated documentation files (the "Software"), to deal in
\r
7 * the Software without restriction, including without limitation the rights to
\r
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
\r
9 * the Software, and to permit persons to whom the Software is furnished to do so,
\r
10 * subject to the following conditions:
\r
12 * The above copyright notice and this permission notice shall be included in all
\r
13 * copies or substantial portions of the Software.
\r
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\r
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
\r
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
\r
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
\r
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
\r
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\r
22 * http://www.FreeRTOS.org
\r
23 * http://aws.amazon.com/freertos
\r
25 * 1 tab == 4 spaces!
\r
29 * Stream buffers are used to send a continuous stream of data from one task or
\r
30 * interrupt to another. Their implementation is light weight, making them
\r
31 * particularly suited for interrupt to task and core to core communication
\r
34 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
35 * implementation (so also the message buffer implementation, as message buffers
\r
36 * are built on top of stream buffers) assumes there is only one task or
\r
37 * interrupt that will write to the buffer (the writer), and only one task or
\r
38 * interrupt that will read from the buffer (the reader). It is safe for the
\r
39 * writer and reader to be different tasks or interrupts, but, unlike other
\r
40 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
41 * multiple different readers. If there are to be multiple different writers
\r
42 * then the application writer must place each call to a writing API function
\r
43 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
44 * block time to 0. Likewise, if there are to be multiple different readers
\r
45 * then the application writer must place each call to a reading API function
\r
46 * (such as xStreamBufferReceive()) inside a critical section section and set the
\r
47 * receive block time to 0.
\r
51 #ifndef STREAM_BUFFER_H
\r
52 #define STREAM_BUFFER_H
\r
54 #ifndef INC_FREERTOS_H
\r
55 #error "include FreeRTOS.h must appear in source files before include stream_buffer.h"
\r
58 #if defined( __cplusplus )
\r
63 * Type by which stream buffers are referenced. For example, a call to
\r
64 * xStreamBufferCreate() returns an StreamBufferHandle_t variable that can
\r
65 * then be used as a parameter to xStreamBufferSend(), xStreamBufferReceive(),
\r
68 struct StreamBufferDef_t;
\r
69 typedef struct StreamBufferDef_t * StreamBufferHandle_t;
\r
76 StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
\r
79 * Creates a new stream buffer using dynamically allocated memory. See
\r
80 * xStreamBufferCreateStatic() for a version that uses statically allocated
\r
81 * memory (memory that is allocated at compile time).
\r
83 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
\r
84 * FreeRTOSConfig.h for xStreamBufferCreate() to be available.
\r
86 * @param xBufferSizeBytes The total number of bytes the stream buffer will be
\r
87 * able to hold at any one time.
\r
89 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
90 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
91 * moved out of the blocked state. For example, if a task is blocked on a read
\r
92 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
93 * unblocked when a single byte is written to the buffer or the task's block
\r
94 * time expires. As another example, if a task is blocked on a read of an empty
\r
95 * stream buffer that has a trigger level of 10 then the task will not be
\r
96 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
97 * block time expires. If a reading task's block time expires before the
\r
98 * trigger level is reached then the task will still receive however many bytes
\r
99 * are actually available. Setting a trigger level of 0 will result in a
\r
100 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
101 * that is greater than the buffer size.
\r
103 * @return If NULL is returned, then the stream buffer cannot be created
\r
104 * because there is insufficient heap memory available for FreeRTOS to allocate
\r
105 * the stream buffer data structures and storage area. A non-NULL value being
\r
106 * returned indicates that the stream buffer has been created successfully -
\r
107 * the returned value should be stored as the handle to the created stream
\r
113 void vAFunction( void )
\r
115 StreamBufferHandle_t xStreamBuffer;
\r
116 const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
\r
118 // Create a stream buffer that can hold 100 bytes. The memory used to hold
\r
119 // both the stream buffer structure and the data in the stream buffer is
\r
120 // allocated dynamically.
\r
121 xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
\r
123 if( xStreamBuffer == NULL )
\r
125 // There was not enough heap memory space available to create the
\r
130 // The stream buffer was created successfully and can now be used.
\r
134 * \defgroup xStreamBufferCreate xStreamBufferCreate
\r
135 * \ingroup StreamBufferManagement
\r
137 #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )
\r
143 StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
\r
144 size_t xTriggerLevelBytes,
\r
145 uint8_t *pucStreamBufferStorageArea,
\r
146 StaticStreamBuffer_t *pxStaticStreamBuffer );
\r
148 * Creates a new stream buffer using statically allocated memory. See
\r
149 * xStreamBufferCreate() for a version that uses dynamically allocated memory.
\r
151 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
\r
152 * xStreamBufferCreateStatic() to be available.
\r
154 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
\r
155 * pucStreamBufferStorageArea parameter.
\r
157 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
158 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
159 * moved out of the blocked state. For example, if a task is blocked on a read
\r
160 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
161 * unblocked when a single byte is written to the buffer or the task's block
\r
162 * time expires. As another example, if a task is blocked on a read of an empty
\r
163 * stream buffer that has a trigger level of 10 then the task will not be
\r
164 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
165 * block time expires. If a reading task's block time expires before the
\r
166 * trigger level is reached then the task will still receive however many bytes
\r
167 * are actually available. Setting a trigger level of 0 will result in a
\r
168 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
169 * that is greater than the buffer size.
\r
171 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at
\r
172 * least xBufferSizeBytes + 1 big. This is the array to which streams are
\r
173 * copied when they are written to the stream buffer.
\r
175 * @param pxStaticStreamBuffer Must point to a variable of type
\r
176 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data
\r
179 * @return If the stream buffer is created successfully then a handle to the
\r
180 * created stream buffer is returned. If either pucStreamBufferStorageArea or
\r
181 * pxStaticstreamBuffer are NULL then NULL is returned.
\r
186 // Used to dimension the array used to hold the streams. The available space
\r
187 // will actually be one less than this, so 999.
\r
188 #define STORAGE_SIZE_BYTES 1000
\r
190 // Defines the memory that will actually hold the streams within the stream
\r
192 static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
\r
194 // The variable used to hold the stream buffer structure.
\r
195 StaticStreamBuffer_t xStreamBufferStruct;
\r
197 void MyFunction( void )
\r
199 StreamBufferHandle_t xStreamBuffer;
\r
200 const size_t xTriggerLevel = 1;
\r
202 xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ),
\r
205 &xStreamBufferStruct );
\r
207 // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
\r
208 // parameters were NULL, xStreamBuffer will not be NULL, and can be used to
\r
209 // reference the created stream buffer in other stream buffer API calls.
\r
211 // Other code that uses the stream buffer can go here.
\r
215 * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic
\r
216 * \ingroup StreamBufferManagement
\r
218 #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )
\r
224 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
225 const void *pvTxData,
\r
226 size_t xDataLengthBytes,
\r
227 TickType_t xTicksToWait );
\r
230 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
\r
232 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
233 * implementation (so also the message buffer implementation, as message buffers
\r
234 * are built on top of stream buffers) assumes there is only one task or
\r
235 * interrupt that will write to the buffer (the writer), and only one task or
\r
236 * interrupt that will read from the buffer (the reader). It is safe for the
\r
237 * writer and reader to be different tasks or interrupts, but, unlike other
\r
238 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
239 * multiple different readers. If there are to be multiple different writers
\r
240 * then the application writer must place each call to a writing API function
\r
241 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
242 * block time to 0. Likewise, if there are to be multiple different readers
\r
243 * then the application writer must place each call to a reading API function
\r
244 * (such as xStreamBufferReceive()) inside a critical section and set the receive
\r
247 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
248 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
249 * service routine (ISR).
\r
251 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
254 * @param pvTxData A pointer to the buffer that holds the bytes to be copied
\r
255 * into the stream buffer.
\r
257 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
258 * into the stream buffer.
\r
260 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
261 * Blocked state to wait for enough space to become available in the stream
\r
262 * buffer, should the stream buffer contain too little space to hold the
\r
263 * another xDataLengthBytes bytes. The block time is specified in tick periods,
\r
264 * so the absolute time it represents is dependent on the tick frequency. The
\r
265 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
\r
266 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
\r
267 * cause the task to wait indefinitely (without timing out), provided
\r
268 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out
\r
269 * before it can write all xDataLengthBytes into the buffer it will still write
\r
270 * as many bytes as possible. A task does not use any CPU time when it is in
\r
271 * the blocked state.
\r
273 * @return The number of bytes written to the stream buffer. If a task times
\r
274 * out before it can write all xDataLengthBytes into the buffer it will still
\r
275 * write as many bytes as possible.
\r
279 void vAFunction( StreamBufferHandle_t xStreamBuffer )
\r
282 uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
\r
283 char *pcStringToSend = "String to send";
\r
284 const TickType_t x100ms = pdMS_TO_TICKS( 100 );
\r
286 // Send an array to the stream buffer, blocking for a maximum of 100ms to
\r
287 // wait for enough space to be available in the stream buffer.
\r
288 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
\r
290 if( xBytesSent != sizeof( ucArrayToSend ) )
\r
292 // The call to xStreamBufferSend() times out before there was enough
\r
293 // space in the buffer for the data to be written, but it did
\r
294 // successfully write xBytesSent bytes.
\r
297 // Send the string to the stream buffer. Return immediately if there is not
\r
298 // enough space in the buffer.
\r
299 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
\r
301 if( xBytesSent != strlen( pcStringToSend ) )
\r
303 // The entire string could not be added to the stream buffer because
\r
304 // there was not enough free space in the buffer, but xBytesSent bytes
\r
305 // were sent. Could try again to send the remaining bytes.
\r
309 * \defgroup xStreamBufferSend xStreamBufferSend
\r
310 * \ingroup StreamBufferManagement
\r
312 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
313 const void *pvTxData,
\r
314 size_t xDataLengthBytes,
\r
315 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
321 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
322 const void *pvTxData,
\r
323 size_t xDataLengthBytes,
\r
324 BaseType_t *pxHigherPriorityTaskWoken );
\r
327 * Interrupt safe version of the API function that sends a stream of bytes to
\r
328 * the stream buffer.
\r
330 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
331 * implementation (so also the message buffer implementation, as message buffers
\r
332 * are built on top of stream buffers) assumes there is only one task or
\r
333 * interrupt that will write to the buffer (the writer), and only one task or
\r
334 * interrupt that will read from the buffer (the reader). It is safe for the
\r
335 * writer and reader to be different tasks or interrupts, but, unlike other
\r
336 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
337 * multiple different readers. If there are to be multiple different writers
\r
338 * then the application writer must place each call to a writing API function
\r
339 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
340 * block time to 0. Likewise, if there are to be multiple different readers
\r
341 * then the application writer must place each call to a reading API function
\r
342 * (such as xStreamBufferReceive()) inside a critical section and set the receive
\r
345 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
346 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
347 * service routine (ISR).
\r
349 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
352 * @param pvTxData A pointer to the data that is to be copied into the stream
\r
355 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
356 * into the stream buffer.
\r
358 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
359 * have a task blocked on it waiting for data. Calling
\r
360 * xStreamBufferSendFromISR() can make data available, and so cause a task that
\r
361 * was waiting for data to leave the Blocked state. If calling
\r
362 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
\r
363 * unblocked task has a priority higher than the currently executing task (the
\r
364 * task that was interrupted), then, internally, xStreamBufferSendFromISR()
\r
365 * will set *pxHigherPriorityTaskWoken to pdTRUE. If
\r
366 * xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a
\r
367 * context switch should be performed before the interrupt is exited. This will
\r
368 * ensure that the interrupt returns directly to the highest priority Ready
\r
369 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
\r
370 * is passed into the function. See the example code below for an example.
\r
372 * @return The number of bytes actually written to the stream buffer, which will
\r
373 * be less than xDataLengthBytes if the stream buffer didn't have enough free
\r
374 * space for all the bytes to be written.
\r
378 // A stream buffer that has already been created.
\r
379 StreamBufferHandle_t xStreamBuffer;
\r
381 void vAnInterruptServiceRoutine( void )
\r
384 char *pcStringToSend = "String to send";
\r
385 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
387 // Attempt to send the string to the stream buffer.
\r
388 xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
\r
389 ( void * ) pcStringToSend,
\r
390 strlen( pcStringToSend ),
\r
391 &xHigherPriorityTaskWoken );
\r
393 if( xBytesSent != strlen( pcStringToSend ) )
\r
395 // There was not enough free space in the stream buffer for the entire
\r
396 // string to be written, ut xBytesSent bytes were written.
\r
399 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
400 // xStreamBufferSendFromISR() then a task that has a priority above the
\r
401 // priority of the currently executing task was unblocked and a context
\r
402 // switch should be performed to ensure the ISR returns to the unblocked
\r
403 // task. In most FreeRTOS ports this is done by simply passing
\r
404 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
405 // variables value, and perform the context switch if necessary. Check the
\r
406 // documentation for the port in use for port specific instructions.
\r
407 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
410 * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR
\r
411 * \ingroup StreamBufferManagement
\r
413 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
414 const void *pvTxData,
\r
415 size_t xDataLengthBytes,
\r
416 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
422 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
424 size_t xBufferLengthBytes,
\r
425 TickType_t xTicksToWait );
\r
428 * Receives bytes from a stream buffer.
\r
430 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
431 * implementation (so also the message buffer implementation, as message buffers
\r
432 * are built on top of stream buffers) assumes there is only one task or
\r
433 * interrupt that will write to the buffer (the writer), and only one task or
\r
434 * interrupt that will read from the buffer (the reader). It is safe for the
\r
435 * writer and reader to be different tasks or interrupts, but, unlike other
\r
436 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
437 * multiple different readers. If there are to be multiple different writers
\r
438 * then the application writer must place each call to a writing API function
\r
439 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
440 * block time to 0. Likewise, if there are to be multiple different readers
\r
441 * then the application writer must place each call to a reading API function
\r
442 * (such as xStreamBufferReceive()) inside a critical section and set the receive
\r
445 * Use xStreamBufferReceive() to read from a stream buffer from a task. Use
\r
446 * xStreamBufferReceiveFromISR() to read from a stream buffer from an
\r
447 * interrupt service routine (ISR).
\r
449 * @param xStreamBuffer The handle of the stream buffer from which bytes are to
\r
452 * @param pvRxData A pointer to the buffer into which the received bytes will be
\r
455 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
456 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
457 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
458 * maximum set by xBufferLengthBytes.
\r
460 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
461 * Blocked state to wait for data to become available if the stream buffer is
\r
462 * empty. xStreamBufferReceive() will return immediately if xTicksToWait is
\r
463 * zero. The block time is specified in tick periods, so the absolute time it
\r
464 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
\r
465 * be used to convert a time specified in milliseconds into a time specified in
\r
466 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
\r
467 * indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1
\r
468 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
\r
471 * @return The number of bytes actually read from the stream buffer, which will
\r
472 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
\r
473 * out before xBufferLengthBytes were available.
\r
477 void vAFunction( StreamBuffer_t xStreamBuffer )
\r
479 uint8_t ucRxData[ 20 ];
\r
480 size_t xReceivedBytes;
\r
481 const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
\r
483 // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
\r
484 // Wait in the Blocked state (so not using any CPU processing time) for a
\r
485 // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
\r
487 xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
\r
488 ( void * ) ucRxData,
\r
489 sizeof( ucRxData ),
\r
492 if( xReceivedBytes > 0 )
\r
494 // A ucRxData contains another xRecievedBytes bytes of data, which can
\r
495 // be processed here....
\r
499 * \defgroup xStreamBufferReceive xStreamBufferReceive
\r
500 * \ingroup StreamBufferManagement
\r
502 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
504 size_t xBufferLengthBytes,
\r
505 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
511 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
513 size_t xBufferLengthBytes,
\r
514 BaseType_t *pxHigherPriorityTaskWoken );
\r
517 * An interrupt safe version of the API function that receives bytes from a
\r
520 * Use xStreamBufferReceive() to read bytes from a stream buffer from a task.
\r
521 * Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an
\r
522 * interrupt service routine (ISR).
\r
524 * @param xStreamBuffer The handle of the stream buffer from which a stream
\r
525 * is being received.
\r
527 * @param pvRxData A pointer to the buffer into which the received bytes are
\r
530 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
531 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
532 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
533 * maximum set by xBufferLengthBytes.
\r
535 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
536 * have a task blocked on it waiting for space to become available. Calling
\r
537 * xStreamBufferReceiveFromISR() can make space available, and so cause a task
\r
538 * that is waiting for space to leave the Blocked state. If calling
\r
539 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
\r
540 * the unblocked task has a priority higher than the currently executing task
\r
541 * (the task that was interrupted), then, internally,
\r
542 * xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
\r
543 * If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a
\r
544 * context switch should be performed before the interrupt is exited. That will
\r
545 * ensure the interrupt returns directly to the highest priority Ready state
\r
546 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
\r
547 * passed into the function. See the code example below for an example.
\r
549 * @return The number of bytes read from the stream buffer, if any.
\r
553 // A stream buffer that has already been created.
\r
554 StreamBuffer_t xStreamBuffer;
\r
556 void vAnInterruptServiceRoutine( void )
\r
558 uint8_t ucRxData[ 20 ];
\r
559 size_t xReceivedBytes;
\r
560 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
562 // Receive the next stream from the stream buffer.
\r
563 xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
\r
564 ( void * ) ucRxData,
\r
565 sizeof( ucRxData ),
\r
566 &xHigherPriorityTaskWoken );
\r
568 if( xReceivedBytes > 0 )
\r
570 // ucRxData contains xReceivedBytes read from the stream buffer.
\r
571 // Process the stream here....
\r
574 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
575 // xStreamBufferReceiveFromISR() then a task that has a priority above the
\r
576 // priority of the currently executing task was unblocked and a context
\r
577 // switch should be performed to ensure the ISR returns to the unblocked
\r
578 // task. In most FreeRTOS ports this is done by simply passing
\r
579 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
580 // variables value, and perform the context switch if necessary. Check the
\r
581 // documentation for the port in use for port specific instructions.
\r
582 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
585 * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR
\r
586 * \ingroup StreamBufferManagement
\r
588 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
590 size_t xBufferLengthBytes,
\r
591 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
597 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
\r
600 * Deletes a stream buffer that was previously created using a call to
\r
601 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
\r
602 * buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
\r
603 * then the allocated memory is freed.
\r
605 * A stream buffer handle must not be used after the stream buffer has been
\r
608 * @param xStreamBuffer The handle of the stream buffer to be deleted.
\r
610 * \defgroup vStreamBufferDelete vStreamBufferDelete
\r
611 * \ingroup StreamBufferManagement
\r
613 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
619 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
\r
622 * Queries a stream buffer to see if it is full. A stream buffer is full if it
\r
623 * does not have any free space, and therefore cannot accept any more data.
\r
625 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
627 * @return If the stream buffer is full then pdTRUE is returned. Otherwise
\r
628 * pdFALSE is returned.
\r
630 * \defgroup xStreamBufferIsFull xStreamBufferIsFull
\r
631 * \ingroup StreamBufferManagement
\r
633 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
639 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
\r
642 * Queries a stream buffer to see if it is empty. A stream buffer is empty if
\r
643 * it does not contain any data.
\r
645 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
647 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise
\r
648 * pdFALSE is returned.
\r
650 * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty
\r
651 * \ingroup StreamBufferManagement
\r
653 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
659 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
\r
662 * Resets a stream buffer to its initial, empty, state. Any data that was in
\r
663 * the stream buffer is discarded. A stream buffer can only be reset if there
\r
664 * are no tasks blocked waiting to either send to or receive from the stream
\r
667 * @param xStreamBuffer The handle of the stream buffer being reset.
\r
669 * @return If the stream buffer is reset then pdPASS is returned. If there was
\r
670 * a task blocked waiting to send to or read from the stream buffer then the
\r
671 * stream buffer is not reset and pdFAIL is returned.
\r
673 * \defgroup xStreamBufferReset xStreamBufferReset
\r
674 * \ingroup StreamBufferManagement
\r
676 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
682 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
685 * Queries a stream buffer to see how much free space it contains, which is
\r
686 * equal to the amount of data that can be sent to the stream buffer before it
\r
689 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
691 * @return The number of bytes that can be written to the stream buffer before
\r
692 * the stream buffer would be full.
\r
694 * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable
\r
695 * \ingroup StreamBufferManagement
\r
697 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
703 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
706 * Queries a stream buffer to see how much data it contains, which is equal to
\r
707 * the number of bytes that can be read from the stream buffer before the stream
\r
708 * buffer would be empty.
\r
710 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
712 * @return The number of bytes that can be read from the stream buffer before
\r
713 * the stream buffer would be empty.
\r
715 * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable
\r
716 * \ingroup StreamBufferManagement
\r
718 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
724 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
\r
727 * A stream buffer's trigger level is the number of bytes that must be in the
\r
728 * stream buffer before a task that is blocked on the stream buffer to
\r
729 * wait for data is moved out of the blocked state. For example, if a task is
\r
730 * blocked on a read of an empty stream buffer that has a trigger level of 1
\r
731 * then the task will be unblocked when a single byte is written to the buffer
\r
732 * or the task's block time expires. As another example, if a task is blocked
\r
733 * on a read of an empty stream buffer that has a trigger level of 10 then the
\r
734 * task will not be unblocked until the stream buffer contains at least 10 bytes
\r
735 * or the task's block time expires. If a reading task's block time expires
\r
736 * before the trigger level is reached then the task will still receive however
\r
737 * many bytes are actually available. Setting a trigger level of 0 will result
\r
738 * in a trigger level of 1 being used. It is not valid to specify a trigger
\r
739 * level that is greater than the buffer size.
\r
741 * A trigger level is set when the stream buffer is created, and can be modified
\r
742 * using xStreamBufferSetTriggerLevel().
\r
744 * @param xStreamBuffer The handle of the stream buffer being updated.
\r
746 * @param xTriggerLevel The new trigger level for the stream buffer.
\r
748 * @return If xTriggerLevel was less than or equal to the stream buffer's length
\r
749 * then the trigger level will be updated and pdTRUE is returned. Otherwise
\r
750 * pdFALSE is returned.
\r
752 * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel
\r
753 * \ingroup StreamBufferManagement
\r
755 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
\r
761 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
764 * For advanced users only.
\r
766 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
767 * data is sent to a message buffer or stream buffer. If there was a task that
\r
768 * was blocked on the message or stream buffer waiting for data to arrive then
\r
769 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
\r
770 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
\r
771 * thing. It is provided to enable application writers to implement their own
\r
772 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
\r
774 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
775 * additional information.
\r
777 * @param xStreamBuffer The handle of the stream buffer to which data was
\r
780 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
781 * initialised to pdFALSE before it is passed into
\r
782 * xStreamBufferSendCompletedFromISR(). If calling
\r
783 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
\r
784 * and the task has a priority above the priority of the currently running task,
\r
785 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
786 * context switch should be performed before exiting the ISR.
\r
788 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
789 * Otherwise pdFALSE is returned.
\r
791 * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR
\r
792 * \ingroup StreamBufferManagement
\r
794 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
800 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
803 * For advanced users only.
\r
805 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
806 * data is read out of a message buffer or stream buffer. If there was a task
\r
807 * that was blocked on the message or stream buffer waiting for data to arrive
\r
808 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
\r
809 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
\r
810 * does the same thing. It is provided to enable application writers to
\r
811 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
\r
814 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
815 * additional information.
\r
817 * @param xStreamBuffer The handle of the stream buffer from which data was
\r
820 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
821 * initialised to pdFALSE before it is passed into
\r
822 * xStreamBufferReceiveCompletedFromISR(). If calling
\r
823 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
\r
824 * and the task has a priority above the priority of the currently running task,
\r
825 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
826 * context switch should be performed before exiting the ISR.
\r
828 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
829 * Otherwise pdFALSE is returned.
\r
831 * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR
\r
832 * \ingroup StreamBufferManagement
\r
834 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
836 /* Functions below here are not part of the public API. */
\r
837 StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
\r
838 size_t xTriggerLevelBytes,
\r
839 BaseType_t xIsMessageBuffer ) PRIVILEGED_FUNCTION;
\r
841 StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
\r
842 size_t xTriggerLevelBytes,
\r
843 BaseType_t xIsMessageBuffer,
\r
844 uint8_t * const pucStreamBufferStorageArea,
\r
845 StaticStreamBuffer_t * const pxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
\r
847 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
849 #if( configUSE_TRACE_FACILITY == 1 )
\r
850 void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer, UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION;
\r
851 UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
852 uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
855 #if defined( __cplusplus )
\r
859 #endif /* !defined( STREAM_BUFFER_H ) */
\r