1 /* 2 * Copyright (c) 2013-2019 Huawei Technologies Co., Ltd. All rights reserved. 3 * Copyright (c) 2020-2022 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_list.h" 41 #include "los_config.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 0. 215 * 216 * Value: 0x02000610 217 * 218 * Solution: Pass in a correct buffer size. 219 */ 220 #define LOS_ERRNO_QUEUE_READSIZE_ISZERO 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 * Queue error code: The buffer size passed in during queue reading or writing is bigger than the biggest size. 337 * 338 * Value: 0x02000620 339 * 340 * Solution: Decrease the buffer size. 341 */ 342 #define LOS_ERRNO_QUEUE_BUFFER_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x20) 343 344 /** 345 * @ingroup los_queue 346 * In struct QueueInfo, the length of each waitReadTask/waitWriteTask/waitMemTask array depends on the value 347 * LOSCFG_BASE_CORE_TSK_LIMIT. The type of each array element is UINT32, which means that each element could 348 * mark 32(=2^5) tasks. 349 * OS_WAIT_TASK_ARRAY_LEN is used to calculate the array length. 350 * OS_WAIT_TASK_ID_TO_ARRAY_IDX is used to transfer task ID to array index. 351 * OS_WAIT_TASK_ARRAY_ELEMENT_MASK is the mask for each element. 352 */ 353 #define OS_WAIT_TASK_ARRAY_LEN ((LOSCFG_BASE_CORE_TSK_LIMIT >> 5) + 1) 354 #define OS_WAIT_TASK_ID_TO_ARRAY_IDX(taskID) (taskID >> 5) 355 #define OS_WAIT_TASK_ARRAY_ELEMENT_MASK (31) 356 357 /** 358 * @ingroup los_queue 359 * Structure of the block for queue information query 360 */ 361 typedef struct tagQueueInfo { 362 UINT32 queueID; /**< Queue ID */ 363 UINT16 queueLen; /**< Queue length */ 364 UINT16 queueSize; /**< Node size */ 365 UINT16 queueHead; /**< Node head */ 366 UINT16 queueTail; /**< Node tail */ 367 UINT16 writableCnt; /**< Count of writable resources */ 368 UINT16 readableCnt; /**< Count of readable resources */ 369 UINT32 waitReadTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Resource reading task*/ 370 UINT32 waitWriteTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Resource writing task */ 371 UINT32 waitMemTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Memory task */ 372 } QUEUE_INFO_S; 373 374 /** 375 * @ingroup los_queue 376 * @brief Create a message queue. 377 * 378 * @par Description: 379 * This API is used to create a message queue. 380 * @attention 381 * <ul> 382 * <li>There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary.</li> 383 * </ul> 384 * @param queueName [IN] Message queue name. 385 * @param len [IN] Queue length. The value range is [1,0xffff]. 386 * @param queueID [OUT] ID of the queue control structure that is successfully created. 387 * @param flags [IN] Queue mode. Reserved parameter, not used for now. 388 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff-4]. 389 * 390 * @retval #LOS_OK The message queue is successfully created. 391 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded. 392 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation. 393 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueID is NULL. 394 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue 395 * creation is 0. 396 * @retval #LOS_ERRNO_QUEUE_SIZE_TOO_BIG The parameter maxMsgSize is larger than 0xffff - 4. 397 * @par Dependency: 398 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 399 * @see LOS_QueueDelete 400 */ 401 extern UINT32 LOS_QueueCreate(const CHAR *queueName, 402 UINT16 len, 403 UINT32 *queueID, 404 UINT32 flags, 405 UINT16 maxMsgSize); 406 407 /** 408 * @ingroup los_queue 409 * @brief Create a static message queue. 410 * 411 * @par Description: 412 * This API is used to create a message queue using static memory for data storage. 413 * @attention 414 * <ul> 415 * <li>There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary.</li> 416 * </ul> 417 * @param queueName [IN] Message queue name. 418 * @param len [IN] Queue length. The value range is [1,0xffff]. 419 * @param queueID [OUT] ID of the queue control structure that is successfully created. 420 * @param staticMem [IN] Pointer to a static memory for the message queue data. 421 * @param flags [IN] Queue mode. Reserved parameter, not used for now. 422 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff-4]. 423 * 424 * @retval #LOS_OK The message queue is successfully created. 425 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded. 426 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation. 427 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueID is NULL. 428 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue 429 * creation is 0. 430 * @retval #LOS_ERRNO_QUEUE_SIZE_TOO_BIG The parameter maxMsgSize is larger than 0xffff - 4. 431 * @par Dependency: 432 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 433 * @see LOS_QueueDelete 434 */ 435 extern UINT32 LOS_QueueCreateStatic(const CHAR *queueName, 436 UINT16 len, 437 UINT32 *queueID, 438 UINT8 *staticMem, 439 UINT32 flags, 440 UINT16 maxMsgSize); 441 442 /** 443 * @ingroup los_queue 444 * @brief Read a queue. 445 * 446 * @par Description: 447 * This API is used to read data in a specified queue, and store the obtained data to the address specified 448 * by bufferAddr. The address and the size of the data to be read are defined by users. 449 * @attention 450 * <ul> 451 * <li>The specific queue should be created firstly.</li> 452 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is read 453 * first.</li> 454 * <li>bufferAddr stores the obtained data.</li> 455 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 456 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 457 * <li>The argument timeOut is a relative time.</li> 458 * </ul> 459 * 460 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 461 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 462 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must not be 463 * null. 464 * @param bufferSize [IN/OUT] Where to maintain the buffer expected-size before read, and the real-size after read. 465 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 466 * 467 * @retval #LOS_OK The queue is successfully read. 468 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 469 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null. 470 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0. 471 * @retval #LOS_ERRNO_QUEUE_READ_IN_INTERRUPT The queue cannot be read during an interrupt when the time for 472 * waiting to processing the queue expires. 473 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created. 474 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for 475 * waiting to processing the queue expires. 476 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 477 * locked. 478 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 479 * @retval #LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL The buffer size passed in during queue reading is less than 480 * the queue size. 481 * @par Dependency: 482 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 483 * @see LOS_QueueWriteCopy | LOS_QueueCreate 484 */ 485 extern UINT32 LOS_QueueReadCopy(UINT32 queueID, 486 VOID *bufferAddr, 487 UINT32 *bufferSize, 488 UINT32 timeOut); 489 490 /** 491 * @ingroup los_queue 492 * @brief Write data into a queue. 493 * 494 * @par Description: 495 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 496 * bufferAddr into a queue. 497 * @attention 498 * <ul> 499 * <li>The specific queue should be created firstly.</li> 500 * <li>Do not read or write a queue in unblocking modes such as interrupt.</li> 501 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 502 * <li>The data to be written is of the size specified by bufferSize and is stored at the address specified by 503 * BufferAddr.</li> 504 * <li>The argument timeOut is a relative time.</li> 505 * </ul> 506 * 507 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 508 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 509 * @param bufferAddr [IN] Starting address that stores the data to be written.The starting address must 510 * not be null. 511 * @param bufferSize [IN] Passed-in buffer size. The value range is [1,USHRT_MAX - sizeof(UINT32)]. 512 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 513 * 514 * @retval #LOS_OK The data is successfully written into the queue. 515 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 516 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 517 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 518 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time 519 * for waiting to processing the queue expires. 520 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 521 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 522 * the queue size. 523 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 524 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when 525 * the task is locked. 526 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 527 * @par Dependency: 528 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 529 * @see LOS_QueueReadCopy | LOS_QueueCreate 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 * </ul> 556 * 557 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 558 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 559 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must 560 * not be null. 561 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff]. 562 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 563 * 564 * @retval #LOS_OK The queue is successfully read. 565 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 566 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null. 567 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0. 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_QueueCreate 579 */ 580 extern UINT32 LOS_QueueRead(UINT32 queueID, 581 VOID *bufferAddr, 582 UINT32 bufferSize, 583 UINT32 timeOut); 584 585 /** 586 * @ingroup los_queue 587 * @brief Write data into a queue. 588 * 589 * @par Description: 590 * This API is used to write the address of data specified by bufferAddr into a queue. 591 * @attention 592 * <ul> 593 * <li>The specific queue should be created firstly.</li> 594 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 595 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 596 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 597 * BufferAddr is to be written.</li> 598 * <li>The argument timeOut is a relative time.</li> 599 * <li>The bufferSize is not really used in LOS_QueueWrite, because the interface is only used to write the address 600 * of data specified by bufferAddr into a queue.</li> 601 * </ul> 602 * 603 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 604 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 605 * @param bufferAddr [IN] Starting address that stores the data to be written. The starting address 606 * must not be null. 607 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff]. 608 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 609 * 610 * @retval #LOS_OK The data is successfully written into the queue. 611 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 612 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 613 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 614 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 615 * waiting to processing the queue expires. 616 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 617 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 618 * the queue size. 619 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 620 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 621 * locked. 622 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 623 * @par Dependency: 624 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 625 * @see LOS_QueueRead | LOS_QueueCreate 626 */ 627 extern UINT32 LOS_QueueWrite(UINT32 queueID, 628 VOID *bufferAddr, 629 UINT32 bufferSize, 630 UINT32 timeOut); 631 632 /** 633 * @ingroup los_queue 634 * @brief Write data into a queue header. 635 * 636 * @par Description: 637 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 638 * bufferAddr into a queue header. 639 * @attention 640 * <ul> 641 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 642 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 643 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 644 * BufferAddr is to be written.</li> 645 * <li>The argument timeOut is a relative time.</li> 646 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to be used. 647 * <li> 648 * </ul> 649 * 650 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 651 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 652 * @param bufferAddr [OUT] Starting address that stores the data to be written. The starting address 653 * must not be null. 654 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff]. 655 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 656 * 657 * @retval #LOS_OK The data is successfully written into the queue. 658 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 659 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 660 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 661 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 662 * waiting to processing the queue expires. 663 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 664 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 665 * the queue size. 666 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 667 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 668 * locked. 669 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 670 * @par Dependency: 671 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 672 * @see LOS_QueueRead | LOS_QueueCreate 673 */ 674 extern UINT32 LOS_QueueWriteHead(UINT32 queueID, 675 VOID *bufferAddr, 676 UINT32 bufferSize, 677 UINT32 timeOut); 678 679 /** 680 * @ingroup los_queue 681 * @brief Write data into a queue header. 682 * 683 * @par Description: 684 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by 685 * bufferAddr into a queue header. 686 * @attention 687 * <ul> 688 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li> 689 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 690 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by 691 * BufferAddr is to be written.</li> 692 * <li>The argument timeOut is a relative time.</li> 693 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to be 694 * used.<li> 695 * </ul> 696 * 697 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 698 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 699 * @param bufferAddr [OUT] Starting address that stores the data to be written. 700 * The starting address must not be null. 701 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff]. 702 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick). 703 * 704 * @retval #LOS_OK The data is successfully written into the queue. 705 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid. 706 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null. 707 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0. 708 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for 709 * waiting to processing the queue expires. 710 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created. 711 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than 712 * the queue size. 713 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing. 714 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is 715 * locked. 716 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires. 717 * @par Dependency: 718 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul> 719 * @see LOS_QueueWrite | LOS_QueueWriteHead 720 */ 721 extern UINT32 LOS_QueueWriteHeadCopy(UINT32 queueID, 722 VOID *bufferAddr, 723 UINT32 bufferSize, 724 UINT32 timeOut); 725 726 /** 727 * @ingroup los_queue 728 * @brief Delete a queue. 729 * 730 * @par Description: 731 * This API is used to delete a queue. 732 * @attention 733 * <ul> 734 * <li>This API cannot be used to delete a queue that is not created.</li> 735 * <li>A synchronous queue fails to be deleted if any tasks are blocked on it, or some queues are being read or 736 * written.</li> 737 * </ul> 738 * 739 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 740 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 741 * 742 * @retval #LOS_OK The queue is successfully deleted. 743 * @retval #LOS_ERRNO_QUEUE_NOT_FOUND The queue cannot be found. 744 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue handle passed in when the queue is being deleted is 745 * incorrect. 746 * @retval #LOS_ERRNO_QUEUE_IN_TSKUSE The queue that blocks a task cannot be deleted. 747 * @retval #LOS_ERRNO_QUEUE_IN_TSKWRITE Queue reading and writing are not synchronous. 748 * @par Dependency: 749 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 750 * @see LOS_QueueCreate | LOS_QueueCreate 751 */ 752 extern UINT32 LOS_QueueDelete(UINT32 queueID); 753 754 /** 755 * @ingroup los_queue 756 * @brief Obtain queue information. 757 * 758 * @par Description: 759 * This API is used to obtain queue information. 760 * @attention 761 * <ul> 762 * <li>The specific queue should be created firstly.</li> 763 * </ul> 764 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is 765 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 766 * @param queueInfo [OUT] The queue information to be read must not be null. 767 * 768 * @retval #LOS_OK The queue information is successfully obtained. 769 * @retval #LOS_ERRNO_QUEUE_PTR_NULL The pointer to the queue information to be obtained is null. 770 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid. 771 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue in which the information to be obtained is stored is 772 * not created. 773 * 774 * @par Dependency: 775 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 776 * @see LOS_QueueCreate 777 */ 778 extern UINT32 LOS_QueueInfoGet(UINT32 queueID, QUEUE_INFO_S *queueInfo); 779 780 typedef enum { 781 OS_QUEUE_READ, 782 OS_QUEUE_WRITE 783 } QueueReadWrite; 784 785 typedef enum { 786 OS_QUEUE_HEAD, 787 OS_QUEUE_TAIL 788 } QueueHeadTail; 789 790 typedef enum { 791 OS_QUEUE_NOT_POINT, 792 OS_QUEUE_POINT 793 } QueuePointOrNot; 794 795 #define OS_QUEUE_OPERATE_TYPE(ReadOrWrite, HeadOrTail, PointOrNot) \ 796 (((UINT32)(PointOrNot) << 2) | ((UINT32)(HeadOrTail) << 1) | (ReadOrWrite)) 797 #define OS_QUEUE_READ_WRITE_GET(type) ((type) & (0x01)) 798 #define OS_QUEUE_READ_HEAD (OS_QUEUE_READ | (OS_QUEUE_HEAD << 1)) 799 #define OS_QUEUE_READ_TAIL (OS_QUEUE_READ | (OS_QUEUE_TAIL << 1)) 800 #define OS_QUEUE_WRITE_HEAD (OS_QUEUE_WRITE | (OS_QUEUE_HEAD << 1)) 801 #define OS_QUEUE_WRITE_TAIL (OS_QUEUE_WRITE | (OS_QUEUE_TAIL << 1)) 802 #define OS_QUEUE_OPERATE_GET(type) ((type) & (0x03)) 803 #define OS_QUEUE_IS_POINT(type) ((type) & (0x04)) 804 #define OS_QUEUE_IS_READ(type) (OS_QUEUE_READ_WRITE_GET(type) == OS_QUEUE_READ) 805 #define OS_QUEUE_IS_WRITE(type) (OS_QUEUE_READ_WRITE_GET(type) == OS_QUEUE_WRITE) 806 #define OS_READWRITE_LEN 2 807 808 /** 809 * @ingroup los_queue 810 * Queue information block structure 811 */ 812 typedef struct { 813 UINT8 *queue; /**< Pointer to a queue handle */ 814 UINT8 *queueName; /**< Queue name */ 815 UINT16 queueState; /**< Queue state */ 816 UINT16 queueLen; /**< Queue length */ 817 UINT16 queueSize; /**< Node size */ 818 UINT16 queueID; /**< queueID */ 819 UINT16 queueHead; /**< Node head */ 820 UINT16 queueTail; /**< Node tail */ 821 UINT16 readWriteableCnt[OS_READWRITE_LEN]; /**< Count of readable or writable resources, 0:readable, 1:writable */ 822 LOS_DL_LIST readWriteList[OS_READWRITE_LEN]; /**< Pointer to the linked list to be read or written, 823 0:readlist, 1:writelist */ 824 LOS_DL_LIST memList; /**< Pointer to the memory linked list */ 825 } LosQueueCB; 826 827 828 extern LosQueueCB *OsGetQueueHandle(UINT32 queueID); 829 830 /* queue state */ 831 /** 832 * @ingroup los_queue 833 * Message queue state: not in use. 834 */ 835 #define OS_QUEUE_UNUSED 0 836 837 /** 838 * @ingroup los_queue 839 * Message queue state: used. 840 */ 841 #define OS_QUEUE_INUSED 1 842 843 /** 844 * @ingroup los_queue 845 * Not in use. 846 */ 847 #define OS_QUEUE_WAIT_FOR_POOL 1 848 849 /** 850 * @ingroup los_queue 851 * Normal message queue. 852 */ 853 #define OS_QUEUE_NORMAL 0 854 855 /** 856 * @ingroup los_queue 857 * Queue information control block 858 */ 859 extern LosQueueCB *g_allQueue; 860 861 /** 862 * @ingroup los_queue 863 * Obtain a handle of the queue that has a specified ID. 864 */ 865 #define GET_QUEUE_HANDLE(QueueID) OsGetQueueHandle(QueueID) 866 867 /** 868 * @ingroup los_queue 869 * Obtain the head node in a queue doubly linked list. 870 */ 871 #define GET_QUEUE_LIST(ptr) LOS_DL_LIST_ENTRY(ptr, LosQueueCB, readWriteList[OS_QUEUE_WRITE]) 872 873 /** 874 * @ingroup los_queue 875 * Maximum number of queues 876 */ 877 #if (LOSCFG_BASE_IPC_QUEUE_STATIC == 1) 878 #define OS_ALL_IPC_QUEUE_LIMIT LOSCFG_BASE_IPC_QUEUE_LIMIT + LOSCFG_BASE_IPC_STATIC_QUEUE_LIMIT 879 #else 880 #define OS_ALL_IPC_QUEUE_LIMIT LOSCFG_BASE_IPC_QUEUE_LIMIT 881 #endif 882 883 /** 884 * @ingroup los_queue 885 * @brief Alloc a stationary memory for a mail. 886 * 887 * @par Description: 888 * This API is used to alloc a stationary memory for a mail according to queueID. 889 * @attention 890 * <ul> 891 * <li>Do not alloc memory in unblocking modes such as interrupt.</li> 892 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 893 * <li>The argument timeOut is a relative time.</li> 894 * </ul> 895 * 896 * @param queueID [IN] Queue ID. The value range is [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 897 * @param mailPool [IN] The memory poll that stores the mail. 898 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER]. 899 * 900 * @retval #NULL The memory allocation is failed. 901 * @retval #mem The address of alloc memory. 902 * @par Dependency: 903 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 904 * @see OsQueueMailFree 905 */ 906 extern VOID *OsQueueMailAlloc(UINT32 queueID, VOID *mailPool, UINT32 timeOut); 907 908 /** 909 * @ingroup los_queue 910 * @brief Free a stationary memory of a mail. 911 * 912 * @par Description: 913 * This API is used to free a stationary memory for a mail according to queueID. 914 * @attention 915 * <ul> 916 * <li>This API cannot be called before the Huawei LiteOS is initialized.</li> 917 * </ul> 918 * 919 * @param queueID [IN] Queue ID. The value range is [1,LOSCFG_BASE_IPC_QUEUE_LIMIT]. 920 * @param mailPool [IN] The mail memory poll address. 921 * @param mailMem [IN] The mail memory block address. 922 * 923 * @retval #LOS_OK 0x00000000: The memory free successfully. 924 * @retval #OS_ERRNO_QUEUE_MAIL_HANDLE_INVALID 0x02000619: The handle of the queue passed-in when the memory for 925 the queue is being freed is invalid. 926 * @retval #OS_ERRNO_QUEUE_MAIL_PTR_INVALID 0x0200061a: The pointer to the memory to be freed is null. 927 * @retval #OS_ERRNO_QUEUE_MAIL_FREE_ERROR 0x0200061b: The memory for the queue fails to be freed. 928 * @par Dependency: 929 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 930 * @see OsQueueMailAlloc 931 */ 932 extern UINT32 OsQueueMailFree(UINT32 queueID, VOID *mailPool, VOID *mailMem); 933 934 /** 935 * @ingroup los_queue 936 * @brief Initialization queue. 937 * 938 * @par Description: 939 * This API is used to initialization queue. 940 * @attention 941 * <ul> 942 * <li>None.</li> 943 * </ul> 944 * 945 * @param None. 946 * 947 * @retval UINT32 Initialization result. 948 * @par Dependency: 949 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 950 * @see None. 951 */ 952 extern UINT32 OsQueueInit(VOID); 953 954 /** 955 * @ingroup los_queue 956 * @brief Handle when read or write queue. 957 * 958 * @par Description: 959 * This API is used to handle when read or write queue. 960 * @attention 961 * <ul> 962 * <li>None.</li> 963 * </ul> 964 * 965 * @param queueID [IN] Queue id. 966 * @param operateType [IN] Operate type 967 * @param bufferAddr [IN] Buffer address. 968 * @param bufferSize [IN] Buffer size. 969 * @param timeOut [IN] Timeout. 970 * 971 * @retval UINT32 Handle result. 972 * @par Dependency: 973 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul> 974 * @see None. 975 */ 976 extern UINT32 OsQueueOperate(UINT32 queueID, UINT32 operateType, VOID *bufferAddr, UINT32 *bufferSize, 977 UINT32 timeOut); 978 979 #ifdef __cplusplus 980 #if __cplusplus 981 } 982 #endif /* __cplusplus */ 983 #endif /* __cplusplus */ 984 985 #endif /* _LOS_QUEUE_H */ 986