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 #include "los_task.h"
43
44 #ifdef __cplusplus
45 #if __cplusplus
46 extern "C" {
47 #endif /* __cplusplus */
48 #endif /* __cplusplus */
49
50 /**
51 * @ingroup los_queue
52 * Queue error code: The maximum number of queue resources is configured to 0.
53 *
54 * Value: 0x02000600
55 *
56 * Solution: Configure the maximum number of queue resources to be greater than 0. If queue modules are not used,
57 * set the configuration item for the tailoring of the maximum number of queue resources to NO.
58 */
59 #define LOS_ERRNO_QUEUE_MAXNUM_ZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x00)
60
61 /**
62 * @ingroup los_queue
63 * Queue error code: The queue block memory fails to be initialized.
64 *
65 * Value: 0x02000601
66 *
67 * Solution: Allocate the queue block bigger memory partition, or decrease the maximum number of queue resources.
68 */
69 #define LOS_ERRNO_QUEUE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x01)
70
71 /**
72 * @ingroup los_queue
73 * Queue error code: The memory for queue creation fails to be requested.
74 *
75 * Value: 0x02000602
76 *
77 * Solution: Allocate more memory for queue creation, or decrease the queue length and the number of nodes
78 * in the queue to be created.
79 */
80 #define LOS_ERRNO_QUEUE_CREATE_NO_MEMORY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x02)
81
82 /**
83 * @ingroup los_queue
84 * Queue error code: The size of the biggest message in the created queue is too big.
85 *
86 * Value: 0x02000603
87 *
88 * Solution: Change the size of the biggest message in the created queue.
89 */
90 #define LOS_ERRNO_QUEUE_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x03)
91
92 /**
93 * @ingroup los_queue
94 * Queue error code: The upper limit of the number of created queues is exceeded.
95 *
96 * Value: 0x02000604
97 *
98 * Solution: Increase the configured number of resources for queues.
99 */
100 #define LOS_ERRNO_QUEUE_CB_UNAVAILABLE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x04)
101
102 /**
103 * @ingroup los_queue
104 * Queue error code: Invalid queue.
105 *
106 * Value: 0x02000605
107 *
108 * Solution: Ensure that the passed-in queue ID is valid.
109 */
110 #define LOS_ERRNO_QUEUE_NOT_FOUND LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x05)
111
112 /**
113 * @ingroup los_queue
114 * Queue error code: The task is forbidden to be blocked on a queue when the task is locked.
115 *
116 * Value: 0x02000606
117 *
118 * Solution: Unlock the task before using a queue.
119 */
120 #define LOS_ERRNO_QUEUE_PEND_IN_LOCK LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x06)
121
122 /**
123 * @ingroup los_queue
124 * Queue error code: The time set for waiting to processing the queue expires.
125 *
126 * Value: 0x02000607
127 *
128 * Solution: Check whether the expiry time setting is appropriate.
129 */
130 #define LOS_ERRNO_QUEUE_TIMEOUT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x07)
131
132 /**
133 * @ingroup los_queue
134 * Queue error code: The queue that blocks a task cannot be deleted.
135 *
136 * Value: 0x02000608
137 *
138 * Solution: Enable the task to obtain resources rather than be blocked on the queue.
139 */
140 #define LOS_ERRNO_QUEUE_IN_TSKUSE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x08)
141
142 /**
143 * @ingroup los_queue
144 * Queue error code: The queue cannot be written during an interrupt when the time for waiting to
145 * processing the queue expires.
146 *
147 * Value: 0x02000609
148 *
149 * Solution: Set the expiry time to the never-waiting mode, or use asynchronous queues.
150 */
151 #define LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x09)
152
153 /**
154 * @ingroup los_queue
155 * Queue error code: The queue is not created.
156 *
157 * Value: 0x0200060a
158 *
159 * Solution: Check whether the passed-in queue handle value is valid.
160 */
161 #define LOS_ERRNO_QUEUE_NOT_CREATE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0a)
162
163 /**
164 * @ingroup los_queue
165 * Queue error code: Queue reading and writing are not synchronous.
166 *
167 * Value: 0x0200060b
168 *
169 * Solution: Synchronize queue reading with queue writing.
170 */
171 #define LOS_ERRNO_QUEUE_IN_TSKWRITE LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0b)
172
173 /**
174 * @ingroup los_queue
175 * Queue error code: Parameters passed in during queue creation are null pointers.
176 *
177 * Value: 0x0200060c
178 *
179 * Solution: Ensure the passed-in parameters are not null pointers.
180 */
181 #define LOS_ERRNO_QUEUE_CREAT_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0c)
182
183 /**
184 * @ingroup los_queue
185 * Queue error code: The queue length or message node size passed in during queue creation is 0.
186 *
187 * Value: 0x0200060d
188 *
189 * Solution: Pass in correct queue length and message node size.
190 */
191 #define LOS_ERRNO_QUEUE_PARA_ISZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0d)
192
193 /**
194 * @ingroup los_queue
195 * Queue error code: The handle of the queue is invalid.
196 *
197 * Value: 0x0200060e
198 *
199 * Solution: Check whether the passed-in queue handle value is valid.
200 */
201 #define LOS_ERRNO_QUEUE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0e)
202
203 /**
204 * @ingroup los_queue
205 * Queue error code: The pointer passed in during queue reading is null.
206 *
207 * Value: 0x0200060f
208 *
209 * Solution: Check whether the passed-in pointer is null.
210 */
211 #define LOS_ERRNO_QUEUE_READ_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x0f)
212
213 /**
214 * @ingroup los_queue
215 * Queue error code: The buffer size passed in during queue reading is 0.
216 *
217 * Value: 0x02000610
218 *
219 * Solution: Pass in a correct buffer size.
220 */
221 #define LOS_ERRNO_QUEUE_READSIZE_ISZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x10)
222
223 /**
224 * @ingroup los_queue
225 * Queue error code: The pointer passed in during queue writing is null.
226 *
227 * Value: 0x02000612
228 *
229 * Solution: Check whether the passed-in pointer is null.
230 */
231 #define LOS_ERRNO_QUEUE_WRITE_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x12)
232
233 /**
234 * @ingroup los_queue
235 * Queue error code: The buffer size passed in during queue writing is 0.
236 *
237 * Value: 0x02000613
238 *
239 * Solution: Pass in a correct buffer size.
240 */
241 #define LOS_ERRNO_QUEUE_WRITESIZE_ISZERO LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x13)
242
243 /**
244 * @ingroup los_queue
245 * Queue error code: The buffer size passed in during queue writing is bigger than the queue size.
246 *
247 * Value: 0x02000615
248 *
249 * Solution: Decrease the buffer size, or use a queue in which nodes are bigger.
250 */
251 #define LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x15)
252
253 /**
254 * @ingroup los_queue
255 * Queue error code: No free node is available during queue writing.
256 *
257 * Value: 0x02000616
258 *
259 * Solution: Ensure that free nodes are available before queue writing.
260 */
261 #define LOS_ERRNO_QUEUE_ISFULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x16)
262
263 /**
264 * @ingroup los_queue
265 * Queue error code: The pointer passed in when the queue information is being obtained is null.
266 *
267 * Value: 0x02000617
268 *
269 * Solution: Check whether the passed-in pointer is null.
270 */
271 #define LOS_ERRNO_QUEUE_PTR_NULL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x17)
272
273 /**
274 * @ingroup los_queue
275 * Queue error code: The queue cannot be read during an interrupt
276 * when the time for waiting to processing the queue expires.
277 *
278 * Value: 0x02000618
279 *
280 * Solution: Set the expiry time to the never-waiting mode, or use asynchronous queues.
281 */
282 #define LOS_ERRNO_QUEUE_READ_IN_INTERRUPT LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x18)
283
284 /**
285 * @ingroup los_queue
286 * Queue error code: The handle of the queue passed-in when the memory for the queue is being freed is invalid.
287 *
288 * Value: 0x02000619
289 *
290 * Solution: Check whether the passed-in queue handle value is valid.
291 */
292 #define LOS_ERRNO_QUEUE_MAIL_HANDLE_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x19)
293
294 /**
295 * @ingroup los_queue
296 * Queue error code: The pointer to the memory to be freed is null.
297 *
298 * Value: 0x0200061a
299 *
300 * Solution: Check whether the passed-in pointer is null.
301 */
302 #define LOS_ERRNO_QUEUE_MAIL_PTR_INVALID LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1a)
303
304 /**
305 * @ingroup los_queue
306 * Queue error code: The memory for the queue fails to be freed.
307 *
308 * Value: 0x0200061b
309 *
310 * Solution: Pass in correct input parameters.
311 */
312 #define LOS_ERRNO_QUEUE_MAIL_FREE_ERROR LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1b)
313
314 /**
315 * @ingroup los_queue
316 * Queue error code: No resource is in the queue that is being read when the
317 * time for waiting to processing the queue expires.
318 *
319 * Value: 0x0200061d
320 *
321 * Solution: Ensure that the queue contains messages when it is being read.
322 */
323 #define LOS_ERRNO_QUEUE_ISEMPTY LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1d)
324
325 /**
326 * @ingroup los_queue
327 * Queue error code: The buffer size passed in during queue reading is smaller than the queue size.
328 *
329 * Value: 0x0200061f
330 *
331 * Solution: Increase the buffer size, or use a queue in which nodes are smaller.
332 */
333 #define LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x1f)
334
335 /**
336 * @ingroup los_queue
337 * Queue error code: The buffer size passed in during queue reading or writing is bigger than the biggest size.
338 *
339 * Value: 0x02000620
340 *
341 * Solution: Decrease the buffer size.
342 */
343 #define LOS_ERRNO_QUEUE_BUFFER_SIZE_TOO_BIG LOS_ERRNO_OS_ERROR(LOS_MOD_QUE, 0x20)
344
345 /**
346 * @ingroup los_queue
347 * In struct QueueInfo, the length of each waitReadTask/waitWriteTask/waitMemTask array depends on the value
348 * LOSCFG_BASE_CORE_TSK_LIMIT. The type of each array element is UINT32, which means that each element could
349 * mark 32(=2^5) tasks.
350 * OS_WAIT_TASK_ARRAY_LEN is used to calculate the array length.
351 * OS_WAIT_TASK_ID_TO_ARRAY_IDX is used to transfer task ID to array index.
352 * OS_WAIT_TASK_ARRAY_ELEMENT_MASK is the mask for each element.
353 */
354 #define OS_WAIT_TASK_ARRAY_LEN ((LOSCFG_BASE_CORE_TSK_LIMIT >> 5) + 1)
355 #define OS_WAIT_TASK_ID_TO_ARRAY_IDX(taskID) (taskID >> 5)
356 #define OS_WAIT_TASK_ARRAY_ELEMENT_MASK (31)
357
358 /**
359 * @ingroup los_queue
360 * Structure of the block for queue information query
361 */
362 typedef struct tagQueueInfo {
363 UINT32 queueID; /**< Queue ID */
364 UINT16 queueLen; /**< Queue length */
365 UINT16 queueSize; /**< Node size */
366 UINT16 queueHead; /**< Node head */
367 UINT16 queueTail; /**< Node tail */
368 UINT16 writableCnt; /**< Count of writable resources */
369 UINT16 readableCnt; /**< Count of readable resources */
370 UINT32 waitReadTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Resource reading task*/
371 UINT32 waitWriteTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Resource writing task */
372 UINT32 waitMemTask[OS_WAIT_TASK_ARRAY_LEN]; /**< Memory task */
373 } QUEUE_INFO_S;
374
375 /**
376 * @ingroup los_queue
377 * @brief Create a message queue.
378 *
379 * @par Description:
380 * This API is used to create a message queue.
381 * @attention
382 * <ul>
383 * <li>There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary.</li>
384 * </ul>
385 * @param queueName [IN] Message queue name.
386 * @param len [IN] Queue length. The value range is [1,0xffff].
387 * @param queueID [OUT] ID of the queue control structure that is successfully created.
388 * @param flags [IN] Queue mode. Reserved parameter, not used for now.
389 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff-4].
390 *
391 * @retval #LOS_OK The message queue is successfully created.
392 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded.
393 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation.
394 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueID is NULL.
395 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue
396 * creation is 0.
397 * @retval #LOS_ERRNO_QUEUE_SIZE_TOO_BIG The parameter maxMsgSize is larger than 0xffff - 4.
398 * @par Dependency:
399 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
400 * @see LOS_QueueDelete
401 */
402 extern UINT32 LOS_QueueCreate(const CHAR *queueName,
403 UINT16 len,
404 UINT32 *queueID,
405 UINT32 flags,
406 UINT16 maxMsgSize);
407
408 /**
409 * @ingroup los_queue
410 * @brief Create a static message queue.
411 *
412 * @par Description:
413 * This API is used to create a message queue using static memory for data storage.
414 * @attention
415 * <ul>
416 * <li>There are LOSCFG_BASE_IPC_QUEUE_LIMIT queues available, change it's value when necessary.</li>
417 * </ul>
418 * @param queueName [IN] Message queue name.
419 * @param len [IN] Queue length. The value range is [1,0xffff].
420 * @param queueID [OUT] ID of the queue control structure that is successfully created.
421 * @param staticMem [IN] Pointer to a static memory for the message queue data.
422 * @param flags [IN] Queue mode. Reserved parameter, not used for now.
423 * @param maxMsgSize [IN] Node size. The value range is [1,0xffff-4].
424 *
425 * @retval #LOS_OK The message queue is successfully created.
426 * @retval #LOS_ERRNO_QUEUE_CB_UNAVAILABLE The upper limit of the number of created queues is exceeded.
427 * @retval #LOS_ERRNO_QUEUE_CREATE_NO_MEMORY Insufficient memory for queue creation.
428 * @retval #LOS_ERRNO_QUEUE_CREAT_PTR_NULL Null pointer, queueID is NULL.
429 * @retval #LOS_ERRNO_QUEUE_PARA_ISZERO The queue length or message node size passed in during queue
430 * creation is 0.
431 * @retval #LOS_ERRNO_QUEUE_SIZE_TOO_BIG The parameter maxMsgSize is larger than 0xffff - 4.
432 * @par Dependency:
433 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
434 * @see LOS_QueueDelete
435 */
436 extern UINT32 LOS_QueueCreateStatic(const CHAR *queueName,
437 UINT16 len,
438 UINT32 *queueID,
439 UINT8 *staticMem,
440 UINT32 flags,
441 UINT16 maxMsgSize);
442
443 /**
444 * @ingroup los_queue
445 * @brief Read a queue.
446 *
447 * @par Description:
448 * This API is used to read data in a specified queue, and store the obtained data to the address specified
449 * by bufferAddr. The address and the size of the data to be read are defined by users.
450 * @attention
451 * <ul>
452 * <li>The specific queue should be created firstly.</li>
453 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is read
454 * first.</li>
455 * <li>bufferAddr stores the obtained data.</li>
456 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li>
457 * <li>This API cannot be called before the kernel is initialized.</li>
458 * <li>The argument timeOut is a relative time.</li>
459 * </ul>
460 *
461 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
462 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
463 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must not be
464 * null.
465 * @param bufferSize [IN/OUT] Where to maintain the buffer expected-size before read, and the real-size after read.
466 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
467 *
468 * @retval #LOS_OK The queue is successfully read.
469 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid.
470 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null.
471 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0.
472 * @retval #LOS_ERRNO_QUEUE_READ_IN_INTERRUPT The queue cannot be read during an interrupt when the time for
473 * waiting to processing the queue expires.
474 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created.
475 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for
476 * waiting to processing the queue expires.
477 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is
478 * locked.
479 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
480 * @retval #LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL The buffer size passed in during queue reading is less than
481 * the queue size.
482 * @par Dependency:
483 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
484 * @see LOS_QueueWriteCopy | LOS_QueueCreate
485 */
486 extern UINT32 LOS_QueueReadCopy(UINT32 queueID,
487 VOID *bufferAddr,
488 UINT32 *bufferSize,
489 UINT32 timeOut);
490
491 /**
492 * @ingroup los_queue
493 * @brief Read a queue in interrupt service routine.
494 *
495 * @par Description:
496 * This API is used to read data in a specified queue, and store the obtained data to the address specified
497 * by bufferAddr. The address and the size of the data to be read are defined by users.
498 * It is safe to use this API from within an interrupt service routine.
499 * @attention
500 * <ul>
501 * <li>The specific queue should be created firstly.</li>
502 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is read
503 * first.</li>
504 * <li>This API read a queue in unblocking modes.</li>
505 * <li>bufferAddr stores the obtained data.</li>
506 * <li>This API cannot be called before the kernel is initialized.</li>
507 * </ul>
508 *
509 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
510 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
511 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must not be
512 * null.
513 * @param bufferSize [IN/OUT] Where to maintain the buffer expected-size before read, and the real-size after read.
514 *
515 * @retval #LOS_OK The queue is successfully read.
516 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid.
517 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null.
518 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0.
519 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created.
520 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for
521 * waiting to processing the queue expires.
522 * @retval #LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL The buffer size passed in during queue reading is less than
523 * the queue size.
524 * @par Dependency:
525 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
526 * @see LOS_QueueWriteCopy | LOS_QueueCreate
527 */
LOS_QueueReadCopyIsr(UINT32 queueID,VOID * bufferAddr,UINT32 * bufferSize)528 STATIC INLINE UINT32 LOS_QueueReadCopyIsr(UINT32 queueID,
529 VOID *bufferAddr,
530 UINT32 *bufferSize)
531 {
532 return LOS_QueueReadCopy(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
533 }
534
535 /**
536 * @ingroup los_queue
537 * @brief Write data into a queue.
538 *
539 * @par Description:
540 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
541 * bufferAddr into a queue.
542 * @attention
543 * <ul>
544 * <li>The specific queue should be created firstly.</li>
545 * <li>Do not read or write a queue in unblocking modes such as interrupt.</li>
546 * <li>This API cannot be called before the kernel is initialized.</li>
547 * <li>The data to be written is of the size specified by bufferSize and is stored at the address specified by
548 * BufferAddr.</li>
549 * <li>The argument timeOut is a relative time.</li>
550 * </ul>
551 *
552 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
553 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
554 * @param bufferAddr [IN] Starting address that stores the data to be written.The starting address must
555 * not be null.
556 * @param bufferSize [IN] Passed-in buffer size. The value range is [1,USHRT_MAX - sizeof(UINT32)].
557 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
558 *
559 * @retval #LOS_OK The data is successfully written into the queue.
560 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
561 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
562 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
563 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time
564 * for waiting to processing the queue expires.
565 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
566 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
567 * the queue size.
568 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
569 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when
570 * the task is locked.
571 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
572 * @par Dependency:
573 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
574 * @see LOS_QueueReadCopy | LOS_QueueCreate
575 */
576 extern UINT32 LOS_QueueWriteCopy(UINT32 queueID,
577 VOID *bufferAddr,
578 UINT32 bufferSize,
579 UINT32 timeOut);
580
581 /**
582 * @ingroup los_queue
583 * @brief Write data into a queue in interrupt service routine.
584 *
585 * @par Description:
586 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
587 * bufferAddr into a queue.It is safe to use this API from within an interrupt service routine.
588 * @attention
589 * <ul>
590 * <li>The specific queue should be created firstly.</li>
591 * <li>This API write data into a queue in unblocking modes.</li>
592 * <li>This API cannot be called before the kernel is initialized.</li>
593 * <li>The data to be written is of the size specified by bufferSize and is stored at the address specified by
594 * BufferAddr.</li>
595 * </ul>
596 *
597 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
598 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
599 * @param bufferAddr [IN] Starting address that stores the data to be written.The starting address must
600 * not be null.
601 * @param bufferSize [IN] Passed-in buffer size. The value range is [1,USHRT_MAX - sizeof(UINT32)].
602 *
603 * @retval #LOS_OK The data is successfully written into the queue.
604 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
605 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
606 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
607 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
608 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
609 * the queue size.
610 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
611 * @par Dependency:
612 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
613 * @see LOS_QueueReadCopy | LOS_QueueCreate
614 */
LOS_QueueWriteCopyIsr(UINT32 queueID,VOID * bufferAddr,UINT32 bufferSize)615 STATIC INLINE UINT32 LOS_QueueWriteCopyIsr(UINT32 queueID,
616 VOID *bufferAddr,
617 UINT32 bufferSize)
618 {
619 return LOS_QueueWriteCopy(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
620 }
621
622 /**
623 * @ingroup los_queue
624 * @brief Read a queue.
625 *
626 * @par Description:
627 * This API is used to read the address of data in a specified queue, and store it to the address specified by
628 * bufferAddr.
629 * @attention
630 * <ul>
631 * <li>The specific queue should be created firstly.</li>
632 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is
633 * read first.</li>
634 * <li>bufferAddr stores the obtained data address.</li>
635 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li>
636 * <li>This API cannot be called before the kernel is initialized.</li>
637 * <li>The argument timeOut is a relative time.</li>
638 * <li>The bufferSize is not really used in LOS_QueueRead, because the interface is only used to
639 * obtain the address of data.</li>
640 * <li>The buffer which the bufferAddr pointing to must be greater than or equal to 4 bytes.</li>
641 * </ul>
642 *
643 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
644 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
645 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must
646 * not be null.
647 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
648 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
649 *
650 * @retval #LOS_OK The queue is successfully read.
651 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid.
652 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null.
653 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0.
654 * @retval #LOS_ERRNO_QUEUE_READ_IN_INTERRUPT The queue cannot be read during an interrupt when the time for
655 * waiting to processing the queue expires.
656 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created.
657 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for
658 * waiting to processing the queue expires.
659 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is
660 * locked.
661 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
662 * @par Dependency:
663 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
664 * @see LOS_QueueWrite | LOS_QueueCreate
665 */
666 extern UINT32 LOS_QueueRead(UINT32 queueID,
667 VOID *bufferAddr,
668 UINT32 bufferSize,
669 UINT32 timeOut);
670
671 /**
672 * @ingroup los_queue
673 * @brief Read a queue in interrupt service routine.
674 *
675 * @par Description:
676 * This API is used to read the address of data in a specified queue, and store it to the address specified by
677 * bufferAddr.It is safe to use this API from within an interrupt service routine.
678 * @attention
679 * <ul>
680 * <li>The specific queue should be created firstly.</li>
681 * <li>Queue reading adopts the fist in first out (FIFO) mode. The data that is first stored in the queue is
682 * read first.</li>
683 * <li>This API read a queue in unblocking modes.</li>
684 * <li>bufferAddr stores the obtained data address.</li>
685 * <li>This API cannot be called before the kernel is initialized.</li>
686 * <li>The bufferSize is not really used in LOS_QueueRead, because the interface is only used to
687 * obtain the address of data.</li>
688 * <li>The buffer which the bufferAddr pointing to must be greater than or equal to 4 bytes.</li>
689 * </ul>
690 *
691 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
692 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
693 * @param bufferAddr [OUT] Starting address that stores the obtained data. The starting address must
694 * not be null.
695 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
696 *
697 * @retval #LOS_OK The queue is successfully read.
698 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid.
699 * @retval #LOS_ERRNO_QUEUE_READ_PTR_NULL The pointer passed in during queue reading is null.
700 * @retval #LOS_ERRNO_QUEUE_READSIZE_ISZERO The buffer size passed in during queue reading is 0.
701 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue to be read is not created.
702 * @retval #LOS_ERRNO_QUEUE_ISEMPTY No resource is in the queue that is being read when the time for
703 * waiting to processing the queue expires.
704 * @par Dependency:
705 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
706 * @see LOS_QueueWrite | LOS_QueueCreate
707 */
LOS_QueueReadIsr(UINT32 queueID,VOID * bufferAddr,UINT32 bufferSize)708 STATIC INLINE UINT32 LOS_QueueReadIsr(UINT32 queueID,
709 VOID *bufferAddr,
710 UINT32 bufferSize)
711 {
712 return LOS_QueueRead(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
713 }
714
715 /**
716 * @ingroup los_queue
717 * @brief Write data into a queue.
718 *
719 * @par Description:
720 * This API is used to write the address of data specified by bufferAddr into a queue.
721 * @attention
722 * <ul>
723 * <li>The specific queue should be created firstly.</li>
724 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li>
725 * <li>This API cannot be called before the kernel is initialized.</li>
726 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
727 * BufferAddr is to be written.</li>
728 * <li>The argument timeOut is a relative time.</li>
729 * <li>The bufferSize is not really used in LOS_QueueWrite, because the interface is only used to write the address
730 * of data specified by bufferAddr into a queue.</li>
731 * </ul>
732 *
733 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
734 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
735 * @param bufferAddr [IN] Starting address that stores the data to be written. The starting address
736 * must not be null.
737 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
738 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
739 *
740 * @retval #LOS_OK The data is successfully written into the queue.
741 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
742 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
743 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
744 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for
745 * waiting to processing the queue expires.
746 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
747 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
748 * the queue size.
749 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
750 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is
751 * locked.
752 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
753 * @par Dependency:
754 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
755 * @see LOS_QueueRead | LOS_QueueCreate
756 */
757 extern UINT32 LOS_QueueWrite(UINT32 queueID,
758 VOID *bufferAddr,
759 UINT32 bufferSize,
760 UINT32 timeOut);
761
762 /**
763 * @ingroup los_queue
764 * @brief Write data into a queue in interrupt service routine.
765 *
766 * @par Description:
767 * This API is used to write the address of data specified by bufferAddr into a queue.
768 * It is safe to use this API from within an interrupt service routine.
769 * @attention
770 * <ul>
771 * <li>The specific queue should be created firstly.</li>
772 * <li>This API write data into a queue in unblocking modes.</li>
773 * <li>This API cannot be called before the kernel is initialized.</li>
774 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
775 * BufferAddr is to be written.</li>
776 * <li>The bufferSize is not really used in LOS_QueueWriteIsr, because the interface is only used to write the address
777 * of data specified by bufferAddr into a queue.</li>
778 * </ul>
779 *
780 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
781 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
782 * @param bufferAddr [IN] Starting address that stores the data to be written. The starting address
783 * must not be null.
784 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
785 *
786 * @retval #LOS_OK The data is successfully written into the queue.
787 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
788 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
789 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
790 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
791 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
792 * the queue size.
793 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
794 * @par Dependency:
795 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
796 * @see LOS_QueueRead | LOS_QueueCreate
797 */
LOS_QueueWriteIsr(UINT32 queueID,VOID * bufferAddr,UINT32 bufferSize)798 STATIC INLINE UINT32 LOS_QueueWriteIsr(UINT32 queueID,
799 VOID *bufferAddr,
800 UINT32 bufferSize)
801 {
802 return LOS_QueueWrite(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
803 }
804
805 /**
806 * @ingroup los_queue
807 * @brief Write data into a queue header.
808 *
809 * @par Description:
810 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
811 * bufferAddr into a queue header.
812 * @attention
813 * <ul>
814 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li>
815 * <li>This API cannot be called before the kernel is initialized.</li>
816 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
817 * BufferAddr is to be written.</li>
818 * <li>The argument timeOut is a relative time.</li>
819 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to be used.
820 * <li>
821 * </ul>
822 *
823 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
824 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
825 * @param bufferAddr [OUT] Starting address that stores the data to be written. The starting address
826 * must not be null.
827 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
828 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
829 *
830 * @retval #LOS_OK The data is successfully written into the queue.
831 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
832 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
833 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
834 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for
835 * waiting to processing the queue expires.
836 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
837 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
838 * the queue size.
839 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
840 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is
841 * locked.
842 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
843 * @par Dependency:
844 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
845 * @see LOS_QueueRead | LOS_QueueCreate
846 */
847 extern UINT32 LOS_QueueWriteHead(UINT32 queueID,
848 VOID *bufferAddr,
849 UINT32 bufferSize,
850 UINT32 timeOut);
851
852 /**
853 * @ingroup los_queue
854 * @brief Write data into a queue header in interrupt service routine.
855 *
856 * @par Description:
857 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
858 * bufferAddr into a queue header.It is safe to use this API from within an interrupt service routine.
859 * @attention
860 * <ul>
861 * <li>This API cannot be called before the kernel is initialized.</li>
862 * <li>This API write data into a queue header in unblocking modes.</li>
863 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
864 * BufferAddr is to be written.</li>
865 * <li>LOS_QueueRead and LOS_QueueWriteHeadIsr are a set of interfaces, and the two groups of interfaces need to be used.
866 * <li>
867 * </ul>
868 *
869 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
870 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
871 * @param bufferAddr [OUT] Starting address that stores the data to be written. The starting address
872 * must not be null.
873 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
874 *
875 * @retval #LOS_OK The data is successfully written into the queue.
876 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
877 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
878 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
879 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
880 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
881 * the queue size.
882 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
883 * @par Dependency:
884 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
885 * @see LOS_QueueRead | LOS_QueueCreate
886 */
LOS_QueueWriteHeadIsr(UINT32 queueID,VOID * bufferAddr,UINT32 bufferSize)887 STATIC INLINE UINT32 LOS_QueueWriteHeadIsr(UINT32 queueID,
888 VOID *bufferAddr,
889 UINT32 bufferSize)
890 {
891 return LOS_QueueWriteHead(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
892 }
893
894 /**
895 * @ingroup los_queue
896 * @brief Write data into a queue header.
897 *
898 * @par Description:
899 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
900 * bufferAddr into a queue header.
901 * @attention
902 * <ul>
903 * <li>Do not read or write a queue in unblocking modes such as an interrupt.</li>
904 * <li>This API cannot be called before the kernel is initialized.</li>
905 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
906 * BufferAddr is to be written.</li>
907 * <li>The argument timeOut is a relative time.</li>
908 * <li>LOS_QueueRead and LOS_QueueWriteHead are a set of interfaces, and the two groups of interfaces need to be
909 * used.<li>
910 * </ul>
911 *
912 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
913 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
914 * @param bufferAddr [OUT] Starting address that stores the data to be written.
915 * The starting address must not be null.
916 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
917 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER](unit: Tick).
918 *
919 * @retval #LOS_OK The data is successfully written into the queue.
920 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
921 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
922 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
923 * @retval #LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT The queue cannot be written during an interrupt when the time for
924 * waiting to processing the queue expires.
925 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
926 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
927 * the queue size.
928 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
929 * @retval #LOS_ERRNO_QUEUE_PEND_IN_LOCK The task is forbidden to be blocked on a queue when the task is
930 * locked.
931 * @retval #LOS_ERRNO_QUEUE_TIMEOUT The time set for waiting to processing the queue expires.
932 * @par Dependency:
933 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
934 * @see LOS_QueueWrite | LOS_QueueWriteHead
935 */
936 extern UINT32 LOS_QueueWriteHeadCopy(UINT32 queueID,
937 VOID *bufferAddr,
938 UINT32 bufferSize,
939 UINT32 timeOut);
940
941 /**
942 * @ingroup los_queue
943 * @brief Write data into a queue header in interrupt service routine.
944 *
945 * @par Description:
946 * This API is used to write the data of the size specified by bufferSize and stored at the address specified by
947 * bufferAddr into a queue header.It is safe to use this API from within an interrupt service routine.
948 * @attention
949 * <ul>
950 * <li>This API cannot be called before the kernel is initialized.</li>
951 * <li>This API write data into a queue header in unblocking modes.</li>
952 * <li>The address of the data of the size specified by bufferSize and stored at the address specified by
953 * BufferAddr is to be written.</li>
954 * <li>LOS_QueueReadCopy and LOS_QueueWriteHeadCopyIsr are a set of interfaces, and the two groups of interfaces need to be
955 * used.<li>
956 * </ul>
957 *
958 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
959 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
960 * @param bufferAddr [OUT] Starting address that stores the data to be written.
961 * The starting address must not be null.
962 * @param bufferSize [IN] Passed-in buffer size, which must not be 0. The value range is [1,0xffffffff].
963 *
964 * @retval #LOS_OK The data is successfully written into the queue.
965 * @retval #LOS_ERRNO_QUEUE_INVALID The queue handle passed in during queue writing is invalid.
966 * @retval #LOS_ERRNO_QUEUE_WRITE_PTR_NULL The pointer passed in during queue writing is null.
967 * @retval #LOS_ERRNO_QUEUE_WRITESIZE_ISZERO The buffer size passed in during queue writing is 0.
968 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue into which the data is written is not created.
969 * @retval #LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG The buffer size passed in during queue writing is bigger than
970 * the queue size.
971 * @retval #LOS_ERRNO_QUEUE_ISFULL No free node is available during queue writing.
972 * @par Dependency:
973 * <ul><li>los_queue.h: The header file that contains the API declaration.</li></ul>
974 * @see LOS_QueueWrite | LOS_QueueWriteHeadIsr
975 */
LOS_QueueWriteHeadCopyIsr(UINT32 queueID,VOID * bufferAddr,UINT32 bufferSize)976 STATIC INLINE UINT32 LOS_QueueWriteHeadCopyIsr(UINT32 queueID,
977 VOID *bufferAddr,
978 UINT32 bufferSize)
979 {
980 return LOS_QueueWriteHeadCopy(queueID, bufferAddr, bufferSize, LOS_NO_WAIT);
981 }
982
983 /**
984 * @ingroup los_queue
985 * @brief Delete a queue.
986 *
987 * @par Description:
988 * This API is used to delete a queue.
989 * @attention
990 * <ul>
991 * <li>This API cannot be used to delete a queue that is not created.</li>
992 * <li>A synchronous queue fails to be deleted if any tasks are blocked on it, or some queues are being read or
993 * written.</li>
994 * </ul>
995 *
996 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
997 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
998 *
999 * @retval #LOS_OK The queue is successfully deleted.
1000 * @retval #LOS_ERRNO_QUEUE_NOT_FOUND The queue cannot be found.
1001 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue handle passed in when the queue is being deleted is
1002 * incorrect.
1003 * @retval #LOS_ERRNO_QUEUE_IN_TSKUSE The queue that blocks a task cannot be deleted.
1004 * @retval #LOS_ERRNO_QUEUE_IN_TSKWRITE Queue reading and writing are not synchronous.
1005 * @par Dependency:
1006 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1007 * @see LOS_QueueCreate | LOS_QueueCreate
1008 */
1009 extern UINT32 LOS_QueueDelete(UINT32 queueID);
1010
1011 /**
1012 * @ingroup los_queue
1013 * @brief Obtain queue information.
1014 *
1015 * @par Description:
1016 * This API is used to obtain queue information.
1017 * @attention
1018 * <ul>
1019 * <li>The specific queue should be created firstly.</li>
1020 * </ul>
1021 * @param queueID [IN] Queue ID created by LOS_QueueCreate. The value range is
1022 * [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
1023 * @param queueInfo [OUT] The queue information to be read must not be null.
1024 *
1025 * @retval #LOS_OK The queue information is successfully obtained.
1026 * @retval #LOS_ERRNO_QUEUE_PTR_NULL The pointer to the queue information to be obtained is null.
1027 * @retval #LOS_ERRNO_QUEUE_INVALID The handle of the queue that is being read is invalid.
1028 * @retval #LOS_ERRNO_QUEUE_NOT_CREATE The queue in which the information to be obtained is stored is
1029 * not created.
1030 *
1031 * @par Dependency:
1032 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1033 * @see LOS_QueueCreate
1034 */
1035 extern UINT32 LOS_QueueInfoGet(UINT32 queueID, QUEUE_INFO_S *queueInfo);
1036
1037 typedef enum {
1038 OS_QUEUE_READ,
1039 OS_QUEUE_WRITE
1040 } QueueReadWrite;
1041
1042 typedef enum {
1043 OS_QUEUE_HEAD,
1044 OS_QUEUE_TAIL
1045 } QueueHeadTail;
1046
1047 typedef enum {
1048 OS_QUEUE_NOT_POINT,
1049 OS_QUEUE_POINT
1050 } QueuePointOrNot;
1051
1052 #define OS_QUEUE_OPERATE_TYPE(ReadOrWrite, HeadOrTail, PointOrNot) \
1053 (((UINT32)(PointOrNot) << 2) | ((UINT32)(HeadOrTail) << 1) | (ReadOrWrite))
1054 #define OS_QUEUE_READ_WRITE_GET(type) ((type) & (0x01))
1055 #define OS_QUEUE_READ_HEAD (OS_QUEUE_READ | (OS_QUEUE_HEAD << 1))
1056 #define OS_QUEUE_READ_TAIL (OS_QUEUE_READ | (OS_QUEUE_TAIL << 1))
1057 #define OS_QUEUE_WRITE_HEAD (OS_QUEUE_WRITE | (OS_QUEUE_HEAD << 1))
1058 #define OS_QUEUE_WRITE_TAIL (OS_QUEUE_WRITE | (OS_QUEUE_TAIL << 1))
1059 #define OS_QUEUE_OPERATE_GET(type) ((type) & (0x03))
1060 #define OS_QUEUE_IS_POINT(type) ((type) & (0x04))
1061 #define OS_QUEUE_IS_READ(type) (OS_QUEUE_READ_WRITE_GET(type) == OS_QUEUE_READ)
1062 #define OS_QUEUE_IS_WRITE(type) (OS_QUEUE_READ_WRITE_GET(type) == OS_QUEUE_WRITE)
1063 #define OS_READWRITE_LEN 2
1064
1065 /**
1066 * @ingroup los_queue
1067 * Queue information block structure
1068 */
1069 typedef struct {
1070 UINT8 *queue; /**< Pointer to a queue handle */
1071 UINT8 *queueName; /**< Queue name */
1072 UINT16 queueState; /**< Queue state */
1073 UINT16 queueLen; /**< Queue length */
1074 UINT16 queueSize; /**< Node size */
1075 UINT16 queueID; /**< queueID */
1076 UINT16 queueHead; /**< Node head */
1077 UINT16 queueTail; /**< Node tail */
1078 UINT16 readWriteableCnt[OS_READWRITE_LEN]; /**< Count of readable or writable resources, 0:readable, 1:writable */
1079 LOS_DL_LIST readWriteList[OS_READWRITE_LEN]; /**< Pointer to the linked list to be read or written,
1080 0:readlist, 1:writelist */
1081 LOS_DL_LIST memList; /**< Pointer to the memory linked list */
1082 } LosQueueCB;
1083
1084
1085 extern LosQueueCB *OsGetQueueHandle(UINT32 queueID);
1086
1087 /* queue state */
1088 /**
1089 * @ingroup los_queue
1090 * Message queue state: not in use.
1091 */
1092 #define OS_QUEUE_UNUSED 0
1093
1094 /**
1095 * @ingroup los_queue
1096 * Message queue state: used.
1097 */
1098 #define OS_QUEUE_INUSED 1
1099
1100 /**
1101 * @ingroup los_queue
1102 * Not in use.
1103 */
1104 #define OS_QUEUE_WAIT_FOR_POOL 1
1105
1106 /**
1107 * @ingroup los_queue
1108 * Normal message queue.
1109 */
1110 #define OS_QUEUE_NORMAL 0
1111
1112 /**
1113 * @ingroup los_queue
1114 * Queue information control block
1115 */
1116 extern LosQueueCB *g_allQueue;
1117
1118 /**
1119 * @ingroup los_queue
1120 * Obtain a handle of the queue that has a specified ID.
1121 */
1122 #define GET_QUEUE_HANDLE(QueueID) OsGetQueueHandle(QueueID)
1123
1124 /**
1125 * @ingroup los_queue
1126 * Obtain the head node in a queue doubly linked list.
1127 */
1128 #define GET_QUEUE_LIST(ptr) LOS_DL_LIST_ENTRY(ptr, LosQueueCB, readWriteList[OS_QUEUE_WRITE])
1129
1130 /**
1131 * @ingroup los_queue
1132 * Maximum number of queues
1133 */
1134 #if (LOSCFG_BASE_IPC_QUEUE_STATIC == 1)
1135 #define OS_ALL_IPC_QUEUE_LIMIT LOSCFG_BASE_IPC_QUEUE_LIMIT + LOSCFG_BASE_IPC_STATIC_QUEUE_LIMIT
1136 #else
1137 #define OS_ALL_IPC_QUEUE_LIMIT LOSCFG_BASE_IPC_QUEUE_LIMIT
1138 #endif
1139
1140 /**
1141 * @ingroup los_queue
1142 * @brief Alloc a stationary memory for a mail.
1143 *
1144 * @par Description:
1145 * This API is used to alloc a stationary memory for a mail according to queueID.
1146 * @attention
1147 * <ul>
1148 * <li>Do not alloc memory in unblocking modes such as interrupt.</li>
1149 * <li>This API cannot be called before the kernel is initialized.</li>
1150 * <li>The argument timeOut is a relative time.</li>
1151 * </ul>
1152 *
1153 * @param queueID [IN] Queue ID. The value range is [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
1154 * @param mailPool [IN] The memory poll that stores the mail.
1155 * @param timeOut [IN] Expiry time. The value range is [0,LOS_WAIT_FOREVER].
1156 *
1157 * @retval #NULL The memory allocation is failed.
1158 * @retval #mem The address of alloc memory.
1159 * @par Dependency:
1160 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1161 * @see OsQueueMailFree
1162 */
1163 extern VOID *OsQueueMailAlloc(UINT32 queueID, VOID *mailPool, UINT32 timeOut);
1164
1165 /**
1166 * @ingroup los_queue
1167 * @brief Free a stationary memory of a mail.
1168 *
1169 * @par Description:
1170 * This API is used to free a stationary memory for a mail according to queueID.
1171 * @attention
1172 * <ul>
1173 * <li>This API cannot be called before the kernel is initialized.</li>
1174 * </ul>
1175 *
1176 * @param queueID [IN] Queue ID. The value range is [1,LOSCFG_BASE_IPC_QUEUE_LIMIT].
1177 * @param mailPool [IN] The mail memory poll address.
1178 * @param mailMem [IN] The mail memory block address.
1179 *
1180 * @retval #LOS_OK 0x00000000: The memory free successfully.
1181 * @retval #OS_ERRNO_QUEUE_MAIL_HANDLE_INVALID 0x02000619: The handle of the queue passed-in when the memory for
1182 the queue is being freed is invalid.
1183 * @retval #OS_ERRNO_QUEUE_MAIL_PTR_INVALID 0x0200061a: The pointer to the memory to be freed is null.
1184 * @retval #OS_ERRNO_QUEUE_MAIL_FREE_ERROR 0x0200061b: The memory for the queue fails to be freed.
1185 * @par Dependency:
1186 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1187 * @see OsQueueMailAlloc
1188 */
1189 extern UINT32 OsQueueMailFree(UINT32 queueID, VOID *mailPool, VOID *mailMem);
1190
1191 /**
1192 * @ingroup los_queue
1193 * @brief Initialization queue.
1194 *
1195 * @par Description:
1196 * This API is used to initialization queue.
1197 * @attention
1198 * <ul>
1199 * <li>None.</li>
1200 * </ul>
1201 *
1202 * @param None.
1203 *
1204 * @retval UINT32 Initialization result.
1205 * @par Dependency:
1206 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1207 * @see None.
1208 */
1209 extern UINT32 OsQueueInit(VOID);
1210
1211 /**
1212 * @ingroup los_queue
1213 * @brief Handle when read or write queue.
1214 *
1215 * @par Description:
1216 * This API is used to handle when read or write queue.
1217 * @attention
1218 * <ul>
1219 * <li>None.</li>
1220 * </ul>
1221 *
1222 * @param queueID [IN] Queue id.
1223 * @param operateType [IN] Operate type
1224 * @param bufferAddr [IN] Buffer address.
1225 * @param bufferSize [IN] Buffer size.
1226 * @param timeOut [IN] Timeout.
1227 *
1228 * @retval UINT32 Handle result.
1229 * @par Dependency:
1230 * <ul><li>los_queue.h: the header file that contains the API declaration.</li></ul>
1231 * @see None.
1232 */
1233 extern UINT32 OsQueueOperate(UINT32 queueID, UINT32 operateType, VOID *bufferAddr, UINT32 *bufferSize,
1234 UINT32 timeOut);
1235
1236 #ifdef __cplusplus
1237 #if __cplusplus
1238 }
1239 #endif /* __cplusplus */
1240 #endif /* __cplusplus */
1241
1242 #endif /* _LOS_QUEUE_H */
1243