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
47 typedef struct QueueDef_t * QueueHandle_t;
\r
50 * Type by which queue sets are referenced. For example, a call to
\r
51 * xQueueCreateSet() returns an xQueueSet variable that can then be used as a
\r
52 * parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc.
\r
54 typedef struct QueueDef_t * QueueSetHandle_t;
\r
57 * Queue sets can contain both queues and semaphores, so the
\r
58 * QueueSetMemberHandle_t is defined as a type to be used where a parameter or
\r
59 * return value can be either an QueueHandle_t or an SemaphoreHandle_t.
\r
61 typedef struct QueueDef_t * QueueSetMemberHandle_t;
\r
63 /* For internal use only. */
\r
64 #define queueSEND_TO_BACK ( ( BaseType_t ) 0 )
\r
65 #define queueSEND_TO_FRONT ( ( BaseType_t ) 1 )
\r
66 #define queueOVERWRITE ( ( BaseType_t ) 2 )
\r
68 /* For internal use only. These definitions *must* match those in queue.c. */
\r
69 #define queueQUEUE_TYPE_BASE ( ( uint8_t ) 0U )
\r
70 #define queueQUEUE_TYPE_SET ( ( uint8_t ) 0U )
\r
71 #define queueQUEUE_TYPE_MUTEX ( ( uint8_t ) 1U )
\r
72 #define queueQUEUE_TYPE_COUNTING_SEMAPHORE ( ( uint8_t ) 2U )
\r
73 #define queueQUEUE_TYPE_BINARY_SEMAPHORE ( ( uint8_t ) 3U )
\r
74 #define queueQUEUE_TYPE_RECURSIVE_MUTEX ( ( uint8_t ) 4U )
\r
79 QueueHandle_t xQueueCreate(
\r
80 UBaseType_t uxQueueLength,
\r
81 UBaseType_t uxItemSize
\r
85 * Creates a new queue instance, and returns a handle by which the new queue
\r
86 * can be referenced.
\r
88 * Internally, within the FreeRTOS implementation, queues use two blocks of
\r
89 * memory. The first block is used to hold the queue's data structures. The
\r
90 * second block is used to hold items placed into the queue. If a queue is
\r
91 * created using xQueueCreate() then both blocks of memory are automatically
\r
92 * dynamically allocated inside the xQueueCreate() function. (see
\r
93 * http://www.freertos.org/a00111.html). If a queue is created using
\r
94 * xQueueCreateStatic() then the application writer must provide the memory that
\r
95 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
\r
96 * be created without using any dynamic memory allocation.
\r
98 * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html
\r
100 * @param uxQueueLength The maximum number of items that the queue can contain.
\r
102 * @param uxItemSize The number of bytes each item in the queue will require.
\r
103 * Items are queued by copy, not by reference, so this is the number of bytes
\r
104 * that will be copied for each posted item. Each item on the queue must be
\r
107 * @return If the queue is successfully create then a handle to the newly
\r
108 * created queue is returned. If the queue cannot be created then 0 is
\r
119 void vATask( void *pvParameters )
\r
121 QueueHandle_t xQueue1, xQueue2;
\r
123 // Create a queue capable of containing 10 uint32_t values.
\r
124 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
127 // Queue was not created and must not be used.
\r
130 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
131 // These should be passed by pointer as they contain a lot of data.
\r
132 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
135 // Queue was not created and must not be used.
\r
138 // ... Rest of task code.
\r
141 * \defgroup xQueueCreate xQueueCreate
\r
142 * \ingroup QueueManagement
\r
144 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
\r
145 #define xQueueCreate( uxQueueLength, uxItemSize ) xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )
\r
151 QueueHandle_t xQueueCreateStatic(
\r
152 UBaseType_t uxQueueLength,
\r
153 UBaseType_t uxItemSize,
\r
154 uint8_t *pucQueueStorageBuffer,
\r
155 StaticQueue_t *pxQueueBuffer
\r
159 * Creates a new queue instance, and returns a handle by which the new queue
\r
160 * can be referenced.
\r
162 * Internally, within the FreeRTOS implementation, queues use two blocks of
\r
163 * memory. The first block is used to hold the queue's data structures. The
\r
164 * second block is used to hold items placed into the queue. If a queue is
\r
165 * created using xQueueCreate() then both blocks of memory are automatically
\r
166 * dynamically allocated inside the xQueueCreate() function. (see
\r
167 * http://www.freertos.org/a00111.html). If a queue is created using
\r
168 * xQueueCreateStatic() then the application writer must provide the memory that
\r
169 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
\r
170 * be created without using any dynamic memory allocation.
\r
172 * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html
\r
174 * @param uxQueueLength The maximum number of items that the queue can contain.
\r
176 * @param uxItemSize The number of bytes each item in the queue will require.
\r
177 * Items are queued by copy, not by reference, so this is the number of bytes
\r
178 * that will be copied for each posted item. Each item on the queue must be
\r
181 * @param pucQueueStorageBuffer If uxItemSize is not zero then
\r
182 * pucQueueStorageBuffer must point to a uint8_t array that is at least large
\r
183 * enough to hold the maximum number of items that can be in the queue at any
\r
184 * one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is
\r
185 * zero then pucQueueStorageBuffer can be NULL.
\r
187 * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which
\r
188 * will be used to hold the queue's data structure.
\r
190 * @return If the queue is created then a handle to the created queue is
\r
191 * returned. If pxQueueBuffer is NULL then NULL is returned.
\r
201 #define QUEUE_LENGTH 10
\r
202 #define ITEM_SIZE sizeof( uint32_t )
\r
204 // xQueueBuffer will hold the queue structure.
\r
205 StaticQueue_t xQueueBuffer;
\r
207 // ucQueueStorage will hold the items posted to the queue. Must be at least
\r
208 // [(queue length) * ( queue item size)] bytes long.
\r
209 uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
\r
211 void vATask( void *pvParameters )
\r
213 QueueHandle_t xQueue1;
\r
215 // Create a queue capable of containing 10 uint32_t values.
\r
216 xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold.
\r
217 ITEM_SIZE // The size of each item in the queue
\r
218 &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the queue.
\r
219 &xQueueBuffer ); // The buffer that will hold the queue structure.
\r
221 // The queue is guaranteed to be created successfully as no dynamic memory
\r
222 // allocation is used. Therefore xQueue1 is now a handle to a valid queue.
\r
224 // ... Rest of task code.
\r
227 * \defgroup xQueueCreateStatic xQueueCreateStatic
\r
228 * \ingroup QueueManagement
\r
230 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
\r
231 #define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer ) xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )
\r
232 #endif /* configSUPPORT_STATIC_ALLOCATION */
\r
237 BaseType_t xQueueSendToToFront(
\r
238 QueueHandle_t xQueue,
\r
239 const void *pvItemToQueue,
\r
240 TickType_t xTicksToWait
\r
244 * Post an item to the front of a queue. The item is queued by copy, not by
\r
245 * reference. This function must not be called from an interrupt service
\r
246 * routine. See xQueueSendFromISR () for an alternative which may be used
\r
249 * @param xQueue The handle to the queue on which the item is to be posted.
\r
251 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
252 * queue. The size of the items the queue will hold was defined when the
\r
253 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
254 * into the queue storage area.
\r
256 * @param xTicksToWait The maximum amount of time the task should block
\r
257 * waiting for space to become available on the queue, should it already
\r
258 * be full. The call will return immediately if this is set to 0 and the
\r
259 * queue is full. The time is defined in tick periods so the constant
\r
260 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
262 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
272 uint32_t ulVar = 10UL;
\r
274 void vATask( void *pvParameters )
\r
276 QueueHandle_t xQueue1, xQueue2;
\r
277 struct AMessage *pxMessage;
\r
279 // Create a queue capable of containing 10 uint32_t values.
\r
280 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
282 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
283 // These should be passed by pointer as they contain a lot of data.
\r
284 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
290 // Send an uint32_t. Wait for 10 ticks for space to become
\r
291 // available if necessary.
\r
292 if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
294 // Failed to post the message, even after 10 ticks.
\r
300 // Send a pointer to a struct AMessage object. Don't block if the
\r
301 // queue is already full.
\r
302 pxMessage = & xMessage;
\r
303 xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
306 // ... Rest of task code.
\r
309 * \defgroup xQueueSend xQueueSend
\r
310 * \ingroup QueueManagement
\r
312 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT )
\r
317 BaseType_t xQueueSendToBack(
\r
318 QueueHandle_t xQueue,
\r
319 const void *pvItemToQueue,
\r
320 TickType_t xTicksToWait
\r
324 * This is a macro that calls xQueueGenericSend().
\r
326 * Post an item to the back of a queue. The item is queued by copy, not by
\r
327 * reference. This function must not be called from an interrupt service
\r
328 * routine. See xQueueSendFromISR () for an alternative which may be used
\r
331 * @param xQueue The handle to the queue on which the item is to be posted.
\r
333 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
334 * queue. The size of the items the queue will hold was defined when the
\r
335 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
336 * into the queue storage area.
\r
338 * @param xTicksToWait The maximum amount of time the task should block
\r
339 * waiting for space to become available on the queue, should it already
\r
340 * be full. The call will return immediately if this is set to 0 and the queue
\r
341 * is full. The time is defined in tick periods so the constant
\r
342 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
344 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
354 uint32_t ulVar = 10UL;
\r
356 void vATask( void *pvParameters )
\r
358 QueueHandle_t xQueue1, xQueue2;
\r
359 struct AMessage *pxMessage;
\r
361 // Create a queue capable of containing 10 uint32_t values.
\r
362 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
364 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
365 // These should be passed by pointer as they contain a lot of data.
\r
366 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
372 // Send an uint32_t. Wait for 10 ticks for space to become
\r
373 // available if necessary.
\r
374 if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
376 // Failed to post the message, even after 10 ticks.
\r
382 // Send a pointer to a struct AMessage object. Don't block if the
\r
383 // queue is already full.
\r
384 pxMessage = & xMessage;
\r
385 xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
388 // ... Rest of task code.
\r
391 * \defgroup xQueueSend xQueueSend
\r
392 * \ingroup QueueManagement
\r
394 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
\r
399 BaseType_t xQueueSend(
\r
400 QueueHandle_t xQueue,
\r
401 const void * pvItemToQueue,
\r
402 TickType_t xTicksToWait
\r
406 * This is a macro that calls xQueueGenericSend(). It is included for
\r
407 * backward compatibility with versions of FreeRTOS.org that did not
\r
408 * include the xQueueSendToFront() and xQueueSendToBack() macros. It is
\r
409 * equivalent to xQueueSendToBack().
\r
411 * Post an item on a queue. The item is queued by copy, not by reference.
\r
412 * This function must not be called from an interrupt service routine.
\r
413 * See xQueueSendFromISR () for an alternative which may be used in an ISR.
\r
415 * @param xQueue The handle to the queue on which the item is to be posted.
\r
417 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
418 * queue. The size of the items the queue will hold was defined when the
\r
419 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
420 * into the queue storage area.
\r
422 * @param xTicksToWait The maximum amount of time the task should block
\r
423 * waiting for space to become available on the queue, should it already
\r
424 * be full. The call will return immediately if this is set to 0 and the
\r
425 * queue is full. The time is defined in tick periods so the constant
\r
426 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
428 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
438 uint32_t ulVar = 10UL;
\r
440 void vATask( void *pvParameters )
\r
442 QueueHandle_t xQueue1, xQueue2;
\r
443 struct AMessage *pxMessage;
\r
445 // Create a queue capable of containing 10 uint32_t values.
\r
446 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
448 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
449 // These should be passed by pointer as they contain a lot of data.
\r
450 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
456 // Send an uint32_t. Wait for 10 ticks for space to become
\r
457 // available if necessary.
\r
458 if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS )
\r
460 // Failed to post the message, even after 10 ticks.
\r
466 // Send a pointer to a struct AMessage object. Don't block if the
\r
467 // queue is already full.
\r
468 pxMessage = & xMessage;
\r
469 xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
472 // ... Rest of task code.
\r
475 * \defgroup xQueueSend xQueueSend
\r
476 * \ingroup QueueManagement
\r
478 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK )
\r
483 BaseType_t xQueueOverwrite(
\r
484 QueueHandle_t xQueue,
\r
485 const void * pvItemToQueue
\r
489 * Only for use with queues that have a length of one - so the queue is either
\r
492 * Post an item on a queue. If the queue is already full then overwrite the
\r
493 * value held in the queue. The item is queued by copy, not by reference.
\r
495 * This function must not be called from an interrupt service routine.
\r
496 * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR.
\r
498 * @param xQueue The handle of the queue to which the data is being sent.
\r
500 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
501 * queue. The size of the items the queue will hold was defined when the
\r
502 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
503 * into the queue storage area.
\r
505 * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and
\r
506 * therefore has the same return values as xQueueSendToFront(). However, pdPASS
\r
507 * is the only value that can be returned because xQueueOverwrite() will write
\r
508 * to the queue even when the queue is already full.
\r
513 void vFunction( void *pvParameters )
\r
515 QueueHandle_t xQueue;
\r
516 uint32_t ulVarToSend, ulValReceived;
\r
518 // Create a queue to hold one uint32_t value. It is strongly
\r
519 // recommended *not* to use xQueueOverwrite() on queues that can
\r
520 // contain more than one value, and doing so will trigger an assertion
\r
521 // if configASSERT() is defined.
\r
522 xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
\r
524 // Write the value 10 to the queue using xQueueOverwrite().
\r
526 xQueueOverwrite( xQueue, &ulVarToSend );
\r
528 // Peeking the queue should now return 10, but leave the value 10 in
\r
529 // the queue. A block time of zero is used as it is known that the
\r
530 // queue holds a value.
\r
532 xQueuePeek( xQueue, &ulValReceived, 0 );
\r
534 if( ulValReceived != 10 )
\r
536 // Error unless the item was removed by a different task.
\r
539 // The queue is still full. Use xQueueOverwrite() to overwrite the
\r
540 // value held in the queue with 100.
\r
542 xQueueOverwrite( xQueue, &ulVarToSend );
\r
544 // This time read from the queue, leaving the queue empty once more.
\r
545 // A block time of 0 is used again.
\r
546 xQueueReceive( xQueue, &ulValReceived, 0 );
\r
548 // The value read should be the last value written, even though the
\r
549 // queue was already full when the value was written.
\r
550 if( ulValReceived != 100 )
\r
558 * \defgroup xQueueOverwrite xQueueOverwrite
\r
559 * \ingroup QueueManagement
\r
561 #define xQueueOverwrite( xQueue, pvItemToQueue ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE )
\r
567 BaseType_t xQueueGenericSend(
\r
568 QueueHandle_t xQueue,
\r
569 const void * pvItemToQueue,
\r
570 TickType_t xTicksToWait
\r
571 BaseType_t xCopyPosition
\r
575 * It is preferred that the macros xQueueSend(), xQueueSendToFront() and
\r
576 * xQueueSendToBack() are used in place of calling this function directly.
\r
578 * Post an item on a queue. The item is queued by copy, not by reference.
\r
579 * This function must not be called from an interrupt service routine.
\r
580 * See xQueueSendFromISR () for an alternative which may be used in an ISR.
\r
582 * @param xQueue The handle to the queue on which the item is to be posted.
\r
584 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
585 * queue. The size of the items the queue will hold was defined when the
\r
586 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
587 * into the queue storage area.
\r
589 * @param xTicksToWait The maximum amount of time the task should block
\r
590 * waiting for space to become available on the queue, should it already
\r
591 * be full. The call will return immediately if this is set to 0 and the
\r
592 * queue is full. The time is defined in tick periods so the constant
\r
593 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
595 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
\r
596 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
\r
597 * at the front of the queue (for high priority messages).
\r
599 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
\r
609 uint32_t ulVar = 10UL;
\r
611 void vATask( void *pvParameters )
\r
613 QueueHandle_t xQueue1, xQueue2;
\r
614 struct AMessage *pxMessage;
\r
616 // Create a queue capable of containing 10 uint32_t values.
\r
617 xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
\r
619 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
620 // These should be passed by pointer as they contain a lot of data.
\r
621 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
627 // Send an uint32_t. Wait for 10 ticks for space to become
\r
628 // available if necessary.
\r
629 if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10, queueSEND_TO_BACK ) != pdPASS )
\r
631 // Failed to post the message, even after 10 ticks.
\r
637 // Send a pointer to a struct AMessage object. Don't block if the
\r
638 // queue is already full.
\r
639 pxMessage = & xMessage;
\r
640 xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0, queueSEND_TO_BACK );
\r
643 // ... Rest of task code.
\r
646 * \defgroup xQueueSend xQueueSend
\r
647 * \ingroup QueueManagement
\r
649 BaseType_t xQueueGenericSend( QueueHandle_t xQueue, const void * const pvItemToQueue, TickType_t xTicksToWait, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
\r
654 BaseType_t xQueuePeek(
\r
655 QueueHandle_t xQueue,
\r
656 void * const pvBuffer,
\r
657 TickType_t xTicksToWait
\r
660 * Receive an item from a queue without removing the item from the queue.
\r
661 * The item is received by copy so a buffer of adequate size must be
\r
662 * provided. The number of bytes copied into the buffer was defined when
\r
663 * the queue was created.
\r
665 * Successfully received items remain on the queue so will be returned again
\r
666 * by the next call, or a call to xQueueReceive().
\r
668 * This macro must not be used in an interrupt service routine. See
\r
669 * xQueuePeekFromISR() for an alternative that can be called from an interrupt
\r
672 * @param xQueue The handle to the queue from which the item is to be
\r
675 * @param pvBuffer Pointer to the buffer into which the received item will
\r
678 * @param xTicksToWait The maximum amount of time the task should block
\r
679 * waiting for an item to receive should the queue be empty at the time
\r
680 * of the call. The time is defined in tick periods so the constant
\r
681 * portTICK_PERIOD_MS should be used to convert to real time if this is required.
\r
682 * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue
\r
685 * @return pdTRUE if an item was successfully received from the queue,
\r
686 * otherwise pdFALSE.
\r
696 QueueHandle_t xQueue;
\r
698 // Task to create a queue and post a value.
\r
699 void vATask( void *pvParameters )
\r
701 struct AMessage *pxMessage;
\r
703 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
704 // These should be passed by pointer as they contain a lot of data.
\r
705 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
708 // Failed to create the queue.
\r
713 // Send a pointer to a struct AMessage object. Don't block if the
\r
714 // queue is already full.
\r
715 pxMessage = & xMessage;
\r
716 xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
718 // ... Rest of task code.
\r
721 // Task to peek the data from the queue.
\r
722 void vADifferentTask( void *pvParameters )
\r
724 struct AMessage *pxRxedMessage;
\r
728 // Peek a message on the created queue. Block for 10 ticks if a
\r
729 // message is not immediately available.
\r
730 if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
\r
732 // pcRxedMessage now points to the struct AMessage variable posted
\r
733 // by vATask, but the item still remains on the queue.
\r
737 // ... Rest of task code.
\r
740 * \defgroup xQueuePeek xQueuePeek
\r
741 * \ingroup QueueManagement
\r
743 BaseType_t xQueuePeek( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
748 BaseType_t xQueuePeekFromISR(
\r
749 QueueHandle_t xQueue,
\r
753 * A version of xQueuePeek() that can be called from an interrupt service
\r
756 * Receive an item from a queue without removing the item from the queue.
\r
757 * The item is received by copy so a buffer of adequate size must be
\r
758 * provided. The number of bytes copied into the buffer was defined when
\r
759 * the queue was created.
\r
761 * Successfully received items remain on the queue so will be returned again
\r
762 * by the next call, or a call to xQueueReceive().
\r
764 * @param xQueue The handle to the queue from which the item is to be
\r
767 * @param pvBuffer Pointer to the buffer into which the received item will
\r
770 * @return pdTRUE if an item was successfully received from the queue,
\r
771 * otherwise pdFALSE.
\r
773 * \defgroup xQueuePeekFromISR xQueuePeekFromISR
\r
774 * \ingroup QueueManagement
\r
776 BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void * const pvBuffer ) PRIVILEGED_FUNCTION;
\r
781 BaseType_t xQueueReceive(
\r
782 QueueHandle_t xQueue,
\r
784 TickType_t xTicksToWait
\r
787 * Receive an item from a queue. The item is received by copy so a buffer of
\r
788 * adequate size must be provided. The number of bytes copied into the buffer
\r
789 * was defined when the queue was created.
\r
791 * Successfully received items are removed from the queue.
\r
793 * This function must not be used in an interrupt service routine. See
\r
794 * xQueueReceiveFromISR for an alternative that can.
\r
796 * @param xQueue The handle to the queue from which the item is to be
\r
799 * @param pvBuffer Pointer to the buffer into which the received item will
\r
802 * @param xTicksToWait The maximum amount of time the task should block
\r
803 * waiting for an item to receive should the queue be empty at the time
\r
804 * of the call. xQueueReceive() will return immediately if xTicksToWait
\r
805 * is zero and the queue is empty. The time is defined in tick periods so the
\r
806 * constant portTICK_PERIOD_MS should be used to convert to real time if this is
\r
809 * @return pdTRUE if an item was successfully received from the queue,
\r
810 * otherwise pdFALSE.
\r
820 QueueHandle_t xQueue;
\r
822 // Task to create a queue and post a value.
\r
823 void vATask( void *pvParameters )
\r
825 struct AMessage *pxMessage;
\r
827 // Create a queue capable of containing 10 pointers to AMessage structures.
\r
828 // These should be passed by pointer as they contain a lot of data.
\r
829 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
\r
832 // Failed to create the queue.
\r
837 // Send a pointer to a struct AMessage object. Don't block if the
\r
838 // queue is already full.
\r
839 pxMessage = & xMessage;
\r
840 xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
\r
842 // ... Rest of task code.
\r
845 // Task to receive from the queue.
\r
846 void vADifferentTask( void *pvParameters )
\r
848 struct AMessage *pxRxedMessage;
\r
852 // Receive a message on the created queue. Block for 10 ticks if a
\r
853 // message is not immediately available.
\r
854 if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
\r
856 // pcRxedMessage now points to the struct AMessage variable posted
\r
861 // ... Rest of task code.
\r
864 * \defgroup xQueueReceive xQueueReceive
\r
865 * \ingroup QueueManagement
\r
867 BaseType_t xQueueReceive( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
871 * <pre>UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );</pre>
\r
873 * Return the number of messages stored in a queue.
\r
875 * @param xQueue A handle to the queue being queried.
\r
877 * @return The number of messages available in the queue.
\r
879 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
\r
880 * \ingroup QueueManagement
\r
882 UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
886 * <pre>UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );</pre>
\r
888 * Return the number of free spaces available in a queue. This is equal to the
\r
889 * number of items that can be sent to the queue before the queue becomes full
\r
890 * if no items are removed.
\r
892 * @param xQueue A handle to the queue being queried.
\r
894 * @return The number of spaces available in the queue.
\r
896 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting
\r
897 * \ingroup QueueManagement
\r
899 UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
903 * <pre>void vQueueDelete( QueueHandle_t xQueue );</pre>
\r
905 * Delete a queue - freeing all the memory allocated for storing of items
\r
906 * placed on the queue.
\r
908 * @param xQueue A handle to the queue to be deleted.
\r
910 * \defgroup vQueueDelete vQueueDelete
\r
911 * \ingroup QueueManagement
\r
913 void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
918 BaseType_t xQueueSendToFrontFromISR(
\r
919 QueueHandle_t xQueue,
\r
920 const void *pvItemToQueue,
\r
921 BaseType_t *pxHigherPriorityTaskWoken
\r
925 * This is a macro that calls xQueueGenericSendFromISR().
\r
927 * Post an item to the front of a queue. It is safe to use this macro from
\r
928 * within an interrupt service routine.
\r
930 * Items are queued by copy not reference so it is preferable to only
\r
931 * queue small items, especially when called from an ISR. In most cases
\r
932 * it would be preferable to store a pointer to the item being queued.
\r
934 * @param xQueue The handle to the queue on which the item is to be posted.
\r
936 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
937 * queue. The size of the items the queue will hold was defined when the
\r
938 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
939 * into the queue storage area.
\r
941 * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set
\r
942 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
943 * to unblock, and the unblocked task has a priority higher than the currently
\r
944 * running task. If xQueueSendToFromFromISR() sets this value to pdTRUE then
\r
945 * a context switch should be requested before the interrupt is exited.
\r
947 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
950 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
953 void vBufferISR( void )
\r
956 BaseType_t xHigherPrioritTaskWoken;
\r
958 // We have not woken a task at the start of the ISR.
\r
959 xHigherPriorityTaskWoken = pdFALSE;
\r
961 // Loop until the buffer is empty.
\r
964 // Obtain a byte from the buffer.
\r
965 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
968 xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
970 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
972 // Now the buffer is empty we can switch context if necessary.
\r
973 if( xHigherPriorityTaskWoken )
\r
980 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
981 * \ingroup QueueManagement
\r
983 #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT )
\r
989 BaseType_t xQueueSendToBackFromISR(
\r
990 QueueHandle_t xQueue,
\r
991 const void *pvItemToQueue,
\r
992 BaseType_t *pxHigherPriorityTaskWoken
\r
996 * This is a macro that calls xQueueGenericSendFromISR().
\r
998 * Post an item to the back of a queue. It is safe to use this macro from
\r
999 * within an interrupt service routine.
\r
1001 * Items are queued by copy not reference so it is preferable to only
\r
1002 * queue small items, especially when called from an ISR. In most cases
\r
1003 * it would be preferable to store a pointer to the item being queued.
\r
1005 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1007 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1008 * queue. The size of the items the queue will hold was defined when the
\r
1009 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1010 * into the queue storage area.
\r
1012 * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set
\r
1013 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1014 * to unblock, and the unblocked task has a priority higher than the currently
\r
1015 * running task. If xQueueSendToBackFromISR() sets this value to pdTRUE then
\r
1016 * a context switch should be requested before the interrupt is exited.
\r
1018 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1021 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1024 void vBufferISR( void )
\r
1027 BaseType_t xHigherPriorityTaskWoken;
\r
1029 // We have not woken a task at the start of the ISR.
\r
1030 xHigherPriorityTaskWoken = pdFALSE;
\r
1032 // Loop until the buffer is empty.
\r
1035 // Obtain a byte from the buffer.
\r
1036 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1039 xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
1041 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1043 // Now the buffer is empty we can switch context if necessary.
\r
1044 if( xHigherPriorityTaskWoken )
\r
1051 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1052 * \ingroup QueueManagement
\r
1054 #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
\r
1059 BaseType_t xQueueOverwriteFromISR(
\r
1060 QueueHandle_t xQueue,
\r
1061 const void * pvItemToQueue,
\r
1062 BaseType_t *pxHigherPriorityTaskWoken
\r
1066 * A version of xQueueOverwrite() that can be used in an interrupt service
\r
1069 * Only for use with queues that can hold a single item - so the queue is either
\r
1072 * Post an item on a queue. If the queue is already full then overwrite the
\r
1073 * value held in the queue. The item is queued by copy, not by reference.
\r
1075 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1077 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1078 * queue. The size of the items the queue will hold was defined when the
\r
1079 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1080 * into the queue storage area.
\r
1082 * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set
\r
1083 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1084 * to unblock, and the unblocked task has a priority higher than the currently
\r
1085 * running task. If xQueueOverwriteFromISR() sets this value to pdTRUE then
\r
1086 * a context switch should be requested before the interrupt is exited.
\r
1088 * @return xQueueOverwriteFromISR() is a macro that calls
\r
1089 * xQueueGenericSendFromISR(), and therefore has the same return values as
\r
1090 * xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be
\r
1091 * returned because xQueueOverwriteFromISR() will write to the queue even when
\r
1092 * the queue is already full.
\r
1097 QueueHandle_t xQueue;
\r
1099 void vFunction( void *pvParameters )
\r
1101 // Create a queue to hold one uint32_t value. It is strongly
\r
1102 // recommended *not* to use xQueueOverwriteFromISR() on queues that can
\r
1103 // contain more than one value, and doing so will trigger an assertion
\r
1104 // if configASSERT() is defined.
\r
1105 xQueue = xQueueCreate( 1, sizeof( uint32_t ) );
\r
1108 void vAnInterruptHandler( void )
\r
1110 // xHigherPriorityTaskWoken must be set to pdFALSE before it is used.
\r
1111 BaseType_t xHigherPriorityTaskWoken = pdFALSE;
\r
1112 uint32_t ulVarToSend, ulValReceived;
\r
1114 // Write the value 10 to the queue using xQueueOverwriteFromISR().
\r
1116 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
\r
1118 // The queue is full, but calling xQueueOverwriteFromISR() again will still
\r
1119 // pass because the value held in the queue will be overwritten with the
\r
1121 ulVarToSend = 100;
\r
1122 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
\r
1124 // Reading from the queue will now return 100.
\r
1128 if( xHigherPrioritytaskWoken == pdTRUE )
\r
1130 // Writing to the queue caused a task to unblock and the unblocked task
\r
1131 // has a priority higher than or equal to the priority of the currently
\r
1132 // executing task (the task this interrupt interrupted). Perform a context
\r
1133 // switch so this interrupt returns directly to the unblocked task.
\r
1134 portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.
\r
1138 * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR
\r
1139 * \ingroup QueueManagement
\r
1141 #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE )
\r
1146 BaseType_t xQueueSendFromISR(
\r
1147 QueueHandle_t xQueue,
\r
1148 const void *pvItemToQueue,
\r
1149 BaseType_t *pxHigherPriorityTaskWoken
\r
1153 * This is a macro that calls xQueueGenericSendFromISR(). It is included
\r
1154 * for backward compatibility with versions of FreeRTOS.org that did not
\r
1155 * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()
\r
1158 * Post an item to the back of a queue. It is safe to use this function from
\r
1159 * within an interrupt service routine.
\r
1161 * Items are queued by copy not reference so it is preferable to only
\r
1162 * queue small items, especially when called from an ISR. In most cases
\r
1163 * it would be preferable to store a pointer to the item being queued.
\r
1165 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1167 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1168 * queue. The size of the items the queue will hold was defined when the
\r
1169 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1170 * into the queue storage area.
\r
1172 * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set
\r
1173 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1174 * to unblock, and the unblocked task has a priority higher than the currently
\r
1175 * running task. If xQueueSendFromISR() sets this value to pdTRUE then
\r
1176 * a context switch should be requested before the interrupt is exited.
\r
1178 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1181 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1184 void vBufferISR( void )
\r
1187 BaseType_t xHigherPriorityTaskWoken;
\r
1189 // We have not woken a task at the start of the ISR.
\r
1190 xHigherPriorityTaskWoken = pdFALSE;
\r
1192 // Loop until the buffer is empty.
\r
1195 // Obtain a byte from the buffer.
\r
1196 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1199 xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
\r
1201 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1203 // Now the buffer is empty we can switch context if necessary.
\r
1204 if( xHigherPriorityTaskWoken )
\r
1206 // Actual macro used here is port specific.
\r
1207 portYIELD_FROM_ISR ();
\r
1212 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1213 * \ingroup QueueManagement
\r
1215 #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK )
\r
1220 BaseType_t xQueueGenericSendFromISR(
\r
1221 QueueHandle_t xQueue,
\r
1222 const void *pvItemToQueue,
\r
1223 BaseType_t *pxHigherPriorityTaskWoken,
\r
1224 BaseType_t xCopyPosition
\r
1228 * It is preferred that the macros xQueueSendFromISR(),
\r
1229 * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place
\r
1230 * of calling this function directly. xQueueGiveFromISR() is an
\r
1231 * equivalent for use by semaphores that don't actually copy any data.
\r
1233 * Post an item on a queue. It is safe to use this function from within an
\r
1234 * interrupt service routine.
\r
1236 * Items are queued by copy not reference so it is preferable to only
\r
1237 * queue small items, especially when called from an ISR. In most cases
\r
1238 * it would be preferable to store a pointer to the item being queued.
\r
1240 * @param xQueue The handle to the queue on which the item is to be posted.
\r
1242 * @param pvItemToQueue A pointer to the item that is to be placed on the
\r
1243 * queue. The size of the items the queue will hold was defined when the
\r
1244 * queue was created, so this many bytes will be copied from pvItemToQueue
\r
1245 * into the queue storage area.
\r
1247 * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set
\r
1248 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
\r
1249 * to unblock, and the unblocked task has a priority higher than the currently
\r
1250 * running task. If xQueueGenericSendFromISR() sets this value to pdTRUE then
\r
1251 * a context switch should be requested before the interrupt is exited.
\r
1253 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
\r
1254 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
\r
1255 * at the front of the queue (for high priority messages).
\r
1257 * @return pdTRUE if the data was successfully sent to the queue, otherwise
\r
1260 * Example usage for buffered IO (where the ISR can obtain more than one value
\r
1263 void vBufferISR( void )
\r
1266 BaseType_t xHigherPriorityTaskWokenByPost;
\r
1268 // We have not woken a task at the start of the ISR.
\r
1269 xHigherPriorityTaskWokenByPost = pdFALSE;
\r
1271 // Loop until the buffer is empty.
\r
1274 // Obtain a byte from the buffer.
\r
1275 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
\r
1277 // Post each byte.
\r
1278 xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );
\r
1280 } while( portINPUT_BYTE( BUFFER_COUNT ) );
\r
1282 // Now the buffer is empty we can switch context if necessary. Note that the
\r
1283 // name of the yield function required is port specific.
\r
1284 if( xHigherPriorityTaskWokenByPost )
\r
1286 taskYIELD_YIELD_FROM_ISR();
\r
1291 * \defgroup xQueueSendFromISR xQueueSendFromISR
\r
1292 * \ingroup QueueManagement
\r
1294 BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, const void * const pvItemToQueue, BaseType_t * const pxHigherPriorityTaskWoken, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
\r
1295 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
1300 BaseType_t xQueueReceiveFromISR(
\r
1301 QueueHandle_t xQueue,
\r
1303 BaseType_t *pxTaskWoken
\r
1307 * Receive an item from a queue. It is safe to use this function from within an
\r
1308 * interrupt service routine.
\r
1310 * @param xQueue The handle to the queue from which the item is to be
\r
1313 * @param pvBuffer Pointer to the buffer into which the received item will
\r
1316 * @param pxTaskWoken A task may be blocked waiting for space to become
\r
1317 * available on the queue. If xQueueReceiveFromISR causes such a task to
\r
1318 * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will
\r
1319 * remain unchanged.
\r
1321 * @return pdTRUE if an item was successfully received from the queue,
\r
1322 * otherwise pdFALSE.
\r
1327 QueueHandle_t xQueue;
\r
1329 // Function to create a queue and post some values.
\r
1330 void vAFunction( void *pvParameters )
\r
1332 char cValueToPost;
\r
1333 const TickType_t xTicksToWait = ( TickType_t )0xff;
\r
1335 // Create a queue capable of containing 10 characters.
\r
1336 xQueue = xQueueCreate( 10, sizeof( char ) );
\r
1339 // Failed to create the queue.
\r
1344 // Post some characters that will be used within an ISR. If the queue
\r
1345 // is full then this task will block for xTicksToWait ticks.
\r
1346 cValueToPost = 'a';
\r
1347 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1348 cValueToPost = 'b';
\r
1349 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1351 // ... keep posting characters ... this task may block when the queue
\r
1354 cValueToPost = 'c';
\r
1355 xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
\r
1358 // ISR that outputs all the characters received on the queue.
\r
1359 void vISR_Routine( void )
\r
1361 BaseType_t xTaskWokenByReceive = pdFALSE;
\r
1364 while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )
\r
1366 // A character was received. Output the character now.
\r
1367 vOutputCharacter( cRxedChar );
\r
1369 // If removing the character from the queue woke the task that was
\r
1370 // posting onto the queue cTaskWokenByReceive will have been set to
\r
1371 // pdTRUE. No matter how many times this loop iterates only one
\r
1372 // task will be woken.
\r
1375 if( cTaskWokenByPost != ( char ) pdFALSE;
\r
1381 * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR
\r
1382 * \ingroup QueueManagement
\r
1384 BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue, void * const pvBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
\r
1387 * Utilities to query queues that are safe to use from an ISR. These utilities
\r
1388 * should be used only from witin an ISR, or within a critical section.
\r
1390 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1391 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1392 UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1395 * The functions defined above are for passing data to and from tasks. The
\r
1396 * functions below are the equivalents for passing data to and from
\r
1399 * These functions are called from the co-routine macro implementation and
\r
1400 * should not be called directly from application code. Instead use the macro
\r
1401 * wrappers defined within croutine.h.
\r
1403 BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t xCoRoutinePreviouslyWoken );
\r
1404 BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxTaskWoken );
\r
1405 BaseType_t xQueueCRSend( QueueHandle_t xQueue, const void *pvItemToQueue, TickType_t xTicksToWait );
\r
1406 BaseType_t xQueueCRReceive( QueueHandle_t xQueue, void *pvBuffer, TickType_t xTicksToWait );
\r
1409 * For internal use only. Use xSemaphoreCreateMutex(),
\r
1410 * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling
\r
1411 * these functions directly.
\r
1413 QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1414 QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION;
\r
1415 QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount ) PRIVILEGED_FUNCTION;
\r
1416 QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION;
\r
1417 BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1418 void* xQueueGetMutexHolder( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
\r
1419 void* xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION;
\r
1422 * For internal use only. Use xSemaphoreTakeMutexRecursive() or
\r
1423 * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.
\r
1425 BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1426 BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION;
\r
1429 * Reset a queue back to its original empty state. The return value is now
\r
1430 * obsolete and is always set to pdPASS.
\r
1432 #define xQueueReset( xQueue ) xQueueGenericReset( xQueue, pdFALSE )
\r
1435 * The registry is provided as a means for kernel aware debuggers to
\r
1436 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add
\r
1437 * a queue, semaphore or mutex handle to the registry if you want the handle
\r
1438 * to be available to a kernel aware debugger. If you are not using a kernel
\r
1439 * aware debugger then this function can be ignored.
\r
1441 * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the
\r
1442 * registry can hold. configQUEUE_REGISTRY_SIZE must be greater than 0
\r
1443 * within FreeRTOSConfig.h for the registry to be available. Its value
\r
1444 * does not effect the number of queues, semaphores and mutexes that can be
\r
1445 * created - just the number that the registry can hold.
\r
1447 * @param xQueue The handle of the queue being added to the registry. This
\r
1448 * is the handle returned by a call to xQueueCreate(). Semaphore and mutex
\r
1449 * handles can also be passed in here.
\r
1451 * @param pcName The name to be associated with the handle. This is the
\r
1452 * name that the kernel aware debugger will display. The queue registry only
\r
1453 * stores a pointer to the string - so the string must be persistent (global or
\r
1454 * preferably in ROM/Flash), not on the stack.
\r
1456 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1457 void vQueueAddToRegistry( QueueHandle_t xQueue, const char *pcQueueName ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
\r
1461 * The registry is provided as a means for kernel aware debuggers to
\r
1462 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add
\r
1463 * a queue, semaphore or mutex handle to the registry if you want the handle
\r
1464 * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to
\r
1465 * remove the queue, semaphore or mutex from the register. If you are not using
\r
1466 * a kernel aware debugger then this function can be ignored.
\r
1468 * @param xQueue The handle of the queue being removed from the registry.
\r
1470 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1471 void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1475 * The queue registry is provided as a means for kernel aware debuggers to
\r
1476 * locate queues, semaphores and mutexes. Call pcQueueGetName() to look
\r
1477 * up and return the name of a queue in the queue registry from the queue's
\r
1480 * @param xQueue The handle of the queue the name of which will be returned.
\r
1481 * @return If the queue is in the registry then a pointer to the name of the
\r
1482 * queue is returned. If the queue is not in the registry then NULL is
\r
1485 #if( configQUEUE_REGISTRY_SIZE > 0 )
\r
1486 const char *pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /*lint !e971 Unqualified char types are allowed for strings and single characters only. */
\r
1490 * Generic version of the function used to creaet a queue using dynamic memory
\r
1491 * allocation. This is called by other functions and macros that create other
\r
1492 * RTOS objects that use the queue structure as their base.
\r
1494 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
\r
1495 QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1499 * Generic version of the function used to creaet a queue using dynamic memory
\r
1500 * allocation. This is called by other functions and macros that create other
\r
1501 * RTOS objects that use the queue structure as their base.
\r
1503 #if( configSUPPORT_STATIC_ALLOCATION == 1 )
\r
1504 QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION;
\r
1508 * Queue sets provide a mechanism to allow a task to block (pend) on a read
\r
1509 * operation from multiple queues or semaphores simultaneously.
\r
1511 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1514 * A queue set must be explicitly created using a call to xQueueCreateSet()
\r
1515 * before it can be used. Once created, standard FreeRTOS queues and semaphores
\r
1516 * can be added to the set using calls to xQueueAddToSet().
\r
1517 * xQueueSelectFromSet() is then used to determine which, if any, of the queues
\r
1518 * or semaphores contained in the set is in a state where a queue read or
\r
1519 * semaphore take operation would be successful.
\r
1521 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html
\r
1522 * for reasons why queue sets are very rarely needed in practice as there are
\r
1523 * simpler methods of blocking on multiple objects.
\r
1525 * Note 2: Blocking on a queue set that contains a mutex will not cause the
\r
1526 * mutex holder to inherit the priority of the blocked task.
\r
1528 * Note 3: An additional 4 bytes of RAM is required for each space in a every
\r
1529 * queue added to a queue set. Therefore counting semaphores that have a high
\r
1530 * maximum count value should not be added to a queue set.
\r
1532 * Note 4: A receive (in the case of a queue) or take (in the case of a
\r
1533 * semaphore) operation must not be performed on a member of a queue set unless
\r
1534 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1536 * @param uxEventQueueLength Queue sets store events that occur on
\r
1537 * the queues and semaphores contained in the set. uxEventQueueLength specifies
\r
1538 * the maximum number of events that can be queued at once. To be absolutely
\r
1539 * certain that events are not lost uxEventQueueLength should be set to the
\r
1540 * total sum of the length of the queues added to the set, where binary
\r
1541 * semaphores and mutexes have a length of 1, and counting semaphores have a
\r
1542 * length set by their maximum count value. Examples:
\r
1543 * + If a queue set is to hold a queue of length 5, another queue of length 12,
\r
1544 * and a binary semaphore, then uxEventQueueLength should be set to
\r
1545 * (5 + 12 + 1), or 18.
\r
1546 * + If a queue set is to hold three binary semaphores then uxEventQueueLength
\r
1547 * should be set to (1 + 1 + 1 ), or 3.
\r
1548 * + If a queue set is to hold a counting semaphore that has a maximum count of
\r
1549 * 5, and a counting semaphore that has a maximum count of 3, then
\r
1550 * uxEventQueueLength should be set to (5 + 3), or 8.
\r
1552 * @return If the queue set is created successfully then a handle to the created
\r
1553 * queue set is returned. Otherwise NULL is returned.
\r
1555 QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION;
\r
1558 * Adds a queue or semaphore to a queue set that was previously created by a
\r
1559 * call to xQueueCreateSet().
\r
1561 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1564 * Note 1: A receive (in the case of a queue) or take (in the case of a
\r
1565 * semaphore) operation must not be performed on a member of a queue set unless
\r
1566 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1568 * @param xQueueOrSemaphore The handle of the queue or semaphore being added to
\r
1569 * the queue set (cast to an QueueSetMemberHandle_t type).
\r
1571 * @param xQueueSet The handle of the queue set to which the queue or semaphore
\r
1574 * @return If the queue or semaphore was successfully added to the queue set
\r
1575 * then pdPASS is returned. If the queue could not be successfully added to the
\r
1576 * queue set because it is already a member of a different queue set then pdFAIL
\r
1579 BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1582 * Removes a queue or semaphore from a queue set. A queue or semaphore can only
\r
1583 * be removed from a set if the queue or semaphore is empty.
\r
1585 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1588 * @param xQueueOrSemaphore The handle of the queue or semaphore being removed
\r
1589 * from the queue set (cast to an QueueSetMemberHandle_t type).
\r
1591 * @param xQueueSet The handle of the queue set in which the queue or semaphore
\r
1594 * @return If the queue or semaphore was successfully removed from the queue set
\r
1595 * then pdPASS is returned. If the queue was not in the queue set, or the
\r
1596 * queue (or semaphore) was not empty, then pdFAIL is returned.
\r
1598 BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1601 * xQueueSelectFromSet() selects from the members of a queue set a queue or
\r
1602 * semaphore that either contains data (in the case of a queue) or is available
\r
1603 * to take (in the case of a semaphore). xQueueSelectFromSet() effectively
\r
1604 * allows a task to block (pend) on a read operation on all the queues and
\r
1605 * semaphores in a queue set simultaneously.
\r
1607 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this
\r
1610 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html
\r
1611 * for reasons why queue sets are very rarely needed in practice as there are
\r
1612 * simpler methods of blocking on multiple objects.
\r
1614 * Note 2: Blocking on a queue set that contains a mutex will not cause the
\r
1615 * mutex holder to inherit the priority of the blocked task.
\r
1617 * Note 3: A receive (in the case of a queue) or take (in the case of a
\r
1618 * semaphore) operation must not be performed on a member of a queue set unless
\r
1619 * a call to xQueueSelectFromSet() has first returned a handle to that set member.
\r
1621 * @param xQueueSet The queue set on which the task will (potentially) block.
\r
1623 * @param xTicksToWait The maximum time, in ticks, that the calling task will
\r
1624 * remain in the Blocked state (with other tasks executing) to wait for a member
\r
1625 * of the queue set to be ready for a successful queue read or semaphore take
\r
1628 * @return xQueueSelectFromSet() will return the handle of a queue (cast to
\r
1629 * a QueueSetMemberHandle_t type) contained in the queue set that contains data,
\r
1630 * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained
\r
1631 * in the queue set that is available, or NULL if no such queue or semaphore
\r
1632 * exists before before the specified block time expires.
\r
1634 QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
\r
1637 * A version of xQueueSelectFromSet() that can be used from an ISR.
\r
1639 QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION;
\r
1641 /* Not public API functions. */
\r
1642 void vQueueWaitForMessageRestricted( QueueHandle_t xQueue, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION;
\r
1643 BaseType_t xQueueGenericReset( QueueHandle_t xQueue, BaseType_t xNewQueue ) PRIVILEGED_FUNCTION;
\r
1644 void vQueueSetQueueNumber( QueueHandle_t xQueue, UBaseType_t uxQueueNumber ) PRIVILEGED_FUNCTION;
\r
1645 UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1646 uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
\r
1649 #ifdef __cplusplus
\r
1653 #endif /* QUEUE_H */
\r
projects / freertos / blob