Rohit Grover
/
FreeRTOS
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: Nucleo freertos_test FreeRTOS_test freertos_bluetooth ... more
Embed:
(wiki syntax)
Show/hide line numbers
queue.h
00001 /* 00002 FreeRTOS V7.6.0 - Copyright (C) 2013 Real Time Engineers Ltd. 00003 All rights reserved 00004 00005 VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. 00006 00007 *************************************************************************** 00008 * * 00009 * FreeRTOS provides completely free yet professionally developed, * 00010 * robust, strictly quality controlled, supported, and cross * 00011 * platform software that has become a de facto standard. * 00012 * * 00013 * Help yourself get started quickly and support the FreeRTOS * 00014 * project by purchasing a FreeRTOS tutorial book, reference * 00015 * manual, or both from: http://www.FreeRTOS.org/Documentation * 00016 * * 00017 * Thank you! * 00018 * * 00019 *************************************************************************** 00020 00021 This file is part of the FreeRTOS distribution. 00022 00023 FreeRTOS is free software; you can redistribute it and/or modify it under 00024 the terms of the GNU General Public License (version 2) as published by the 00025 Free Software Foundation >>!AND MODIFIED BY!<< the FreeRTOS exception. 00026 00027 >>! NOTE: The modification to the GPL is included to allow you to distribute 00028 >>! a combined work that includes FreeRTOS without being obliged to provide 00029 >>! the source code for proprietary components outside of the FreeRTOS 00030 >>! kernel. 00031 00032 FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY 00033 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00034 FOR A PARTICULAR PURPOSE. Full license text is available from the following 00035 link: http://www.freertos.org/a00114.html 00036 00037 1 tab == 4 spaces! 00038 00039 *************************************************************************** 00040 * * 00041 * Having a problem? Start by reading the FAQ "My application does * 00042 * not run, what could be wrong?" * 00043 * * 00044 * http://www.FreeRTOS.org/FAQHelp.html * 00045 * * 00046 *************************************************************************** 00047 00048 http://www.FreeRTOS.org - Documentation, books, training, latest versions, 00049 license and Real Time Engineers Ltd. contact details. 00050 00051 http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, 00052 including FreeRTOS+Trace - an indispensable productivity tool, a DOS 00053 compatible FAT file system, and our tiny thread aware UDP/IP stack. 00054 00055 http://www.OpenRTOS.com - Real Time Engineers ltd license FreeRTOS to High 00056 Integrity Systems to sell under the OpenRTOS brand. Low cost OpenRTOS 00057 licenses offer ticketed support, indemnification and middleware. 00058 00059 http://www.SafeRTOS.com - High Integrity Systems also provide a safety 00060 engineered and independently SIL3 certified version for use in safety and 00061 mission critical applications that require provable dependability. 00062 00063 1 tab == 4 spaces! 00064 */ 00065 00066 00067 #ifndef QUEUE_H 00068 #define QUEUE_H 00069 00070 #ifndef INC_FREERTOS_H 00071 #error "include FreeRTOS.h" must appear in source files before "include queue.h" 00072 #endif 00073 00074 #ifdef __cplusplus 00075 extern "C" { 00076 #endif 00077 00078 00079 /** 00080 * Type by which queues are referenced. For example, a call to xQueueCreate() 00081 * returns an xQueueHandle variable that can then be used as a parameter to 00082 * xQueueSend(), xQueueReceive(), etc. 00083 */ 00084 typedef void * xQueueHandle; 00085 00086 /** 00087 * Type by which queue sets are referenced. For example, a call to 00088 * xQueueCreateSet() returns an xQueueSet variable that can then be used as a 00089 * parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc. 00090 */ 00091 typedef void * xQueueSetHandle; 00092 00093 /** 00094 * Queue sets can contain both queues and semaphores, so the 00095 * xQueueSetMemberHandle is defined as a type to be used where a parameter or 00096 * return value can be either an xQueueHandle or an xSemaphoreHandle. 00097 */ 00098 typedef void * xQueueSetMemberHandle; 00099 00100 /* For internal use only. */ 00101 #define queueSEND_TO_BACK ( ( portBASE_TYPE ) 0 ) 00102 #define queueSEND_TO_FRONT ( ( portBASE_TYPE ) 1 ) 00103 #define queueOVERWRITE ( ( portBASE_TYPE ) 2 ) 00104 00105 /* For internal use only. These definitions *must* match those in queue.c. */ 00106 #define queueQUEUE_TYPE_BASE ( ( unsigned char ) 0U ) 00107 #define queueQUEUE_TYPE_SET ( ( unsigned char ) 0U ) 00108 #define queueQUEUE_TYPE_MUTEX ( ( unsigned char ) 1U ) 00109 #define queueQUEUE_TYPE_COUNTING_SEMAPHORE ( ( unsigned char ) 2U ) 00110 #define queueQUEUE_TYPE_BINARY_SEMAPHORE ( ( unsigned char ) 3U ) 00111 #define queueQUEUE_TYPE_RECURSIVE_MUTEX ( ( unsigned char ) 4U ) 00112 00113 /** 00114 * queue. h 00115 * <pre> 00116 xQueueHandle xQueueCreate( 00117 unsigned portBASE_TYPE uxQueueLength, 00118 unsigned portBASE_TYPE uxItemSize 00119 ); 00120 * </pre> 00121 * 00122 * Creates a new queue instance. This allocates the storage required by the 00123 * new queue and returns a handle for the queue. 00124 * 00125 * @param uxQueueLength The maximum number of items that the queue can contain. 00126 * 00127 * @param uxItemSize The number of bytes each item in the queue will require. 00128 * Items are queued by copy, not by reference, so this is the number of bytes 00129 * that will be copied for each posted item. Each item on the queue must be 00130 * the same size. 00131 * 00132 * @return If the queue is successfully create then a handle to the newly 00133 * created queue is returned. If the queue cannot be created then 0 is 00134 * returned. 00135 * 00136 * Example usage: 00137 <pre> 00138 struct AMessage 00139 { 00140 char ucMessageID; 00141 char ucData[ 20 ]; 00142 }; 00143 00144 void vATask( void *pvParameters ) 00145 { 00146 xQueueHandle xQueue1, xQueue2; 00147 00148 // Create a queue capable of containing 10 unsigned long values. 00149 xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) ); 00150 if( xQueue1 == 0 ) 00151 { 00152 // Queue was not created and must not be used. 00153 } 00154 00155 // Create a queue capable of containing 10 pointers to AMessage structures. 00156 // These should be passed by pointer as they contain a lot of data. 00157 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00158 if( xQueue2 == 0 ) 00159 { 00160 // Queue was not created and must not be used. 00161 } 00162 00163 // ... Rest of task code. 00164 } 00165 </pre> 00166 * \defgroup xQueueCreate xQueueCreate 00167 * \ingroup QueueManagement 00168 */ 00169 #define xQueueCreate( uxQueueLength, uxItemSize ) xQueueGenericCreate( uxQueueLength, uxItemSize, queueQUEUE_TYPE_BASE ) 00170 00171 /** 00172 * queue. h 00173 * <pre> 00174 portBASE_TYPE xQueueSendToToFront( 00175 xQueueHandle xQueue, 00176 const void * pvItemToQueue, 00177 portTickType xTicksToWait 00178 ); 00179 * </pre> 00180 * 00181 * This is a macro that calls xQueueGenericSend(). 00182 * 00183 * Post an item to the front of a queue. The item is queued by copy, not by 00184 * reference. This function must not be called from an interrupt service 00185 * routine. See xQueueSendFromISR () for an alternative which may be used 00186 * in an ISR. 00187 * 00188 * @param xQueue The handle to the queue on which the item is to be posted. 00189 * 00190 * @param pvItemToQueue A pointer to the item that is to be placed on the 00191 * queue. The size of the items the queue will hold was defined when the 00192 * queue was created, so this many bytes will be copied from pvItemToQueue 00193 * into the queue storage area. 00194 * 00195 * @param xTicksToWait The maximum amount of time the task should block 00196 * waiting for space to become available on the queue, should it already 00197 * be full. The call will return immediately if this is set to 0 and the 00198 * queue is full. The time is defined in tick periods so the constant 00199 * portTICK_RATE_MS should be used to convert to real time if this is required. 00200 * 00201 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 00202 * 00203 * Example usage: 00204 <pre> 00205 struct AMessage 00206 { 00207 char ucMessageID; 00208 char ucData[ 20 ]; 00209 } xMessage; 00210 00211 unsigned long ulVar = 10UL; 00212 00213 void vATask( void *pvParameters ) 00214 { 00215 xQueueHandle xQueue1, xQueue2; 00216 struct AMessage *pxMessage; 00217 00218 // Create a queue capable of containing 10 unsigned long values. 00219 xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) ); 00220 00221 // Create a queue capable of containing 10 pointers to AMessage structures. 00222 // These should be passed by pointer as they contain a lot of data. 00223 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00224 00225 // ... 00226 00227 if( xQueue1 != 0 ) 00228 { 00229 // Send an unsigned long. Wait for 10 ticks for space to become 00230 // available if necessary. 00231 if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS ) 00232 { 00233 // Failed to post the message, even after 10 ticks. 00234 } 00235 } 00236 00237 if( xQueue2 != 0 ) 00238 { 00239 // Send a pointer to a struct AMessage object. Don't block if the 00240 // queue is already full. 00241 pxMessage = & xMessage; 00242 xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 ); 00243 } 00244 00245 // ... Rest of task code. 00246 } 00247 </pre> 00248 * \defgroup xQueueSend xQueueSend 00249 * \ingroup QueueManagement 00250 */ 00251 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT ) 00252 00253 /** 00254 * queue. h 00255 * <pre> 00256 portBASE_TYPE xQueueSendToBack( 00257 xQueueHandle xQueue, 00258 const void * pvItemToQueue, 00259 portTickType xTicksToWait 00260 ); 00261 * </pre> 00262 * 00263 * This is a macro that calls xQueueGenericSend(). 00264 * 00265 * Post an item to the back of a queue. The item is queued by copy, not by 00266 * reference. This function must not be called from an interrupt service 00267 * routine. See xQueueSendFromISR () for an alternative which may be used 00268 * in an ISR. 00269 * 00270 * @param xQueue The handle to the queue on which the item is to be posted. 00271 * 00272 * @param pvItemToQueue A pointer to the item that is to be placed on the 00273 * queue. The size of the items the queue will hold was defined when the 00274 * queue was created, so this many bytes will be copied from pvItemToQueue 00275 * into the queue storage area. 00276 * 00277 * @param xTicksToWait The maximum amount of time the task should block 00278 * waiting for space to become available on the queue, should it already 00279 * be full. The call will return immediately if this is set to 0 and the queue 00280 * is full. The time is defined in tick periods so the constant 00281 * portTICK_RATE_MS should be used to convert to real time if this is required. 00282 * 00283 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 00284 * 00285 * Example usage: 00286 <pre> 00287 struct AMessage 00288 { 00289 char ucMessageID; 00290 char ucData[ 20 ]; 00291 } xMessage; 00292 00293 unsigned long ulVar = 10UL; 00294 00295 void vATask( void *pvParameters ) 00296 { 00297 xQueueHandle xQueue1, xQueue2; 00298 struct AMessage *pxMessage; 00299 00300 // Create a queue capable of containing 10 unsigned long values. 00301 xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) ); 00302 00303 // Create a queue capable of containing 10 pointers to AMessage structures. 00304 // These should be passed by pointer as they contain a lot of data. 00305 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00306 00307 // ... 00308 00309 if( xQueue1 != 0 ) 00310 { 00311 // Send an unsigned long. Wait for 10 ticks for space to become 00312 // available if necessary. 00313 if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS ) 00314 { 00315 // Failed to post the message, even after 10 ticks. 00316 } 00317 } 00318 00319 if( xQueue2 != 0 ) 00320 { 00321 // Send a pointer to a struct AMessage object. Don't block if the 00322 // queue is already full. 00323 pxMessage = & xMessage; 00324 xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 ); 00325 } 00326 00327 // ... Rest of task code. 00328 } 00329 </pre> 00330 * \defgroup xQueueSend xQueueSend 00331 * \ingroup QueueManagement 00332 */ 00333 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) 00334 00335 /** 00336 * queue. h 00337 * <pre> 00338 portBASE_TYPE xQueueSend( 00339 xQueueHandle xQueue, 00340 const void * pvItemToQueue, 00341 portTickType xTicksToWait 00342 ); 00343 * </pre> 00344 * 00345 * This is a macro that calls xQueueGenericSend(). It is included for 00346 * backward compatibility with versions of FreeRTOS.org that did not 00347 * include the xQueueSendToFront() and xQueueSendToBack() macros. It is 00348 * equivalent to xQueueSendToBack(). 00349 * 00350 * Post an item on a queue. The item is queued by copy, not by reference. 00351 * This function must not be called from an interrupt service routine. 00352 * See xQueueSendFromISR () for an alternative which may be used in an ISR. 00353 * 00354 * @param xQueue The handle to the queue on which the item is to be posted. 00355 * 00356 * @param pvItemToQueue A pointer to the item that is to be placed on the 00357 * queue. The size of the items the queue will hold was defined when the 00358 * queue was created, so this many bytes will be copied from pvItemToQueue 00359 * into the queue storage area. 00360 * 00361 * @param xTicksToWait The maximum amount of time the task should block 00362 * waiting for space to become available on the queue, should it already 00363 * be full. The call will return immediately if this is set to 0 and the 00364 * queue is full. The time is defined in tick periods so the constant 00365 * portTICK_RATE_MS should be used to convert to real time if this is required. 00366 * 00367 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 00368 * 00369 * Example usage: 00370 <pre> 00371 struct AMessage 00372 { 00373 char ucMessageID; 00374 char ucData[ 20 ]; 00375 } xMessage; 00376 00377 unsigned long ulVar = 10UL; 00378 00379 void vATask( void *pvParameters ) 00380 { 00381 xQueueHandle xQueue1, xQueue2; 00382 struct AMessage *pxMessage; 00383 00384 // Create a queue capable of containing 10 unsigned long values. 00385 xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) ); 00386 00387 // Create a queue capable of containing 10 pointers to AMessage structures. 00388 // These should be passed by pointer as they contain a lot of data. 00389 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00390 00391 // ... 00392 00393 if( xQueue1 != 0 ) 00394 { 00395 // Send an unsigned long. Wait for 10 ticks for space to become 00396 // available if necessary. 00397 if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS ) 00398 { 00399 // Failed to post the message, even after 10 ticks. 00400 } 00401 } 00402 00403 if( xQueue2 != 0 ) 00404 { 00405 // Send a pointer to a struct AMessage object. Don't block if the 00406 // queue is already full. 00407 pxMessage = & xMessage; 00408 xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 ); 00409 } 00410 00411 // ... Rest of task code. 00412 } 00413 </pre> 00414 * \defgroup xQueueSend xQueueSend 00415 * \ingroup QueueManagement 00416 */ 00417 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) 00418 00419 /** 00420 * queue. h 00421 * <pre> 00422 portBASE_TYPE xQueueOverwrite( 00423 xQueueHandle xQueue, 00424 const void * pvItemToQueue 00425 ); 00426 * </pre> 00427 * 00428 * Only for use with queues that have a length of one - so the queue is either 00429 * empty or full. 00430 * 00431 * Post an item on a queue. If the queue is already full then overwrite the 00432 * value held in the queue. The item is queued by copy, not by reference. 00433 * 00434 * This function must not be called from an interrupt service routine. 00435 * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR. 00436 * 00437 * @param xQueue The handle of the queue to which the data is being sent. 00438 * 00439 * @param pvItemToQueue A pointer to the item that is to be placed on the 00440 * queue. The size of the items the queue will hold was defined when the 00441 * queue was created, so this many bytes will be copied from pvItemToQueue 00442 * into the queue storage area. 00443 * 00444 * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and 00445 * therefore has the same return values as xQueueSendToFront(). However, pdPASS 00446 * is the only value that can be returned because xQueueOverwrite() will write 00447 * to the queue even when the queue is already full. 00448 * 00449 * Example usage: 00450 <pre> 00451 00452 void vFunction( void *pvParameters ) 00453 { 00454 xQueueHandle xQueue; 00455 unsigned long ulVarToSend, ulValReceived; 00456 00457 // Create a queue to hold one unsigned long value. It is strongly 00458 // recommended *not* to use xQueueOverwrite() on queues that can 00459 // contain more than one value, and doing so will trigger an assertion 00460 // if configASSERT() is defined. 00461 xQueue = xQueueCreate( 1, sizeof( unsigned long ) ); 00462 00463 // Write the value 10 to the queue using xQueueOverwrite(). 00464 ulVarToSend = 10; 00465 xQueueOverwrite( xQueue, &ulVarToSend ); 00466 00467 // Peeking the queue should now return 10, but leave the value 10 in 00468 // the queue. A block time of zero is used as it is known that the 00469 // queue holds a value. 00470 ulValReceived = 0; 00471 xQueuePeek( xQueue, &ulValReceived, 0 ); 00472 00473 if( ulValReceived != 10 ) 00474 { 00475 // Error unless the item was removed by a different task. 00476 } 00477 00478 // The queue is still full. Use xQueueOverwrite() to overwrite the 00479 // value held in the queue with 100. 00480 ulVarToSend = 100; 00481 xQueueOverwrite( xQueue, &ulVarToSend ); 00482 00483 // This time read from the queue, leaving the queue empty once more. 00484 // A block time of 0 is used again. 00485 xQueueReceive( xQueue, &ulValReceived, 0 ); 00486 00487 // The value read should be the last value written, even though the 00488 // queue was already full when the value was written. 00489 if( ulValReceived != 100 ) 00490 { 00491 // Error! 00492 } 00493 00494 // ... 00495 } 00496 </pre> 00497 * \defgroup xQueueOverwrite xQueueOverwrite 00498 * \ingroup QueueManagement 00499 */ 00500 #define xQueueOverwrite( xQueue, pvItemToQueue ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE ) 00501 00502 00503 /** 00504 * queue. h 00505 * <pre> 00506 portBASE_TYPE xQueueGenericSend( 00507 xQueueHandle xQueue, 00508 const void * pvItemToQueue, 00509 portTickType xTicksToWait 00510 portBASE_TYPE xCopyPosition 00511 ); 00512 * </pre> 00513 * 00514 * It is preferred that the macros xQueueSend(), xQueueSendToFront() and 00515 * xQueueSendToBack() are used in place of calling this function directly. 00516 * 00517 * Post an item on a queue. The item is queued by copy, not by reference. 00518 * This function must not be called from an interrupt service routine. 00519 * See xQueueSendFromISR () for an alternative which may be used in an ISR. 00520 * 00521 * @param xQueue The handle to the queue on which the item is to be posted. 00522 * 00523 * @param pvItemToQueue A pointer to the item that is to be placed on the 00524 * queue. The size of the items the queue will hold was defined when the 00525 * queue was created, so this many bytes will be copied from pvItemToQueue 00526 * into the queue storage area. 00527 * 00528 * @param xTicksToWait The maximum amount of time the task should block 00529 * waiting for space to become available on the queue, should it already 00530 * be full. The call will return immediately if this is set to 0 and the 00531 * queue is full. The time is defined in tick periods so the constant 00532 * portTICK_RATE_MS should be used to convert to real time if this is required. 00533 * 00534 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the 00535 * item at the back of the queue, or queueSEND_TO_FRONT to place the item 00536 * at the front of the queue (for high priority messages). 00537 * 00538 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 00539 * 00540 * Example usage: 00541 <pre> 00542 struct AMessage 00543 { 00544 char ucMessageID; 00545 char ucData[ 20 ]; 00546 } xMessage; 00547 00548 unsigned long ulVar = 10UL; 00549 00550 void vATask( void *pvParameters ) 00551 { 00552 xQueueHandle xQueue1, xQueue2; 00553 struct AMessage *pxMessage; 00554 00555 // Create a queue capable of containing 10 unsigned long values. 00556 xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) ); 00557 00558 // Create a queue capable of containing 10 pointers to AMessage structures. 00559 // These should be passed by pointer as they contain a lot of data. 00560 xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00561 00562 // ... 00563 00564 if( xQueue1 != 0 ) 00565 { 00566 // Send an unsigned long. Wait for 10 ticks for space to become 00567 // available if necessary. 00568 if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10, queueSEND_TO_BACK ) != pdPASS ) 00569 { 00570 // Failed to post the message, even after 10 ticks. 00571 } 00572 } 00573 00574 if( xQueue2 != 0 ) 00575 { 00576 // Send a pointer to a struct AMessage object. Don't block if the 00577 // queue is already full. 00578 pxMessage = & xMessage; 00579 xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0, queueSEND_TO_BACK ); 00580 } 00581 00582 // ... Rest of task code. 00583 } 00584 </pre> 00585 * \defgroup xQueueSend xQueueSend 00586 * \ingroup QueueManagement 00587 */ 00588 signed portBASE_TYPE xQueueGenericSend( xQueueHandle xQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition ) PRIVILEGED_FUNCTION; 00589 00590 /** 00591 * queue. h 00592 * <pre> 00593 portBASE_TYPE xQueuePeek( 00594 xQueueHandle xQueue, 00595 void *pvBuffer, 00596 portTickType xTicksToWait 00597 );</pre> 00598 * 00599 * This is a macro that calls the xQueueGenericReceive() function. 00600 * 00601 * Receive an item from a queue without removing the item from the queue. 00602 * The item is received by copy so a buffer of adequate size must be 00603 * provided. The number of bytes copied into the buffer was defined when 00604 * the queue was created. 00605 * 00606 * Successfully received items remain on the queue so will be returned again 00607 * by the next call, or a call to xQueueReceive(). 00608 * 00609 * This macro must not be used in an interrupt service routine. See 00610 * xQueuePeekFromISR() for an alternative that can be called from an interrupt 00611 * service routine. 00612 * 00613 * @param xQueue The handle to the queue from which the item is to be 00614 * received. 00615 * 00616 * @param pvBuffer Pointer to the buffer into which the received item will 00617 * be copied. 00618 * 00619 * @param xTicksToWait The maximum amount of time the task should block 00620 * waiting for an item to receive should the queue be empty at the time 00621 * of the call. The time is defined in tick periods so the constant 00622 * portTICK_RATE_MS should be used to convert to real time if this is required. 00623 * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue 00624 * is empty. 00625 * 00626 * @return pdTRUE if an item was successfully received from the queue, 00627 * otherwise pdFALSE. 00628 * 00629 * Example usage: 00630 <pre> 00631 struct AMessage 00632 { 00633 char ucMessageID; 00634 char ucData[ 20 ]; 00635 } xMessage; 00636 00637 xQueueHandle xQueue; 00638 00639 // Task to create a queue and post a value. 00640 void vATask( void *pvParameters ) 00641 { 00642 struct AMessage *pxMessage; 00643 00644 // Create a queue capable of containing 10 pointers to AMessage structures. 00645 // These should be passed by pointer as they contain a lot of data. 00646 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00647 if( xQueue == 0 ) 00648 { 00649 // Failed to create the queue. 00650 } 00651 00652 // ... 00653 00654 // Send a pointer to a struct AMessage object. Don't block if the 00655 // queue is already full. 00656 pxMessage = & xMessage; 00657 xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 ); 00658 00659 // ... Rest of task code. 00660 } 00661 00662 // Task to peek the data from the queue. 00663 void vADifferentTask( void *pvParameters ) 00664 { 00665 struct AMessage *pxRxedMessage; 00666 00667 if( xQueue != 0 ) 00668 { 00669 // Peek a message on the created queue. Block for 10 ticks if a 00670 // message is not immediately available. 00671 if( xQueuePeek( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) ) 00672 { 00673 // pcRxedMessage now points to the struct AMessage variable posted 00674 // by vATask, but the item still remains on the queue. 00675 } 00676 } 00677 00678 // ... Rest of task code. 00679 } 00680 </pre> 00681 * \defgroup xQueueReceive xQueueReceive 00682 * \ingroup QueueManagement 00683 */ 00684 #define xQueuePeek( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdTRUE ) 00685 00686 /** 00687 * queue. h 00688 * <pre> 00689 portBASE_TYPE xQueuePeekFromISR( 00690 xQueueHandle xQueue, 00691 void *pvBuffer, 00692 );</pre> 00693 * 00694 * A version of xQueuePeek() that can be called from an interrupt service 00695 * routine (ISR). 00696 * 00697 * Receive an item from a queue without removing the item from the queue. 00698 * The item is received by copy so a buffer of adequate size must be 00699 * provided. The number of bytes copied into the buffer was defined when 00700 * the queue was created. 00701 * 00702 * Successfully received items remain on the queue so will be returned again 00703 * by the next call, or a call to xQueueReceive(). 00704 * 00705 * @param xQueue The handle to the queue from which the item is to be 00706 * received. 00707 * 00708 * @param pvBuffer Pointer to the buffer into which the received item will 00709 * be copied. 00710 * 00711 * @return pdTRUE if an item was successfully received from the queue, 00712 * otherwise pdFALSE. 00713 * 00714 * \defgroup xQueuePeekFromISR xQueuePeekFromISR 00715 * \ingroup QueueManagement 00716 */ 00717 signed portBASE_TYPE xQueuePeekFromISR( xQueueHandle xQueue, void * const pvBuffer ) PRIVILEGED_FUNCTION; 00718 00719 /** 00720 * queue. h 00721 * <pre> 00722 portBASE_TYPE xQueueReceive( 00723 xQueueHandle xQueue, 00724 void *pvBuffer, 00725 portTickType xTicksToWait 00726 );</pre> 00727 * 00728 * This is a macro that calls the xQueueGenericReceive() function. 00729 * 00730 * Receive an item from a queue. The item is received by copy so a buffer of 00731 * adequate size must be provided. The number of bytes copied into the buffer 00732 * was defined when the queue was created. 00733 * 00734 * Successfully received items are removed from the queue. 00735 * 00736 * This function must not be used in an interrupt service routine. See 00737 * xQueueReceiveFromISR for an alternative that can. 00738 * 00739 * @param xQueue The handle to the queue from which the item is to be 00740 * received. 00741 * 00742 * @param pvBuffer Pointer to the buffer into which the received item will 00743 * be copied. 00744 * 00745 * @param xTicksToWait The maximum amount of time the task should block 00746 * waiting for an item to receive should the queue be empty at the time 00747 * of the call. xQueueReceive() will return immediately if xTicksToWait 00748 * is zero and the queue is empty. The time is defined in tick periods so the 00749 * constant portTICK_RATE_MS should be used to convert to real time if this is 00750 * required. 00751 * 00752 * @return pdTRUE if an item was successfully received from the queue, 00753 * otherwise pdFALSE. 00754 * 00755 * Example usage: 00756 <pre> 00757 struct AMessage 00758 { 00759 char ucMessageID; 00760 char ucData[ 20 ]; 00761 } xMessage; 00762 00763 xQueueHandle xQueue; 00764 00765 // Task to create a queue and post a value. 00766 void vATask( void *pvParameters ) 00767 { 00768 struct AMessage *pxMessage; 00769 00770 // Create a queue capable of containing 10 pointers to AMessage structures. 00771 // These should be passed by pointer as they contain a lot of data. 00772 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00773 if( xQueue == 0 ) 00774 { 00775 // Failed to create the queue. 00776 } 00777 00778 // ... 00779 00780 // Send a pointer to a struct AMessage object. Don't block if the 00781 // queue is already full. 00782 pxMessage = & xMessage; 00783 xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 ); 00784 00785 // ... Rest of task code. 00786 } 00787 00788 // Task to receive from the queue. 00789 void vADifferentTask( void *pvParameters ) 00790 { 00791 struct AMessage *pxRxedMessage; 00792 00793 if( xQueue != 0 ) 00794 { 00795 // Receive a message on the created queue. Block for 10 ticks if a 00796 // message is not immediately available. 00797 if( xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) ) 00798 { 00799 // pcRxedMessage now points to the struct AMessage variable posted 00800 // by vATask. 00801 } 00802 } 00803 00804 // ... Rest of task code. 00805 } 00806 </pre> 00807 * \defgroup xQueueReceive xQueueReceive 00808 * \ingroup QueueManagement 00809 */ 00810 #define xQueueReceive( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdFALSE ) 00811 00812 00813 /** 00814 * queue. h 00815 * <pre> 00816 portBASE_TYPE xQueueGenericReceive( 00817 xQueueHandle xQueue, 00818 void *pvBuffer, 00819 portTickType xTicksToWait 00820 portBASE_TYPE xJustPeek 00821 );</pre> 00822 * 00823 * It is preferred that the macro xQueueReceive() be used rather than calling 00824 * this function directly. 00825 * 00826 * Receive an item from a queue. The item is received by copy so a buffer of 00827 * adequate size must be provided. The number of bytes copied into the buffer 00828 * was defined when the queue was created. 00829 * 00830 * This function must not be used in an interrupt service routine. See 00831 * xQueueReceiveFromISR for an alternative that can. 00832 * 00833 * @param xQueue The handle to the queue from which the item is to be 00834 * received. 00835 * 00836 * @param pvBuffer Pointer to the buffer into which the received item will 00837 * be copied. 00838 * 00839 * @param xTicksToWait The maximum amount of time the task should block 00840 * waiting for an item to receive should the queue be empty at the time 00841 * of the call. The time is defined in tick periods so the constant 00842 * portTICK_RATE_MS should be used to convert to real time if this is required. 00843 * xQueueGenericReceive() will return immediately if the queue is empty and 00844 * xTicksToWait is 0. 00845 * 00846 * @param xJustPeek When set to true, the item received from the queue is not 00847 * actually removed from the queue - meaning a subsequent call to 00848 * xQueueReceive() will return the same item. When set to false, the item 00849 * being received from the queue is also removed from the queue. 00850 * 00851 * @return pdTRUE if an item was successfully received from the queue, 00852 * otherwise pdFALSE. 00853 * 00854 * Example usage: 00855 <pre> 00856 struct AMessage 00857 { 00858 char ucMessageID; 00859 char ucData[ 20 ]; 00860 } xMessage; 00861 00862 xQueueHandle xQueue; 00863 00864 // Task to create a queue and post a value. 00865 void vATask( void *pvParameters ) 00866 { 00867 struct AMessage *pxMessage; 00868 00869 // Create a queue capable of containing 10 pointers to AMessage structures. 00870 // These should be passed by pointer as they contain a lot of data. 00871 xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); 00872 if( xQueue == 0 ) 00873 { 00874 // Failed to create the queue. 00875 } 00876 00877 // ... 00878 00879 // Send a pointer to a struct AMessage object. Don't block if the 00880 // queue is already full. 00881 pxMessage = & xMessage; 00882 xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 ); 00883 00884 // ... Rest of task code. 00885 } 00886 00887 // Task to receive from the queue. 00888 void vADifferentTask( void *pvParameters ) 00889 { 00890 struct AMessage *pxRxedMessage; 00891 00892 if( xQueue != 0 ) 00893 { 00894 // Receive a message on the created queue. Block for 10 ticks if a 00895 // message is not immediately available. 00896 if( xQueueGenericReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) ) 00897 { 00898 // pcRxedMessage now points to the struct AMessage variable posted 00899 // by vATask. 00900 } 00901 } 00902 00903 // ... Rest of task code. 00904 } 00905 </pre> 00906 * \defgroup xQueueReceive xQueueReceive 00907 * \ingroup QueueManagement 00908 */ 00909 signed portBASE_TYPE xQueueGenericReceive( xQueueHandle xQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeek ) PRIVILEGED_FUNCTION; 00910 00911 /** 00912 * queue. h 00913 * <pre>unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );</pre> 00914 * 00915 * Return the number of messages stored in a queue. 00916 * 00917 * @param xQueue A handle to the queue being queried. 00918 * 00919 * @return The number of messages available in the queue. 00920 * 00921 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting 00922 * \ingroup QueueManagement 00923 */ 00924 unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 00925 00926 /** 00927 * queue. h 00928 * <pre>unsigned portBASE_TYPE uxQueueSpacesAvailable( const xQueueHandle xQueue );</pre> 00929 * 00930 * Return the number of free spaces available in a queue. This is equal to the 00931 * number of items that can be sent to the queue before the queue becomes full 00932 * if no items are removed. 00933 * 00934 * @param xQueue A handle to the queue being queried. 00935 * 00936 * @return The number of spaces available in the queue. 00937 * 00938 * \defgroup uxQueueMessagesWaiting uxQueueMessagesWaiting 00939 * \ingroup QueueManagement 00940 */ 00941 unsigned portBASE_TYPE uxQueueSpacesAvailable( const xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 00942 00943 /** 00944 * queue. h 00945 * <pre>void vQueueDelete( xQueueHandle xQueue );</pre> 00946 * 00947 * Delete a queue - freeing all the memory allocated for storing of items 00948 * placed on the queue. 00949 * 00950 * @param xQueue A handle to the queue to be deleted. 00951 * 00952 * \defgroup vQueueDelete vQueueDelete 00953 * \ingroup QueueManagement 00954 */ 00955 void vQueueDelete( xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 00956 00957 /** 00958 * queue. h 00959 * <pre> 00960 portBASE_TYPE xQueueSendToFrontFromISR( 00961 xQueueHandle xQueue, 00962 const void *pvItemToQueue, 00963 portBASE_TYPE *pxHigherPriorityTaskWoken 00964 ); 00965 </pre> 00966 * 00967 * This is a macro that calls xQueueGenericSendFromISR(). 00968 * 00969 * Post an item to the front of a queue. It is safe to use this macro from 00970 * within an interrupt service routine. 00971 * 00972 * Items are queued by copy not reference so it is preferable to only 00973 * queue small items, especially when called from an ISR. In most cases 00974 * it would be preferable to store a pointer to the item being queued. 00975 * 00976 * @param xQueue The handle to the queue on which the item is to be posted. 00977 * 00978 * @param pvItemToQueue A pointer to the item that is to be placed on the 00979 * queue. The size of the items the queue will hold was defined when the 00980 * queue was created, so this many bytes will be copied from pvItemToQueue 00981 * into the queue storage area. 00982 * 00983 * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set 00984 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 00985 * to unblock, and the unblocked task has a priority higher than the currently 00986 * running task. If xQueueSendToFromFromISR() sets this value to pdTRUE then 00987 * a context switch should be requested before the interrupt is exited. 00988 * 00989 * @return pdTRUE if the data was successfully sent to the queue, otherwise 00990 * errQUEUE_FULL. 00991 * 00992 * Example usage for buffered IO (where the ISR can obtain more than one value 00993 * per call): 00994 <pre> 00995 void vBufferISR( void ) 00996 { 00997 char cIn; 00998 portBASE_TYPE xHigherPrioritTaskWoken; 00999 01000 // We have not woken a task at the start of the ISR. 01001 xHigherPriorityTaskWoken = pdFALSE; 01002 01003 // Loop until the buffer is empty. 01004 do 01005 { 01006 // Obtain a byte from the buffer. 01007 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 01008 01009 // Post the byte. 01010 xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 01011 01012 } while( portINPUT_BYTE( BUFFER_COUNT ) ); 01013 01014 // Now the buffer is empty we can switch context if necessary. 01015 if( xHigherPriorityTaskWoken ) 01016 { 01017 taskYIELD (); 01018 } 01019 } 01020 </pre> 01021 * 01022 * \defgroup xQueueSendFromISR xQueueSendFromISR 01023 * \ingroup QueueManagement 01024 */ 01025 #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT ) 01026 01027 01028 /** 01029 * queue. h 01030 * <pre> 01031 portBASE_TYPE xQueueSendToBackFromISR( 01032 xQueueHandle xQueue, 01033 const void *pvItemToQueue, 01034 portBASE_TYPE *pxHigherPriorityTaskWoken 01035 ); 01036 </pre> 01037 * 01038 * This is a macro that calls xQueueGenericSendFromISR(). 01039 * 01040 * Post an item to the back of a queue. It is safe to use this macro from 01041 * within an interrupt service routine. 01042 * 01043 * Items are queued by copy not reference so it is preferable to only 01044 * queue small items, especially when called from an ISR. In most cases 01045 * it would be preferable to store a pointer to the item being queued. 01046 * 01047 * @param xQueue The handle to the queue on which the item is to be posted. 01048 * 01049 * @param pvItemToQueue A pointer to the item that is to be placed on the 01050 * queue. The size of the items the queue will hold was defined when the 01051 * queue was created, so this many bytes will be copied from pvItemToQueue 01052 * into the queue storage area. 01053 * 01054 * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set 01055 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 01056 * to unblock, and the unblocked task has a priority higher than the currently 01057 * running task. If xQueueSendToBackFromISR() sets this value to pdTRUE then 01058 * a context switch should be requested before the interrupt is exited. 01059 * 01060 * @return pdTRUE if the data was successfully sent to the queue, otherwise 01061 * errQUEUE_FULL. 01062 * 01063 * Example usage for buffered IO (where the ISR can obtain more than one value 01064 * per call): 01065 <pre> 01066 void vBufferISR( void ) 01067 { 01068 char cIn; 01069 portBASE_TYPE xHigherPriorityTaskWoken; 01070 01071 // We have not woken a task at the start of the ISR. 01072 xHigherPriorityTaskWoken = pdFALSE; 01073 01074 // Loop until the buffer is empty. 01075 do 01076 { 01077 // Obtain a byte from the buffer. 01078 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 01079 01080 // Post the byte. 01081 xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 01082 01083 } while( portINPUT_BYTE( BUFFER_COUNT ) ); 01084 01085 // Now the buffer is empty we can switch context if necessary. 01086 if( xHigherPriorityTaskWoken ) 01087 { 01088 taskYIELD (); 01089 } 01090 } 01091 </pre> 01092 * 01093 * \defgroup xQueueSendFromISR xQueueSendFromISR 01094 * \ingroup QueueManagement 01095 */ 01096 #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) 01097 01098 /** 01099 * queue. h 01100 * <pre> 01101 portBASE_TYPE xQueueOverwriteFromISR( 01102 xQueueHandle xQueue, 01103 const void * pvItemToQueue, 01104 portBASE_TYPE *pxHigherPriorityTaskWoken 01105 ); 01106 * </pre> 01107 * 01108 * A version of xQueueOverwrite() that can be used in an interrupt service 01109 * routine (ISR). 01110 * 01111 * Only for use with queues that can hold a single item - so the queue is either 01112 * empty or full. 01113 * 01114 * Post an item on a queue. If the queue is already full then overwrite the 01115 * value held in the queue. The item is queued by copy, not by reference. 01116 * 01117 * @param xQueue The handle to the queue on which the item is to be posted. 01118 * 01119 * @param pvItemToQueue A pointer to the item that is to be placed on the 01120 * queue. The size of the items the queue will hold was defined when the 01121 * queue was created, so this many bytes will be copied from pvItemToQueue 01122 * into the queue storage area. 01123 * 01124 * @param pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set 01125 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 01126 * to unblock, and the unblocked task has a priority higher than the currently 01127 * running task. If xQueueOverwriteFromISR() sets this value to pdTRUE then 01128 * a context switch should be requested before the interrupt is exited. 01129 * 01130 * @return xQueueOverwriteFromISR() is a macro that calls 01131 * xQueueGenericSendFromISR(), and therefore has the same return values as 01132 * xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be 01133 * returned because xQueueOverwriteFromISR() will write to the queue even when 01134 * the queue is already full. 01135 * 01136 * Example usage: 01137 <pre> 01138 01139 xQueueHandle xQueue; 01140 01141 void vFunction( void *pvParameters ) 01142 { 01143 // Create a queue to hold one unsigned long value. It is strongly 01144 // recommended *not* to use xQueueOverwriteFromISR() on queues that can 01145 // contain more than one value, and doing so will trigger an assertion 01146 // if configASSERT() is defined. 01147 xQueue = xQueueCreate( 1, sizeof( unsigned long ) ); 01148 } 01149 01150 void vAnInterruptHandler( void ) 01151 { 01152 // xHigherPriorityTaskWoken must be set to pdFALSE before it is used. 01153 portBASE_TYPE xHigherPriorityTaskWoken = pdFALSE; 01154 unsigned long ulVarToSend, ulValReceived; 01155 01156 // Write the value 10 to the queue using xQueueOverwriteFromISR(). 01157 ulVarToSend = 10; 01158 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken ); 01159 01160 // The queue is full, but calling xQueueOverwriteFromISR() again will still 01161 // pass because the value held in the queue will be overwritten with the 01162 // new value. 01163 ulVarToSend = 100; 01164 xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken ); 01165 01166 // Reading from the queue will now return 100. 01167 01168 // ... 01169 01170 if( xHigherPrioritytaskWoken == pdTRUE ) 01171 { 01172 // Writing to the queue caused a task to unblock and the unblocked task 01173 // has a priority higher than or equal to the priority of the currently 01174 // executing task (the task this interrupt interrupted). Perform a context 01175 // switch so this interrupt returns directly to the unblocked task. 01176 portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port. 01177 } 01178 } 01179 </pre> 01180 * \defgroup xQueueOverwriteFromISR xQueueOverwriteFromISR 01181 * \ingroup QueueManagement 01182 */ 01183 #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE ) 01184 01185 /** 01186 * queue. h 01187 * <pre> 01188 portBASE_TYPE xQueueSendFromISR( 01189 xQueueHandle xQueue, 01190 const void *pvItemToQueue, 01191 portBASE_TYPE *pxHigherPriorityTaskWoken 01192 ); 01193 </pre> 01194 * 01195 * This is a macro that calls xQueueGenericSendFromISR(). It is included 01196 * for backward compatibility with versions of FreeRTOS.org that did not 01197 * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR() 01198 * macros. 01199 * 01200 * Post an item to the back of a queue. It is safe to use this function from 01201 * within an interrupt service routine. 01202 * 01203 * Items are queued by copy not reference so it is preferable to only 01204 * queue small items, especially when called from an ISR. In most cases 01205 * it would be preferable to store a pointer to the item being queued. 01206 * 01207 * @param xQueue The handle to the queue on which the item is to be posted. 01208 * 01209 * @param pvItemToQueue A pointer to the item that is to be placed on the 01210 * queue. The size of the items the queue will hold was defined when the 01211 * queue was created, so this many bytes will be copied from pvItemToQueue 01212 * into the queue storage area. 01213 * 01214 * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set 01215 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 01216 * to unblock, and the unblocked task has a priority higher than the currently 01217 * running task. If xQueueSendFromISR() sets this value to pdTRUE then 01218 * a context switch should be requested before the interrupt is exited. 01219 * 01220 * @return pdTRUE if the data was successfully sent to the queue, otherwise 01221 * errQUEUE_FULL. 01222 * 01223 * Example usage for buffered IO (where the ISR can obtain more than one value 01224 * per call): 01225 <pre> 01226 void vBufferISR( void ) 01227 { 01228 char cIn; 01229 portBASE_TYPE xHigherPriorityTaskWoken; 01230 01231 // We have not woken a task at the start of the ISR. 01232 xHigherPriorityTaskWoken = pdFALSE; 01233 01234 // Loop until the buffer is empty. 01235 do 01236 { 01237 // Obtain a byte from the buffer. 01238 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 01239 01240 // Post the byte. 01241 xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 01242 01243 } while( portINPUT_BYTE( BUFFER_COUNT ) ); 01244 01245 // Now the buffer is empty we can switch context if necessary. 01246 if( xHigherPriorityTaskWoken ) 01247 { 01248 // Actual macro used here is port specific. 01249 portYIELD_FROM_ISR (); 01250 } 01251 } 01252 </pre> 01253 * 01254 * \defgroup xQueueSendFromISR xQueueSendFromISR 01255 * \ingroup QueueManagement 01256 */ 01257 #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) 01258 01259 /** 01260 * queue. h 01261 * <pre> 01262 portBASE_TYPE xQueueGenericSendFromISR( 01263 xQueueHandle xQueue, 01264 const void *pvItemToQueue, 01265 portBASE_TYPE *pxHigherPriorityTaskWoken, 01266 portBASE_TYPE xCopyPosition 01267 ); 01268 </pre> 01269 * 01270 * It is preferred that the macros xQueueSendFromISR(), 01271 * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place 01272 * of calling this function directly. 01273 * 01274 * Post an item on a queue. It is safe to use this function from within an 01275 * interrupt service routine. 01276 * 01277 * Items are queued by copy not reference so it is preferable to only 01278 * queue small items, especially when called from an ISR. In most cases 01279 * it would be preferable to store a pointer to the item being queued. 01280 * 01281 * @param xQueue The handle to the queue on which the item is to be posted. 01282 * 01283 * @param pvItemToQueue A pointer to the item that is to be placed on the 01284 * queue. The size of the items the queue will hold was defined when the 01285 * queue was created, so this many bytes will be copied from pvItemToQueue 01286 * into the queue storage area. 01287 * 01288 * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set 01289 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 01290 * to unblock, and the unblocked task has a priority higher than the currently 01291 * running task. If xQueueGenericSendFromISR() sets this value to pdTRUE then 01292 * a context switch should be requested before the interrupt is exited. 01293 * 01294 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the 01295 * item at the back of the queue, or queueSEND_TO_FRONT to place the item 01296 * at the front of the queue (for high priority messages). 01297 * 01298 * @return pdTRUE if the data was successfully sent to the queue, otherwise 01299 * errQUEUE_FULL. 01300 * 01301 * Example usage for buffered IO (where the ISR can obtain more than one value 01302 * per call): 01303 <pre> 01304 void vBufferISR( void ) 01305 { 01306 char cIn; 01307 portBASE_TYPE xHigherPriorityTaskWokenByPost; 01308 01309 // We have not woken a task at the start of the ISR. 01310 xHigherPriorityTaskWokenByPost = pdFALSE; 01311 01312 // Loop until the buffer is empty. 01313 do 01314 { 01315 // Obtain a byte from the buffer. 01316 cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 01317 01318 // Post each byte. 01319 xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK ); 01320 01321 } while( portINPUT_BYTE( BUFFER_COUNT ) ); 01322 01323 // Now the buffer is empty we can switch context if necessary. Note that the 01324 // name of the yield function required is port specific. 01325 if( xHigherPriorityTaskWokenByPost ) 01326 { 01327 taskYIELD_YIELD_FROM_ISR(); 01328 } 01329 } 01330 </pre> 01331 * 01332 * \defgroup xQueueSendFromISR xQueueSendFromISR 01333 * \ingroup QueueManagement 01334 */ 01335 signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle xQueue, const void * const pvItemToQueue, signed portBASE_TYPE *pxHigherPriorityTaskWoken, portBASE_TYPE xCopyPosition ) PRIVILEGED_FUNCTION; 01336 01337 /** 01338 * queue. h 01339 * <pre> 01340 portBASE_TYPE xQueueReceiveFromISR( 01341 xQueueHandle xQueue, 01342 void *pvBuffer, 01343 portBASE_TYPE *pxTaskWoken 01344 ); 01345 * </pre> 01346 * 01347 * Receive an item from a queue. It is safe to use this function from within an 01348 * interrupt service routine. 01349 * 01350 * @param xQueue The handle to the queue from which the item is to be 01351 * received. 01352 * 01353 * @param pvBuffer Pointer to the buffer into which the received item will 01354 * be copied. 01355 * 01356 * @param pxTaskWoken A task may be blocked waiting for space to become 01357 * available on the queue. If xQueueReceiveFromISR causes such a task to 01358 * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will 01359 * remain unchanged. 01360 * 01361 * @return pdTRUE if an item was successfully received from the queue, 01362 * otherwise pdFALSE. 01363 * 01364 * Example usage: 01365 <pre> 01366 01367 xQueueHandle xQueue; 01368 01369 // Function to create a queue and post some values. 01370 void vAFunction( void *pvParameters ) 01371 { 01372 char cValueToPost; 01373 const portTickType xBlockTime = ( portTickType )0xff; 01374 01375 // Create a queue capable of containing 10 characters. 01376 xQueue = xQueueCreate( 10, sizeof( char ) ); 01377 if( xQueue == 0 ) 01378 { 01379 // Failed to create the queue. 01380 } 01381 01382 // ... 01383 01384 // Post some characters that will be used within an ISR. If the queue 01385 // is full then this task will block for xBlockTime ticks. 01386 cValueToPost = 'a'; 01387 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime ); 01388 cValueToPost = 'b'; 01389 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime ); 01390 01391 // ... keep posting characters ... this task may block when the queue 01392 // becomes full. 01393 01394 cValueToPost = 'c'; 01395 xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime ); 01396 } 01397 01398 // ISR that outputs all the characters received on the queue. 01399 void vISR_Routine( void ) 01400 { 01401 portBASE_TYPE xTaskWokenByReceive = pdFALSE; 01402 char cRxedChar; 01403 01404 while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) ) 01405 { 01406 // A character was received. Output the character now. 01407 vOutputCharacter( cRxedChar ); 01408 01409 // If removing the character from the queue woke the task that was 01410 // posting onto the queue cTaskWokenByReceive will have been set to 01411 // pdTRUE. No matter how many times this loop iterates only one 01412 // task will be woken. 01413 } 01414 01415 if( cTaskWokenByPost != ( char ) pdFALSE; 01416 { 01417 taskYIELD (); 01418 } 01419 } 01420 </pre> 01421 * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR 01422 * \ingroup QueueManagement 01423 */ 01424 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle xQueue, void * const pvBuffer, signed portBASE_TYPE *pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 01425 01426 /* 01427 * Utilities to query queues that are safe to use from an ISR. These utilities 01428 * should be used only from witin an ISR, or within a critical section. 01429 */ 01430 signed portBASE_TYPE xQueueIsQueueEmptyFromISR( const xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01431 signed portBASE_TYPE xQueueIsQueueFullFromISR( const xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01432 unsigned portBASE_TYPE uxQueueMessagesWaitingFromISR( const xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01433 01434 01435 /* 01436 * xQueueAltGenericSend() is an alternative version of xQueueGenericSend(). 01437 * Likewise xQueueAltGenericReceive() is an alternative version of 01438 * xQueueGenericReceive(). 01439 * 01440 * The source code that implements the alternative (Alt) API is much 01441 * simpler because it executes everything from within a critical section. 01442 * This is the approach taken by many other RTOSes, but FreeRTOS.org has the 01443 * preferred fully featured API too. The fully featured API has more 01444 * complex code that takes longer to execute, but makes much less use of 01445 * critical sections. Therefore the alternative API sacrifices interrupt 01446 * responsiveness to gain execution speed, whereas the fully featured API 01447 * sacrifices execution speed to ensure better interrupt responsiveness. 01448 */ 01449 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle xQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition ); 01450 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle xQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking ); 01451 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT ) 01452 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) 01453 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdFALSE ) 01454 #define xQueueAltPeek( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( ( xQueue ), ( pvBuffer ), ( xTicksToWait ), pdTRUE ) 01455 01456 /* 01457 * The functions defined above are for passing data to and from tasks. The 01458 * functions below are the equivalents for passing data to and from 01459 * co-routines. 01460 * 01461 * These functions are called from the co-routine macro implementation and 01462 * should not be called directly from application code. Instead use the macro 01463 * wrappers defined within croutine.h. 01464 */ 01465 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle xQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken ); 01466 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle xQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken ); 01467 signed portBASE_TYPE xQueueCRSend( xQueueHandle xQueue, const void *pvItemToQueue, portTickType xTicksToWait ); 01468 signed portBASE_TYPE xQueueCRReceive( xQueueHandle xQueue, void *pvBuffer, portTickType xTicksToWait ); 01469 01470 /* 01471 * For internal use only. Use xSemaphoreCreateMutex(), 01472 * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling 01473 * these functions directly. 01474 */ 01475 xQueueHandle xQueueCreateMutex( unsigned char ucQueueType ) PRIVILEGED_FUNCTION; 01476 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxMaxCount, unsigned portBASE_TYPE uxInitialCount ) PRIVILEGED_FUNCTION; 01477 void* xQueueGetMutexHolder( xQueueHandle xSemaphore ) PRIVILEGED_FUNCTION; 01478 01479 /* 01480 * For internal use only. Use xSemaphoreTakeMutexRecursive() or 01481 * xSemaphoreGiveMutexRecursive() instead of calling these functions directly. 01482 */ 01483 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle xMutex, portTickType xBlockTime ) PRIVILEGED_FUNCTION; 01484 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle pxMutex ) PRIVILEGED_FUNCTION; 01485 01486 /* 01487 * Reset a queue back to its original empty state. pdPASS is returned if the 01488 * queue is successfully reset. pdFAIL is returned if the queue could not be 01489 * reset because there are tasks blocked on the queue waiting to either 01490 * receive from the queue or send to the queue. 01491 */ 01492 #define xQueueReset( xQueue ) xQueueGenericReset( xQueue, pdFALSE ) 01493 01494 /* 01495 * The registry is provided as a means for kernel aware debuggers to 01496 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add 01497 * a queue, semaphore or mutex handle to the registry if you want the handle 01498 * to be available to a kernel aware debugger. If you are not using a kernel 01499 * aware debugger then this function can be ignored. 01500 * 01501 * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the 01502 * registry can hold. configQUEUE_REGISTRY_SIZE must be greater than 0 01503 * within FreeRTOSConfig.h for the registry to be available. Its value 01504 * does not effect the number of queues, semaphores and mutexes that can be 01505 * created - just the number that the registry can hold. 01506 * 01507 * @param xQueue The handle of the queue being added to the registry. This 01508 * is the handle returned by a call to xQueueCreate(). Semaphore and mutex 01509 * handles can also be passed in here. 01510 * 01511 * @param pcName The name to be associated with the handle. This is the 01512 * name that the kernel aware debugger will display. 01513 */ 01514 #if configQUEUE_REGISTRY_SIZE > 0 01515 void vQueueAddToRegistry( xQueueHandle xQueue, signed char *pcName ) PRIVILEGED_FUNCTION; 01516 #endif 01517 01518 /* 01519 * The registry is provided as a means for kernel aware debuggers to 01520 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add 01521 * a queue, semaphore or mutex handle to the registry if you want the handle 01522 * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to 01523 * remove the queue, semaphore or mutex from the register. If you are not using 01524 * a kernel aware debugger then this function can be ignored. 01525 * 01526 * @param xQueue The handle of the queue being removed from the registry. 01527 */ 01528 #if configQUEUE_REGISTRY_SIZE > 0 01529 void vQueueUnregisterQueue( xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01530 #endif 01531 01532 /* 01533 * Generic version of the queue creation function, which is in turn called by 01534 * any queue, semaphore or mutex creation function or macro. 01535 */ 01536 xQueueHandle xQueueGenericCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize, unsigned char ucQueueType ) PRIVILEGED_FUNCTION; 01537 01538 /* 01539 * Queue sets provide a mechanism to allow a task to block (pend) on a read 01540 * operation from multiple queues or semaphores simultaneously. 01541 * 01542 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 01543 * function. 01544 * 01545 * A queue set must be explicitly created using a call to xQueueCreateSet() 01546 * before it can be used. Once created, standard FreeRTOS queues and semaphores 01547 * can be added to the set using calls to xQueueAddToSet(). 01548 * xQueueSelectFromSet() is then used to determine which, if any, of the queues 01549 * or semaphores contained in the set is in a state where a queue read or 01550 * semaphore take operation would be successful. 01551 * 01552 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html 01553 * for reasons why queue sets are very rarely needed in practice as there are 01554 * simpler methods of blocking on multiple objects. 01555 * 01556 * Note 2: Blocking on a queue set that contains a mutex will not cause the 01557 * mutex holder to inherit the priority of the blocked task. 01558 * 01559 * Note 3: An additional 4 bytes of RAM is required for each space in a every 01560 * queue added to a queue set. Therefore counting semaphores that have a high 01561 * maximum count value should not be added to a queue set. 01562 * 01563 * Note 4: A receive (in the case of a queue) or take (in the case of a 01564 * semaphore) operation must not be performed on a member of a queue set unless 01565 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 01566 * 01567 * @param uxEventQueueLength Queue sets store events that occur on 01568 * the queues and semaphores contained in the set. uxEventQueueLength specifies 01569 * the maximum number of events that can be queued at once. To be absolutely 01570 * certain that events are not lost uxEventQueueLength should be set to the 01571 * total sum of the length of the queues added to the set, where binary 01572 * semaphores and mutexes have a length of 1, and counting semaphores have a 01573 * length set by their maximum count value. Examples: 01574 * + If a queue set is to hold a queue of length 5, another queue of length 12, 01575 * and a binary semaphore, then uxEventQueueLength should be set to 01576 * (5 + 12 + 1), or 18. 01577 * + If a queue set is to hold three binary semaphores then uxEventQueueLength 01578 * should be set to (1 + 1 + 1 ), or 3. 01579 * + If a queue set is to hold a counting semaphore that has a maximum count of 01580 * 5, and a counting semaphore that has a maximum count of 3, then 01581 * uxEventQueueLength should be set to (5 + 3), or 8. 01582 * 01583 * @return If the queue set is created successfully then a handle to the created 01584 * queue set is returned. Otherwise NULL is returned. 01585 */ 01586 xQueueSetHandle xQueueCreateSet( unsigned portBASE_TYPE uxEventQueueLength ) PRIVILEGED_FUNCTION; 01587 01588 /* 01589 * Adds a queue or semaphore to a queue set that was previously created by a 01590 * call to xQueueCreateSet(). 01591 * 01592 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 01593 * function. 01594 * 01595 * Note 1: A receive (in the case of a queue) or take (in the case of a 01596 * semaphore) operation must not be performed on a member of a queue set unless 01597 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 01598 * 01599 * @param xQueueOrSemaphore The handle of the queue or semaphore being added to 01600 * the queue set (cast to an xQueueSetMemberHandle type). 01601 * 01602 * @param xQueueSet The handle of the queue set to which the queue or semaphore 01603 * is being added. 01604 * 01605 * @return If the queue or semaphore was successfully added to the queue set 01606 * then pdPASS is returned. If the queue could not be successfully added to the 01607 * queue set because it is already a member of a different queue set then pdFAIL 01608 * is returned. 01609 */ 01610 portBASE_TYPE xQueueAddToSet( xQueueSetMemberHandle xQueueOrSemaphore, xQueueSetHandle xQueueSet ) PRIVILEGED_FUNCTION; 01611 01612 /* 01613 * Removes a queue or semaphore from a queue set. A queue or semaphore can only 01614 * be removed from a set if the queue or semaphore is empty. 01615 * 01616 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 01617 * function. 01618 * 01619 * @param xQueueOrSemaphore The handle of the queue or semaphore being removed 01620 * from the queue set (cast to an xQueueSetMemberHandle type). 01621 * 01622 * @param xQueueSet The handle of the queue set in which the queue or semaphore 01623 * is included. 01624 * 01625 * @return If the queue or semaphore was successfully removed from the queue set 01626 * then pdPASS is returned. If the queue was not in the queue set, or the 01627 * queue (or semaphore) was not empty, then pdFAIL is returned. 01628 */ 01629 portBASE_TYPE xQueueRemoveFromSet( xQueueSetMemberHandle xQueueOrSemaphore, xQueueSetHandle xQueueSet ) PRIVILEGED_FUNCTION; 01630 01631 /* 01632 * xQueueSelectFromSet() selects from the members of a queue set a queue or 01633 * semaphore that either contains data (in the case of a queue) or is available 01634 * to take (in the case of a semaphore). xQueueSelectFromSet() effectively 01635 * allows a task to block (pend) on a read operation on all the queues and 01636 * semaphores in a queue set simultaneously. 01637 * 01638 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 01639 * function. 01640 * 01641 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html 01642 * for reasons why queue sets are very rarely needed in practice as there are 01643 * simpler methods of blocking on multiple objects. 01644 * 01645 * Note 2: Blocking on a queue set that contains a mutex will not cause the 01646 * mutex holder to inherit the priority of the blocked task. 01647 * 01648 * Note 3: A receive (in the case of a queue) or take (in the case of a 01649 * semaphore) operation must not be performed on a member of a queue set unless 01650 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 01651 * 01652 * @param xQueueSet The queue set on which the task will (potentially) block. 01653 * 01654 * @param xBlockTimeTicks The maximum time, in ticks, that the calling task will 01655 * remain in the Blocked state (with other tasks executing) to wait for a member 01656 * of the queue set to be ready for a successful queue read or semaphore take 01657 * operation. 01658 * 01659 * @return xQueueSelectFromSet() will return the handle of a queue (cast to 01660 * a xQueueSetMemberHandle type) contained in the queue set that contains data, 01661 * or the handle of a semaphore (cast to a xQueueSetMemberHandle type) contained 01662 * in the queue set that is available, or NULL if no such queue or semaphore 01663 * exists before before the specified block time expires. 01664 */ 01665 xQueueSetMemberHandle xQueueSelectFromSet( xQueueSetHandle xQueueSet, portTickType xBlockTimeTicks ) PRIVILEGED_FUNCTION; 01666 01667 /* 01668 * A version of xQueueSelectFromSet() that can be used from an ISR. 01669 */ 01670 xQueueSetMemberHandle xQueueSelectFromSetFromISR( xQueueSetHandle xQueueSet ) PRIVILEGED_FUNCTION; 01671 01672 /* Not public API functions. */ 01673 void vQueueWaitForMessageRestricted( xQueueHandle xQueue, portTickType xTicksToWait ) PRIVILEGED_FUNCTION; 01674 portBASE_TYPE xQueueGenericReset( xQueueHandle xQueue, portBASE_TYPE xNewQueue ) PRIVILEGED_FUNCTION; 01675 void vQueueSetQueueNumber( xQueueHandle xQueue, unsigned char ucQueueNumber ) PRIVILEGED_FUNCTION; 01676 unsigned char ucQueueGetQueueNumber( xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01677 unsigned char ucQueueGetQueueType( xQueueHandle xQueue ) PRIVILEGED_FUNCTION; 01678 01679 01680 #ifdef __cplusplus 01681 } 01682 #endif 01683 01684 #endif /* QUEUE_H */ 01685
Generated on Tue Jul 12 2022 11:36:40 by
1.7.2