2 * FreeRTOS Kernel V10.0.1
\r
3 * Copyright (C) 2017 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 typedef void * StreamBufferHandle_t;
\r
71 StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
\r
74 * Creates a new stream buffer using dynamically allocated memory. See
\r
75 * xStreamBufferCreateStatic() for a version that uses statically allocated
\r
76 * memory (memory that is allocated at compile time).
\r
78 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
\r
79 * FreeRTOSConfig.h for xStreamBufferCreate() to be available.
\r
81 * @param xBufferSizeBytes The total number of bytes the stream buffer will be
\r
82 * able to hold at any one time.
\r
84 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
85 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
86 * moved out of the blocked state. For example, if a task is blocked on a read
\r
87 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
88 * unblocked when a single byte is written to the buffer or the task's block
\r
89 * time expires. As another example, if a task is blocked on a read of an empty
\r
90 * stream buffer that has a trigger level of 10 then the task will not be
\r
91 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
92 * block time expires. If a reading task's block time expires before the
\r
93 * trigger level is reached then the task will still receive however many bytes
\r
94 * are actually available. Setting a trigger level of 0 will result in a
\r
95 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
96 * that is greater than the buffer size.
\r
98 * @return If NULL is returned, then the stream buffer cannot be created
\r
99 * because there is insufficient heap memory available for FreeRTOS to allocate
\r
100 * the stream buffer data structures and storage area. A non-NULL value being
\r
101 * returned indicates that the stream buffer has been created successfully -
\r
102 * the returned value should be stored as the handle to the created stream
\r
108 void vAFunction( void )
\r
110 StreamBufferHandle_t xStreamBuffer;
\r
111 const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
\r
113 // Create a stream buffer that can hold 100 bytes. The memory used to hold
\r
114 // both the stream buffer structure and the data in the stream buffer is
\r
115 // allocated dynamically.
\r
116 xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
\r
118 if( xStreamBuffer == NULL )
\r
120 // There was not enough heap memory space available to create the
\r
125 // The stream buffer was created successfully and can now be used.
\r
129 * \defgroup xStreamBufferCreate xStreamBufferCreate
\r
130 * \ingroup StreamBufferManagement
\r
132 #define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )
\r
138 StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
\r
139 size_t xTriggerLevelBytes,
\r
140 uint8_t *pucStreamBufferStorageArea,
\r
141 StaticStreamBuffer_t *pxStaticStreamBuffer );
\r
143 * Creates a new stream buffer using statically allocated memory. See
\r
144 * xStreamBufferCreate() for a version that uses dynamically allocated memory.
\r
146 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
\r
147 * xStreamBufferCreateStatic() to be available.
\r
149 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
\r
150 * pucStreamBufferStorageArea parameter.
\r
152 * @param xTriggerLevelBytes The number of bytes that must be in the stream
\r
153 * buffer before a task that is blocked on the stream buffer to wait for data is
\r
154 * moved out of the blocked state. For example, if a task is blocked on a read
\r
155 * of an empty stream buffer that has a trigger level of 1 then the task will be
\r
156 * unblocked when a single byte is written to the buffer or the task's block
\r
157 * time expires. As another example, if a task is blocked on a read of an empty
\r
158 * stream buffer that has a trigger level of 10 then the task will not be
\r
159 * unblocked until the stream buffer contains at least 10 bytes or the task's
\r
160 * block time expires. If a reading task's block time expires before the
\r
161 * trigger level is reached then the task will still receive however many bytes
\r
162 * are actually available. Setting a trigger level of 0 will result in a
\r
163 * trigger level of 1 being used. It is not valid to specify a trigger level
\r
164 * that is greater than the buffer size.
\r
166 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at
\r
167 * least xBufferSizeBytes + 1 big. This is the array to which streams are
\r
168 * copied when they are written to the stream buffer.
\r
170 * @param pxStaticStreamBuffer Must point to a variable of type
\r
171 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data
\r
174 * @return If the stream buffer is created successfully then a handle to the
\r
175 * created stream buffer is returned. If either pucStreamBufferStorageArea or
\r
176 * pxStaticstreamBuffer are NULL then NULL is returned.
\r
181 // Used to dimension the array used to hold the streams. The available space
\r
182 // will actually be one less than this, so 999.
\r
183 #define STORAGE_SIZE_BYTES 1000
\r
185 // Defines the memory that will actually hold the streams within the stream
\r
187 static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
\r
189 // The variable used to hold the stream buffer structure.
\r
190 StaticStreamBuffer_t xStreamBufferStruct;
\r
192 void MyFunction( void )
\r
194 StreamBufferHandle_t xStreamBuffer;
\r
195 const size_t xTriggerLevel = 1;
\r
197 xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ),
\r
200 &xStreamBufferStruct );
\r
202 // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
\r
203 // parameters were NULL, xStreamBuffer will not be NULL, and can be used to
\r
204 // reference the created stream buffer in other stream buffer API calls.
\r
206 // Other code that uses the stream buffer can go here.
\r
210 * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic
\r
211 * \ingroup StreamBufferManagement
\r
213 #define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )
\r
219 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
220 const void *pvTxData,
\r
221 size_t xDataLengthBytes,
\r
222 TickType_t xTicksToWait );
\r
225 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
\r
227 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
228 * implementation (so also the message buffer implementation, as message buffers
\r
229 * are built on top of stream buffers) assumes there is only one task or
\r
230 * interrupt that will write to the buffer (the writer), and only one task or
\r
231 * interrupt that will read from the buffer (the reader). It is safe for the
\r
232 * writer and reader to be different tasks or interrupts, but, unlike other
\r
233 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
234 * multiple different readers. If there are to be multiple different writers
\r
235 * then the application writer must place each call to a writing API function
\r
236 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
237 * block time to 0. Likewise, if there are to be multiple different readers
\r
238 * then the application writer must place each call to a reading API function
\r
239 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
242 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
243 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
244 * service routine (ISR).
\r
246 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
249 * @param pvTxData A pointer to the buffer that holds the bytes to be copied
\r
250 * into the stream buffer.
\r
252 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
253 * into the stream buffer.
\r
255 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
256 * Blocked state to wait for enough space to become available in the stream
\r
257 * buffer, should the stream buffer contain too little space to hold the
\r
258 * another xDataLengthBytes bytes. The block time is specified in tick periods,
\r
259 * so the absolute time it represents is dependent on the tick frequency. The
\r
260 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
\r
261 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
\r
262 * cause the task to wait indefinitely (without timing out), provided
\r
263 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out
\r
264 * before it can write all xDataLengthBytes into the buffer it will still write
\r
265 * as many bytes as possible. A task does not use any CPU time when it is in
\r
266 * the blocked state.
\r
268 * @return The number of bytes written to the stream buffer. If a task times
\r
269 * out before it can write all xDataLengthBytes into the buffer it will still
\r
270 * write as many bytes as possible.
\r
274 void vAFunction( StreamBufferHandle_t xStreamBuffer )
\r
277 uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
\r
278 char *pcStringToSend = "String to send";
\r
279 const TickType_t x100ms = pdMS_TO_TICKS( 100 );
\r
281 // Send an array to the stream buffer, blocking for a maximum of 100ms to
\r
282 // wait for enough space to be available in the stream buffer.
\r
283 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
\r
285 if( xBytesSent != sizeof( ucArrayToSend ) )
\r
287 // The call to xStreamBufferSend() times out before there was enough
\r
288 // space in the buffer for the data to be written, but it did
\r
289 // successfully write xBytesSent bytes.
\r
292 // Send the string to the stream buffer. Return immediately if there is not
\r
293 // enough space in the buffer.
\r
294 xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
\r
296 if( xBytesSent != strlen( pcStringToSend ) )
\r
298 // The entire string could not be added to the stream buffer because
\r
299 // there was not enough free space in the buffer, but xBytesSent bytes
\r
300 // were sent. Could try again to send the remaining bytes.
\r
304 * \defgroup xStreamBufferSend xStreamBufferSend
\r
305 * \ingroup StreamBufferManagement
\r
307 size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
\r
308 const void *pvTxData,
\r
309 size_t xDataLengthBytes,
\r
310 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
316 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
317 const void *pvTxData,
\r
318 size_t xDataLengthBytes,
\r
319 BaseType_t *pxHigherPriorityTaskWoken );
\r
322 * Interrupt safe version of the API function that sends a stream of bytes to
\r
323 * the stream buffer.
\r
325 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
326 * implementation (so also the message buffer implementation, as message buffers
\r
327 * are built on top of stream buffers) assumes there is only one task or
\r
328 * interrupt that will write to the buffer (the writer), and only one task or
\r
329 * interrupt that will read from the buffer (the reader). It is safe for the
\r
330 * writer and reader to be different tasks or interrupts, but, unlike other
\r
331 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
332 * multiple different readers. If there are to be multiple different writers
\r
333 * then the application writer must place each call to a writing API function
\r
334 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
335 * block time to 0. Likewise, if there are to be multiple different readers
\r
336 * then the application writer must place each call to a reading API function
\r
337 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
340 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
\r
341 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
\r
342 * service routine (ISR).
\r
344 * @param xStreamBuffer The handle of the stream buffer to which a stream is
\r
347 * @param pvTxData A pointer to the data that is to be copied into the stream
\r
350 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
\r
351 * into the stream buffer.
\r
353 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
354 * have a task blocked on it waiting for data. Calling
\r
355 * xStreamBufferSendFromISR() can make data available, and so cause a task that
\r
356 * was waiting for data to leave the Blocked state. If calling
\r
357 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
\r
358 * unblocked task has a priority higher than the currently executing task (the
\r
359 * task that was interrupted), then, internally, xStreamBufferSendFromISR()
\r
360 * will set *pxHigherPriorityTaskWoken to pdTRUE. If
\r
361 * xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a
\r
362 * context switch should be performed before the interrupt is exited. This will
\r
363 * ensure that the interrupt returns directly to the highest priority Ready
\r
364 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
\r
365 * is passed into the function. See the example code below for an example.
\r
367 * @return The number of bytes actually written to the stream buffer, which will
\r
368 * be less than xDataLengthBytes if the stream buffer didn't have enough free
\r
369 * space for all the bytes to be written.
\r
373 // A stream buffer that has already been created.
\r
374 StreamBufferHandle_t xStreamBuffer;
\r
376 void vAnInterruptServiceRoutine( void )
\r
379 char *pcStringToSend = "String to send";
\r
380 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
382 // Attempt to send the string to the stream buffer.
\r
383 xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
\r
384 ( void * ) pcStringToSend,
\r
385 strlen( pcStringToSend ),
\r
386 &xHigherPriorityTaskWoken );
\r
388 if( xBytesSent != strlen( pcStringToSend ) )
\r
390 // There was not enough free space in the stream buffer for the entire
\r
391 // string to be written, ut xBytesSent bytes were written.
\r
394 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
395 // xStreamBufferSendFromISR() then a task that has a priority above the
\r
396 // priority of the currently executing task was unblocked and a context
\r
397 // switch should be performed to ensure the ISR returns to the unblocked
\r
398 // task. In most FreeRTOS ports this is done by simply passing
\r
399 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
400 // variables value, and perform the context switch if necessary. Check the
\r
401 // documentation for the port in use for port specific instructions.
\r
402 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
405 * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR
\r
406 * \ingroup StreamBufferManagement
\r
408 size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
\r
409 const void *pvTxData,
\r
410 size_t xDataLengthBytes,
\r
411 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
417 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
419 size_t xBufferLengthBytes,
\r
420 TickType_t xTicksToWait );
\r
423 * Receives bytes from a stream buffer.
\r
425 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
\r
426 * implementation (so also the message buffer implementation, as message buffers
\r
427 * are built on top of stream buffers) assumes there is only one task or
\r
428 * interrupt that will write to the buffer (the writer), and only one task or
\r
429 * interrupt that will read from the buffer (the reader). It is safe for the
\r
430 * writer and reader to be different tasks or interrupts, but, unlike other
\r
431 * FreeRTOS objects, it is not safe to have multiple different writers or
\r
432 * multiple different readers. If there are to be multiple different writers
\r
433 * then the application writer must place each call to a writing API function
\r
434 * (such as xStreamBufferSend()) inside a critical section and set the send
\r
435 * block time to 0. Likewise, if there are to be multiple different readers
\r
436 * then the application writer must place each call to a reading API function
\r
437 * (such as xStreamBufferRead()) inside a critical section and set the receive
\r
440 * Use xStreamBufferReceive() to read from a stream buffer from a task. Use
\r
441 * xStreamBufferReceiveFromISR() to read from a stream buffer from an
\r
442 * interrupt service routine (ISR).
\r
444 * @param xStreamBuffer The handle of the stream buffer from which bytes are to
\r
447 * @param pvRxData A pointer to the buffer into which the received bytes will be
\r
450 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
451 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
452 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
453 * maximum set by xBufferLengthBytes.
\r
455 * @param xTicksToWait The maximum amount of time the task should remain in the
\r
456 * Blocked state to wait for data to become available if the stream buffer is
\r
457 * empty. xStreamBufferReceive() will return immediately if xTicksToWait is
\r
458 * zero. The block time is specified in tick periods, so the absolute time it
\r
459 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
\r
460 * be used to convert a time specified in milliseconds into a time specified in
\r
461 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
\r
462 * indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1
\r
463 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
\r
466 * @return The number of bytes actually read from the stream buffer, which will
\r
467 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
\r
468 * out before xBufferLengthBytes were available.
\r
472 void vAFunction( StreamBuffer_t xStreamBuffer )
\r
474 uint8_t ucRxData[ 20 ];
\r
475 size_t xReceivedBytes;
\r
476 const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
\r
478 // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
\r
479 // Wait in the Blocked state (so not using any CPU processing time) for a
\r
480 // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
\r
482 xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
\r
483 ( void * ) ucRxData,
\r
484 sizeof( ucRxData ),
\r
487 if( xReceivedBytes > 0 )
\r
489 // A ucRxData contains another xRecievedBytes bytes of data, which can
\r
490 // be processed here....
\r
494 * \defgroup xStreamBufferReceive xStreamBufferReceive
\r
495 * \ingroup StreamBufferManagement
\r
497 size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
\r
499 size_t xBufferLengthBytes,
\r
500 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
506 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
508 size_t xBufferLengthBytes,
\r
509 BaseType_t *pxHigherPriorityTaskWoken );
\r
512 * An interrupt safe version of the API function that receives bytes from a
\r
515 * Use xStreamBufferReceive() to read bytes from a stream buffer from a task.
\r
516 * Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an
\r
517 * interrupt service routine (ISR).
\r
519 * @param xStreamBuffer The handle of the stream buffer from which a stream
\r
520 * is being received.
\r
522 * @param pvRxData A pointer to the buffer into which the received bytes are
\r
525 * @param xBufferLengthBytes The length of the buffer pointed to by the
\r
526 * pvRxData parameter. This sets the maximum number of bytes to receive in one
\r
527 * call. xStreamBufferReceive will return as many bytes as possible up to a
\r
528 * maximum set by xBufferLengthBytes.
\r
530 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
\r
531 * have a task blocked on it waiting for space to become available. Calling
\r
532 * xStreamBufferReceiveFromISR() can make space available, and so cause a task
\r
533 * that is waiting for space to leave the Blocked state. If calling
\r
534 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
\r
535 * the unblocked task has a priority higher than the currently executing task
\r
536 * (the task that was interrupted), then, internally,
\r
537 * xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
\r
538 * If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a
\r
539 * context switch should be performed before the interrupt is exited. That will
\r
540 * ensure the interrupt returns directly to the highest priority Ready state
\r
541 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
\r
542 * passed into the function. See the code example below for an example.
\r
544 * @return The number of bytes read from the stream buffer, if any.
\r
548 // A stream buffer that has already been created.
\r
549 StreamBuffer_t xStreamBuffer;
\r
551 void vAnInterruptServiceRoutine( void )
\r
553 uint8_t ucRxData[ 20 ];
\r
554 size_t xReceivedBytes;
\r
555 BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
\r
557 // Receive the next stream from the stream buffer.
\r
558 xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
\r
559 ( void * ) ucRxData,
\r
560 sizeof( ucRxData ),
\r
561 &xHigherPriorityTaskWoken );
\r
563 if( xReceivedBytes > 0 )
\r
565 // ucRxData contains xReceivedBytes read from the stream buffer.
\r
566 // Process the stream here....
\r
569 // If xHigherPriorityTaskWoken was set to pdTRUE inside
\r
570 // xStreamBufferReceiveFromISR() then a task that has a priority above the
\r
571 // priority of the currently executing task was unblocked and a context
\r
572 // switch should be performed to ensure the ISR returns to the unblocked
\r
573 // task. In most FreeRTOS ports this is done by simply passing
\r
574 // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
\r
575 // variables value, and perform the context switch if necessary. Check the
\r
576 // documentation for the port in use for port specific instructions.
\r
577 taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
\r
580 * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR
\r
581 * \ingroup StreamBufferManagement
\r
583 size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
\r
585 size_t xBufferLengthBytes,
\r
586 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
592 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
\r
595 * Deletes a stream buffer that was previously created using a call to
\r
596 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
\r
597 * buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
\r
598 * then the allocated memory is freed.
\r
600 * A stream buffer handle must not be used after the stream buffer has been
\r
603 * @param xStreamBuffer The handle of the stream buffer to be deleted.
\r
605 * \defgroup vStreamBufferDelete vStreamBufferDelete
\r
606 * \ingroup StreamBufferManagement
\r
608 void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
614 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
\r
617 * Queries a stream buffer to see if it is full. A stream buffer is full if it
\r
618 * does not have any free space, and therefore cannot accept any more data.
\r
620 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
622 * @return If the stream buffer is full then pdTRUE is returned. Otherwise
\r
623 * pdFALSE is returned.
\r
625 * \defgroup xStreamBufferIsFull xStreamBufferIsFull
\r
626 * \ingroup StreamBufferManagement
\r
628 BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
634 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
\r
637 * Queries a stream buffer to see if it is empty. A stream buffer is empty if
\r
638 * it does not contain any data.
\r
640 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
642 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise
\r
643 * pdFALSE is returned.
\r
645 * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty
\r
646 * \ingroup StreamBufferManagement
\r
648 BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
654 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
\r
657 * Resets a stream buffer to its initial, empty, state. Any data that was in
\r
658 * the stream buffer is discarded. A stream buffer can only be reset if there
\r
659 * are no tasks blocked waiting to either send to or receive from the stream
\r
662 * @param xStreamBuffer The handle of the stream buffer being reset.
\r
664 * @return If the stream buffer is reset then pdPASS is returned. If there was
\r
665 * a task blocked waiting to send to or read from the stream buffer then the
\r
666 * stream buffer is not reset and pdFAIL is returned.
\r
668 * \defgroup xStreamBufferReset xStreamBufferReset
\r
669 * \ingroup StreamBufferManagement
\r
671 BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
677 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
680 * Queries a stream buffer to see how much free space it contains, which is
\r
681 * equal to the amount of data that can be sent to the stream buffer before it
\r
684 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
686 * @return The number of bytes that can be written to the stream buffer before
\r
687 * the stream buffer would be full.
\r
689 * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable
\r
690 * \ingroup StreamBufferManagement
\r
692 size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
698 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
\r
701 * Queries a stream buffer to see how much data it contains, which is equal to
\r
702 * the number of bytes that can be read from the stream buffer before the stream
\r
703 * buffer would be empty.
\r
705 * @param xStreamBuffer The handle of the stream buffer being queried.
\r
707 * @return The number of bytes that can be read from the stream buffer before
\r
708 * the stream buffer would be empty.
\r
710 * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable
\r
711 * \ingroup StreamBufferManagement
\r
713 size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
719 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
\r
722 * A stream buffer's trigger level is the number of bytes that must be in the
\r
723 * stream buffer before a task that is blocked on the stream buffer to
\r
724 * wait for data is moved out of the blocked state. For example, if a task is
\r
725 * blocked on a read of an empty stream buffer that has a trigger level of 1
\r
726 * then the task will be unblocked when a single byte is written to the buffer
\r
727 * or the task's block time expires. As another example, if a task is blocked
\r
728 * on a read of an empty stream buffer that has a trigger level of 10 then the
\r
729 * task will not be unblocked until the stream buffer contains at least 10 bytes
\r
730 * or the task's block time expires. If a reading task's block time expires
\r
731 * before the trigger level is reached then the task will still receive however
\r
732 * many bytes are actually available. Setting a trigger level of 0 will result
\r
733 * in a trigger level of 1 being used. It is not valid to specify a trigger
\r
734 * level that is greater than the buffer size.
\r
736 * A trigger level is set when the stream buffer is created, and can be modified
\r
737 * using xStreamBufferSetTriggerLevel().
\r
739 * @param xStreamBuffer The handle of the stream buffer being updated.
\r
741 * @param xTriggerLevel The new trigger level for the stream buffer.
\r
743 * @return If xTriggerLevel was less than or equal to the stream buffer's length
\r
744 * then the trigger level will be updated and pdTRUE is returned. Otherwise
\r
745 * pdFALSE is returned.
\r
747 * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel
\r
748 * \ingroup StreamBufferManagement
\r
750 BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
\r
756 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
759 * For advanced users only.
\r
761 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
762 * data is sent to a message buffer or stream buffer. If there was a task that
\r
763 * was blocked on the message or stream buffer waiting for data to arrive then
\r
764 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
\r
765 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
\r
766 * thing. It is provided to enable application writers to implement their own
\r
767 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
\r
769 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
770 * additional information.
\r
772 * @param xStreamBuffer The handle of the stream buffer to which data was
\r
775 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
776 * initialised to pdFALSE before it is passed into
\r
777 * xStreamBufferSendCompletedFromISR(). If calling
\r
778 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
\r
779 * and the task has a priority above the priority of the currently running task,
\r
780 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
781 * context switch should be performed before exiting the ISR.
\r
783 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
784 * Otherwise pdFALSE is returned.
\r
786 * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR
\r
787 * \ingroup StreamBufferManagement
\r
789 BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
795 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
\r
798 * For advanced users only.
\r
800 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
\r
801 * data is read out of a message buffer or stream buffer. If there was a task
\r
802 * that was blocked on the message or stream buffer waiting for data to arrive
\r
803 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
\r
804 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
\r
805 * does the same thing. It is provided to enable application writers to
\r
806 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
\r
809 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
\r
810 * additional information.
\r
812 * @param xStreamBuffer The handle of the stream buffer from which data was
\r
815 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
\r
816 * initialised to pdFALSE before it is passed into
\r
817 * xStreamBufferReceiveCompletedFromISR(). If calling
\r
818 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
\r
819 * and the task has a priority above the priority of the currently running task,
\r
820 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
\r
821 * context switch should be performed before exiting the ISR.
\r
823 * @return If a task was removed from the Blocked state then pdTRUE is returned.
\r
824 * Otherwise pdFALSE is returned.
\r
826 * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR
\r
827 * \ingroup StreamBufferManagement
\r
829 BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
831 /* Functions below here are not part of the public API. */
\r
832 StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
\r
833 size_t xTriggerLevelBytes,
\r
834 BaseType_t xIsMessageBuffer ) PRIVILEGED_FUNCTION;
\r
836 StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
\r
837 size_t xTriggerLevelBytes,
\r
838 BaseType_t xIsMessageBuffer,
\r
839 uint8_t * const pucStreamBufferStorageArea,
\r
840 StaticStreamBuffer_t * const pxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
\r
842 size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
844 #if( configUSE_TRACE_FACILITY == 1 )
\r
845 void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer, UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION;
\r
846 UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
847 uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
\r
850 #if defined( __cplusplus )
\r
854 #endif /* !defined( STREAM_BUFFER_H ) */
\r