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