1 /* ---------------------------------------------------------------------------- 2 * Copyright (c) Huawei Technologies Co., Ltd. 2013-2022. All rights reserved. 3 * Description: Queue 4 * Author: Huawei LiteOS Team 5 * Create: 2013-01-01 6 * Redistribution and use in source and binary forms, with or without modification, 7 * are permitted provided that the following conditions are met: 8 * 1. Redistributions of source code must retain the above copyright notice, this list of 9 * conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list 11 * of conditions and the following disclaimer in the documentation and/or other materials 12 * provided with the distribution. 13 * 3. Neither the name of the copyright holder nor the names of its contributors may be used 14 * to endorse or promote products derived from this software without specific prior written 15 * permission. 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 18 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 20 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 21 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 22 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 23 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 25 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 26 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 * --------------------------------------------------------------------------- */ 28 29 /** 30 * @defgroup los_queue Queue 31 * @ingroup kernel 32 */ 33 34 #ifndef _LOS_QUEUE_H 35 #define _LOS_QUEUE_H 36 37 #include "los_base.h" 38 #include "los_list.h" 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif /* __cplusplus */ 43 44 /** 45 * @ingroup los_queue 46 * Queue error code: The maximum number of queue resources is configured to 0. 47 * 48 * Value: 0x02000600. 49 * 50 * Solution: Configure the maximum number of queue resources to be greater than 0. If queue 51 * modules are not used, set the configuration item for the tailoring of the maximum number 52 * of queue resources to NO. 53 * @deprecated This error code is obsolete since LiteOS 5.0.0. 54 */ 55 #define LOS_ERRNO_QUEUE_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x00) 56 57 /** 58 * @ingroup los_queue 59 * Queue error code: The queue block memory fails to be initialized. 60 * 61 * Value: 0x02000601. 62 * 63 * Solution: Allocate the queue block bigger memory partition, or decrease the maximum 64 * number of queue resources. 65 */ 66 #define LOS_ERRNO_QUEUE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x01) 67 68 /** 69 * @ingroup los_queue 70 * Queue error code: The memory for queue creation fails to be requested. 71 * 72 * Value: 0x02000602. 73 * 74 * Solution: Allocate more memory for queue creation, or decrease the queue length and 75 * the number of nodes in the queue to be created. 76 */ 77 #define LOS_ERRNO_QUEUE_CREATE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x02) 78 79 /** 80 * @ingroup los_queue 81 * Queue error code: The size of the biggest message in the created queue is too big. 82 * 83 * Value: 0x02000603. 84 * 85 * Solution: Change the size of the biggest message in the created queue. 86 */ 87 #define LOS_ERRNO_QUEUE_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x03) 88 89 /** 90 * @ingroup los_queue 91 * Queue error code: The upper limit of the number of created queues is exceeded. 92 * 93 * Value: 0x02000604. 94 * 95 * Solution: Increase the configured number of resources for queues. 96 */ 97 #define LOS_ERRNO_QUEUE_CB_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x04) 98 99 /** 100 * @ingroup los_queue 101 * Queue error code: Invalid queue. 102 * 103 * Value: 0x02000605. 104 * 105 * Solution: Ensure that the passed-in queue ID is valid. 106 */ 107 #define LOS_ERRNO_QUEUE_NOT_FOUND LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x05) 108 109 /** 110 * @ingroup los_queue 111 * Queue error code: The task is forbidden to be blocked on a queue when the task is locked. 112 * 113 * Value: 0x02000606. 114 * 115 * Solution: Unlock the task before using a queue. 116 */ 117 #define LOS_ERRNO_QUEUE_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x06) 118 119 /** 120 * @ingroup los_queue 121 * Queue error code: The time set for waiting to processing the queue expires. 122 * 123 * Value: 0x02000607. 124 * 125 * Solution: Check whether the expiry time setting is appropriate. 126 */ 127 #define LOS_ERRNO_QUEUE_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x07) 128 129 /** 130 * @ingroup los_queue 131 * Queue error code: The queue that blocks a task cannot be deleted. 132 * 133 * Value: 0x02000608. 134 * 135 * Solution: Enable the task to obtain resources rather than be blocked on the queue. 136 */ 137 #define LOS_ERRNO_QUEUE_IN_TSKUSE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x08) 138 139 /** 140 * @ingroup los_queue 141 * Queue error code: The queue cannot be written during an interrupt when the time for 142 * waiting to processing the queue expires. 143 * 144 * Value: 0x02000609. 145 * 146 * Solution: Set the expiry time to the never-waiting mode, or use asynchronous queues. 147 */ 148 #define LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x09) 149 150 /** 151 * @ingroup los_queue 152 * Queue error code: The queue is not created. 153 * 154 * Value: 0x0200060a. 155 * 156 * Solution: Check whether the passed-in queue handle value is valid. 157 */ 158 #define LOS_ERRNO_QUEUE_NOT_CREATE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0a) 159 160 /** 161 * @ingroup los_queue 162 * Queue error code: Queue reading and writing are not synchronous. 163 * 164 * Value: 0x0200060b. 165 * 166 * Solution: Synchronize queue reading with queue writing. 167 */ 168 #define LOS_ERRNO_QUEUE_IN_TSKWRITE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0b) 169 170 /** 171 * @ingroup los_queue 172 * Queue error code: Parameters passed in during queue creation are null pointers. 173 * 174 * Value: 0x0200060c. 175 * 176 * Solution: Ensure the passed-in parameters are not null pointers. 177 */ 178 #define LOS_ERRNO_QUEUE_CREAT_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0c) 179 180 /** 181 * @ingroup los_queue 182 * Queue error code: The queue length or message node size passed in during queue creation is 0. 183 * 184 * Value: 0x0200060d. 185 * 186 * Solution: Pass in correct queue length and message node size. 187 */ 188 #define LOS_ERRNO_QUEUE_PARA_ISZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0d) 189 190 /** 191 * @ingroup los_queue 192 * Queue error code: The handle of the queue is invalid. 193 * 194 * Value: 0x0200060e. 195 * 196 * Solution: Check whether the passed-in queue handle value is valid. 197 */ 198 #define LOS_ERRNO_QUEUE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0e) 199 200 /** 201 * @ingroup los_queue 202 * Queue error code: The pointer passed in during queue reading is null. 203 * 204 * Value: 0x0200060f. 205 * 206 * Solution: Check whether the passed-in pointer is null. 207 */ 208 #define LOS_ERRNO_QUEUE_READ_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0f) 209 210 /** 211 * @ingroup los_queue 212 * Queue error code: The buffer size passed in during queue reading is too small or too big. 213 * 214 * Value: 0x02000610. 215 * 216 * Solution: Pass in a correct buffer size between [sizeof(CHAR*), OS_NULL_SHORT]. 217 */ 218 #define LOS_ERRNO_QUEUE_READSIZE_IS_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x10) 219 220 /** 221 * @ingroup los_queue 222 * Queue error code: The pointer passed in during queue writing is null. 223 * 224 * Value: 0x02000612. 225 * 226 * Solution: Check whether the passed-in pointer is null. 227 */ 228 #define LOS_ERRNO_QUEUE_WRITE_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x12) 229 230 /** 231 * @ingroup los_queue 232 * Queue error code: The buffer size passed in during queue writing is 0. 233 * 234 * Value: 0x02000613. 235 * 236 * Solution: Pass in a correct buffer size. 237 */ 238 #define LOS_ERRNO_QUEUE_WRITESIZE_ISZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x13) 239 240 /** 241 * @ingroup los_queue 242 * Queue error code: The buffer size passed in during queue writing is bigger than the queue size. 243 * 244 * Value: 0x02000615. 245 * 246 * Solution: Decrease the buffer size, or use a queue in which nodes are bigger. 247 */ 248 #define LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x15) 249 250 /** 251 * @ingroup los_queue 252 * Queue error code: No free node is available during queue writing. 253 * 254 * Value: 0x02000616. 255 * 256 * Solution: Ensure that free nodes are available before queue writing. 257 */ 258 #define LOS_ERRNO_QUEUE_ISFULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x16) 259 260 /** 261 * @ingroup los_queue 262 * Queue error code: The pointer passed in when the queue information is being obtained is null. 263 * 264 * Value: 0x02000617. 265 * 266 * Solution: Check whether the passed-in pointer is null. 267 */ 268 #define LOS_ERRNO_QUEUE_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x17) 269 270 /** 271 * @ingroup los_queue 272 * Queue error code: The queue cannot be read during an interrupt 273 * when the time for waiting to processing the queue expires. 274 * 275 * Value: 0x02000618. 276 * 277 * Solution: Set the expiry time to the never-waiting mode, or use asynchronous queues. 278 */ 279 #define LOS_ERRNO_QUEUE_READ_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x18) 280 281 /** 282 * @ingroup los_queue 283 * Queue error code: The handle of the queue passed-in when the memory for the queue is being freed is invalid. 284 * 285 * Value: 0x02000619. 286 * 287 * Solution: Check whether the passed-in queue handle value is valid. 288 */ 289 #define LOS_ERRNO_QUEUE_MAIL_HANDLE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x19) 290 291 /** 292 * @ingroup los_queue 293 * Queue error code: The pointer to the memory to be freed is null. 294 * 295 * Value: 0x0200061a. 296 * 297 * Solution: Check whether the passed-in pointer is null. 298 */ 299 #define LOS_ERRNO_QUEUE_MAIL_PTR_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1a) 300 301 /** 302 * @ingroup los_queue 303 * Queue error code: The memory for the queue fails to be freed. 304 * 305 * Value: 0x0200061b. 306 * 307 * Solution: Pass in correct input parameters. 308 */ 309 #define LOS_ERRNO_QUEUE_MAIL_FREE_ERROR LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1b) 310 311 /** 312 * @ingroup los_queue 313 * Queue error code: No resource is in the queue that is being read when the 314 * time for waiting to processing the queue expires. 315 * 316 * Value: 0x0200061d. 317 * 318 * Solution: Ensure that the queue contains messages when it is being read. 319 */ 320 #define LOS_ERRNO_QUEUE_ISEMPTY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1d) 321 322 /** 323 * @ingroup los_queue 324 * Queue error code: The buffer size passed in during queue reading is smaller than the queue size. 325 * 326 * Value: 0x0200061f. 327 * 328 * Solution: Increase the buffer size, or use a queue in which nodes are smaller. 329 */ 330 #define LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1f) 331 332 /** 333 * @ingroup los_queue 334 * Structure of the block for queue information query 335 */ 336 typedef struct tagQueueInfo { 337 UINT32 uwQueueID; /**< Queue ID */ 338 UINT16 usQueueLen; /**< Queue length, that is the number of node in the queue */ 339 UINT16 usQueueSize; /**< Node size in the queue */ 340 UINT16 usQueueHead; /**< The position of queue header node, it is an array subscript */ 341 UINT16 usQueueTail; /**< The position of queue tail node, it is an array subscript */ 342 UINT16 usWritableCnt; /**< Count of writable resources */ 343 UINT16 usReadableCnt; /**< Count of readable resources */ 344 UINT64 uwWaitReadTask; /**< Tasks waiting for reading message. It is a 64-bit unsigned 345 integer, each bit represents a task ID. Therefore, 64 tasks 346 can be represented, and the maximum task ID is 63. For example, 347 0x0200060001002010 means there are 6 tasks whose IDs are 4, 348 13, 24, 41, 42, and 57. */ 349 UINT64 uwWaitWriteTask; /**< Tasks waiting for writing message. It is a 64-bit unsigned 350 integer same with #uwWaitReadTask, each bit represents a task ID. */ 351 UINT64 uwWaitMemTask; /**< Tasks waiting for memory used by the MailBox in the CMSIS-RTOS. 352 It is a 64-bit unsigned integer same with #uwWaitReadTask, 353 each bit represents a task ID. */ 354 } QUEUE_INFO_S; 355 356 #ifdef LOSCFG_QUEUE_STATIC_ALLOCATION 357 /** 358 * @ingroup los_queue 359 * Size for external queue memory. 360 */ 361 #define LOS_QUEUEMEM_SIZE(msgSize, len) ((len) * ((msgSize) + sizeof(UINT32))) 362 363 /** 364 * @ingroup los_queue 365 * @brief Create a message queue. 366 * 367 * @par Description: 368 * This API is used to create a message queue by transferring the static memory for the queue. 369 * The input parameter "queueMem" is the pointer to the static memory the API can use directly. 370 * The input parameter "memSize" is the static memory size. 371 * @attention 372 * <ul> 373 * <li>There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary.</li> 374 * </ul> 375 * @param queueName [IN] Message queue name. Reserved parameter, not used for now. 376 * @param len [IN] Queue length. The value range is [1,0xffff]. 377 * @param queueId [OUT] ID of the queue control structure that is successfully created. 378 * @param flags [IN] Queue mode. Reserved parameter, not used for now. 379 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff]. 380 * @param queueMem [IN] Static queue memory. The value range is [0,0xffffffff]. 381 * @param memSize [IN] Queue memory size. The value range is [1,0xffff]. 382 383 * @retval #LOS_OK The message queue is successfully created. 384 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded. 385 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation. 386 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueID is NULL. 387 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue 388 * creation is 0. 389 * @par Dependency: 390 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 391 * @see LOS_QueueDelete | LOS_QueueCreate 392 * @since Huawei LiteOS V200R005C00 393 */ 394 extern UINT32 LOS_QueueCreateStatic(const CHAR *queueName, 395 UINT16 len, 396 UINT32 *queueId, 397 UINT32 flags, 398 UINT16 maxMsgSize, 399 VOID *queueMem, 400 UINT16 memSize); 401 #endif 402 403 #ifdef LOSCFG_QUEUE_DYNAMIC_ALLOCATION 404 /** 405 * @ingroup los_queue 406 * @brief Create a message queue. 407 * 408 * @par Description: 409 * This API is used to create a message queue. Different from LOS_QueueCreateStatic, 410 * the user does not need to transfer the queue memory. In the API, system allocated 411 * the queue memory automatically. 412 * @attention 413 * There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary. 414 * This function is defined only when LOSCFG_QUEUE_DYNAMIC_ALLOCATION is defined. 415 * @param queueName [IN] Message queue name. Reserved parameter, not used for now. 416 * @param len [IN] Queue length. The value range is [1,0xffff]. 417 * @param queueId [OUT] ID of the queue control structure that is successfully created. 418 * @param flags [IN] Queue mode. Reserved parameter, not used for now. 419 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff]. 420 * 421 * @retval #LOS_OK The message queue is successfully created. 422 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded. 423 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation. 424 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueId is NULL. 425 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue 426 * creation is 0. 427 * @par Dependency: 428 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 429 * @see LOS_QueueDelete | LOS_QueueCreateStatic 430 * @since Huawei LiteOS V100R001C00 431 */ 432 extern UINT32 LOS_QueueCreate(const CHAR *queueName, 433 UINT16 len, 434 UINT32 *queueId, 435 UINT32 flags, 436 UINT16 maxMsgSize); 437 #endif 438 439 /** 440 * @ingroup los_queue 441 * @brief Read a queue. 442 * 443 * @par Description: 444 * This API is used to read data in a specified queue, and store the obtained data to the address specified 445 * by bufferAddr. The address and the size of the data to be read are defined by users. 446 * @attention 447 * <ul> 448 * <li>The specific queue should be created firstly.</li> 449 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is read 450 * first.</li> 451 * <li>bufferAddr stores the obtained data.</li> 452 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 453 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 454 * <li>The argument timeout is a relative time.</li> 455 * <li>Do not call this API in software timer callback. </li> 456 * </ul> 457 * 458 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 459 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 460 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must not be 461 * null. 462 * @param bufferSize [IN/OUT] Where to maintain the buffer wanted-size before read, and the real-size after read. 463 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 464 * 465 * @retval #LOS_OK The queue is successfully read. 466 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 467 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null. 468 * @retval #LOS_ERRNO_QUEUE_READ_IN_INTERRUPT The queue cannot be read during an interrupt when the time for 469 * waiting to processing the queue expires. 470 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created. 471 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for 472 * waiting to processing the queue expires. 473 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 474 * locked. 475 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 476 * @retval #LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL The buffer size passed in during queue reading is less than 477 * the queue size. 478 * @par Dependency: 479 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 480 * @see LOS_QueueWriteCopy | LOS_QueueWriteHeadCopy | LOS_QueueCreate | LOS_QueueCreateStatic 481 * @since Huawei LiteOS V100R001C00 482 */ 483 extern UINT32 LOS_QueueReadCopy(UINT32 queueId, 484 VOID *bufferAddr, 485 UINT32 *bufferSize, 486 UINT32 timeout); 487 488 /** 489 * @ingroup los_queue 490 * @brief Write data into a queue. 491 * 492 * @par Description: 493 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 494 * bufferAddr into a queue. 495 * @attention 496 * <ul> 497 * <li>The specific queue should be created firstly.</li> 498 * <li>Do not read or write a queue in unblocking modes such as interrupt.</li> 499 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 500 * <li>The data to be written is of the size specified by bufferSize and is stored at the address specified by 501 * bufferAddr.</li> 502 * <li>The argument timeout is a relative time.</li> 503 * <li>Do not call this API in software timer callback. </li> 504 * </ul> 505 * 506 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 507 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 508 * @param bufferAddr [IN] Starting address that stores the data to be written.The starting address must 509 * not be null. 510 * @param bufferSize [IN] Passed-in buffer size. The value range is [1,USHRT_MAX - sizeof(UINT32)]. 511 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 512 * 513 * @retval #LOS_OK The data is successfully written into the queue. 514 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 515 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 516 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 517 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time 518 * for waiting to processing the queue expires. 519 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 520 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 521 * the queue size. 522 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 523 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when 524 * the task is locked. 525 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 526 * @par Dependency: 527 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 528 * @see LOS_QueueReadCopy | LOS_QueueWriteHeadCopy | LOS_QueueCreate | LOS_QueueCreateStatic 529 * @since Huawei LiteOS V100R001C00 530 */ 531 extern UINT32 LOS_QueueWriteCopy(UINT32 queueId, 532 VOID *bufferAddr, 533 UINT32 bufferSize, 534 UINT32 timeout); 535 536 /** 537 * @ingroup los_queue 538 * @brief Read a queue. 539 * 540 * @par Description: 541 * This API is used to read the address of data in a specified queue, and store it to the address specified by 542 * bufferAddr. 543 * @attention 544 * <ul> 545 * <li>The specific queue should be created firstly.</li> 546 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is 547 * read first.</li> 548 * <li>bufferAddr stores the obtained data address.</li> 549 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 550 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 551 * <li>The argument timeout is a relative time.</li> 552 * <li>The bufferSize is not really used in LOS_QueueRead, because the interface is only used to 553 * obtain the address of data.</li> 554 * <li>The buffer which the bufferAddr pointing to must be greater than or equal to 4 bytes.</li> 555 * <li>Do not call this API in software timer callback. </li> 556 * </ul> 557 * 558 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 559 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 560 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must 561 * not be null. 562 * @param bufferSize [IN] Passed-in buffer size,The value must be greater than sizeof(CHAR*). 563 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 564 * 565 * @retval #LOS_OK The queue is successfully read. 566 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 567 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null. 568 * @retval #LOS_ERRNO_QUEUE_READ_IN_INTERRUPT The queue cannot be read during an interrupt when the time for 569 * waiting to processing the queue expires. 570 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created. 571 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for 572 * waiting to processing the queue expires. 573 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 574 * locked. 575 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 576 * @par Dependency: 577 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 578 * @see LOS_QueueWrite | LOS_QueueWriteHead | LOS_QueueCreate | LOS_QueueCreateStatic 579 * @since Huawei LiteOS V100R001C00 580 */ 581 extern UINT32 LOS_QueueRead(UINT32 queueId, 582 VOID *bufferAddr, 583 UINT32 bufferSize, 584 UINT32 timeout); 585 586 /** 587 * @ingroup los_queue 588 * @brief Write data into a queue. 589 * 590 * @par Description: 591 * This API is used to write the address of data specified by bufferAddr into a queue. 592 * @attention 593 * <ul> 594 * <li>The specific queue should be created firstly.</li> 595 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 596 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 597 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 598 * bufferAddr is to be written.</li> 599 * <li>The argument timeout is a relative time.</li> 600 * <li>The bufferSize is not really used in LOS_QueueWrite, because the interface is only used to write the address 601 * of data specified by bufferAddr into a queue.</li> 602 * <li>Do not call this API in software timer callback. </li> 603 * </ul> 604 * 605 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 606 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 607 * @param bufferAddr [IN] Starting address that stores the data to be written. The starting address 608 * must not be null. 609 * @param bufferSize [IN] This parameter is not in use temporarily. 610 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 611 * 612 * @retval #LOS_OK The data is successfully written into the queue. 613 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 614 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 615 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 616 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 617 * waiting to processing the queue expires. 618 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 619 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 620 * the queue size. 621 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 622 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 623 * locked. 624 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 625 * @par Dependency: 626 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 627 * @see LOS_QueueRead | LOS_QueueWriteHead | LOS_QueueCreate | LOS_QueueCreateStatic 628 * @since Huawei LiteOS V100R001C00 629 */ 630 extern UINT32 LOS_QueueWrite(UINT32 queueId, 631 VOID *bufferAddr, 632 UINT32 bufferSize, 633 UINT32 timeout); 634 635 /** 636 * @ingroup los_queue 637 * @brief Write data into a queue header. 638 * 639 * @par Description: 640 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 641 * bufferAddr into a queue header. 642 * @attention 643 * <ul> 644 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 645 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 646 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 647 * bufferAddr is to be written.</li> 648 * <li>The argument timeout is a relative time.</li> 649 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to 650 * be used.</li> 651 * <li>Do not call this API in software timer callback. </li> 652 * </ul> 653 * 654 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 655 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 656 * @param bufferAddr [OUT] Starting address that stores the data to be written. The starting address 657 * must not be null. 658 * @param bufferSize [IN] This parameter is not in use temporarily. 659 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 660 * 661 * @retval #LOS_OK The data is successfully written into the queue. 662 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 663 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 664 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 665 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 666 * waiting to processing the queue expires. waiting to processing the queue expires. 667 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 668 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 669 * the queue size. 670 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 671 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 672 * locked. 673 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 674 * @par Dependency: 675 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 676 * @see LOS_QueueWrite | LOS_QueueRead | LOS_QueueCreate | LOS_QueueCreateStatic 677 * @since Huawei LiteOS V100R001C00 678 */ 679 extern UINT32 LOS_QueueWriteHead(UINT32 queueId, 680 VOID *bufferAddr, 681 UINT32 bufferSize, 682 UINT32 timeout); 683 684 /** 685 * @ingroup los_queue 686 * @brief Write data into a queue header. 687 * 688 * @par Description: 689 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 690 * bufferAddr into a queue header. 691 * @attention 692 * <ul> 693 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 694 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 695 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 696 * bufferAddr is to be written.</li> 697 * <li>The argument timeout is a relative time.</li> 698 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to be 699 * used.</li> 700 * <li>Do not call this API in software timer callback. </li> 701 * </ul> 702 * 703 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 704 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 705 * @param bufferAddr [OUT] Starting address that stores the data to be written. 706 * The starting address must not be null. 707 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff]. 708 * @param timeout [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 709 * 710 * @retval #LOS_OK The data is successfully written into the queue. 711 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 712 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 713 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 714 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 715 * waiting to processing the queue expires. 716 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 717 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 718 * the queue size. 719 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 720 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 721 * locked. 722 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 723 * @par Dependency: 724 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 725 * @see LOS_QueueWriteCopy | LOS_QueueReadCopy 726 * @since Huawei LiteOS V100R001C00 727 */ 728 extern UINT32 LOS_QueueWriteHeadCopy(UINT32 queueId, 729 VOID *bufferAddr, 730 UINT32 bufferSize, 731 UINT32 timeout); 732 733 /** 734 * @ingroup los_queue 735 * @brief Delete a queue. 736 * 737 * @par Description: 738 * This API is used to delete a queue. 739 * @attention 740 * <ul> 741 * <li>This API cannot be used to delete a queue that is not created.</li> 742 * <li>A synchronous queue fails to be deleted if any tasks are blocked on it, or some queues are being read or 743 * written.</li> 744 * </ul> 745 * 746 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 747 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 748 * 749 * @retval #LOS_OK The queue is successfully deleted. 750 * @retval #LOS_NOK Failed to release the queue memory. 751 * @retval #LOS_ERRNO_QUEUE_NOT_FOUND The queue cannot be found. 752 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue handle passed in when the queue is being deleted is 753 * incorrect. 754 * @retval #LOS_ERRNO_QUEUE_IN_TSKUSE The queue that blocks a task cannot be deleted. 755 * @retval #LOS_ERRNO_QUEUE_IN_TSKWRITE Queue reading and writing are not synchronous. 756 * @par Dependency: 757 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 758 * @see LOS_QueueCreate | LOS_QueueCreateStatic 759 * @since Huawei LiteOS V100R001C00 760 */ 761 extern UINT32 LOS_QueueDelete(UINT32 queueId); 762 763 /** 764 * @ingroup los_queue 765 * @brief Obtain queue information. 766 * 767 * @par Description: 768 * This API is used to obtain queue information. 769 * @attention 770 * The specific queue should be created firstly before getting the queue information. 771 * @param queueId [IN] Queue ID created by LOS_QueueCreate or LOS_QueueCreateStatic. 772 * The value range is [0, LOSCFG_BASE_IPC_QUEUE_LIMIT - 1]. 773 * @param queueInfo [OUT] The queue information to be read must not be null. 774 * 775 * @retval #LOS_OK The queue information is successfully obtained. 776 * @retval #LOS_ERRNO_QUEUE_PTR_NULL The pointer to the queue information to be obtained is null. 777 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 778 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue in which the information to be obtained is stored is 779 * not created. 780 * 781 * @par Dependency: 782 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 783 * @see LOS_QueueCreate | LOS_QueueCreateStatic 784 * @since Huawei LiteOS V100R001C00 785 */ 786 extern UINT32 LOS_QueueInfoGet(UINT32 queueId, QUEUE_INFO_S *queueInfo); 787 788 #ifdef __cplusplus 789 } 790 #endif /* __cplusplus */ 791 792 #endif /* _LOS_QUEUE_H */ 793