1 /* 2 * FreeRTOS Kernel V10.2.1 3 * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining a copy of 6 * this software and associated documentation files (the "Software"), to deal in 7 * the Software without restriction, including without limitation the rights to 8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 * the Software, and to permit persons to whom the Software is furnished to do so, 10 * subject to the following conditions: 11 * 12 * The above copyright notice and this permission notice shall be included in all 13 * copies or substantial portions of the Software. 14 * 15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 * 22 * http://www.FreeRTOS.org 23 * http://aws.amazon.com/freertos 24 * 25 * 1 tab == 4 spaces! 26 */ 27 28 29 #ifndef QUEUE_H 30 #define QUEUE_H 31 32 #ifndef INC_FREERTOS_H 33 #error "include FreeRTOS.h" must appear in source files before "include queue.h" 34 #endif 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 #include "task.h" 41 42 /** 43 * Type by which queues are referenced. For example, a call to xQueueCreate() 44 * returns an QueueHandle_t variable that can then be used as a parameter to 45 * xQueueSend(), xQueueReceive(), etc. 46 */ 47 struct QueueDefinition; /* Using old naming convention so as not to break kernel aware debuggers. */ 48 typedef struct QueueDefinition * QueueHandle_t; 49 50 /** 51 * Type by which queue sets are referenced. For example, a call to 52 * xQueueCreateSet() returns an xQueueSet variable that can then be used as a 53 * parameter to xQueueSelectFromSet(), xQueueAddToSet(), etc. 54 */ 55 typedef struct QueueDefinition * QueueSetHandle_t; 56 57 /** 58 * Queue sets can contain both queues and semaphores, so the 59 * QueueSetMemberHandle_t is defined as a type to be used where a parameter or 60 * return value can be either an QueueHandle_t or an SemaphoreHandle_t. 61 */ 62 typedef struct QueueDefinition * QueueSetMemberHandle_t; 63 64 /** @cond */ 65 66 /* For internal use only. */ 67 #define queueSEND_TO_BACK ( ( BaseType_t ) 0 ) 68 #define queueSEND_TO_FRONT ( ( BaseType_t ) 1 ) 69 #define queueOVERWRITE ( ( BaseType_t ) 2 ) 70 71 /* For internal use only. These definitions *must* match those in queue.c. */ 72 #define queueQUEUE_TYPE_BASE ( ( uint8_t ) 0U ) 73 #define queueQUEUE_TYPE_SET ( ( uint8_t ) 0U ) 74 #define queueQUEUE_TYPE_MUTEX ( ( uint8_t ) 1U ) 75 #define queueQUEUE_TYPE_COUNTING_SEMAPHORE ( ( uint8_t ) 2U ) 76 #define queueQUEUE_TYPE_BINARY_SEMAPHORE ( ( uint8_t ) 3U ) 77 #define queueQUEUE_TYPE_RECURSIVE_MUTEX ( ( uint8_t ) 4U ) 78 79 /** @endcond */ 80 81 /** 82 * Creates a new queue instance. This allocates the storage required by the 83 * new queue and returns a handle for the queue. 84 * 85 * @param uxQueueLength The maximum number of items that the queue can contain. 86 * 87 * @param uxItemSize The number of bytes each item in the queue will require. 88 * Items are queued by copy, not by reference, so this is the number of bytes 89 * that will be copied for each posted item. Each item on the queue must be 90 * the same size. 91 * 92 * @return If the queue is successfully create then a handle to the newly 93 * created queue is returned. If the queue cannot be created then 0 is 94 * returned. 95 * 96 * Example usage: 97 * @code{c} 98 * struct AMessage 99 * { 100 * char ucMessageID; 101 * char ucData[ 20 ]; 102 * }; 103 * 104 * void vATask( void *pvParameters ) 105 * { 106 * QueueHandle_t xQueue1, xQueue2; 107 * 108 * // Create a queue capable of containing 10 uint32_t values. 109 * xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); 110 * if( xQueue1 == 0 ) 111 * { 112 * // Queue was not created and must not be used. 113 * } 114 * 115 * // Create a queue capable of containing 10 pointers to AMessage structures. 116 * // These should be passed by pointer as they contain a lot of data. 117 * xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 118 * if( xQueue2 == 0 ) 119 * { 120 * // Queue was not created and must not be used. 121 * } 122 * 123 * // ... Rest of task code. 124 * } 125 * @endcode 126 * \ingroup QueueManagement 127 */ 128 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) 129 #define xQueueCreate( uxQueueLength, uxItemSize ) xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) ) 130 #endif 131 132 /** 133 * Creates a new queue instance, and returns a handle by which the new queue 134 * can be referenced. 135 * 136 * Internally, within the FreeRTOS implementation, queues use two blocks of 137 * memory. The first block is used to hold the queue's data structures. The 138 * second block is used to hold items placed into the queue. If a queue is 139 * created using xQueueCreate() then both blocks of memory are automatically 140 * dynamically allocated inside the xQueueCreate() function. (see 141 * http://www.freertos.org/a00111.html). If a queue is created using 142 * xQueueCreateStatic() then the application writer must provide the memory that 143 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to 144 * be created without using any dynamic memory allocation. 145 * 146 * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html 147 * 148 * @param uxQueueLength The maximum number of items that the queue can contain. 149 * 150 * @param uxItemSize The number of bytes each item in the queue will require. 151 * Items are queued by copy, not by reference, so this is the number of bytes 152 * that will be copied for each posted item. Each item on the queue must be 153 * the same size. 154 * 155 * @param pucQueueStorage If uxItemSize is not zero then 156 * pucQueueStorageBuffer must point to a uint8_t array that is at least large 157 * enough to hold the maximum number of items that can be in the queue at any 158 * one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is 159 * zero then pucQueueStorageBuffer can be NULL. 160 * 161 * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which 162 * will be used to hold the queue's data structure. 163 * 164 * @return If the queue is created then a handle to the created queue is 165 * returned. If pxQueueBuffer is NULL then NULL is returned. 166 * 167 * Example usage: 168 * @code{c} 169 * struct AMessage 170 * { 171 * char ucMessageID; 172 * char ucData[ 20 ]; 173 * }; 174 * 175 * #define QUEUE_LENGTH 10 176 * #define ITEM_SIZE sizeof( uint32_t ) 177 * 178 * // xQueueBuffer will hold the queue structure. 179 * StaticQueue_t xQueueBuffer; 180 * 181 * // ucQueueStorage will hold the items posted to the queue. Must be at least 182 * // [(queue length) * ( queue item size)] bytes long. 183 * uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ]; 184 * 185 * void vATask( void *pvParameters ) 186 * { 187 * QueueHandle_t xQueue1; 188 * 189 * // Create a queue capable of containing 10 uint32_t values. 190 * xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold. 191 * ITEM_SIZE // The size of each item in the queue 192 * &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the queue. 193 * &xQueueBuffer ); // The buffer that will hold the queue structure. 194 * 195 * // The queue is guaranteed to be created successfully as no dynamic memory 196 * // allocation is used. Therefore xQueue1 is now a handle to a valid queue. 197 * 198 * // ... Rest of task code. 199 * } 200 * @endcode 201 * \ingroup QueueManagement 202 */ 203 #if( configSUPPORT_STATIC_ALLOCATION == 1 ) 204 #define xQueueCreateStatic( uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer ) xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) ) 205 #endif /* configSUPPORT_STATIC_ALLOCATION */ 206 207 /** 208 * Post an item to the front of a queue. The item is queued by copy, not by 209 * reference. This function must not be called from an interrupt service 210 * routine. See xQueueSendFromISR () for an alternative which may be used 211 * in an ISR. 212 * 213 * @param xQueue The handle to the queue on which the item is to be posted. 214 * 215 * @param pvItemToQueue A pointer to the item that is to be placed on the 216 * queue. The size of the items the queue will hold was defined when the 217 * queue was created, so this many bytes will be copied from pvItemToQueue 218 * into the queue storage area. 219 * 220 * @param xTicksToWait The maximum amount of time the task should block 221 * waiting for space to become available on the queue, should it already 222 * be full. The call will return immediately if this is set to 0 and the 223 * queue is full. The time is defined in tick periods so the constant 224 * portTICK_PERIOD_MS should be used to convert to real time if this is required. 225 * 226 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 227 * 228 * Example usage: 229 * @code{c} 230 * struct AMessage 231 * { 232 * char ucMessageID; 233 * char ucData[ 20 ]; 234 * } xMessage; 235 * 236 * uint32_t ulVar = 10UL; 237 * 238 * void vATask( void *pvParameters ) 239 * { 240 * QueueHandle_t xQueue1, xQueue2; 241 * struct AMessage *pxMessage; 242 * 243 * // Create a queue capable of containing 10 uint32_t values. 244 * xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); 245 * 246 * // Create a queue capable of containing 10 pointers to AMessage structures. 247 * // These should be passed by pointer as they contain a lot of data. 248 * xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 249 * 250 * // ... 251 * 252 * if( xQueue1 != 0 ) 253 * { 254 * // Send an uint32_t. Wait for 10 ticks for space to become 255 * // available if necessary. 256 * if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) 257 * { 258 * // Failed to post the message, even after 10 ticks. 259 * } 260 * } 261 * 262 * if( xQueue2 != 0 ) 263 * { 264 * // Send a pointer to a struct AMessage object. Don't block if the 265 * // queue is already full. 266 * pxMessage = & xMessage; 267 * xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); 268 * } 269 * 270 * // ... Rest of task code. 271 * } 272 * @endcode 273 * \ingroup QueueManagement 274 */ 275 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_FRONT ) 276 277 /** 278 * This is a macro that calls xQueueGenericSend(). 279 * 280 * Post an item to the back of a queue. The item is queued by copy, not by 281 * reference. This function must not be called from an interrupt service 282 * routine. See xQueueSendFromISR () for an alternative which may be used 283 * in an ISR. 284 * 285 * @param xQueue The handle to the queue on which the item is to be posted. 286 * 287 * @param pvItemToQueue A pointer to the item that is to be placed on the 288 * queue. The size of the items the queue will hold was defined when the 289 * queue was created, so this many bytes will be copied from pvItemToQueue 290 * into the queue storage area. 291 * 292 * @param xTicksToWait The maximum amount of time the task should block 293 * waiting for space to become available on the queue, should it already 294 * be full. The call will return immediately if this is set to 0 and the queue 295 * is full. The time is defined in tick periods so the constant 296 * portTICK_PERIOD_MS should be used to convert to real time if this is required. 297 * 298 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 299 * 300 * Example usage: 301 * @code{c} 302 * struct AMessage 303 * { 304 * char ucMessageID; 305 * char ucData[ 20 ]; 306 * } xMessage; 307 * 308 * uint32_t ulVar = 10UL; 309 * 310 * void vATask( void *pvParameters ) 311 * { 312 * QueueHandle_t xQueue1, xQueue2; 313 * struct AMessage *pxMessage; 314 * 315 * // Create a queue capable of containing 10 uint32_t values. 316 * xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); 317 * 318 * // Create a queue capable of containing 10 pointers to AMessage structures. 319 * // These should be passed by pointer as they contain a lot of data. 320 * xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 321 * 322 * // ... 323 * 324 * if( xQueue1 != 0 ) 325 * { 326 * // Send an uint32_t. Wait for 10 ticks for space to become 327 * // available if necessary. 328 * if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) 329 * { 330 * // Failed to post the message, even after 10 ticks. 331 * } 332 * } 333 * 334 * if( xQueue2 != 0 ) 335 * { 336 * // Send a pointer to a struct AMessage object. Don't block if the 337 * // queue is already full. 338 * pxMessage = & xMessage; 339 * xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); 340 * } 341 * 342 * // ... Rest of task code. 343 * } 344 * @endcode 345 * \ingroup QueueManagement 346 */ 347 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) 348 349 /** 350 * This is a macro that calls xQueueGenericSend(). It is included for 351 * backward compatibility with versions of FreeRTOS.org that did not 352 * include the xQueueSendToFront() and xQueueSendToBack() macros. It is 353 * equivalent to xQueueSendToBack(). 354 * 355 * Post an item on a queue. The item is queued by copy, not by reference. 356 * This function must not be called from an interrupt service routine. 357 * See xQueueSendFromISR () for an alternative which may be used in an ISR. 358 * 359 * @param xQueue The handle to the queue on which the item is to be posted. 360 * 361 * @param pvItemToQueue A pointer to the item that is to be placed on the 362 * queue. The size of the items the queue will hold was defined when the 363 * queue was created, so this many bytes will be copied from pvItemToQueue 364 * into the queue storage area. 365 * 366 * @param xTicksToWait The maximum amount of time the task should block 367 * waiting for space to become available on the queue, should it already 368 * be full. The call will return immediately if this is set to 0 and the 369 * queue is full. The time is defined in tick periods so the constant 370 * portTICK_PERIOD_MS should be used to convert to real time if this is required. 371 * 372 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 373 * 374 * Example usage: 375 * @code{c} 376 * struct AMessage 377 * { 378 * char ucMessageID; 379 * char ucData[ 20 ]; 380 * } xMessage; 381 * 382 * uint32_t ulVar = 10UL; 383 * 384 * void vATask( void *pvParameters ) 385 * { 386 * QueueHandle_t xQueue1, xQueue2; 387 * struct AMessage *pxMessage; 388 * 389 * // Create a queue capable of containing 10 uint32_t values. 390 * xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); 391 * 392 * // Create a queue capable of containing 10 pointers to AMessage structures. 393 * // These should be passed by pointer as they contain a lot of data. 394 * xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 395 * 396 * // ... 397 * 398 * if( xQueue1 != 0 ) 399 * { 400 * // Send an uint32_t. Wait for 10 ticks for space to become 401 * // available if necessary. 402 * if( xQueueSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10 ) != pdPASS ) 403 * { 404 * // Failed to post the message, even after 10 ticks. 405 * } 406 * } 407 * 408 * if( xQueue2 != 0 ) 409 * { 410 * // Send a pointer to a struct AMessage object. Don't block if the 411 * // queue is already full. 412 * pxMessage = & xMessage; 413 * xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 ); 414 * } 415 * 416 * // ... Rest of task code. 417 * } 418 * @endcode 419 * \ingroup QueueManagement 420 */ 421 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), ( xTicksToWait ), queueSEND_TO_BACK ) 422 423 /** 424 * Only for use with queues that have a length of one - so the queue is either 425 * empty or full. 426 * 427 * Post an item on a queue. If the queue is already full then overwrite the 428 * value held in the queue. The item is queued by copy, not by reference. 429 * 430 * This function must not be called from an interrupt service routine. 431 * See xQueueOverwriteFromISR () for an alternative which may be used in an ISR. 432 * 433 * @param xQueue The handle of the queue to which the data is being sent. 434 * 435 * @param pvItemToQueue A pointer to the item that is to be placed on the 436 * queue. The size of the items the queue will hold was defined when the 437 * queue was created, so this many bytes will be copied from pvItemToQueue 438 * into the queue storage area. 439 * 440 * @return xQueueOverwrite() is a macro that calls xQueueGenericSend(), and 441 * therefore has the same return values as xQueueSendToFront(). However, pdPASS 442 * is the only value that can be returned because xQueueOverwrite() will write 443 * to the queue even when the queue is already full. 444 * 445 * Example usage: 446 * @code{c} 447 * 448 * void vFunction( void *pvParameters ) 449 * { 450 * QueueHandle_t xQueue; 451 * uint32_t ulVarToSend, ulValReceived; 452 * 453 * // Create a queue to hold one uint32_t value. It is strongly 454 * // recommended *not* to use xQueueOverwrite() on queues that can 455 * // contain more than one value, and doing so will trigger an assertion 456 * // if configASSERT() is defined. 457 * xQueue = xQueueCreate( 1, sizeof( uint32_t ) ); 458 * 459 * // Write the value 10 to the queue using xQueueOverwrite(). 460 * ulVarToSend = 10; 461 * xQueueOverwrite( xQueue, &ulVarToSend ); 462 * 463 * // Peeking the queue should now return 10, but leave the value 10 in 464 * // the queue. A block time of zero is used as it is known that the 465 * // queue holds a value. 466 * ulValReceived = 0; 467 * xQueuePeek( xQueue, &ulValReceived, 0 ); 468 * 469 * if( ulValReceived != 10 ) 470 * { 471 * // Error unless the item was removed by a different task. 472 * } 473 * 474 * // The queue is still full. Use xQueueOverwrite() to overwrite the 475 * // value held in the queue with 100. 476 * ulVarToSend = 100; 477 * xQueueOverwrite( xQueue, &ulVarToSend ); 478 * 479 * // This time read from the queue, leaving the queue empty once more. 480 * // A block time of 0 is used again. 481 * xQueueReceive( xQueue, &ulValReceived, 0 ); 482 * 483 * // The value read should be the last value written, even though the 484 * // queue was already full when the value was written. 485 * if( ulValReceived != 100 ) 486 * { 487 * // Error! 488 * } 489 * 490 * // ... 491 * } 492 * @endcode 493 * \ingroup QueueManagement 494 */ 495 #define xQueueOverwrite( xQueue, pvItemToQueue ) xQueueGenericSend( ( xQueue ), ( pvItemToQueue ), 0, queueOVERWRITE ) 496 497 498 /** 499 * It is preferred that the macros xQueueSend(), xQueueSendToFront() and 500 * xQueueSendToBack() are used in place of calling this function directly. 501 * 502 * Post an item on a queue. The item is queued by copy, not by reference. 503 * This function must not be called from an interrupt service routine. 504 * See xQueueSendFromISR () for an alternative which may be used in an ISR. 505 * 506 * @param xQueue The handle to the queue on which the item is to be posted. 507 * 508 * @param pvItemToQueue A pointer to the item that is to be placed on the 509 * queue. The size of the items the queue will hold was defined when the 510 * queue was created, so this many bytes will be copied from pvItemToQueue 511 * into the queue storage area. 512 * 513 * @param xTicksToWait The maximum amount of time the task should block 514 * waiting for space to become available on the queue, should it already 515 * be full. The call will return immediately if this is set to 0 and the 516 * queue is full. The time is defined in tick periods so the constant 517 * portTICK_PERIOD_MS should be used to convert to real time if this is required. 518 * 519 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the 520 * item at the back of the queue, or queueSEND_TO_FRONT to place the item 521 * at the front of the queue (for high priority messages). 522 * 523 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL. 524 * 525 * Example usage: 526 * @code{c} 527 * struct AMessage 528 * { 529 * char ucMessageID; 530 * char ucData[ 20 ]; 531 * } xMessage; 532 * 533 * uint32_t ulVar = 10UL; 534 * 535 * void vATask( void *pvParameters ) 536 * { 537 * QueueHandle_t xQueue1, xQueue2; 538 * struct AMessage *pxMessage; 539 * 540 * // Create a queue capable of containing 10 uint32_t values. 541 * xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) ); 542 * 543 * // Create a queue capable of containing 10 pointers to AMessage structures. 544 * // These should be passed by pointer as they contain a lot of data. 545 * xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) ); 546 * 547 * // ... 548 * 549 * if( xQueue1 != 0 ) 550 * { 551 * // Send an uint32_t. Wait for 10 ticks for space to become 552 * // available if necessary. 553 * if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( TickType_t ) 10, queueSEND_TO_BACK ) != pdPASS ) 554 * { 555 * // Failed to post the message, even after 10 ticks. 556 * } 557 * } 558 * 559 * if( xQueue2 != 0 ) 560 * { 561 * // Send a pointer to a struct AMessage object. Don't block if the 562 * // queue is already full. 563 * pxMessage = & xMessage; 564 * xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0, queueSEND_TO_BACK ); 565 * } 566 * 567 * // ... Rest of task code. 568 * } 569 * @endcode 570 * \ingroup QueueManagement 571 */ 572 BaseType_t xQueueGenericSend( QueueHandle_t xQueue, const void * const pvItemToQueue, TickType_t xTicksToWait, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION; 573 574 /** 575 * Receive an item from a queue without removing the item from the queue. 576 * The item is received by copy so a buffer of adequate size must be 577 * provided. The number of bytes copied into the buffer was defined when 578 * the queue was created. 579 * 580 * Successfully received items remain on the queue so will be returned again 581 * by the next call, or a call to xQueueReceive(). 582 * 583 * This macro must not be used in an interrupt service routine. See 584 * xQueuePeekFromISR() for an alternative that can be called from an interrupt 585 * service routine. 586 * 587 * @param xQueue The handle to the queue from which the item is to be 588 * received. 589 * 590 * @param pvBuffer Pointer to the buffer into which the received item will 591 * be copied. 592 * 593 * @param xTicksToWait The maximum amount of time the task should block 594 * waiting for an item to receive should the queue be empty at the time 595 * of the call. The time is defined in tick periods so the constant 596 * portTICK_PERIOD_MS should be used to convert to real time if this is required. 597 * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue 598 * is empty. 599 * 600 * @return pdTRUE if an item was successfully received from the queue, 601 * otherwise pdFALSE. 602 * 603 * Example usage: 604 * @code{c} 605 * struct AMessage 606 * { 607 * char ucMessageID; 608 * char ucData[ 20 ]; 609 * } xMessage; 610 * 611 * QueueHandle_t xQueue; 612 * 613 * // Task to create a queue and post a value. 614 * void vATask( void *pvParameters ) 615 * { 616 * struct AMessage *pxMessage; 617 * 618 * // Create a queue capable of containing 10 pointers to AMessage structures. 619 * // These should be passed by pointer as they contain a lot of data. 620 * xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); 621 * if( xQueue == 0 ) 622 * { 623 * // Failed to create the queue. 624 * } 625 * 626 * // ... 627 * 628 * // Send a pointer to a struct AMessage object. Don't block if the 629 * // queue is already full. 630 * pxMessage = & xMessage; 631 * xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 ); 632 * 633 * // ... Rest of task code. 634 * } 635 * 636 * // Task to peek the data from the queue. 637 * void vADifferentTask( void *pvParameters ) 638 * { 639 * struct AMessage *pxRxedMessage; 640 * 641 * if( xQueue != 0 ) 642 * { 643 * // Peek a message on the created queue. Block for 10 ticks if a 644 * // message is not immediately available. 645 * if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) ) 646 * { 647 * // pcRxedMessage now points to the struct AMessage variable posted 648 * // by vATask, but the item still remains on the queue. 649 * } 650 * } 651 * 652 * // ... Rest of task code. 653 * } 654 * @endcode 655 * \ingroup QueueManagement 656 */ 657 BaseType_t xQueuePeek( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 658 659 /** 660 * A version of xQueuePeek() that can be called from an interrupt service 661 * routine (ISR). 662 * 663 * Receive an item from a queue without removing the item from the queue. 664 * The item is received by copy so a buffer of adequate size must be 665 * provided. The number of bytes copied into the buffer was defined when 666 * the queue was created. 667 * 668 * Successfully received items remain on the queue so will be returned again 669 * by the next call, or a call to xQueueReceive(). 670 * 671 * @param xQueue The handle to the queue from which the item is to be 672 * received. 673 * 674 * @param pvBuffer Pointer to the buffer into which the received item will 675 * be copied. 676 * 677 * @return pdTRUE if an item was successfully received from the queue, 678 * otherwise pdFALSE. 679 * 680 * \ingroup QueueManagement 681 */ 682 BaseType_t xQueuePeekFromISR( QueueHandle_t xQueue, void * const pvBuffer ) PRIVILEGED_FUNCTION; 683 684 /** 685 * Receive an item from a queue. The item is received by copy so a buffer of 686 * adequate size must be provided. The number of bytes copied into the buffer 687 * was defined when the queue was created. 688 * 689 * Successfully received items are removed from the queue. 690 * 691 * This function must not be used in an interrupt service routine. See 692 * xQueueReceiveFromISR for an alternative that can. 693 * 694 * @param xQueue The handle to the queue from which the item is to be 695 * received. 696 * 697 * @param pvBuffer Pointer to the buffer into which the received item will 698 * be copied. 699 * 700 * @param xTicksToWait The maximum amount of time the task should block 701 * waiting for an item to receive should the queue be empty at the time 702 * of the call. xQueueReceive() will return immediately if xTicksToWait 703 * is zero and the queue is empty. The time is defined in tick periods so the 704 * constant portTICK_PERIOD_MS should be used to convert to real time if this is 705 * required. 706 * 707 * @return pdTRUE if an item was successfully received from the queue, 708 * otherwise pdFALSE. 709 * 710 * Example usage: 711 * @code{c} 712 * struct AMessage 713 * { 714 * char ucMessageID; 715 * char ucData[ 20 ]; 716 * } xMessage; 717 * 718 * QueueHandle_t xQueue; 719 * 720 * // Task to create a queue and post a value. 721 * void vATask( void *pvParameters ) 722 * { 723 * struct AMessage *pxMessage; 724 * 725 * // Create a queue capable of containing 10 pointers to AMessage structures. 726 * // These should be passed by pointer as they contain a lot of data. 727 * xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) ); 728 * if( xQueue == 0 ) 729 * { 730 * // Failed to create the queue. 731 * } 732 * 733 * // ... 734 * 735 * // Send a pointer to a struct AMessage object. Don't block if the 736 * // queue is already full. 737 * pxMessage = & xMessage; 738 * xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 ); 739 * 740 * // ... Rest of task code. 741 * } 742 * 743 * // Task to receive from the queue. 744 * void vADifferentTask( void *pvParameters ) 745 * { 746 * struct AMessage *pxRxedMessage; 747 * 748 * if( xQueue != 0 ) 749 * { 750 * // Receive a message on the created queue. Block for 10 ticks if a 751 * // message is not immediately available. 752 * if( xQueueReceive( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) ) 753 * { 754 * // pcRxedMessage now points to the struct AMessage variable posted 755 * // by vATask. 756 * } 757 * } 758 * 759 * // ... Rest of task code. 760 * } 761 * @endcode 762 * \ingroup QueueManagement 763 */ 764 BaseType_t xQueueReceive( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 765 766 /** 767 * Return the number of messages stored in a queue. 768 * 769 * @param xQueue A handle to the queue being queried. 770 * 771 * @return The number of messages available in the queue. 772 * 773 * \ingroup QueueManagement 774 */ 775 UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 776 777 /** 778 * Return the number of free spaces available in a queue. This is equal to the 779 * number of items that can be sent to the queue before the queue becomes full 780 * if no items are removed. 781 * 782 * @param xQueue A handle to the queue being queried. 783 * 784 * @return The number of spaces available in the queue. 785 * 786 * \ingroup QueueManagement 787 */ 788 UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 789 790 /** 791 * Delete a queue - freeing all the memory allocated for storing of items 792 * placed on the queue. 793 * 794 * @param xQueue A handle to the queue to be deleted. 795 * 796 * \ingroup QueueManagement 797 */ 798 void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 799 800 /** 801 * This is a macro that calls xQueueGenericSendFromISR(). 802 * 803 * Post an item to the front of a queue. It is safe to use this macro from 804 * within an interrupt service routine. 805 * 806 * Items are queued by copy not reference so it is preferable to only 807 * queue small items, especially when called from an ISR. In most cases 808 * it would be preferable to store a pointer to the item being queued. 809 * 810 * @param xQueue The handle to the queue on which the item is to be posted. 811 * 812 * @param pvItemToQueue A pointer to the item that is to be placed on the 813 * queue. The size of the items the queue will hold was defined when the 814 * queue was created, so this many bytes will be copied from pvItemToQueue 815 * into the queue storage area. 816 * 817 * @param[out] pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set 818 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 819 * to unblock, and the unblocked task has a priority higher than the currently 820 * running task. If xQueueSendToFromFromISR() sets this value to pdTRUE then 821 * a context switch should be requested before the interrupt is exited. 822 * 823 * @return pdTRUE if the data was successfully sent to the queue, otherwise 824 * errQUEUE_FULL. 825 * 826 * Example usage for buffered IO (where the ISR can obtain more than one value 827 * per call): 828 * @code{c} 829 * void vBufferISR( void ) 830 * { 831 * char cIn; 832 * BaseType_t xHigherPrioritTaskWoken; 833 * 834 * // We have not woken a task at the start of the ISR. 835 * xHigherPriorityTaskWoken = pdFALSE; 836 * 837 * // Loop until the buffer is empty. 838 * do 839 * { 840 * // Obtain a byte from the buffer. 841 * cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 842 * 843 * // Post the byte. 844 * xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 845 * 846 * } while( portINPUT_BYTE( BUFFER_COUNT ) ); 847 * 848 * // Now the buffer is empty we can switch context if necessary. 849 * if( xHigherPriorityTaskWoken ) 850 * { 851 * portYIELD_FROM_ISR (); 852 * } 853 * } 854 * @endcode 855 * \ingroup QueueManagement 856 */ 857 #define xQueueSendToFrontFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_FRONT ) 858 859 860 /** 861 * This is a macro that calls xQueueGenericSendFromISR(). 862 * 863 * Post an item to the back of a queue. It is safe to use this macro from 864 * within an interrupt service routine. 865 * 866 * Items are queued by copy not reference so it is preferable to only 867 * queue small items, especially when called from an ISR. In most cases 868 * it would be preferable to store a pointer to the item being queued. 869 * 870 * @param xQueue The handle to the queue on which the item is to be posted. 871 * 872 * @param pvItemToQueue A pointer to the item that is to be placed on the 873 * queue. The size of the items the queue will hold was defined when the 874 * queue was created, so this many bytes will be copied from pvItemToQueue 875 * into the queue storage area. 876 * 877 * @param[out] pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set 878 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 879 * to unblock, and the unblocked task has a priority higher than the currently 880 * running task. If xQueueSendToBackFromISR() sets this value to pdTRUE then 881 * a context switch should be requested before the interrupt is exited. 882 * 883 * @return pdTRUE if the data was successfully sent to the queue, otherwise 884 * errQUEUE_FULL. 885 * 886 * Example usage for buffered IO (where the ISR can obtain more than one value 887 * per call): 888 * @code{c} 889 * void vBufferISR( void ) 890 * { 891 * char cIn; 892 * BaseType_t xHigherPriorityTaskWoken; 893 * 894 * // We have not woken a task at the start of the ISR. 895 * xHigherPriorityTaskWoken = pdFALSE; 896 * 897 * // Loop until the buffer is empty. 898 * do 899 * { 900 * // Obtain a byte from the buffer. 901 * cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 902 * 903 * // Post the byte. 904 * xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 905 * 906 * } while( portINPUT_BYTE( BUFFER_COUNT ) ); 907 * 908 * // Now the buffer is empty we can switch context if necessary. 909 * if( xHigherPriorityTaskWoken ) 910 * { 911 * portYIELD_FROM_ISR (); 912 * } 913 * } 914 * @endcode 915 * \ingroup QueueManagement 916 */ 917 #define xQueueSendToBackFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) 918 919 /** 920 * A version of xQueueOverwrite() that can be used in an interrupt service 921 * routine (ISR). 922 * 923 * Only for use with queues that can hold a single item - so the queue is either 924 * empty or full. 925 * 926 * Post an item on a queue. If the queue is already full then overwrite the 927 * value held in the queue. The item is queued by copy, not by reference. 928 * 929 * @param xQueue The handle to the queue on which the item is to be posted. 930 * 931 * @param pvItemToQueue A pointer to the item that is to be placed on the 932 * queue. The size of the items the queue will hold was defined when the 933 * queue was created, so this many bytes will be copied from pvItemToQueue 934 * into the queue storage area. 935 * 936 * @param[out] pxHigherPriorityTaskWoken xQueueOverwriteFromISR() will set 937 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 938 * to unblock, and the unblocked task has a priority higher than the currently 939 * running task. If xQueueOverwriteFromISR() sets this value to pdTRUE then 940 * a context switch should be requested before the interrupt is exited. 941 * 942 * @return xQueueOverwriteFromISR() is a macro that calls 943 * xQueueGenericSendFromISR(), and therefore has the same return values as 944 * xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be 945 * returned because xQueueOverwriteFromISR() will write to the queue even when 946 * the queue is already full. 947 * 948 * Example usage: 949 * @code{c} 950 * QueueHandle_t xQueue; 951 * 952 * void vFunction( void *pvParameters ) 953 * { 954 * // Create a queue to hold one uint32_t value. It is strongly 955 * // recommended *not* to use xQueueOverwriteFromISR() on queues that can 956 * // contain more than one value, and doing so will trigger an assertion 957 * // if configASSERT() is defined. 958 * xQueue = xQueueCreate( 1, sizeof( uint32_t ) ); 959 * } 960 * 961 * void vAnInterruptHandler( void ) 962 * { 963 * // xHigherPriorityTaskWoken must be set to pdFALSE before it is used. 964 * BaseType_t xHigherPriorityTaskWoken = pdFALSE; 965 * uint32_t ulVarToSend, ulValReceived; 966 * 967 * // Write the value 10 to the queue using xQueueOverwriteFromISR(). 968 * ulVarToSend = 10; 969 * xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken ); 970 * 971 * // The queue is full, but calling xQueueOverwriteFromISR() again will still 972 * // pass because the value held in the queue will be overwritten with the 973 * // new value. 974 * ulVarToSend = 100; 975 * xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken ); 976 * 977 * // Reading from the queue will now return 100. 978 * 979 * // ... 980 * 981 * if( xHigherPrioritytaskWoken == pdTRUE ) 982 * { 983 * // Writing to the queue caused a task to unblock and the unblocked task 984 * // has a priority higher than or equal to the priority of the currently 985 * // executing task (the task this interrupt interrupted). Perform a context 986 * // switch so this interrupt returns directly to the unblocked task. 987 * portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port. 988 * } 989 * } 990 * @endcode 991 * \ingroup QueueManagement 992 */ 993 #define xQueueOverwriteFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueOVERWRITE ) 994 995 /** 996 * This is a macro that calls xQueueGenericSendFromISR(). It is included 997 * for backward compatibility with versions of FreeRTOS.org that did not 998 * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR() 999 * macros. 1000 * 1001 * Post an item to the back of a queue. It is safe to use this function from 1002 * within an interrupt service routine. 1003 * 1004 * Items are queued by copy not reference so it is preferable to only 1005 * queue small items, especially when called from an ISR. In most cases 1006 * it would be preferable to store a pointer to the item being queued. 1007 * 1008 * @param xQueue The handle to the queue on which the item is to be posted. 1009 * 1010 * @param pvItemToQueue A pointer to the item that is to be placed on the 1011 * queue. The size of the items the queue will hold was defined when the 1012 * queue was created, so this many bytes will be copied from pvItemToQueue 1013 * into the queue storage area. 1014 * 1015 * @param[out] pxHigherPriorityTaskWoken xQueueSendFromISR() will set 1016 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 1017 * to unblock, and the unblocked task has a priority higher than the currently 1018 * running task. If xQueueSendFromISR() sets this value to pdTRUE then 1019 * a context switch should be requested before the interrupt is exited. 1020 * 1021 * @return pdTRUE if the data was successfully sent to the queue, otherwise 1022 * errQUEUE_FULL. 1023 * 1024 * Example usage for buffered IO (where the ISR can obtain more than one value 1025 * per call): 1026 * @code{c} 1027 * void vBufferISR( void ) 1028 * { 1029 * char cIn; 1030 * BaseType_t xHigherPriorityTaskWoken; 1031 * 1032 * // We have not woken a task at the start of the ISR. 1033 * xHigherPriorityTaskWoken = pdFALSE; 1034 * 1035 * // Loop until the buffer is empty. 1036 * do 1037 * { 1038 * // Obtain a byte from the buffer. 1039 * cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 1040 * 1041 * // Post the byte. 1042 * xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken ); 1043 * 1044 * } while( portINPUT_BYTE( BUFFER_COUNT ) ); 1045 * 1046 * // Now the buffer is empty we can switch context if necessary. 1047 * if( xHigherPriorityTaskWoken ) 1048 * { 1049 * // Actual macro used here is port specific. 1050 * portYIELD_FROM_ISR (); 1051 * } 1052 * } 1053 * @endcode 1054 * 1055 * \ingroup QueueManagement 1056 */ 1057 #define xQueueSendFromISR( xQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( ( xQueue ), ( pvItemToQueue ), ( pxHigherPriorityTaskWoken ), queueSEND_TO_BACK ) 1058 1059 /**@{*/ 1060 /** 1061 * It is preferred that the macros xQueueSendFromISR(), 1062 * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place 1063 * of calling this function directly. xQueueGiveFromISR() is an 1064 * equivalent for use by semaphores that don't actually copy any data. 1065 * 1066 * Post an item on a queue. It is safe to use this function from within an 1067 * interrupt service routine. 1068 * 1069 * Items are queued by copy not reference so it is preferable to only 1070 * queue small items, especially when called from an ISR. In most cases 1071 * it would be preferable to store a pointer to the item being queued. 1072 * 1073 * @param xQueue The handle to the queue on which the item is to be posted. 1074 * 1075 * @param pvItemToQueue A pointer to the item that is to be placed on the 1076 * queue. The size of the items the queue will hold was defined when the 1077 * queue was created, so this many bytes will be copied from pvItemToQueue 1078 * into the queue storage area. 1079 * 1080 * @param[out] pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set 1081 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task 1082 * to unblock, and the unblocked task has a priority higher than the currently 1083 * running task. If xQueueGenericSendFromISR() sets this value to pdTRUE then 1084 * a context switch should be requested before the interrupt is exited. 1085 * 1086 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the 1087 * item at the back of the queue, or queueSEND_TO_FRONT to place the item 1088 * at the front of the queue (for high priority messages). 1089 * 1090 * @return pdTRUE if the data was successfully sent to the queue, otherwise 1091 * errQUEUE_FULL. 1092 * 1093 * Example usage for buffered IO (where the ISR can obtain more than one value 1094 * per call): 1095 * @code{c} 1096 * void vBufferISR( void ) 1097 * { 1098 * char cIn; 1099 * BaseType_t xHigherPriorityTaskWokenByPost; 1100 * 1101 * // We have not woken a task at the start of the ISR. 1102 * xHigherPriorityTaskWokenByPost = pdFALSE; 1103 * 1104 * // Loop until the buffer is empty. 1105 * do 1106 * { 1107 * // Obtain a byte from the buffer. 1108 * cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS ); 1109 * 1110 * // Post each byte. 1111 * xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK ); 1112 * 1113 * } while( portINPUT_BYTE( BUFFER_COUNT ) ); 1114 * 1115 * // Now the buffer is empty we can switch context if necessary. Note that the 1116 * // name of the yield function required is port specific. 1117 * if( xHigherPriorityTaskWokenByPost ) 1118 * { 1119 * taskYIELD_YIELD_FROM_ISR(); 1120 * } 1121 * } 1122 * @endcode 1123 * \ingroup QueueManagement 1124 */ 1125 BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue, const void * const pvItemToQueue, BaseType_t * const pxHigherPriorityTaskWoken, const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION; 1126 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1127 /**@}*/ 1128 1129 /** 1130 * Receive an item from a queue. It is safe to use this function from within an 1131 * interrupt service routine. 1132 * 1133 * @param xQueue The handle to the queue from which the item is to be 1134 * received. 1135 * 1136 * @param pvBuffer Pointer to the buffer into which the received item will 1137 * be copied. 1138 * 1139 * @param[out] pxHigherPriorityTaskWoken A task may be blocked waiting for space to become 1140 * available on the queue. If xQueueReceiveFromISR causes such a task to 1141 * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will 1142 * remain unchanged. 1143 * 1144 * @return pdTRUE if an item was successfully received from the queue, 1145 * otherwise pdFALSE. 1146 * 1147 * Example usage: 1148 * @code{c} 1149 * QueueHandle_t xQueue; 1150 * 1151 * // Function to create a queue and post some values. 1152 * void vAFunction( void *pvParameters ) 1153 * { 1154 * char cValueToPost; 1155 * const TickType_t xTicksToWait = ( TickType_t )0xff; 1156 * 1157 * // Create a queue capable of containing 10 characters. 1158 * xQueue = xQueueCreate( 10, sizeof( char ) ); 1159 * if( xQueue == 0 ) 1160 * { 1161 * // Failed to create the queue. 1162 * } 1163 * 1164 * // ... 1165 * 1166 * // Post some characters that will be used within an ISR. If the queue 1167 * // is full then this task will block for xTicksToWait ticks. 1168 * cValueToPost = 'a'; 1169 * xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait ); 1170 * cValueToPost = 'b'; 1171 * xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait ); 1172 * 1173 * // ... keep posting characters ... this task may block when the queue 1174 * // becomes full. 1175 * 1176 * cValueToPost = 'c'; 1177 * xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait ); 1178 * } 1179 * 1180 * // ISR that outputs all the characters received on the queue. 1181 * void vISR_Routine( void ) 1182 * { 1183 * BaseType_t xTaskWokenByReceive = pdFALSE; 1184 * char cRxedChar; 1185 * 1186 * while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) ) 1187 * { 1188 * // A character was received. Output the character now. 1189 * vOutputCharacter( cRxedChar ); 1190 * 1191 * // If removing the character from the queue woke the task that was 1192 * // posting onto the queue cTaskWokenByReceive will have been set to 1193 * // pdTRUE. No matter how many times this loop iterates only one 1194 * // task will be woken. 1195 * } 1196 * 1197 * if( cTaskWokenByPost != ( char ) pdFALSE; 1198 * { 1199 * taskYIELD (); 1200 * } 1201 * } 1202 * @endcode 1203 * \ingroup QueueManagement 1204 */ 1205 BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue, void * const pvBuffer, BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION; 1206 1207 /* 1208 * Utilities to query queues that are safe to use from an ISR. These utilities 1209 * should be used only from witin an ISR, or within a critical section. 1210 */ 1211 BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1212 BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1213 UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1214 1215 /** @cond */ 1216 /** 1217 * The functions defined above are for passing data to and from tasks. The 1218 * functions below are the equivalents for passing data to and from 1219 * co-routines. 1220 * 1221 * These functions are called from the co-routine macro implementation and 1222 * should not be called directly from application code. Instead use the macro 1223 * wrappers defined within croutine.h. 1224 */ 1225 BaseType_t xQueueCRSendFromISR( QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t xCoRoutinePreviouslyWoken ); 1226 BaseType_t xQueueCRReceiveFromISR( QueueHandle_t xQueue, void *pvBuffer, BaseType_t *pxTaskWoken ); 1227 BaseType_t xQueueCRSend( QueueHandle_t xQueue, const void *pvItemToQueue, TickType_t xTicksToWait ); 1228 BaseType_t xQueueCRReceive( QueueHandle_t xQueue, void *pvBuffer, TickType_t xTicksToWait ); 1229 1230 /** 1231 * For internal use only. Use xSemaphoreCreateMutex(), 1232 * xSemaphoreCreateCounting() or xSemaphoreGetMutexHolder() instead of calling 1233 * these functions directly. 1234 */ 1235 QueueHandle_t xQueueCreateMutex( const uint8_t ucQueueType ) PRIVILEGED_FUNCTION; 1236 QueueHandle_t xQueueCreateMutexStatic( const uint8_t ucQueueType, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION; 1237 QueueHandle_t xQueueCreateCountingSemaphore( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount ) PRIVILEGED_FUNCTION; 1238 QueueHandle_t xQueueCreateCountingSemaphoreStatic( const UBaseType_t uxMaxCount, const UBaseType_t uxInitialCount, StaticQueue_t *pxStaticQueue ) PRIVILEGED_FUNCTION; 1239 BaseType_t xQueueSemaphoreTake( QueueHandle_t xQueue, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 1240 TaskHandle_t xQueueGetMutexHolder( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION; 1241 TaskHandle_t xQueueGetMutexHolderFromISR( QueueHandle_t xSemaphore ) PRIVILEGED_FUNCTION; 1242 1243 /** 1244 * For internal use only. Use xSemaphoreTakeMutexRecursive() or 1245 * xSemaphoreGiveMutexRecursive() instead of calling these functions directly. 1246 */ 1247 BaseType_t xQueueTakeMutexRecursive( QueueHandle_t xMutex, TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 1248 BaseType_t xQueueGiveMutexRecursive( QueueHandle_t xMutex ) PRIVILEGED_FUNCTION; 1249 1250 /** @endcond */ 1251 1252 /** 1253 * Reset a queue back to its original empty state. The return value is now 1254 * obsolete and is always set to pdPASS. 1255 */ 1256 #define xQueueReset( xQueue ) xQueueGenericReset( xQueue, pdFALSE ) 1257 1258 /** 1259 * The registry is provided as a means for kernel aware debuggers to 1260 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add 1261 * a queue, semaphore or mutex handle to the registry if you want the handle 1262 * to be available to a kernel aware debugger. If you are not using a kernel 1263 * aware debugger then this function can be ignored. 1264 * 1265 * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the 1266 * registry can hold. configQUEUE_REGISTRY_SIZE must be greater than 0 1267 * within FreeRTOSConfig.h for the registry to be available. Its value 1268 * does not effect the number of queues, semaphores and mutexes that can be 1269 * created - just the number that the registry can hold. 1270 * 1271 * @param xQueue The handle of the queue being added to the registry. This 1272 * is the handle returned by a call to xQueueCreate(). Semaphore and mutex 1273 * handles can also be passed in here. 1274 * 1275 * @param pcQueueName The name to be associated with the handle. This is the 1276 * name that the kernel aware debugger will display. The queue registry only 1277 * stores a pointer to the string - so the string must be persistent (global or 1278 * preferably in ROM/Flash), not on the stack. 1279 */ 1280 #if( configQUEUE_REGISTRY_SIZE > 0 ) 1281 void vQueueAddToRegistry( QueueHandle_t xQueue, const char *pcQueueName ) PRIVILEGED_FUNCTION; /**lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1282 #endif 1283 1284 /** 1285 * The registry is provided as a means for kernel aware debuggers to 1286 * locate queues, semaphores and mutexes. Call vQueueAddToRegistry() add 1287 * a queue, semaphore or mutex handle to the registry if you want the handle 1288 * to be available to a kernel aware debugger, and vQueueUnregisterQueue() to 1289 * remove the queue, semaphore or mutex from the register. If you are not using 1290 * a kernel aware debugger then this function can be ignored. 1291 * 1292 * @param xQueue The handle of the queue being removed from the registry. 1293 */ 1294 #if( configQUEUE_REGISTRY_SIZE > 0 ) 1295 void vQueueUnregisterQueue( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1296 #endif 1297 1298 /** 1299 * The queue registry is provided as a means for kernel aware debuggers to 1300 * locate queues, semaphores and mutexes. Call pcQueueGetName() to look 1301 * up and return the name of a queue in the queue registry from the queue's 1302 * handle. 1303 * 1304 * @param xQueue The handle of the queue the name of which will be returned. 1305 * @return If the queue is in the registry then a pointer to the name of the 1306 * queue is returned. If the queue is not in the registry then NULL is 1307 * returned. 1308 */ 1309 #if( configQUEUE_REGISTRY_SIZE > 0 ) 1310 const char *pcQueueGetName( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; /**lint !e971 Unqualified char types are allowed for strings and single characters only. */ 1311 #endif 1312 1313 /** 1314 * Generic version of the function used to creaet a queue using dynamic memory 1315 * allocation. This is called by other functions and macros that create other 1316 * RTOS objects that use the queue structure as their base. 1317 */ 1318 #if( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) 1319 QueueHandle_t xQueueGenericCreate( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION; 1320 #endif 1321 1322 /** 1323 * Generic version of the function used to creaet a queue using dynamic memory 1324 * allocation. This is called by other functions and macros that create other 1325 * RTOS objects that use the queue structure as their base. 1326 */ 1327 #if( configSUPPORT_STATIC_ALLOCATION == 1 ) 1328 QueueHandle_t xQueueGenericCreateStatic( const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType ) PRIVILEGED_FUNCTION; 1329 #endif 1330 1331 /** 1332 * Queue sets provide a mechanism to allow a task to block (pend) on a read 1333 * operation from multiple queues or semaphores simultaneously. 1334 * 1335 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 1336 * function. 1337 * 1338 * A queue set must be explicitly created using a call to xQueueCreateSet() 1339 * before it can be used. Once created, standard FreeRTOS queues and semaphores 1340 * can be added to the set using calls to xQueueAddToSet(). 1341 * xQueueSelectFromSet() is then used to determine which, if any, of the queues 1342 * or semaphores contained in the set is in a state where a queue read or 1343 * semaphore take operation would be successful. 1344 * 1345 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html 1346 * for reasons why queue sets are very rarely needed in practice as there are 1347 * simpler methods of blocking on multiple objects. 1348 * 1349 * Note 2: Blocking on a queue set that contains a mutex will not cause the 1350 * mutex holder to inherit the priority of the blocked task. 1351 * 1352 * Note 3: An additional 4 bytes of RAM is required for each space in a every 1353 * queue added to a queue set. Therefore counting semaphores that have a high 1354 * maximum count value should not be added to a queue set. 1355 * 1356 * Note 4: A receive (in the case of a queue) or take (in the case of a 1357 * semaphore) operation must not be performed on a member of a queue set unless 1358 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 1359 * 1360 * @param uxEventQueueLength Queue sets store events that occur on 1361 * the queues and semaphores contained in the set. uxEventQueueLength specifies 1362 * the maximum number of events that can be queued at once. To be absolutely 1363 * certain that events are not lost uxEventQueueLength should be set to the 1364 * total sum of the length of the queues added to the set, where binary 1365 * semaphores and mutexes have a length of 1, and counting semaphores have a 1366 * length set by their maximum count value. Examples: 1367 * + If a queue set is to hold a queue of length 5, another queue of length 12, 1368 * and a binary semaphore, then uxEventQueueLength should be set to 1369 * (5 + 12 + 1), or 18. 1370 * + If a queue set is to hold three binary semaphores then uxEventQueueLength 1371 * should be set to (1 + 1 + 1 ), or 3. 1372 * + If a queue set is to hold a counting semaphore that has a maximum count of 1373 * 5, and a counting semaphore that has a maximum count of 3, then 1374 * uxEventQueueLength should be set to (5 + 3), or 8. 1375 * 1376 * @return If the queue set is created successfully then a handle to the created 1377 * queue set is returned. Otherwise NULL is returned. 1378 */ 1379 QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength ) PRIVILEGED_FUNCTION; 1380 1381 /** 1382 * Adds a queue or semaphore to a queue set that was previously created by a 1383 * call to xQueueCreateSet(). 1384 * 1385 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 1386 * function. 1387 * 1388 * Note 1: A receive (in the case of a queue) or take (in the case of a 1389 * semaphore) operation must not be performed on a member of a queue set unless 1390 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 1391 * 1392 * @param xQueueOrSemaphore The handle of the queue or semaphore being added to 1393 * the queue set (cast to an QueueSetMemberHandle_t type). 1394 * 1395 * @param xQueueSet The handle of the queue set to which the queue or semaphore 1396 * is being added. 1397 * 1398 * @return If the queue or semaphore was successfully added to the queue set 1399 * then pdPASS is returned. If the queue could not be successfully added to the 1400 * queue set because it is already a member of a different queue set then pdFAIL 1401 * is returned. 1402 */ 1403 BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; 1404 1405 /** 1406 * Removes a queue or semaphore from a queue set. A queue or semaphore can only 1407 * be removed from a set if the queue or semaphore is empty. 1408 * 1409 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 1410 * function. 1411 * 1412 * @param xQueueOrSemaphore The handle of the queue or semaphore being removed 1413 * from the queue set (cast to an QueueSetMemberHandle_t type). 1414 * 1415 * @param xQueueSet The handle of the queue set in which the queue or semaphore 1416 * is included. 1417 * 1418 * @return If the queue or semaphore was successfully removed from the queue set 1419 * then pdPASS is returned. If the queue was not in the queue set, or the 1420 * queue (or semaphore) was not empty, then pdFAIL is returned. 1421 */ 1422 BaseType_t xQueueRemoveFromSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; 1423 1424 /** 1425 * xQueueSelectFromSet() selects from the members of a queue set a queue or 1426 * semaphore that either contains data (in the case of a queue) or is available 1427 * to take (in the case of a semaphore). xQueueSelectFromSet() effectively 1428 * allows a task to block (pend) on a read operation on all the queues and 1429 * semaphores in a queue set simultaneously. 1430 * 1431 * See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this 1432 * function. 1433 * 1434 * Note 1: See the documentation on http://wwwFreeRTOS.org/RTOS-queue-sets.html 1435 * for reasons why queue sets are very rarely needed in practice as there are 1436 * simpler methods of blocking on multiple objects. 1437 * 1438 * Note 2: Blocking on a queue set that contains a mutex will not cause the 1439 * mutex holder to inherit the priority of the blocked task. 1440 * 1441 * Note 3: A receive (in the case of a queue) or take (in the case of a 1442 * semaphore) operation must not be performed on a member of a queue set unless 1443 * a call to xQueueSelectFromSet() has first returned a handle to that set member. 1444 * 1445 * @param xQueueSet The queue set on which the task will (potentially) block. 1446 * 1447 * @param xTicksToWait The maximum time, in ticks, that the calling task will 1448 * remain in the Blocked state (with other tasks executing) to wait for a member 1449 * of the queue set to be ready for a successful queue read or semaphore take 1450 * operation. 1451 * 1452 * @return xQueueSelectFromSet() will return the handle of a queue (cast to 1453 * a QueueSetMemberHandle_t type) contained in the queue set that contains data, 1454 * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained 1455 * in the queue set that is available, or NULL if no such queue or semaphore 1456 * exists before before the specified block time expires. 1457 */ 1458 QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait ) PRIVILEGED_FUNCTION; 1459 1460 /** 1461 * A version of xQueueSelectFromSet() that can be used from an ISR. 1462 */ 1463 QueueSetMemberHandle_t xQueueSelectFromSetFromISR( QueueSetHandle_t xQueueSet ) PRIVILEGED_FUNCTION; 1464 1465 /** @cond */ 1466 1467 /* Not public API functions. */ 1468 void vQueueWaitForMessageRestricted( QueueHandle_t xQueue, TickType_t xTicksToWait, const BaseType_t xWaitIndefinitely ) PRIVILEGED_FUNCTION; 1469 BaseType_t xQueueGenericReset( QueueHandle_t xQueue, BaseType_t xNewQueue ) PRIVILEGED_FUNCTION; 1470 void vQueueSetQueueNumber( QueueHandle_t xQueue, UBaseType_t uxQueueNumber ) PRIVILEGED_FUNCTION; 1471 UBaseType_t uxQueueGetQueueNumber( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1472 uint8_t ucQueueGetQueueType( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION; 1473 1474 /** @endcond */ 1475 1476 #ifdef __cplusplus 1477 } 1478 #endif 1479 1480 #endif /* QUEUE_H */ 1481
