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