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