2 * FreeRTOS Kernel V10.1.0
\r
3 * Copyright (C) 2018 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 xStreamBufferRead()) 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 #if defined( __cplusplus )
\r
59 * Type by which stream buffers are referenced. For example, a call to
\r
60 * xStreamBufferCreate() returns an StreamBufferHandle_t variable that can
\r
61 * then be used as a parameter to xStreamBufferSend(), xStreamBufferReceive(),
\r
64 struct StreamBufferDef_t;
\r
65 typedef struct StreamBufferDef_t * StreamBufferHandle_t;
\r
72 StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
\r
75 * Creates a new stream buffer using dynamically allocated memory. See
\r
76 * xStreamBufferCreateStatic() for a version that uses statically allocated
\r
77 * memory (memory that is allocated at compile time).
\r
79 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
\r
80 * FreeRTOSConfig.h for xStreamBufferCreate() to be available.
\r
82 * @param xBufferSizeBytes The total number of bytes the stream buffer will be
\r
83 * able to hold at any one time.
\r
85 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
86 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
87 * moved out of the blocked state. For example, if a task is blocked on a read
\r
88 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
89 * unblocked when a single byte is written to the buffer or the task's block
\r
90 * time expires. As another example, if a task is blocked on a read of an empty
\r
91 * stream buffer that has a trigger level of 10 then the task will not be
\r
92 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
93 * block time expires. If a reading task's block time expires before the
\r
94 * trigger level is reached then the task will still receive however many bytes
\r
95 * are actually available. Setting a trigger level of 0 will result in a
\r
96 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
97 * that is greater than the buffer size.
\r
99 * @return If NULL is returned, then the stream buffer cannot be created
\r
100 * because there is insufficient heap memory available for FreeRTOS to allocate
\r
101 * the stream buffer data structures and storage area. A non-NULL value being
\r
102 * returned indicates that the stream buffer has been created successfully -
\r
103 * the returned value should be stored as the handle to the created stream
\r
109 void vAFunction( void )
\r
111 StreamBufferHandle_t xStreamBuffer;
\r
112 const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
\r
114 // Create a stream buffer that can hold 100 bytes. The memory used to hold
\r
115 // both the stream buffer structure and the data in the stream buffer is
\r
116 // allocated dynamically.
\r
117 xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
\r
119 if( xStreamBuffer == NULL )
\r
121 // There was not enough heap memory space available to create the
\r
126 // The stream buffer was created successfully and can now be used.
\r
130 * \defgroup xStreamBufferCreate xStreamBufferCreate
\r
131 * \ingroup StreamBufferManagement
\r
133 #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )
\r
139 StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
\r
140 size_t xTriggerLevelBytes,
\r
141 uint8_t *pucStreamBufferStorageArea,
\r
142 StaticStreamBuffer_t *pxStaticStreamBuffer );
\r
144 * Creates a new stream buffer using statically allocated memory. See
\r
145 * xStreamBufferCreate() for a version that uses dynamically allocated memory.
\r
147 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
\r
148 * xStreamBufferCreateStatic() to be available.
\r
150 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
\r
151 * pucStreamBufferStorageArea parameter.
\r
153 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
154 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
155 * moved out of the blocked state. For example, if a task is blocked on a read
\r
156 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
157 * unblocked when a single byte is written to the buffer or the task's block
\r
158 * time expires. As another example, if a task is blocked on a read of an empty
\r
159 * stream buffer that has a trigger level of 10 then the task will not be
\r
160 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
161 * block time expires. If a reading task's block time expires before the
\r
162 * trigger level is reached then the task will still receive however many bytes
\r
163 * are actually available. Setting a trigger level of 0 will result in a
\r
164 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
165 * that is greater than the buffer size.
\r
167 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at
\r
168 * least xBufferSizeBytes + 1 big. This is the array to which streams are
\r
169 * copied when they are written to the stream buffer.
\r
171 * @param pxStaticStreamBuffer Must point to a variable of type
\r
172 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data
\r
175 * @return If the stream buffer is created successfully then a handle to the
\r
176 * created stream buffer is returned. If either pucStreamBufferStorageArea or
\r
177 * pxStaticstreamBuffer are NULL then NULL is returned.
\r
182 // Used to dimension the array used to hold the streams. The available space
\r
183 // will actually be one less than this, so 999.
\r
184 #define STORAGE_SIZE_BYTES 1000
\r
186 // Defines the memory that will actually hold the streams within the stream
\r
188 static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
\r
190 // The variable used to hold the stream buffer structure.
\r
191 StaticStreamBuffer_t xStreamBufferStruct;
\r
193 void MyFunction( void )
\r
195 StreamBufferHandle_t xStreamBuffer;
\r
196 const size_t xTriggerLevel = 1;
\r
198 xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ),
\r
201 &xStreamBufferStruct );
\r
203 // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
\r
204 // parameters were NULL, xStreamBuffer will not be NULL, and can be used to
\r
205 // reference the created stream buffer in other stream buffer API calls.
\r
207 // Other code that uses the stream buffer can go here.
\r
211 * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic
\r
212 * \ingroup StreamBufferManagement
\r
214 #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )
\r
220 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
221 const void *pvTxData,
\r
222 size_t xDataLengthBytes,
\r
223 TickType_t xTicksToWait );
\r
226 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
\r
228 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
229 * implementation (so also the message buffer implementation, as message buffers
\r
230 * are built on top of stream buffers) assumes there is only one task or
\r
231 * interrupt that will write to the buffer (the writer), and only one task or
\r
232 * interrupt that will read from the buffer (the reader). It is safe for the
\r
233 * writer and reader to be different tasks or interrupts, but, unlike other
\r
234 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
235 * multiple different readers. If there are to be multiple different writers
\r
236 * then the application writer must place each call to a writing API function
\r
237 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
238 * block time to 0. Likewise, if there are to be multiple different readers
\r
239 * then the application writer must place each call to a reading API function
\r
240 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
243 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
244 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
245 * service routine (ISR).
\r
247 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
250 * @param pvTxData A pointer to the buffer that holds the bytes to be copied
\r
251 * into the stream buffer.
\r
253 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
254 * into the stream buffer.
\r
256 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
257 * Blocked state to wait for enough space to become available in the stream
\r
258 * buffer, should the stream buffer contain too little space to hold the
\r
259 * another xDataLengthBytes bytes. The block time is specified in tick periods,
\r
260 * so the absolute time it represents is dependent on the tick frequency. The
\r
261 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
\r
262 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
\r
263 * cause the task to wait indefinitely (without timing out), provided
\r
264 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out
\r
265 * before it can write all xDataLengthBytes into the buffer it will still write
\r
266 * as many bytes as possible. A task does not use any CPU time when it is in
\r
267 * the blocked state.
\r
269 * @return The number of bytes written to the stream buffer. If a task times
\r
270 * out before it can write all xDataLengthBytes into the buffer it will still
\r
271 * write as many bytes as possible.
\r
275 void vAFunction( StreamBufferHandle_t xStreamBuffer )
\r
278 uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
\r
279 char *pcStringToSend = "String to send";
\r
280 const TickType_t x100ms = pdMS_TO_TICKS( 100 );
\r
282 // Send an array to the stream buffer, blocking for a maximum of 100ms to
\r
283 // wait for enough space to be available in the stream buffer.
\r
284 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
\r
286 if( xBytesSent != sizeof( ucArrayToSend ) )
\r
288 // The call to xStreamBufferSend() times out before there was enough
\r
289 // space in the buffer for the data to be written, but it did
\r
290 // successfully write xBytesSent bytes.
\r
293 // Send the string to the stream buffer. Return immediately if there is not
\r
294 // enough space in the buffer.
\r
295 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
\r
297 if( xBytesSent != strlen( pcStringToSend ) )
\r
299 // The entire string could not be added to the stream buffer because
\r
300 // there was not enough free space in the buffer, but xBytesSent bytes
\r
301 // were sent. Could try again to send the remaining bytes.
\r
305 * \defgroup xStreamBufferSend xStreamBufferSend
\r
306 * \ingroup StreamBufferManagement
\r
308 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
309 const void *pvTxData,
\r
310 size_t xDataLengthBytes,
\r
311 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
317 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
318 const void *pvTxData,
\r
319 size_t xDataLengthBytes,
\r
320 BaseType_t *pxHigherPriorityTaskWoken );
\r
323 * Interrupt safe version of the API function that sends a stream of bytes to
\r
324 * the stream buffer.
\r
326 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
327 * implementation (so also the message buffer implementation, as message buffers
\r
328 * are built on top of stream buffers) assumes there is only one task or
\r
329 * interrupt that will write to the buffer (the writer), and only one task or
\r
330 * interrupt that will read from the buffer (the reader). It is safe for the
\r
331 * writer and reader to be different tasks or interrupts, but, unlike other
\r
332 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
333 * multiple different readers. If there are to be multiple different writers
\r
334 * then the application writer must place each call to a writing API function
\r
335 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
336 * block time to 0. Likewise, if there are to be multiple different readers
\r
337 * then the application writer must place each call to a reading API function
\r
338 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
341 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
342 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
343 * service routine (ISR).
\r
345 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
348 * @param pvTxData A pointer to the data that is to be copied into the stream
\r
351 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
352 * into the stream buffer.
\r
354 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
355 * have a task blocked on it waiting for data. Calling
\r
356 * xStreamBufferSendFromISR() can make data available, and so cause a task that
\r
357 * was waiting for data to leave the Blocked state. If calling
\r
358 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
\r
359 * unblocked task has a priority higher than the currently executing task (the
\r
360 * task that was interrupted), then, internally, xStreamBufferSendFromISR()
\r
361 * will set *pxHigherPriorityTaskWoken to pdTRUE. If
\r
362 * xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a
\r
363 * context switch should be performed before the interrupt is exited. This will
\r
364 * ensure that the interrupt returns directly to the highest priority Ready
\r
365 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
\r
366 * is passed into the function. See the example code below for an example.
\r
368 * @return The number of bytes actually written to the stream buffer, which will
\r
369 * be less than xDataLengthBytes if the stream buffer didn't have enough free
\r
370 * space for all the bytes to be written.
\r
374 // A stream buffer that has already been created.
\r
375 StreamBufferHandle_t xStreamBuffer;
\r
377 void vAnInterruptServiceRoutine( void )
\r
380 char *pcStringToSend = "String to send";
\r
381 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
383 // Attempt to send the string to the stream buffer.
\r
384 xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
\r
385 ( void * ) pcStringToSend,
\r
386 strlen( pcStringToSend ),
\r
387 &xHigherPriorityTaskWoken );
\r
389 if( xBytesSent != strlen( pcStringToSend ) )
\r
391 // There was not enough free space in the stream buffer for the entire
\r
392 // string to be written, ut xBytesSent bytes were written.
\r
395 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
396 // xStreamBufferSendFromISR() then a task that has a priority above the
\r
397 // priority of the currently executing task was unblocked and a context
\r
398 // switch should be performed to ensure the ISR returns to the unblocked
\r
399 // task. In most FreeRTOS ports this is done by simply passing
\r
400 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
401 // variables value, and perform the context switch if necessary. Check the
\r
402 // documentation for the port in use for port specific instructions.
\r
403 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
406 * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR
\r
407 * \ingroup StreamBufferManagement
\r
409 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
410 const void *pvTxData,
\r
411 size_t xDataLengthBytes,
\r
412 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
418 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
420 size_t xBufferLengthBytes,
\r
421 TickType_t xTicksToWait );
\r
424 * Receives bytes from a stream buffer.
\r
426 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
427 * implementation (so also the message buffer implementation, as message buffers
\r
428 * are built on top of stream buffers) assumes there is only one task or
\r
429 * interrupt that will write to the buffer (the writer), and only one task or
\r
430 * interrupt that will read from the buffer (the reader). It is safe for the
\r
431 * writer and reader to be different tasks or interrupts, but, unlike other
\r
432 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
433 * multiple different readers. If there are to be multiple different writers
\r
434 * then the application writer must place each call to a writing API function
\r
435 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
436 * block time to 0. Likewise, if there are to be multiple different readers
\r
437 * then the application writer must place each call to a reading API function
\r
438 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
441 * Use xStreamBufferReceive() to read from a stream buffer from a task. Use
\r
442 * xStreamBufferReceiveFromISR() to read from a stream buffer from an
\r
443 * interrupt service routine (ISR).
\r
445 * @param xStreamBuffer The handle of the stream buffer from which bytes are to
\r
448 * @param pvRxData A pointer to the buffer into which the received bytes will be
\r
451 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
452 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
453 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
454 * maximum set by xBufferLengthBytes.
\r
456 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
457 * Blocked state to wait for data to become available if the stream buffer is
\r
458 * empty. xStreamBufferReceive() will return immediately if xTicksToWait is
\r
459 * zero. The block time is specified in tick periods, so the absolute time it
\r
460 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
\r
461 * be used to convert a time specified in milliseconds into a time specified in
\r
462 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
\r
463 * indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1
\r
464 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
\r
467 * @return The number of bytes actually read from the stream buffer, which will
\r
468 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
\r
469 * out before xBufferLengthBytes were available.
\r
473 void vAFunction( StreamBuffer_t xStreamBuffer )
\r
475 uint8_t ucRxData[ 20 ];
\r
476 size_t xReceivedBytes;
\r
477 const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
\r
479 // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
\r
480 // Wait in the Blocked state (so not using any CPU processing time) for a
\r
481 // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
\r
483 xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
\r
484 ( void * ) ucRxData,
\r
485 sizeof( ucRxData ),
\r
488 if( xReceivedBytes > 0 )
\r
490 // A ucRxData contains another xRecievedBytes bytes of data, which can
\r
491 // be processed here....
\r
495 * \defgroup xStreamBufferReceive xStreamBufferReceive
\r
496 * \ingroup StreamBufferManagement
\r
498 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
500 size_t xBufferLengthBytes,
\r
501 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
507 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
509 size_t xBufferLengthBytes,
\r
510 BaseType_t *pxHigherPriorityTaskWoken );
\r
513 * An interrupt safe version of the API function that receives bytes from a
\r
516 * Use xStreamBufferReceive() to read bytes from a stream buffer from a task.
\r
517 * Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an
\r
518 * interrupt service routine (ISR).
\r
520 * @param xStreamBuffer The handle of the stream buffer from which a stream
\r
521 * is being received.
\r
523 * @param pvRxData A pointer to the buffer into which the received bytes are
\r
526 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
527 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
528 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
529 * maximum set by xBufferLengthBytes.
\r
531 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
532 * have a task blocked on it waiting for space to become available. Calling
\r
533 * xStreamBufferReceiveFromISR() can make space available, and so cause a task
\r
534 * that is waiting for space to leave the Blocked state. If calling
\r
535 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
\r
536 * the unblocked task has a priority higher than the currently executing task
\r
537 * (the task that was interrupted), then, internally,
\r
538 * xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
\r
539 * If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a
\r
540 * context switch should be performed before the interrupt is exited. That will
\r
541 * ensure the interrupt returns directly to the highest priority Ready state
\r
542 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
\r
543 * passed into the function. See the code example below for an example.
\r
545 * @return The number of bytes read from the stream buffer, if any.
\r
549 // A stream buffer that has already been created.
\r
550 StreamBuffer_t xStreamBuffer;
\r
552 void vAnInterruptServiceRoutine( void )
\r
554 uint8_t ucRxData[ 20 ];
\r
555 size_t xReceivedBytes;
\r
556 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
558 // Receive the next stream from the stream buffer.
\r
559 xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
\r
560 ( void * ) ucRxData,
\r
561 sizeof( ucRxData ),
\r
562 &xHigherPriorityTaskWoken );
\r
564 if( xReceivedBytes > 0 )
\r
566 // ucRxData contains xReceivedBytes read from the stream buffer.
\r
567 // Process the stream here....
\r
570 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
571 // xStreamBufferReceiveFromISR() then a task that has a priority above the
\r
572 // priority of the currently executing task was unblocked and a context
\r
573 // switch should be performed to ensure the ISR returns to the unblocked
\r
574 // task. In most FreeRTOS ports this is done by simply passing
\r
575 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
576 // variables value, and perform the context switch if necessary. Check the
\r
577 // documentation for the port in use for port specific instructions.
\r
578 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
581 * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR
\r
582 * \ingroup StreamBufferManagement
\r
584 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
586 size_t xBufferLengthBytes,
\r
587 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
593 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
\r
596 * Deletes a stream buffer that was previously created using a call to
\r
597 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
\r
598 * buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
\r
599 * then the allocated memory is freed.
\r
601 * A stream buffer handle must not be used after the stream buffer has been
\r
604 * @param xStreamBuffer The handle of the stream buffer to be deleted.
\r
606 * \defgroup vStreamBufferDelete vStreamBufferDelete
\r
607 * \ingroup StreamBufferManagement
\r
609 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
615 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
\r
618 * Queries a stream buffer to see if it is full. A stream buffer is full if it
\r
619 * does not have any free space, and therefore cannot accept any more data.
\r
621 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
623 * @return If the stream buffer is full then pdTRUE is returned. Otherwise
\r
624 * pdFALSE is returned.
\r
626 * \defgroup xStreamBufferIsFull xStreamBufferIsFull
\r
627 * \ingroup StreamBufferManagement
\r
629 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
635 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
\r
638 * Queries a stream buffer to see if it is empty. A stream buffer is empty if
\r
639 * it does not contain any data.
\r
641 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
643 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise
\r
644 * pdFALSE is returned.
\r
646 * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty
\r
647 * \ingroup StreamBufferManagement
\r
649 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
655 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
\r
658 * Resets a stream buffer to its initial, empty, state. Any data that was in
\r
659 * the stream buffer is discarded. A stream buffer can only be reset if there
\r
660 * are no tasks blocked waiting to either send to or receive from the stream
\r
663 * @param xStreamBuffer The handle of the stream buffer being reset.
\r
665 * @return If the stream buffer is reset then pdPASS is returned. If there was
\r
666 * a task blocked waiting to send to or read from the stream buffer then the
\r
667 * stream buffer is not reset and pdFAIL is returned.
\r
669 * \defgroup xStreamBufferReset xStreamBufferReset
\r
670 * \ingroup StreamBufferManagement
\r
672 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
678 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
681 * Queries a stream buffer to see how much free space it contains, which is
\r
682 * equal to the amount of data that can be sent to the stream buffer before it
\r
685 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
687 * @return The number of bytes that can be written to the stream buffer before
\r
688 * the stream buffer would be full.
\r
690 * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable
\r
691 * \ingroup StreamBufferManagement
\r
693 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
699 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
702 * Queries a stream buffer to see how much data it contains, which is equal to
\r
703 * the number of bytes that can be read from the stream buffer before the stream
\r
704 * buffer would be empty.
\r
706 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
708 * @return The number of bytes that can be read from the stream buffer before
\r
709 * the stream buffer would be empty.
\r
711 * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable
\r
712 * \ingroup StreamBufferManagement
\r
714 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
720 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
\r
723 * A stream buffer's trigger level is the number of bytes that must be in the
\r
724 * stream buffer before a task that is blocked on the stream buffer to
\r
725 * wait for data is moved out of the blocked state. For example, if a task is
\r
726 * blocked on a read of an empty stream buffer that has a trigger level of 1
\r
727 * then the task will be unblocked when a single byte is written to the buffer
\r
728 * or the task's block time expires. As another example, if a task is blocked
\r
729 * on a read of an empty stream buffer that has a trigger level of 10 then the
\r
730 * task will not be unblocked until the stream buffer contains at least 10 bytes
\r
731 * or the task's block time expires. If a reading task's block time expires
\r
732 * before the trigger level is reached then the task will still receive however
\r
733 * many bytes are actually available. Setting a trigger level of 0 will result
\r
734 * in a trigger level of 1 being used. It is not valid to specify a trigger
\r
735 * level that is greater than the buffer size.
\r
737 * A trigger level is set when the stream buffer is created, and can be modified
\r
738 * using xStreamBufferSetTriggerLevel().
\r
740 * @param xStreamBuffer The handle of the stream buffer being updated.
\r
742 * @param xTriggerLevel The new trigger level for the stream buffer.
\r
744 * @return If xTriggerLevel was less than or equal to the stream buffer's length
\r
745 * then the trigger level will be updated and pdTRUE is returned. Otherwise
\r
746 * pdFALSE is returned.
\r
748 * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel
\r
749 * \ingroup StreamBufferManagement
\r
751 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
\r
757 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
760 * For advanced users only.
\r
762 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
763 * data is sent to a message buffer or stream buffer. If there was a task that
\r
764 * was blocked on the message or stream buffer waiting for data to arrive then
\r
765 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
\r
766 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
\r
767 * thing. It is provided to enable application writers to implement their own
\r
768 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
\r
770 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
771 * additional information.
\r
773 * @param xStreamBuffer The handle of the stream buffer to which data was
\r
776 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
777 * initialised to pdFALSE before it is passed into
\r
778 * xStreamBufferSendCompletedFromISR(). If calling
\r
779 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
\r
780 * and the task has a priority above the priority of the currently running task,
\r
781 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
782 * context switch should be performed before exiting the ISR.
\r
784 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
785 * Otherwise pdFALSE is returned.
\r
787 * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR
\r
788 * \ingroup StreamBufferManagement
\r
790 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
796 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
799 * For advanced users only.
\r
801 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
802 * data is read out of a message buffer or stream buffer. If there was a task
\r
803 * that was blocked on the message or stream buffer waiting for data to arrive
\r
804 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
\r
805 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
\r
806 * does the same thing. It is provided to enable application writers to
\r
807 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
\r
810 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
811 * additional information.
\r
813 * @param xStreamBuffer The handle of the stream buffer from which data was
\r
816 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
817 * initialised to pdFALSE before it is passed into
\r
818 * xStreamBufferReceiveCompletedFromISR(). If calling
\r
819 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
\r
820 * and the task has a priority above the priority of the currently running task,
\r
821 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
822 * context switch should be performed before exiting the ISR.
\r
824 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
825 * Otherwise pdFALSE is returned.
\r
827 * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR
\r
828 * \ingroup StreamBufferManagement
\r
830 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
832 /* Functions below here are not part of the public API. */
\r
833 StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
\r
834 size_t xTriggerLevelBytes,
\r
835 BaseType_t xIsMessageBuffer ) PRIVILEGED_FUNCTION;
\r
837 StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
\r
838 size_t xTriggerLevelBytes,
\r
839 BaseType_t xIsMessageBuffer,
\r
840 uint8_t * const pucStreamBufferStorageArea,
\r
841 StaticStreamBuffer_t * const pxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
\r
843 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
845 #if( configUSE_TRACE_FACILITY == 1 )
\r
846 void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer, UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION;
\r
847 UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
848 uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
851 #if defined( __cplusplus )
\r
855 #endif /* !defined( STREAM_BUFFER_H ) */
\r