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