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
32 #ifndef INC_FREERTOS_H
\r
33 #error "include FreeRTOS.h" must appear in source files before "include queue.h"
\r
42 * Type by which queues are referenced. For example, a call to xQueueCreate()
\r
43 * returns an QueueHandle_t variable that can then be used as a parameter to
\r
44 * xQueueSend(), xQueueReceive(), etc.
\r
46 typedef void * QueueHandle_t;
\r
49 * Type by which queue sets are referenced. For example, a call to
\r
50 * xQueueCreateSet() returns an xQueueSet variable that can then be used as a
\r
51 * parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc.
\r
53 typedef void * QueueSetHandle_t;
\r
56 * Queue sets can contain both queues and semaphores, so the
\r
57 * QueueSetMemberHandle_t is defined as a type to be used where a parameter or
\r
58 * return value can be either an QueueHandle_t or an SemaphoreHandle_t.
\r
60 typedef void * QueueSetMemberHandle_t;
\r
62 /* For internal use only. */
\r
63 #define queueSEND_TO_BACK ( ( BaseType_t ) 0 )
\r
64 #define queueSEND_TO_FRONT ( ( BaseType_t ) 1 )
\r
65 #define queueOVERWRITE ( ( BaseType_t ) 2 )
\r
67 /* For internal use only. These definitions *must* match those in queue.c. */
\r
68 #define queueQUEUE_TYPE_BASE ( ( uint8_t ) 0U )
\r
69 #define queueQUEUE_TYPE_SET ( ( uint8_t ) 0U )
\r
70 #define queueQUEUE_TYPE_MUTEX ( ( uint8_t ) 1U )
\r
71 #define queueQUEUE_TYPE_COUNTING_SEMAPHORE ( ( uint8_t ) 2U )
\r
72 #define queueQUEUE_TYPE_BINARY_SEMAPHORE ( ( uint8_t ) 3U )
\r
73 #define queueQUEUE_TYPE_RECURSIVE_MUTEX ( ( uint8_t ) 4U )
\r
78 QueueHandle_t xQueueCreate(
\r
79 UBaseType_t uxQueueLength,
\r
80 UBaseType_t uxItemSize
\r
84 * Creates a new queue instance, and returns a handle by which the new queue
\r
85 * can be referenced.
\r
87 * Internally, within the FreeRTOS implementation, queues use two blocks of
\r
88 * memory. The first block is used to hold the queue's data structures. The
\r
89 * second block is used to hold items placed into the queue. If a queue is
\r
90 * created using xQueueCreate() then both blocks of memory are automatically
\r
91 * dynamically allocated inside the xQueueCreate() function. (see
\r
92 * http://www.freertos.org/a00111.html). If a queue is created using
\r
93 * xQueueCreateStatic() then the application writer must provide the memory that
\r
94 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
\r
95 * be created without using any dynamic memory allocation.
\r
97 * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html
\r
99 * @param uxQueueLength The maximum number of items that the queue can contain.
\r
101 * @param uxItemSize The number of bytes each item in the queue will require.
\r
102 * Items are queued by copy, not by reference, so this is the number of bytes
\r
103 * that will be copied for each posted item. Each item on the queue must be
\r
106 * @return If the queue is successfully create then a handle to the newly
\r
107 * created queue is returned. If the queue cannot be created then 0 is
\r
118 void vATask( void *pvParameters )
\r
120 QueueHandle_t xQueue1, xQueue2;
\r
122 // Create a queue capable of containing 10 uint32_t values.
\r
123 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
126 // Queue was not created and must not be used.
\r
129 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
130 // These should be passed by pointer as they contain a lot of data.
\r
131 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
134 // Queue was not created and must not be used.
\r
137 // ... Rest of task code.
\r
140 * \defgroup xQueueCreate xQueueCreate
\r
141 * \ingroup QueueManagement
\r
143 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
\r
144 #define xQueueCreate( uxQueueLength, uxItemSize ) xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )
\r
150 QueueHandle_t xQueueCreateStatic(
\r
151 UBaseType_t uxQueueLength,
\r
152 UBaseType_t uxItemSize,
\r
153 uint8_t *pucQueueStorageBuffer,
\r
154 StaticQueue_t *pxQueueBuffer
\r
158 * Creates a new queue instance, and returns a handle by which the new queue
\r
159 * can be referenced.
\r
161 * Internally, within the FreeRTOS implementation, queues use two blocks of
\r
162 * memory. The first block is used to hold the queue's data structures. The
\r
163 * second block is used to hold items placed into the queue. If a queue is
\r
164 * created using xQueueCreate() then both blocks of memory are automatically
\r
165 * dynamically allocated inside the xQueueCreate() function. (see
\r
166 * http://www.freertos.org/a00111.html). If a queue is created using
\r
167 * xQueueCreateStatic() then the application writer must provide the memory that
\r
168 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
\r
169 * be created without using any dynamic memory allocation.
\r
171 * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html
\r
173 * @param uxQueueLength The maximum number of items that the queue can contain.
\r
175 * @param uxItemSize The number of bytes each item in the queue will require.
\r
176 * Items are queued by copy, not by reference, so this is the number of bytes
\r
177 * that will be copied for each posted item. Each item on the queue must be
\r
180 * @param pucQueueStorageBuffer If uxItemSize is not zero then
\r
181 * pucQueueStorageBuffer must point to a uint8_t array that is at least large
\r
182 * enough to hold the maximum number of items that can be in the queue at any
\r
183 * one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is
\r
184 * zero then pucQueueStorageBuffer can be NULL.
\r
186 * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which
\r
187 * will be used to hold the queue's data structure.
\r
189 * @return If the queue is created then a handle to the created queue is
\r
190 * returned. If pxQueueBuffer is NULL then NULL is returned.
\r
200 #define QUEUE_LENGTH 10
\r
201 #define ITEM_SIZE sizeof( uint32_t )
\r
203 // xQueueBuffer will hold the queue structure.
\r
204 StaticQueue_t xQueueBuffer;
\r
206 // ucQueueStorage will hold the items posted to the queue. Must be at least
\r
207 // [(queue length) * ( queue item size)] bytes long.
\r
208 uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
\r
210 void vATask( void *pvParameters )
\r
212 QueueHandle_t xQueue1;
\r
214 // Create a queue capable of containing 10 uint32_t values.
\r
215 xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold.
\r
216 ITEM_SIZE // The size of each item in the queue
\r
217 &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the queue.
\r
218 &xQueueBuffer ); // The buffer that will hold the queue structure.
\r
220 // The queue is guaranteed to be created successfully as no dynamic memory
\r
221 // allocation is used. Therefore xQueue1 is now a handle to a valid queue.
\r
223 // ... Rest of task code.
\r
226 * \defgroup xQueueCreateStatic xQueueCreateStatic
\r
227 * \ingroup QueueManagement
\r
229 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
\r
230 #define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer ) xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )
\r
231 #endif /* configSUPPORT_STATIC_ALLOCATION */
\r
236 BaseType_t xQueueSendToFront(
\r
237 QueueHandle_t xQueue,
\r
238 const void *pvItemToQueue,
\r
239 TickType_t xTicksToWait
\r
243 * Post an item to the front of a queue. The item is queued by copy, not by
\r
244 * reference. This function must not be called from an interrupt service
\r
245 * routine. See xQueueSendFromISR () for an alternative which may be used
\r
248 * @param xQueue The handle to the queue on which the item is to be posted.
\r
250 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
251 * queue. The size of the items the queue will hold was defined when the
\r
252 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
253 * into the queue storage area.
\r
255 * @param xTicksToWait The maximum amount of time the task should block
\r
256 * waiting for space to become available on the queue, should it already
\r
257 * be full. The call will return immediately if this is set to 0 and the
\r
258 * queue is full. The time is defined in tick periods so the constant
\r
259 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
261 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
271 uint32_t ulVar = 10UL;
\r
273 void vATask( void *pvParameters )
\r
275 QueueHandle_t xQueue1, xQueue2;
\r
276 struct AMessage *pxMessage;
\r
278 // Create a queue capable of containing 10 uint32_t values.
\r
279 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
281 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
282 // These should be passed by pointer as they contain a lot of data.
\r
283 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
289 // Send an uint32_t. Wait for 10 ticks for space to become
\r
290 // available if necessary.
\r
291 if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
293 // Failed to post the message, even after 10 ticks.
\r
299 // Send a pointer to a struct AMessage object. Don't block if the
\r
300 // queue is already full.
\r
301 pxMessage = & xMessage;
\r
302 xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
305 // ... Rest of task code.
\r
308 * \defgroup xQueueSend xQueueSend
\r
309 * \ingroup QueueManagement
\r
311 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT )
\r
316 BaseType_t xQueueSendToBack(
\r
317 QueueHandle_t xQueue,
\r
318 const void *pvItemToQueue,
\r
319 TickType_t xTicksToWait
\r
323 * This is a macro that calls xQueueGenericSend().
\r
325 * Post an item to the back of a queue. The item is queued by copy, not by
\r
326 * reference. This function must not be called from an interrupt service
\r
327 * routine. See xQueueSendFromISR () for an alternative which may be used
\r
330 * @param xQueue The handle to the queue on which the item is to be posted.
\r
332 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
333 * queue. The size of the items the queue will hold was defined when the
\r
334 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
335 * into the queue storage area.
\r
337 * @param xTicksToWait The maximum amount of time the task should block
\r
338 * waiting for space to become available on the queue, should it already
\r
339 * be full. The call will return immediately if this is set to 0 and the queue
\r
340 * is full. The time is defined in tick periods so the constant
\r
341 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
343 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
353 uint32_t ulVar = 10UL;
\r
355 void vATask( void *pvParameters )
\r
357 QueueHandle_t xQueue1, xQueue2;
\r
358 struct AMessage *pxMessage;
\r
360 // Create a queue capable of containing 10 uint32_t values.
\r
361 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
363 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
364 // These should be passed by pointer as they contain a lot of data.
\r
365 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
371 // Send an uint32_t. Wait for 10 ticks for space to become
\r
372 // available if necessary.
\r
373 if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
375 // Failed to post the message, even after 10 ticks.
\r
381 // Send a pointer to a struct AMessage object. Don't block if the
\r
382 // queue is already full.
\r
383 pxMessage = & xMessage;
\r
384 xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
387 // ... Rest of task code.
\r
390 * \defgroup xQueueSend xQueueSend
\r
391 * \ingroup QueueManagement
\r
393 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
\r
398 BaseType_t xQueueSend(
\r
399 QueueHandle_t xQueue,
\r
400 const void * pvItemToQueue,
\r
401 TickType_t xTicksToWait
\r
405 * This is a macro that calls xQueueGenericSend(). It is included for
\r
406 * backward compatibility with versions of FreeRTOS.org that did not
\r
407 * include the xQueueSendToFront() and xQueueSendToBack() macros. It is
\r
408 * equivalent to xQueueSendToBack().
\r
410 * Post an item on a queue. The item is queued by copy, not by reference.
\r
411 * This function must not be called from an interrupt service routine.
\r
412 * See xQueueSendFromISR () for an alternative which may be used in an ISR.
\r
414 * @param xQueue The handle to the queue on which the item is to be posted.
\r
416 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
417 * queue. The size of the items the queue will hold was defined when the
\r
418 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
419 * into the queue storage area.
\r
421 * @param xTicksToWait The maximum amount of time the task should block
\r
422 * waiting for space to become available on the queue, should it already
\r
423 * be full. The call will return immediately if this is set to 0 and the
\r
424 * queue is full. The time is defined in tick periods so the constant
\r
425 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
427 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
437 uint32_t ulVar = 10UL;
\r
439 void vATask( void *pvParameters )
\r
441 QueueHandle_t xQueue1, xQueue2;
\r
442 struct AMessage *pxMessage;
\r
444 // Create a queue capable of containing 10 uint32_t values.
\r
445 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
447 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
448 // These should be passed by pointer as they contain a lot of data.
\r
449 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
455 // Send an uint32_t. Wait for 10 ticks for space to become
\r
456 // available if necessary.
\r
457 if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
459 // Failed to post the message, even after 10 ticks.
\r
465 // Send a pointer to a struct AMessage object. Don't block if the
\r
466 // queue is already full.
\r
467 pxMessage = & xMessage;
\r
468 xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
471 // ... Rest of task code.
\r
474 * \defgroup xQueueSend xQueueSend
\r
475 * \ingroup QueueManagement
\r
477 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
\r
482 BaseType_t xQueueOverwrite(
\r
483 QueueHandle_t xQueue,
\r
484 const void * pvItemToQueue
\r
488 * Only for use with queues that have a length of one - so the queue is either
\r
491 * Post an item on a queue. If the queue is already full then overwrite the
\r
492 * value held in the queue. The item is queued by copy, not by reference.
\r
494 * This function must not be called from an interrupt service routine.
\r
495 * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR.
\r
497 * @param xQueue The handle of the queue to which the data is being sent.
\r
499 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
500 * queue. The size of the items the queue will hold was defined when the
\r
501 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
502 * into the queue storage area.
\r
504 * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and
\r
505 * therefore has the same return values as xQueueSendToFront(). However, pdPASS
\r
506 * is the only value that can be returned because xQueueOverwrite() will write
\r
507 * to the queue even when the queue is already full.
\r
512 void vFunction( void *pvParameters )
\r
514 QueueHandle_t xQueue;
\r
515 uint32_t ulVarToSend, ulValReceived;
\r
517 // Create a queue to hold one uint32_t value. It is strongly
\r
518 // recommended *not* to use xQueueOverwrite() on queues that can
\r
519 // contain more than one value, and doing so will trigger an assertion
\r
520 // if configASSERT() is defined.
\r
521 xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
\r
523 // Write the value 10 to the queue using xQueueOverwrite().
\r
525 xQueueOverwrite( xQueue, &ulVarToSend );
\r
527 // Peeking the queue should now return 10, but leave the value 10 in
\r
528 // the queue. A block time of zero is used as it is known that the
\r
529 // queue holds a value.
\r
531 xQueuePeek( xQueue, &ulValReceived, 0 );
\r
533 if( ulValReceived != 10 )
\r
535 // Error unless the item was removed by a different task.
\r
538 // The queue is still full. Use xQueueOverwrite() to overwrite the
\r
539 // value held in the queue with 100.
\r
541 xQueueOverwrite( xQueue, &ulVarToSend );
\r
543 // This time read from the queue, leaving the queue empty once more.
\r
544 // A block time of 0 is used again.
\r
545 xQueueReceive( xQueue, &ulValReceived, 0 );
\r
547 // The value read should be the last value written, even though the
\r
548 // queue was already full when the value was written.
\r
549 if( ulValReceived != 100 )
\r
557 * \defgroup xQueueOverwrite xQueueOverwrite
\r
558 * \ingroup QueueManagement
\r
560 #define xQueueOverwrite( xQueue, pvItemToQueue ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE )
\r
566 BaseType_t xQueueGenericSend(
\r
567 QueueHandle_t xQueue,
\r
568 const void * pvItemToQueue,
\r
569 TickType_t xTicksToWait
\r
570 BaseType_t xCopyPosition
\r
574 * It is preferred that the macros xQueueSend(), xQueueSendToFront() and
\r
575 * xQueueSendToBack() are used in place of calling this function directly.
\r
577 * Post an item on a queue. The item is queued by copy, not by reference.
\r
578 * This function must not be called from an interrupt service routine.
\r
579 * See xQueueSendFromISR () for an alternative which may be used in an ISR.
\r
581 * @param xQueue The handle to the queue on which the item is to be posted.
\r
583 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
584 * queue. The size of the items the queue will hold was defined when the
\r
585 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
586 * into the queue storage area.
\r
588 * @param xTicksToWait The maximum amount of time the task should block
\r
589 * waiting for space to become available on the queue, should it already
\r
590 * be full. The call will return immediately if this is set to 0 and the
\r
591 * queue is full. The time is defined in tick periods so the constant
\r
592 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
594 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
\r
595 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
\r
596 * at the front of the queue (for high priority messages).
\r
598 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
608 uint32_t ulVar = 10UL;
\r
610 void vATask( void *pvParameters )
\r
612 QueueHandle_t xQueue1, xQueue2;
\r
613 struct AMessage *pxMessage;
\r
615 // Create a queue capable of containing 10 uint32_t values.
\r
616 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
618 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
619 // These should be passed by pointer as they contain a lot of data.
\r
620 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
626 // Send an uint32_t. Wait for 10 ticks for space to become
\r
627 // available if necessary.
\r
628 if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10, queueSEND_TO_BACK ) != pdPASS )
\r
630 // Failed to post the message, even after 10 ticks.
\r
636 // Send a pointer to a struct AMessage object. Don't block if the
\r
637 // queue is already full.
\r
638 pxMessage = & xMessage;
\r
639 xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0, queueSEND_TO_BACK );
\r
642 // ... Rest of task code.
\r
645 * \defgroup xQueueSend xQueueSend
\r
646 * \ingroup QueueManagement
\r
648 BaseType_t xQueueGenericSend( QueueHandle_t xQueue, const void * const pvItemToQueue, TickType_t xTicksToWait, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
\r
653 BaseType_t xQueuePeek(
\r
654 QueueHandle_t xQueue,
\r
655 void * const pvBuffer,
\r
656 TickType_t xTicksToWait
\r
659 * Receive an item from a queue without removing the item from the queue.
\r
660 * The item is received by copy so a buffer of adequate size must be
\r
661 * provided. The number of bytes copied into the buffer was defined when
\r
662 * the queue was created.
\r
664 * Successfully received items remain on the queue so will be returned again
\r
665 * by the next call, or a call to xQueueReceive().
\r
667 * This macro must not be used in an interrupt service routine. See
\r
668 * xQueuePeekFromISR() for an alternative that can be called from an interrupt
\r
671 * @param xQueue The handle to the queue from which the item is to be
\r
674 * @param pvBuffer Pointer to the buffer into which the received item will
\r
677 * @param xTicksToWait The maximum amount of time the task should block
\r
678 * waiting for an item to receive should the queue be empty at the time
\r
679 * of the call. The time is defined in tick periods so the constant
\r
680 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
681 * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue
\r
684 * @return pdTRUE if an item was successfully received from the queue,
\r
685 * otherwise pdFALSE.
\r
695 QueueHandle_t xQueue;
\r
697 // Task to create a queue and post a value.
\r
698 void vATask( void *pvParameters )
\r
700 struct AMessage *pxMessage;
\r
702 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
703 // These should be passed by pointer as they contain a lot of data.
\r
704 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
707 // Failed to create the queue.
\r
712 // Send a pointer to a struct AMessage object. Don't block if the
\r
713 // queue is already full.
\r
714 pxMessage = & xMessage;
\r
715 xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
717 // ... Rest of task code.
\r
720 // Task to peek the data from the queue.
\r
721 void vADifferentTask( void *pvParameters )
\r
723 struct AMessage *pxRxedMessage;
\r
727 // Peek a message on the created queue. Block for 10 ticks if a
\r
728 // message is not immediately available.
\r
729 if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
\r
731 // pcRxedMessage now points to the struct AMessage variable posted
\r
732 // by vATask, but the item still remains on the queue.
\r
736 // ... Rest of task code.
\r
739 * \defgroup xQueuePeek xQueuePeek
\r
740 * \ingroup QueueManagement
\r
742 BaseType_t xQueuePeek( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
747 BaseType_t xQueuePeekFromISR(
\r
748 QueueHandle_t xQueue,
\r
752 * A version of xQueuePeek() that can be called from an interrupt service
\r
755 * Receive an item from a queue without removing the item from the queue.
\r
756 * The item is received by copy so a buffer of adequate size must be
\r
757 * provided. The number of bytes copied into the buffer was defined when
\r
758 * the queue was created.
\r
760 * Successfully received items remain on the queue so will be returned again
\r
761 * by the next call, or a call to xQueueReceive().
\r
763 * @param xQueue The handle to the queue from which the item is to be
\r
766 * @param pvBuffer Pointer to the buffer into which the received item will
\r
769 * @return pdTRUE if an item was successfully received from the queue,
\r
770 * otherwise pdFALSE.
\r
772 * \defgroup xQueuePeekFromISR xQueuePeekFromISR
\r
773 * \ingroup QueueManagement
\r
775 BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void * const pvBuffer ) PRIVILEGED_FUNCTION;
\r
780 BaseType_t xQueueReceive(
\r
781 QueueHandle_t xQueue,
\r
783 TickType_t xTicksToWait
\r
786 * Receive an item from a queue. The item is received by copy so a buffer of
\r
787 * adequate size must be provided. The number of bytes copied into the buffer
\r
788 * was defined when the queue was created.
\r
790 * Successfully received items are removed from the queue.
\r
792 * This function must not be used in an interrupt service routine. See
\r
793 * xQueueReceiveFromISR for an alternative that can.
\r
795 * @param xQueue The handle to the queue from which the item is to be
\r
798 * @param pvBuffer Pointer to the buffer into which the received item will
\r
801 * @param xTicksToWait The maximum amount of time the task should block
\r
802 * waiting for an item to receive should the queue be empty at the time
\r
803 * of the call. xQueueReceive() will return immediately if xTicksToWait
\r
804 * is zero and the queue is empty. The time is defined in tick periods so the
\r
805 * constant portTICK_PERIOD_MS should be used to convert to real time if this is
\r
808 * @return pdTRUE if an item was successfully received from the queue,
\r
809 * otherwise pdFALSE.
\r
819 QueueHandle_t xQueue;
\r
821 // Task to create a queue and post a value.
\r
822 void vATask( void *pvParameters )
\r
824 struct AMessage *pxMessage;
\r
826 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
827 // These should be passed by pointer as they contain a lot of data.
\r
828 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
831 // Failed to create the queue.
\r
836 // Send a pointer to a struct AMessage object. Don't block if the
\r
837 // queue is already full.
\r
838 pxMessage = & xMessage;
\r
839 xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
841 // ... Rest of task code.
\r
844 // Task to receive from the queue.
\r
845 void vADifferentTask( void *pvParameters )
\r
847 struct AMessage *pxRxedMessage;
\r
851 // Receive a message on the created queue. Block for 10 ticks if a
\r
852 // message is not immediately available.
\r
853 if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
\r
855 // pcRxedMessage now points to the struct AMessage variable posted
\r
860 // ... Rest of task code.
\r
863 * \defgroup xQueueReceive xQueueReceive
\r
864 * \ingroup QueueManagement
\r
866 BaseType_t xQueueReceive( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
870 * <pre>UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );</pre>
\r
872 * Return the number of messages stored in a queue.
\r
874 * @param xQueue A handle to the queue being queried.
\r
876 * @return The number of messages available in the queue.
\r
878 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
\r
879 * \ingroup QueueManagement
\r
881 UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
885 * <pre>UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );</pre>
\r
887 * Return the number of free spaces available in a queue. This is equal to the
\r
888 * number of items that can be sent to the queue before the queue becomes full
\r
889 * if no items are removed.
\r
891 * @param xQueue A handle to the queue being queried.
\r
893 * @return The number of spaces available in the queue.
\r
895 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
\r
896 * \ingroup QueueManagement
\r
898 UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
902 * <pre>void vQueueDelete( QueueHandle_t xQueue );</pre>
\r
904 * Delete a queue - freeing all the memory allocated for storing of items
\r
905 * placed on the queue.
\r
907 * @param xQueue A handle to the queue to be deleted.
\r
909 * \defgroup vQueueDelete vQueueDelete
\r
910 * \ingroup QueueManagement
\r
912 void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
917 BaseType_t xQueueSendToFrontFromISR(
\r
918 QueueHandle_t xQueue,
\r
919 const void *pvItemToQueue,
\r
920 BaseType_t *pxHigherPriorityTaskWoken
\r
924 * This is a macro that calls xQueueGenericSendFromISR().
\r
926 * Post an item to the front of a queue. It is safe to use this macro from
\r
927 * within an interrupt service routine.
\r
929 * Items are queued by copy not reference so it is preferable to only
\r
930 * queue small items, especially when called from an ISR. In most cases
\r
931 * it would be preferable to store a pointer to the item being queued.
\r
933 * @param xQueue The handle to the queue on which the item is to be posted.
\r
935 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
936 * queue. The size of the items the queue will hold was defined when the
\r
937 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
938 * into the queue storage area.
\r
940 * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set
\r
941 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
942 * to unblock, and the unblocked task has a priority higher than the currently
\r
943 * running task. If xQueueSendToFromFromISR() sets this value to pdTRUE then
\r
944 * a context switch should be requested before the interrupt is exited.
\r
946 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
949 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
952 void vBufferISR( void )
\r
955 BaseType_t xHigherPrioritTaskWoken;
\r
957 // We have not woken a task at the start of the ISR.
\r
958 xHigherPriorityTaskWoken = pdFALSE;
\r
960 // Loop until the buffer is empty.
\r
963 // Obtain a byte from the buffer.
\r
964 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
967 xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
969 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
971 // Now the buffer is empty we can switch context if necessary.
\r
972 if( xHigherPriorityTaskWoken )
\r
979 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
980 * \ingroup QueueManagement
\r
982 #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT )
\r
988 BaseType_t xQueueSendToBackFromISR(
\r
989 QueueHandle_t xQueue,
\r
990 const void *pvItemToQueue,
\r
991 BaseType_t *pxHigherPriorityTaskWoken
\r
995 * This is a macro that calls xQueueGenericSendFromISR().
\r
997 * Post an item to the back of a queue. It is safe to use this macro from
\r
998 * within an interrupt service routine.
\r
1000 * Items are queued by copy not reference so it is preferable to only
\r
1001 * queue small items, especially when called from an ISR. In most cases
\r
1002 * it would be preferable to store a pointer to the item being queued.
\r
1004 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1006 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1007 * queue. The size of the items the queue will hold was defined when the
\r
1008 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1009 * into the queue storage area.
\r
1011 * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set
\r
1012 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1013 * to unblock, and the unblocked task has a priority higher than the currently
\r
1014 * running task. If xQueueSendToBackFromISR() sets this value to pdTRUE then
\r
1015 * a context switch should be requested before the interrupt is exited.
\r
1017 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1020 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1023 void vBufferISR( void )
\r
1026 BaseType_t xHigherPriorityTaskWoken;
\r
1028 // We have not woken a task at the start of the ISR.
\r
1029 xHigherPriorityTaskWoken = pdFALSE;
\r
1031 // Loop until the buffer is empty.
\r
1034 // Obtain a byte from the buffer.
\r
1035 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1038 xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
1040 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1042 // Now the buffer is empty we can switch context if necessary.
\r
1043 if( xHigherPriorityTaskWoken )
\r
1050 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1051 * \ingroup QueueManagement
\r
1053 #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
\r
1058 BaseType_t xQueueOverwriteFromISR(
\r
1059 QueueHandle_t xQueue,
\r
1060 const void * pvItemToQueue,
\r
1061 BaseType_t *pxHigherPriorityTaskWoken
\r
1065 * A version of xQueueOverwrite() that can be used in an interrupt service
\r
1068 * Only for use with queues that can hold a single item - so the queue is either
\r
1071 * Post an item on a queue. If the queue is already full then overwrite the
\r
1072 * value held in the queue. The item is queued by copy, not by reference.
\r
1074 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1076 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1077 * queue. The size of the items the queue will hold was defined when the
\r
1078 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1079 * into the queue storage area.
\r
1081 * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set
\r
1082 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1083 * to unblock, and the unblocked task has a priority higher than the currently
\r
1084 * running task. If xQueueOverwriteFromISR() sets this value to pdTRUE then
\r
1085 * a context switch should be requested before the interrupt is exited.
\r
1087 * @return xQueueOverwriteFromISR() is a macro that calls
\r
1088 * xQueueGenericSendFromISR(), and therefore has the same return values as
\r
1089 * xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be
\r
1090 * returned because xQueueOverwriteFromISR() will write to the queue even when
\r
1091 * the queue is already full.
\r
1096 QueueHandle_t xQueue;
\r
1098 void vFunction( void *pvParameters )
\r
1100 // Create a queue to hold one uint32_t value. It is strongly
\r
1101 // recommended *not* to use xQueueOverwriteFromISR() on queues that can
\r
1102 // contain more than one value, and doing so will trigger an assertion
\r
1103 // if configASSERT() is defined.
\r
1104 xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
\r
1107 void vAnInterruptHandler( void )
\r
1109 // xHigherPriorityTaskWoken must be set to pdFALSE before it is used.
\r
1110 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
\r
1111 uint32_t ulVarToSend, ulValReceived;
\r
1113 // Write the value 10 to the queue using xQueueOverwriteFromISR().
\r
1115 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
\r
1117 // The queue is full, but calling xQueueOverwriteFromISR() again will still
\r
1118 // pass because the value held in the queue will be overwritten with the
\r
1120 ulVarToSend = 100;
\r
1121 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
\r
1123 // Reading from the queue will now return 100.
\r
1127 if( xHigherPrioritytaskWoken == pdTRUE )
\r
1129 // Writing to the queue caused a task to unblock and the unblocked task
\r
1130 // has a priority higher than or equal to the priority of the currently
\r
1131 // executing task (the task this interrupt interrupted). Perform a context
\r
1132 // switch so this interrupt returns directly to the unblocked task.
\r
1133 portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.
\r
1137 * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR
\r
1138 * \ingroup QueueManagement
\r
1140 #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE )
\r
1145 BaseType_t xQueueSendFromISR(
\r
1146 QueueHandle_t xQueue,
\r
1147 const void *pvItemToQueue,
\r
1148 BaseType_t *pxHigherPriorityTaskWoken
\r
1152 * This is a macro that calls xQueueGenericSendFromISR(). It is included
\r
1153 * for backward compatibility with versions of FreeRTOS.org that did not
\r
1154 * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()
\r
1157 * Post an item to the back of a queue. It is safe to use this function from
\r
1158 * within an interrupt service routine.
\r
1160 * Items are queued by copy not reference so it is preferable to only
\r
1161 * queue small items, especially when called from an ISR. In most cases
\r
1162 * it would be preferable to store a pointer to the item being queued.
\r
1164 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1166 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1167 * queue. The size of the items the queue will hold was defined when the
\r
1168 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1169 * into the queue storage area.
\r
1171 * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set
\r
1172 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1173 * to unblock, and the unblocked task has a priority higher than the currently
\r
1174 * running task. If xQueueSendFromISR() sets this value to pdTRUE then
\r
1175 * a context switch should be requested before the interrupt is exited.
\r
1177 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1180 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1183 void vBufferISR( void )
\r
1186 BaseType_t xHigherPriorityTaskWoken;
\r
1188 // We have not woken a task at the start of the ISR.
\r
1189 xHigherPriorityTaskWoken = pdFALSE;
\r
1191 // Loop until the buffer is empty.
\r
1194 // Obtain a byte from the buffer.
\r
1195 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1198 xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
1200 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1202 // Now the buffer is empty we can switch context if necessary.
\r
1203 if( xHigherPriorityTaskWoken )
\r
1205 // Actual macro used here is port specific.
\r
1206 portYIELD_FROM_ISR ();
\r
1211 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1212 * \ingroup QueueManagement
\r
1214 #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
\r
1219 BaseType_t xQueueGenericSendFromISR(
\r
1220 QueueHandle_t xQueue,
\r
1221 const void *pvItemToQueue,
\r
1222 BaseType_t *pxHigherPriorityTaskWoken,
\r
1223 BaseType_t xCopyPosition
\r
1227 * It is preferred that the macros xQueueSendFromISR(),
\r
1228 * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place
\r
1229 * of calling this function directly. xQueueGiveFromISR() is an
\r
1230 * equivalent for use by semaphores that don't actually copy any data.
\r
1232 * Post an item on a queue. It is safe to use this function from within an
\r
1233 * interrupt service routine.
\r
1235 * Items are queued by copy not reference so it is preferable to only
\r
1236 * queue small items, especially when called from an ISR. In most cases
\r
1237 * it would be preferable to store a pointer to the item being queued.
\r
1239 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1241 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1242 * queue. The size of the items the queue will hold was defined when the
\r
1243 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1244 * into the queue storage area.
\r
1246 * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set
\r
1247 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1248 * to unblock, and the unblocked task has a priority higher than the currently
\r
1249 * running task. If xQueueGenericSendFromISR() sets this value to pdTRUE then
\r
1250 * a context switch should be requested before the interrupt is exited.
\r
1252 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
\r
1253 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
\r
1254 * at the front of the queue (for high priority messages).
\r
1256 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1259 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1262 void vBufferISR( void )
\r
1265 BaseType_t xHigherPriorityTaskWokenByPost;
\r
1267 // We have not woken a task at the start of the ISR.
\r
1268 xHigherPriorityTaskWokenByPost = pdFALSE;
\r
1270 // Loop until the buffer is empty.
\r
1273 // Obtain a byte from the buffer.
\r
1274 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1276 // Post each byte.
\r
1277 xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );
\r
1279 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1281 // Now the buffer is empty we can switch context if necessary. Note that the
\r
1282 // name of the yield function required is port specific.
\r
1283 if( xHigherPriorityTaskWokenByPost )
\r
1285 taskYIELD_YIELD_FROM_ISR();
\r
1290 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1291 * \ingroup QueueManagement
\r
1293 BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, const void * const pvItemToQueue, BaseType_t * const pxHigherPriorityTaskWoken, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
\r
1294 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
1299 BaseType_t xQueueReceiveFromISR(
\r
1300 QueueHandle_t xQueue,
\r
1302 BaseType_t *pxTaskWoken
\r
1306 * Receive an item from a queue. It is safe to use this function from within an
\r
1307 * interrupt service routine.
\r
1309 * @param xQueue The handle to the queue from which the item is to be
\r
1312 * @param pvBuffer Pointer to the buffer into which the received item will
\r
1315 * @param pxTaskWoken A task may be blocked waiting for space to become
\r
1316 * available on the queue. If xQueueReceiveFromISR causes such a task to
\r
1317 * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will
\r
1318 * remain unchanged.
\r
1320 * @return pdTRUE if an item was successfully received from the queue,
\r
1321 * otherwise pdFALSE.
\r
1326 QueueHandle_t xQueue;
\r
1328 // Function to create a queue and post some values.
\r
1329 void vAFunction( void *pvParameters )
\r
1331 char cValueToPost;
\r
1332 const TickType_t xTicksToWait = ( TickType_t )0xff;
\r
1334 // Create a queue capable of containing 10 characters.
\r
1335 xQueue = xQueueCreate( 10, sizeof( char ) );
\r
1338 // Failed to create the queue.
\r
1343 // Post some characters that will be used within an ISR. If the queue
\r
1344 // is full then this task will block for xTicksToWait ticks.
\r
1345 cValueToPost = 'a';
\r
1346 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1347 cValueToPost = 'b';
\r
1348 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1350 // ... keep posting characters ... this task may block when the queue
\r
1353 cValueToPost = 'c';
\r
1354 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1357 // ISR that outputs all the characters received on the queue.
\r
1358 void vISR_Routine( void )
\r
1360 BaseType_t xTaskWokenByReceive = pdFALSE;
\r
1363 while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )
\r
1365 // A character was received. Output the character now.
\r
1366 vOutputCharacter( cRxedChar );
\r
1368 // If removing the character from the queue woke the task that was
\r
1369 // posting onto the queue cTaskWokenByReceive will have been set to
\r
1370 // pdTRUE. No matter how many times this loop iterates only one
\r
1371 // task will be woken.
\r
1374 if( cTaskWokenByPost != ( char ) pdFALSE;
\r
1380 * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR
\r
1381 * \ingroup QueueManagement
\r
1383 BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue, void * const pvBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
1386 * Utilities to query queues that are safe to use from an ISR. These utilities
\r
1387 * should be used only from witin an ISR, or within a critical section.
\r
1389 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1390 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1391 UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1394 * The functions defined above are for passing data to and from tasks. The
\r
1395 * functions below are the equivalents for passing data to and from
\r
1398 * These functions are called from the co-routine macro implementation and
\r
1399 * should not be called directly from application code. Instead use the macro
\r
1400 * wrappers defined within croutine.h.
\r
1402 BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t xCoRoutinePreviouslyWoken );
\r
1403 BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxTaskWoken );
\r
1404 BaseType_t xQueueCRSend( QueueHandle_t xQueue, const void *pvItemToQueue, TickType_t xTicksToWait );
\r
1405 BaseType_t xQueueCRReceive( QueueHandle_t xQueue, void *pvBuffer, TickType_t xTicksToWait );
\r
1408 * For internal use only. Use xSemaphoreCreateMutex(),
\r
1409 * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling
\r
1410 * these functions directly.
\r
1412 QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1413 QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION;
\r
1414 QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount ) PRIVILEGED_FUNCTION;
\r
1415 QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION;
\r
1416 BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1417 void* xQueueGetMutexHolder( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
\r
1418 void* xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
\r
1421 * For internal use only. Use xSemaphoreTakeMutexRecursive() or
\r
1422 * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.
\r
1424 BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1425 BaseType_t xQueueGiveMutexRecursive( QueueHandle_t pxMutex ) PRIVILEGED_FUNCTION;
\r
1428 * Reset a queue back to its original empty state. The return value is now
\r
1429 * obsolete and is always set to pdPASS.
\r
1431 #define xQueueReset( xQueue ) xQueueGenericReset( xQueue, pdFALSE )
\r
1434 * The registry is provided as a means for kernel aware debuggers to
\r
1435 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add
\r
1436 * a queue, semaphore or mutex handle to the registry if you want the handle
\r
1437 * to be available to a kernel aware debugger. If you are not using a kernel
\r
1438 * aware debugger then this function can be ignored.
\r
1440 * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the
\r
1441 * registry can hold. configQUEUE_REGISTRY_SIZE must be greater than 0
\r
1442 * within FreeRTOSConfig.h for the registry to be available. Its value
\r
1443 * does not effect the number of queues, semaphores and mutexes that can be
\r
1444 * created - just the number that the registry can hold.
\r
1446 * @param xQueue The handle of the queue being added to the registry. This
\r
1447 * is the handle returned by a call to xQueueCreate(). Semaphore and mutex
\r
1448 * handles can also be passed in here.
\r
1450 * @param pcName The name to be associated with the handle. This is the
\r
1451 * name that the kernel aware debugger will display. The queue registry only
\r
1452 * stores a pointer to the string - so the string must be persistent (global or
\r
1453 * preferably in ROM/Flash), not on the stack.
\r
1455 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1456 void vQueueAddToRegistry( QueueHandle_t xQueue, const char *pcName ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
\r
1460 * The registry is provided as a means for kernel aware debuggers to
\r
1461 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add
\r
1462 * a queue, semaphore or mutex handle to the registry if you want the handle
\r
1463 * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to
\r
1464 * remove the queue, semaphore or mutex from the register. If you are not using
\r
1465 * a kernel aware debugger then this function can be ignored.
\r
1467 * @param xQueue The handle of the queue being removed from the registry.
\r
1469 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1470 void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1474 * The queue registry is provided as a means for kernel aware debuggers to
\r
1475 * locate queues, semaphores and mutexes. Call pcQueueGetName() to look
\r
1476 * up and return the name of a queue in the queue registry from the queue's
\r
1479 * @param xQueue The handle of the queue the name of which will be returned.
\r
1480 * @return If the queue is in the registry then a pointer to the name of the
\r
1481 * queue is returned. If the queue is not in the registry then NULL is
\r
1484 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1485 const char *pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
\r
1489 * Generic version of the function used to creaet a queue using dynamic memory
\r
1490 * allocation. This is called by other functions and macros that create other
\r
1491 * RTOS objects that use the queue structure as their base.
\r
1493 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
\r
1494 QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1498 * Generic version of the function used to creaet a queue using dynamic memory
\r
1499 * allocation. This is called by other functions and macros that create other
\r
1500 * RTOS objects that use the queue structure as their base.
\r
1502 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
\r
1503 QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1507 * Queue sets provide a mechanism to allow a task to block (pend) on a read
\r
1508 * operation from multiple queues or semaphores simultaneously.
\r
1510 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1513 * A queue set must be explicitly created using a call to xQueueCreateSet()
\r
1514 * before it can be used. Once created, standard FreeRTOS queues and semaphores
\r
1515 * can be added to the set using calls to xQueueAddToSet().
\r
1516 * xQueueSelectFromSet() is then used to determine which, if any, of the queues
\r
1517 * or semaphores contained in the set is in a state where a queue read or
\r
1518 * semaphore take operation would be successful.
\r
1520 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html
\r
1521 * for reasons why queue sets are very rarely needed in practice as there are
\r
1522 * simpler methods of blocking on multiple objects.
\r
1524 * Note 2: Blocking on a queue set that contains a mutex will not cause the
\r
1525 * mutex holder to inherit the priority of the blocked task.
\r
1527 * Note 3: An additional 4 bytes of RAM is required for each space in a every
\r
1528 * queue added to a queue set. Therefore counting semaphores that have a high
\r
1529 * maximum count value should not be added to a queue set.
\r
1531 * Note 4: A receive (in the case of a queue) or take (in the case of a
\r
1532 * semaphore) operation must not be performed on a member of a queue set unless
\r
1533 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1535 * @param uxEventQueueLength Queue sets store events that occur on
\r
1536 * the queues and semaphores contained in the set. uxEventQueueLength specifies
\r
1537 * the maximum number of events that can be queued at once. To be absolutely
\r
1538 * certain that events are not lost uxEventQueueLength should be set to the
\r
1539 * total sum of the length of the queues added to the set, where binary
\r
1540 * semaphores and mutexes have a length of 1, and counting semaphores have a
\r
1541 * length set by their maximum count value. Examples:
\r
1542 * + If a queue set is to hold a queue of length 5, another queue of length 12,
\r
1543 * and a binary semaphore, then uxEventQueueLength should be set to
\r
1544 * (5 + 12 + 1), or 18.
\r
1545 * + If a queue set is to hold three binary semaphores then uxEventQueueLength
\r
1546 * should be set to (1 + 1 + 1 ), or 3.
\r
1547 * + If a queue set is to hold a counting semaphore that has a maximum count of
\r
1548 * 5, and a counting semaphore that has a maximum count of 3, then
\r
1549 * uxEventQueueLength should be set to (5 + 3), or 8.
\r
1551 * @return If the queue set is created successfully then a handle to the created
\r
1552 * queue set is returned. Otherwise NULL is returned.
\r
1554 QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION;
\r
1557 * Adds a queue or semaphore to a queue set that was previously created by a
\r
1558 * call to xQueueCreateSet().
\r
1560 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1563 * Note 1: A receive (in the case of a queue) or take (in the case of a
\r
1564 * semaphore) operation must not be performed on a member of a queue set unless
\r
1565 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1567 * @param xQueueOrSemaphore The handle of the queue or semaphore being added to
\r
1568 * the queue set (cast to an QueueSetMemberHandle_t type).
\r
1570 * @param xQueueSet The handle of the queue set to which the queue or semaphore
\r
1573 * @return If the queue or semaphore was successfully added to the queue set
\r
1574 * then pdPASS is returned. If the queue could not be successfully added to the
\r
1575 * queue set because it is already a member of a different queue set then pdFAIL
\r
1578 BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1581 * Removes a queue or semaphore from a queue set. A queue or semaphore can only
\r
1582 * be removed from a set if the queue or semaphore is empty.
\r
1584 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1587 * @param xQueueOrSemaphore The handle of the queue or semaphore being removed
\r
1588 * from the queue set (cast to an QueueSetMemberHandle_t type).
\r
1590 * @param xQueueSet The handle of the queue set in which the queue or semaphore
\r
1593 * @return If the queue or semaphore was successfully removed from the queue set
\r
1594 * then pdPASS is returned. If the queue was not in the queue set, or the
\r
1595 * queue (or semaphore) was not empty, then pdFAIL is returned.
\r
1597 BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1600 * xQueueSelectFromSet() selects from the members of a queue set a queue or
\r
1601 * semaphore that either contains data (in the case of a queue) or is available
\r
1602 * to take (in the case of a semaphore). xQueueSelectFromSet() effectively
\r
1603 * allows a task to block (pend) on a read operation on all the queues and
\r
1604 * semaphores in a queue set simultaneously.
\r
1606 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1609 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html
\r
1610 * for reasons why queue sets are very rarely needed in practice as there are
\r
1611 * simpler methods of blocking on multiple objects.
\r
1613 * Note 2: Blocking on a queue set that contains a mutex will not cause the
\r
1614 * mutex holder to inherit the priority of the blocked task.
\r
1616 * Note 3: A receive (in the case of a queue) or take (in the case of a
\r
1617 * semaphore) operation must not be performed on a member of a queue set unless
\r
1618 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1620 * @param xQueueSet The queue set on which the task will (potentially) block.
\r
1622 * @param xTicksToWait The maximum time, in ticks, that the calling task will
\r
1623 * remain in the Blocked state (with other tasks executing) to wait for a member
\r
1624 * of the queue set to be ready for a successful queue read or semaphore take
\r
1627 * @return xQueueSelectFromSet() will return the handle of a queue (cast to
\r
1628 * a QueueSetMemberHandle_t type) contained in the queue set that contains data,
\r
1629 * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained
\r
1630 * in the queue set that is available, or NULL if no such queue or semaphore
\r
1631 * exists before before the specified block time expires.
\r
1633 QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1636 * A version of xQueueSelectFromSet() that can be used from an ISR.
\r
1638 QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1640 /* Not public API functions. */
\r
1641 void vQueueWaitForMessageRestricted( QueueHandle_t xQueue, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
\r
1642 BaseType_t xQueueGenericReset( QueueHandle_t xQueue, BaseType_t xNewQueue ) PRIVILEGED_FUNCTION;
\r
1643 void vQueueSetQueueNumber( QueueHandle_t xQueue, UBaseType_t uxQueueNumber ) PRIVILEGED_FUNCTION;
\r
1644 UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1645 uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1648 #ifdef __cplusplus
\r
1652 #endif /* QUEUE_H */
\r
projects / freertos / blob