blob: c5eac02b02f9ec6e7ebf5c653f4e9164b2674bbb [file] [log] [blame]
Joseph Julicher989bc332021-03-15 17:29:08 -07001/*
Gaurav-Aggarwal-AWS2b0fdf22021-10-13 18:38:24 -07002 * FreeRTOS SMP Kernel V202110.00
Joseph Julicher989bc332021-03-15 17:29:08 -07003 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 * the Software, and to permit persons to whom the Software is furnished to do so,
10 * subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 *
22 * https://www.FreeRTOS.org
23 * https://github.com/FreeRTOS
24 *
25 */
26
27/*
28 * Stream buffers are used to send a continuous stream of data from one task or
29 * interrupt to another. Their implementation is light weight, making them
30 * particularly suited for interrupt to task and core to core communication
31 * scenarios.
32 *
33 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
34 * implementation (so also the message buffer implementation, as message buffers
35 * are built on top of stream buffers) assumes there is only one task or
36 * interrupt that will write to the buffer (the writer), and only one task or
37 * interrupt that will read from the buffer (the reader). It is safe for the
38 * writer and reader to be different tasks or interrupts, but, unlike other
39 * FreeRTOS objects, it is not safe to have multiple different writers or
40 * multiple different readers. If there are to be multiple different writers
41 * then the application writer must place each call to a writing API function
42 * (such as xStreamBufferSend()) inside a critical section and set the send
43 * block time to 0. Likewise, if there are to be multiple different readers
44 * then the application writer must place each call to a reading API function
45 * (such as xStreamBufferReceive()) inside a critical section section and set the
46 * receive block time to 0.
47 *
48 */
49
50#ifndef STREAM_BUFFER_H
51#define STREAM_BUFFER_H
52
53#ifndef INC_FREERTOS_H
54 #error "include FreeRTOS.h must appear in source files before include stream_buffer.h"
55#endif
56
57/* *INDENT-OFF* */
58#if defined( __cplusplus )
59 extern "C" {
60#endif
61/* *INDENT-ON* */
62
63/**
64 * Type by which stream buffers are referenced. For example, a call to
65 * xStreamBufferCreate() returns an StreamBufferHandle_t variable that can
66 * then be used as a parameter to xStreamBufferSend(), xStreamBufferReceive(),
67 * etc.
68 */
69struct StreamBufferDef_t;
70typedef struct StreamBufferDef_t * StreamBufferHandle_t;
71
72
73/**
74 * message_buffer.h
75 *
76 * <pre>
77 * StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes, size_t xTriggerLevelBytes );
78 * </pre>
79 *
80 * Creates a new stream buffer using dynamically allocated memory. See
81 * xStreamBufferCreateStatic() for a version that uses statically allocated
82 * memory (memory that is allocated at compile time).
83 *
84 * configSUPPORT_DYNAMIC_ALLOCATION must be set to 1 or left undefined in
85 * FreeRTOSConfig.h for xStreamBufferCreate() to be available.
86 *
87 * @param xBufferSizeBytes The total number of bytes the stream buffer will be
88 * able to hold at any one time.
89 *
90 * @param xTriggerLevelBytes The number of bytes that must be in the stream
91 * buffer before a task that is blocked on the stream buffer to wait for data is
92 * moved out of the blocked state. For example, if a task is blocked on a read
93 * of an empty stream buffer that has a trigger level of 1 then the task will be
94 * unblocked when a single byte is written to the buffer or the task's block
95 * time expires. As another example, if a task is blocked on a read of an empty
96 * stream buffer that has a trigger level of 10 then the task will not be
97 * unblocked until the stream buffer contains at least 10 bytes or the task's
98 * block time expires. If a reading task's block time expires before the
99 * trigger level is reached then the task will still receive however many bytes
100 * are actually available. Setting a trigger level of 0 will result in a
101 * trigger level of 1 being used. It is not valid to specify a trigger level
102 * that is greater than the buffer size.
103 *
104 * @return If NULL is returned, then the stream buffer cannot be created
105 * because there is insufficient heap memory available for FreeRTOS to allocate
106 * the stream buffer data structures and storage area. A non-NULL value being
107 * returned indicates that the stream buffer has been created successfully -
108 * the returned value should be stored as the handle to the created stream
109 * buffer.
110 *
111 * Example use:
112 * <pre>
113 *
114 * void vAFunction( void )
115 * {
116 * StreamBufferHandle_t xStreamBuffer;
117 * const size_t xStreamBufferSizeBytes = 100, xTriggerLevel = 10;
118 *
119 * // Create a stream buffer that can hold 100 bytes. The memory used to hold
120 * // both the stream buffer structure and the data in the stream buffer is
121 * // allocated dynamically.
122 * xStreamBuffer = xStreamBufferCreate( xStreamBufferSizeBytes, xTriggerLevel );
123 *
124 * if( xStreamBuffer == NULL )
125 * {
126 * // There was not enough heap memory space available to create the
127 * // stream buffer.
128 * }
129 * else
130 * {
131 * // The stream buffer was created successfully and can now be used.
132 * }
133 * }
134 * </pre>
135 * \defgroup xStreamBufferCreate xStreamBufferCreate
136 * \ingroup StreamBufferManagement
137 */
138#define xStreamBufferCreate( xBufferSizeBytes, xTriggerLevelBytes ) xStreamBufferGenericCreate( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE )
139
140/**
141 * stream_buffer.h
142 *
143 * <pre>
144 * StreamBufferHandle_t xStreamBufferCreateStatic( size_t xBufferSizeBytes,
145 * size_t xTriggerLevelBytes,
146 * uint8_t *pucStreamBufferStorageArea,
147 * StaticStreamBuffer_t *pxStaticStreamBuffer );
148 * </pre>
149 * Creates a new stream buffer using statically allocated memory. See
150 * xStreamBufferCreate() for a version that uses dynamically allocated memory.
151 *
152 * configSUPPORT_STATIC_ALLOCATION must be set to 1 in FreeRTOSConfig.h for
153 * xStreamBufferCreateStatic() to be available.
154 *
155 * @param xBufferSizeBytes The size, in bytes, of the buffer pointed to by the
156 * pucStreamBufferStorageArea parameter.
157 *
158 * @param xTriggerLevelBytes The number of bytes that must be in the stream
159 * buffer before a task that is blocked on the stream buffer to wait for data is
160 * moved out of the blocked state. For example, if a task is blocked on a read
161 * of an empty stream buffer that has a trigger level of 1 then the task will be
162 * unblocked when a single byte is written to the buffer or the task's block
163 * time expires. As another example, if a task is blocked on a read of an empty
164 * stream buffer that has a trigger level of 10 then the task will not be
165 * unblocked until the stream buffer contains at least 10 bytes or the task's
166 * block time expires. If a reading task's block time expires before the
167 * trigger level is reached then the task will still receive however many bytes
168 * are actually available. Setting a trigger level of 0 will result in a
169 * trigger level of 1 being used. It is not valid to specify a trigger level
170 * that is greater than the buffer size.
171 *
172 * @param pucStreamBufferStorageArea Must point to a uint8_t array that is at
173 * least xBufferSizeBytes + 1 big. This is the array to which streams are
174 * copied when they are written to the stream buffer.
175 *
176 * @param pxStaticStreamBuffer Must point to a variable of type
177 * StaticStreamBuffer_t, which will be used to hold the stream buffer's data
178 * structure.
179 *
180 * @return If the stream buffer is created successfully then a handle to the
181 * created stream buffer is returned. If either pucStreamBufferStorageArea or
182 * pxStaticstreamBuffer are NULL then NULL is returned.
183 *
184 * Example use:
185 * <pre>
186 *
187 * // Used to dimension the array used to hold the streams. The available space
188 * // will actually be one less than this, so 999.
189 #define STORAGE_SIZE_BYTES 1000
190 *
191 * // Defines the memory that will actually hold the streams within the stream
192 * // buffer.
193 * static uint8_t ucStorageBuffer[ STORAGE_SIZE_BYTES ];
194 *
195 * // The variable used to hold the stream buffer structure.
196 * StaticStreamBuffer_t xStreamBufferStruct;
197 *
198 * void MyFunction( void )
199 * {
200 * StreamBufferHandle_t xStreamBuffer;
201 * const size_t xTriggerLevel = 1;
202 *
203 * xStreamBuffer = xStreamBufferCreateStatic( sizeof( ucBufferStorage ),
204 * xTriggerLevel,
205 * ucBufferStorage,
206 * &xStreamBufferStruct );
207 *
208 * // As neither the pucStreamBufferStorageArea or pxStaticStreamBuffer
209 * // parameters were NULL, xStreamBuffer will not be NULL, and can be used to
210 * // reference the created stream buffer in other stream buffer API calls.
211 *
212 * // Other code that uses the stream buffer can go here.
213 * }
214 *
215 * </pre>
216 * \defgroup xStreamBufferCreateStatic xStreamBufferCreateStatic
217 * \ingroup StreamBufferManagement
218 */
219#define xStreamBufferCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pucStreamBufferStorageArea, pxStaticStreamBuffer ) \
220 xStreamBufferGenericCreateStatic( xBufferSizeBytes, xTriggerLevelBytes, pdFALSE, pucStreamBufferStorageArea, pxStaticStreamBuffer )
221
222/**
223 * stream_buffer.h
224 *
225 * <pre>
226 * size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
227 * const void *pvTxData,
228 * size_t xDataLengthBytes,
229 * TickType_t xTicksToWait );
230 * </pre>
231 *
232 * Sends bytes to a stream buffer. The bytes are copied into the stream buffer.
233 *
234 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
235 * implementation (so also the message buffer implementation, as message buffers
236 * are built on top of stream buffers) assumes there is only one task or
237 * interrupt that will write to the buffer (the writer), and only one task or
238 * interrupt that will read from the buffer (the reader). It is safe for the
239 * writer and reader to be different tasks or interrupts, but, unlike other
240 * FreeRTOS objects, it is not safe to have multiple different writers or
241 * multiple different readers. If there are to be multiple different writers
242 * then the application writer must place each call to a writing API function
243 * (such as xStreamBufferSend()) inside a critical section and set the send
244 * block time to 0. Likewise, if there are to be multiple different readers
245 * then the application writer must place each call to a reading API function
246 * (such as xStreamBufferReceive()) inside a critical section and set the receive
247 * block time to 0.
248 *
249 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
250 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
251 * service routine (ISR).
252 *
253 * @param xStreamBuffer The handle of the stream buffer to which a stream is
254 * being sent.
255 *
256 * @param pvTxData A pointer to the buffer that holds the bytes to be copied
257 * into the stream buffer.
258 *
259 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
260 * into the stream buffer.
261 *
262 * @param xTicksToWait The maximum amount of time the task should remain in the
263 * Blocked state to wait for enough space to become available in the stream
264 * buffer, should the stream buffer contain too little space to hold the
265 * another xDataLengthBytes bytes. The block time is specified in tick periods,
266 * so the absolute time it represents is dependent on the tick frequency. The
267 * macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds
268 * into a time specified in ticks. Setting xTicksToWait to portMAX_DELAY will
269 * cause the task to wait indefinitely (without timing out), provided
270 * INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h. If a task times out
271 * before it can write all xDataLengthBytes into the buffer it will still write
272 * as many bytes as possible. A task does not use any CPU time when it is in
273 * the blocked state.
274 *
275 * @return The number of bytes written to the stream buffer. If a task times
276 * out before it can write all xDataLengthBytes into the buffer it will still
277 * write as many bytes as possible.
278 *
279 * Example use:
280 * <pre>
281 * void vAFunction( StreamBufferHandle_t xStreamBuffer )
282 * {
283 * size_t xBytesSent;
284 * uint8_t ucArrayToSend[] = { 0, 1, 2, 3 };
285 * char *pcStringToSend = "String to send";
286 * const TickType_t x100ms = pdMS_TO_TICKS( 100 );
287 *
288 * // Send an array to the stream buffer, blocking for a maximum of 100ms to
289 * // wait for enough space to be available in the stream buffer.
290 * xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) ucArrayToSend, sizeof( ucArrayToSend ), x100ms );
291 *
292 * if( xBytesSent != sizeof( ucArrayToSend ) )
293 * {
294 * // The call to xStreamBufferSend() times out before there was enough
295 * // space in the buffer for the data to be written, but it did
296 * // successfully write xBytesSent bytes.
297 * }
298 *
299 * // Send the string to the stream buffer. Return immediately if there is not
300 * // enough space in the buffer.
301 * xBytesSent = xStreamBufferSend( xStreamBuffer, ( void * ) pcStringToSend, strlen( pcStringToSend ), 0 );
302 *
303 * if( xBytesSent != strlen( pcStringToSend ) )
304 * {
305 * // The entire string could not be added to the stream buffer because
306 * // there was not enough free space in the buffer, but xBytesSent bytes
307 * // were sent. Could try again to send the remaining bytes.
308 * }
309 * }
310 * </pre>
311 * \defgroup xStreamBufferSend xStreamBufferSend
312 * \ingroup StreamBufferManagement
313 */
314size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
315 const void * pvTxData,
316 size_t xDataLengthBytes,
317 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
318
319/**
320 * stream_buffer.h
321 *
322 * <pre>
323 * size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
324 * const void *pvTxData,
325 * size_t xDataLengthBytes,
326 * BaseType_t *pxHigherPriorityTaskWoken );
327 * </pre>
328 *
329 * Interrupt safe version of the API function that sends a stream of bytes to
330 * the stream buffer.
331 *
332 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
333 * implementation (so also the message buffer implementation, as message buffers
334 * are built on top of stream buffers) assumes there is only one task or
335 * interrupt that will write to the buffer (the writer), and only one task or
336 * interrupt that will read from the buffer (the reader). It is safe for the
337 * writer and reader to be different tasks or interrupts, but, unlike other
338 * FreeRTOS objects, it is not safe to have multiple different writers or
339 * multiple different readers. If there are to be multiple different writers
340 * then the application writer must place each call to a writing API function
341 * (such as xStreamBufferSend()) inside a critical section and set the send
342 * block time to 0. Likewise, if there are to be multiple different readers
343 * then the application writer must place each call to a reading API function
344 * (such as xStreamBufferReceive()) inside a critical section and set the receive
345 * block time to 0.
346 *
347 * Use xStreamBufferSend() to write to a stream buffer from a task. Use
348 * xStreamBufferSendFromISR() to write to a stream buffer from an interrupt
349 * service routine (ISR).
350 *
351 * @param xStreamBuffer The handle of the stream buffer to which a stream is
352 * being sent.
353 *
354 * @param pvTxData A pointer to the data that is to be copied into the stream
355 * buffer.
356 *
357 * @param xDataLengthBytes The maximum number of bytes to copy from pvTxData
358 * into the stream buffer.
359 *
360 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
361 * have a task blocked on it waiting for data. Calling
362 * xStreamBufferSendFromISR() can make data available, and so cause a task that
363 * was waiting for data to leave the Blocked state. If calling
364 * xStreamBufferSendFromISR() causes a task to leave the Blocked state, and the
365 * unblocked task has a priority higher than the currently executing task (the
366 * task that was interrupted), then, internally, xStreamBufferSendFromISR()
367 * will set *pxHigherPriorityTaskWoken to pdTRUE. If
368 * xStreamBufferSendFromISR() sets this value to pdTRUE, then normally a
369 * context switch should be performed before the interrupt is exited. This will
370 * ensure that the interrupt returns directly to the highest priority Ready
371 * state task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it
372 * is passed into the function. See the example code below for an example.
373 *
374 * @return The number of bytes actually written to the stream buffer, which will
375 * be less than xDataLengthBytes if the stream buffer didn't have enough free
376 * space for all the bytes to be written.
377 *
378 * Example use:
379 * <pre>
380 * // A stream buffer that has already been created.
381 * StreamBufferHandle_t xStreamBuffer;
382 *
383 * void vAnInterruptServiceRoutine( void )
384 * {
385 * size_t xBytesSent;
386 * char *pcStringToSend = "String to send";
387 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
388 *
389 * // Attempt to send the string to the stream buffer.
390 * xBytesSent = xStreamBufferSendFromISR( xStreamBuffer,
391 * ( void * ) pcStringToSend,
392 * strlen( pcStringToSend ),
393 * &xHigherPriorityTaskWoken );
394 *
395 * if( xBytesSent != strlen( pcStringToSend ) )
396 * {
397 * // There was not enough free space in the stream buffer for the entire
398 * // string to be written, ut xBytesSent bytes were written.
399 * }
400 *
401 * // If xHigherPriorityTaskWoken was set to pdTRUE inside
402 * // xStreamBufferSendFromISR() then a task that has a priority above the
403 * // priority of the currently executing task was unblocked and a context
404 * // switch should be performed to ensure the ISR returns to the unblocked
405 * // task. In most FreeRTOS ports this is done by simply passing
406 * // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
407 * // variables value, and perform the context switch if necessary. Check the
408 * // documentation for the port in use for port specific instructions.
409 * taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
410 * }
411 * </pre>
412 * \defgroup xStreamBufferSendFromISR xStreamBufferSendFromISR
413 * \ingroup StreamBufferManagement
414 */
415size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
416 const void * pvTxData,
417 size_t xDataLengthBytes,
418 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
419
420/**
421 * stream_buffer.h
422 *
423 * <pre>
424 * size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
425 * void *pvRxData,
426 * size_t xBufferLengthBytes,
427 * TickType_t xTicksToWait );
428 * </pre>
429 *
430 * Receives bytes from a stream buffer.
431 *
432 * ***NOTE***: Uniquely among FreeRTOS objects, the stream buffer
433 * implementation (so also the message buffer implementation, as message buffers
434 * are built on top of stream buffers) assumes there is only one task or
435 * interrupt that will write to the buffer (the writer), and only one task or
436 * interrupt that will read from the buffer (the reader). It is safe for the
437 * writer and reader to be different tasks or interrupts, but, unlike other
438 * FreeRTOS objects, it is not safe to have multiple different writers or
439 * multiple different readers. If there are to be multiple different writers
440 * then the application writer must place each call to a writing API function
441 * (such as xStreamBufferSend()) inside a critical section and set the send
442 * block time to 0. Likewise, if there are to be multiple different readers
443 * then the application writer must place each call to a reading API function
444 * (such as xStreamBufferReceive()) inside a critical section and set the receive
445 * block time to 0.
446 *
447 * Use xStreamBufferReceive() to read from a stream buffer from a task. Use
448 * xStreamBufferReceiveFromISR() to read from a stream buffer from an
449 * interrupt service routine (ISR).
450 *
451 * @param xStreamBuffer The handle of the stream buffer from which bytes are to
452 * be received.
453 *
454 * @param pvRxData A pointer to the buffer into which the received bytes will be
455 * copied.
456 *
457 * @param xBufferLengthBytes The length of the buffer pointed to by the
458 * pvRxData parameter. This sets the maximum number of bytes to receive in one
459 * call. xStreamBufferReceive will return as many bytes as possible up to a
460 * maximum set by xBufferLengthBytes.
461 *
462 * @param xTicksToWait The maximum amount of time the task should remain in the
463 * Blocked state to wait for data to become available if the stream buffer is
464 * empty. xStreamBufferReceive() will return immediately if xTicksToWait is
465 * zero. The block time is specified in tick periods, so the absolute time it
466 * represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can
467 * be used to convert a time specified in milliseconds into a time specified in
468 * ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait
469 * indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1
470 * in FreeRTOSConfig.h. A task does not use any CPU time when it is in the
471 * Blocked state.
472 *
473 * @return The number of bytes actually read from the stream buffer, which will
474 * be less than xBufferLengthBytes if the call to xStreamBufferReceive() timed
475 * out before xBufferLengthBytes were available.
476 *
477 * Example use:
478 * <pre>
479 * void vAFunction( StreamBuffer_t xStreamBuffer )
480 * {
481 * uint8_t ucRxData[ 20 ];
482 * size_t xReceivedBytes;
483 * const TickType_t xBlockTime = pdMS_TO_TICKS( 20 );
484 *
485 * // Receive up to another sizeof( ucRxData ) bytes from the stream buffer.
486 * // Wait in the Blocked state (so not using any CPU processing time) for a
487 * // maximum of 100ms for the full sizeof( ucRxData ) number of bytes to be
488 * // available.
489 * xReceivedBytes = xStreamBufferReceive( xStreamBuffer,
490 * ( void * ) ucRxData,
491 * sizeof( ucRxData ),
492 * xBlockTime );
493 *
494 * if( xReceivedBytes > 0 )
495 * {
496 * // A ucRxData contains another xRecievedBytes bytes of data, which can
497 * // be processed here....
498 * }
499 * }
500 * </pre>
501 * \defgroup xStreamBufferReceive xStreamBufferReceive
502 * \ingroup StreamBufferManagement
503 */
504size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
505 void * pvRxData,
506 size_t xBufferLengthBytes,
507 TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
508
509/**
510 * stream_buffer.h
511 *
512 * <pre>
513 * size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
514 * void *pvRxData,
515 * size_t xBufferLengthBytes,
516 * BaseType_t *pxHigherPriorityTaskWoken );
517 * </pre>
518 *
519 * An interrupt safe version of the API function that receives bytes from a
520 * stream buffer.
521 *
522 * Use xStreamBufferReceive() to read bytes from a stream buffer from a task.
523 * Use xStreamBufferReceiveFromISR() to read bytes from a stream buffer from an
524 * interrupt service routine (ISR).
525 *
526 * @param xStreamBuffer The handle of the stream buffer from which a stream
527 * is being received.
528 *
529 * @param pvRxData A pointer to the buffer into which the received bytes are
530 * copied.
531 *
532 * @param xBufferLengthBytes The length of the buffer pointed to by the
533 * pvRxData parameter. This sets the maximum number of bytes to receive in one
534 * call. xStreamBufferReceive will return as many bytes as possible up to a
535 * maximum set by xBufferLengthBytes.
536 *
537 * @param pxHigherPriorityTaskWoken It is possible that a stream buffer will
538 * have a task blocked on it waiting for space to become available. Calling
539 * xStreamBufferReceiveFromISR() can make space available, and so cause a task
540 * that is waiting for space to leave the Blocked state. If calling
541 * xStreamBufferReceiveFromISR() causes a task to leave the Blocked state, and
542 * the unblocked task has a priority higher than the currently executing task
543 * (the task that was interrupted), then, internally,
544 * xStreamBufferReceiveFromISR() will set *pxHigherPriorityTaskWoken to pdTRUE.
545 * If xStreamBufferReceiveFromISR() sets this value to pdTRUE, then normally a
546 * context switch should be performed before the interrupt is exited. That will
547 * ensure the interrupt returns directly to the highest priority Ready state
548 * task. *pxHigherPriorityTaskWoken should be set to pdFALSE before it is
549 * passed into the function. See the code example below for an example.
550 *
551 * @return The number of bytes read from the stream buffer, if any.
552 *
553 * Example use:
554 * <pre>
555 * // A stream buffer that has already been created.
556 * StreamBuffer_t xStreamBuffer;
557 *
558 * void vAnInterruptServiceRoutine( void )
559 * {
560 * uint8_t ucRxData[ 20 ];
561 * size_t xReceivedBytes;
562 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; // Initialised to pdFALSE.
563 *
564 * // Receive the next stream from the stream buffer.
565 * xReceivedBytes = xStreamBufferReceiveFromISR( xStreamBuffer,
566 * ( void * ) ucRxData,
567 * sizeof( ucRxData ),
568 * &xHigherPriorityTaskWoken );
569 *
570 * if( xReceivedBytes > 0 )
571 * {
572 * // ucRxData contains xReceivedBytes read from the stream buffer.
573 * // Process the stream here....
574 * }
575 *
576 * // If xHigherPriorityTaskWoken was set to pdTRUE inside
577 * // xStreamBufferReceiveFromISR() then a task that has a priority above the
578 * // priority of the currently executing task was unblocked and a context
579 * // switch should be performed to ensure the ISR returns to the unblocked
580 * // task. In most FreeRTOS ports this is done by simply passing
581 * // xHigherPriorityTaskWoken into taskYIELD_FROM_ISR(), which will test the
582 * // variables value, and perform the context switch if necessary. Check the
583 * // documentation for the port in use for port specific instructions.
584 * taskYIELD_FROM_ISR( xHigherPriorityTaskWoken );
585 * }
586 * </pre>
587 * \defgroup xStreamBufferReceiveFromISR xStreamBufferReceiveFromISR
588 * \ingroup StreamBufferManagement
589 */
590size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
591 void * pvRxData,
592 size_t xBufferLengthBytes,
593 BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
594
595/**
596 * stream_buffer.h
597 *
598 * <pre>
599 * void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );
600 * </pre>
601 *
602 * Deletes a stream buffer that was previously created using a call to
603 * xStreamBufferCreate() or xStreamBufferCreateStatic(). If the stream
604 * buffer was created using dynamic memory (that is, by xStreamBufferCreate()),
605 * then the allocated memory is freed.
606 *
607 * A stream buffer handle must not be used after the stream buffer has been
608 * deleted.
609 *
610 * @param xStreamBuffer The handle of the stream buffer to be deleted.
611 *
612 * \defgroup vStreamBufferDelete vStreamBufferDelete
613 * \ingroup StreamBufferManagement
614 */
615void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
616
617/**
618 * stream_buffer.h
619 *
620 * <pre>
621 * BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer );
622 * </pre>
623 *
624 * Queries a stream buffer to see if it is full. A stream buffer is full if it
625 * does not have any free space, and therefore cannot accept any more data.
626 *
627 * @param xStreamBuffer The handle of the stream buffer being queried.
628 *
629 * @return If the stream buffer is full then pdTRUE is returned. Otherwise
630 * pdFALSE is returned.
631 *
632 * \defgroup xStreamBufferIsFull xStreamBufferIsFull
633 * \ingroup StreamBufferManagement
634 */
635BaseType_t xStreamBufferIsFull( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
636
637/**
638 * stream_buffer.h
639 *
640 * <pre>
641 * BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer );
642 * </pre>
643 *
644 * Queries a stream buffer to see if it is empty. A stream buffer is empty if
645 * it does not contain any data.
646 *
647 * @param xStreamBuffer The handle of the stream buffer being queried.
648 *
649 * @return If the stream buffer is empty then pdTRUE is returned. Otherwise
650 * pdFALSE is returned.
651 *
652 * \defgroup xStreamBufferIsEmpty xStreamBufferIsEmpty
653 * \ingroup StreamBufferManagement
654 */
655BaseType_t xStreamBufferIsEmpty( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
656
657/**
658 * stream_buffer.h
659 *
660 * <pre>
661 * BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer );
662 * </pre>
663 *
664 * Resets a stream buffer to its initial, empty, state. Any data that was in
665 * the stream buffer is discarded. A stream buffer can only be reset if there
666 * are no tasks blocked waiting to either send to or receive from the stream
667 * buffer.
668 *
669 * @param xStreamBuffer The handle of the stream buffer being reset.
670 *
671 * @return If the stream buffer is reset then pdPASS is returned. If there was
672 * a task blocked waiting to send to or read from the stream buffer then the
673 * stream buffer is not reset and pdFAIL is returned.
674 *
675 * \defgroup xStreamBufferReset xStreamBufferReset
676 * \ingroup StreamBufferManagement
677 */
678BaseType_t xStreamBufferReset( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
679
680/**
681 * stream_buffer.h
682 *
683 * <pre>
684 * size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );
685 * </pre>
686 *
687 * Queries a stream buffer to see how much free space it contains, which is
688 * equal to the amount of data that can be sent to the stream buffer before it
689 * is full.
690 *
691 * @param xStreamBuffer The handle of the stream buffer being queried.
692 *
693 * @return The number of bytes that can be written to the stream buffer before
694 * the stream buffer would be full.
695 *
696 * \defgroup xStreamBufferSpacesAvailable xStreamBufferSpacesAvailable
697 * \ingroup StreamBufferManagement
698 */
699size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
700
701/**
702 * stream_buffer.h
703 *
704 * <pre>
705 * size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );
706 * </pre>
707 *
708 * Queries a stream buffer to see how much data it contains, which is equal to
709 * the number of bytes that can be read from the stream buffer before the stream
710 * buffer would be empty.
711 *
712 * @param xStreamBuffer The handle of the stream buffer being queried.
713 *
714 * @return The number of bytes that can be read from the stream buffer before
715 * the stream buffer would be empty.
716 *
717 * \defgroup xStreamBufferBytesAvailable xStreamBufferBytesAvailable
718 * \ingroup StreamBufferManagement
719 */
720size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
721
722/**
723 * stream_buffer.h
724 *
725 * <pre>
726 * BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer, size_t xTriggerLevel );
727 * </pre>
728 *
729 * A stream buffer's trigger level is the number of bytes that must be in the
730 * stream buffer before a task that is blocked on the stream buffer to
731 * wait for data is moved out of the blocked state. For example, if a task is
732 * blocked on a read of an empty stream buffer that has a trigger level of 1
733 * then the task will be unblocked when a single byte is written to the buffer
734 * or the task's block time expires. As another example, if a task is blocked
735 * on a read of an empty stream buffer that has a trigger level of 10 then the
736 * task will not be unblocked until the stream buffer contains at least 10 bytes
737 * or the task's block time expires. If a reading task's block time expires
738 * before the trigger level is reached then the task will still receive however
739 * many bytes are actually available. Setting a trigger level of 0 will result
740 * in a trigger level of 1 being used. It is not valid to specify a trigger
741 * level that is greater than the buffer size.
742 *
743 * A trigger level is set when the stream buffer is created, and can be modified
744 * using xStreamBufferSetTriggerLevel().
745 *
746 * @param xStreamBuffer The handle of the stream buffer being updated.
747 *
748 * @param xTriggerLevel The new trigger level for the stream buffer.
749 *
750 * @return If xTriggerLevel was less than or equal to the stream buffer's length
751 * then the trigger level will be updated and pdTRUE is returned. Otherwise
752 * pdFALSE is returned.
753 *
754 * \defgroup xStreamBufferSetTriggerLevel xStreamBufferSetTriggerLevel
755 * \ingroup StreamBufferManagement
756 */
757BaseType_t xStreamBufferSetTriggerLevel( StreamBufferHandle_t xStreamBuffer,
758 size_t xTriggerLevel ) PRIVILEGED_FUNCTION;
759
760/**
761 * stream_buffer.h
762 *
763 * <pre>
764 * BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
765 * </pre>
766 *
767 * For advanced users only.
768 *
769 * The sbSEND_COMPLETED() macro is called from within the FreeRTOS APIs when
770 * data is sent to a message buffer or stream buffer. If there was a task that
771 * was blocked on the message or stream buffer waiting for data to arrive then
772 * the sbSEND_COMPLETED() macro sends a notification to the task to remove it
773 * from the Blocked state. xStreamBufferSendCompletedFromISR() does the same
774 * thing. It is provided to enable application writers to implement their own
775 * version of sbSEND_COMPLETED(), and MUST NOT BE USED AT ANY OTHER TIME.
776 *
777 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
778 * additional information.
779 *
780 * @param xStreamBuffer The handle of the stream buffer to which data was
781 * written.
782 *
783 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
784 * initialised to pdFALSE before it is passed into
785 * xStreamBufferSendCompletedFromISR(). If calling
786 * xStreamBufferSendCompletedFromISR() removes a task from the Blocked state,
787 * and the task has a priority above the priority of the currently running task,
788 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
789 * context switch should be performed before exiting the ISR.
790 *
791 * @return If a task was removed from the Blocked state then pdTRUE is returned.
792 * Otherwise pdFALSE is returned.
793 *
794 * \defgroup xStreamBufferSendCompletedFromISR xStreamBufferSendCompletedFromISR
795 * \ingroup StreamBufferManagement
796 */
797BaseType_t xStreamBufferSendCompletedFromISR( StreamBufferHandle_t xStreamBuffer,
798 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
799
800/**
801 * stream_buffer.h
802 *
803 * <pre>
804 * BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer, BaseType_t *pxHigherPriorityTaskWoken );
805 * </pre>
806 *
807 * For advanced users only.
808 *
809 * The sbRECEIVE_COMPLETED() macro is called from within the FreeRTOS APIs when
810 * data is read out of a message buffer or stream buffer. If there was a task
811 * that was blocked on the message or stream buffer waiting for data to arrive
812 * then the sbRECEIVE_COMPLETED() macro sends a notification to the task to
813 * remove it from the Blocked state. xStreamBufferReceiveCompletedFromISR()
814 * does the same thing. It is provided to enable application writers to
815 * implement their own version of sbRECEIVE_COMPLETED(), and MUST NOT BE USED AT
816 * ANY OTHER TIME.
817 *
818 * See the example implemented in FreeRTOS/Demo/Minimal/MessageBufferAMP.c for
819 * additional information.
820 *
821 * @param xStreamBuffer The handle of the stream buffer from which data was
822 * read.
823 *
824 * @param pxHigherPriorityTaskWoken *pxHigherPriorityTaskWoken should be
825 * initialised to pdFALSE before it is passed into
826 * xStreamBufferReceiveCompletedFromISR(). If calling
827 * xStreamBufferReceiveCompletedFromISR() removes a task from the Blocked state,
828 * and the task has a priority above the priority of the currently running task,
829 * then *pxHigherPriorityTaskWoken will get set to pdTRUE indicating that a
830 * context switch should be performed before exiting the ISR.
831 *
832 * @return If a task was removed from the Blocked state then pdTRUE is returned.
833 * Otherwise pdFALSE is returned.
834 *
835 * \defgroup xStreamBufferReceiveCompletedFromISR xStreamBufferReceiveCompletedFromISR
836 * \ingroup StreamBufferManagement
837 */
838BaseType_t xStreamBufferReceiveCompletedFromISR( StreamBufferHandle_t xStreamBuffer,
839 BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
840
841/* Functions below here are not part of the public API. */
842StreamBufferHandle_t xStreamBufferGenericCreate( size_t xBufferSizeBytes,
843 size_t xTriggerLevelBytes,
844 BaseType_t xIsMessageBuffer ) PRIVILEGED_FUNCTION;
845
846StreamBufferHandle_t xStreamBufferGenericCreateStatic( size_t xBufferSizeBytes,
847 size_t xTriggerLevelBytes,
848 BaseType_t xIsMessageBuffer,
849 uint8_t * const pucStreamBufferStorageArea,
850 StaticStreamBuffer_t * const pxStaticStreamBuffer ) PRIVILEGED_FUNCTION;
851
852size_t xStreamBufferNextMessageLengthBytes( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
853
854#if ( configUSE_TRACE_FACILITY == 1 )
855 void vStreamBufferSetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer,
856 UBaseType_t uxStreamBufferNumber ) PRIVILEGED_FUNCTION;
857 UBaseType_t uxStreamBufferGetStreamBufferNumber( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
858 uint8_t ucStreamBufferGetStreamBufferType( StreamBufferHandle_t xStreamBuffer ) PRIVILEGED_FUNCTION;
859#endif
860
861/* *INDENT-OFF* */
862#if defined( __cplusplus )
863 }
864#endif
865/* *INDENT-ON* */
866
867#endif /* !defined( STREAM_BUFFER_H ) */