1 /* 2 * Copyright (c) 2009-2022 Huawei Technologies Co., Ltd. All rights reserved. 3 * 4 * UniProton is licensed under Mulan PSL v2. 5 * You can use this software according to the terms and conditions of the Mulan PSL v2. 6 * You may obtain a copy of Mulan PSL v2 at: 7 * http://license.coscl.org.cn/MulanPSL2 8 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, 9 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, 10 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE. 11 * See the Mulan PSL v2 for more details. 12 * Create: 2009-12-22 13 * Description: 队列模块的对外头文件。 14 */ 15 #ifndef PRT_QUEUE_H 16 #define PRT_QUEUE_H 17 18 #include "prt_module.h" 19 #include "prt_errno.h" 20 21 #ifdef __cplusplus 22 #if __cplusplus 23 extern "C" { 24 #endif /* __cpluscplus */ 25 #endif /* __cpluscplus */ 26 27 /* 28 * 队列错误码：队列最大资源数配置成0。 29 * 30 * 值: 0x02000c01 31 * 32 * 解决方案: 队列最大资源数配置大于0，如果不用队列模块，可以配置裁剪开关为NO。 33 */ 34 #define OS_ERRNO_QUEUE_MAXNUM_ZERO OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x01) 35 36 /* 37 * 队列错误码：初始化队列内存不足。 38 * 39 * 值: 0x02000c02 40 * 41 * 解决方案: 分配更大的内存分区。 42 */ 43 #define OS_ERRNO_QUEUE_NO_MEMORY OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x02) 44 45 /* 46 * 队列错误码：队列创建时内存不足。 47 * 48 * 值: 0x02000c03 49 * 50 * 解决方案: 可以将内存空间配大。或将创建队列的节点长度和节点个数减少。 51 */ 52 #define OS_ERRNO_QUEUE_CREATE_NO_MEMORY OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x03) 53 54 /* 55 * 队列错误码：没有空闲的队列资源，已经达到配置的最大队列数。 56 * 57 * 值: 0x02000c04 58 * 59 * 解决方案: 增加配置项中队列资源数配置。 60 */ 61 #define OS_ERRNO_QUEUE_CB_UNAVAILABLE OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x04) 62 63 /* 64 * 队列错误码：任务切换锁定时，禁止任务阻塞于队列。 65 * 66 * 值: 0x02000c05 67 * 68 * 解决方案: 使用前，任务先解锁。 69 */ 70 #define OS_ERRNO_QUEUE_PEND_IN_LOCK OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x05) 71 72 /* 73 * 队列错误码：队列等待超时。 74 * 75 * 值: 0x02000c06 76 * 77 * 解决方案: 请查看超时时间设置是否合适。 78 */ 79 #define OS_ERRNO_QUEUE_TIMEOUT OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x06) 80 81 /* 82 * 队列错误码：不能删除被任务阻塞的队列。 83 * 84 * 值: 0x02000c07 85 * 86 * 解决方案: 让阻塞的任务获得资源，不阻塞在此队列上。 87 */ 88 #define OS_ERRNO_QUEUE_IN_TSKUSE OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x07) 89 90 /* 91 * 队列错误码：有超时情况下写队列不能在中断中使用。 92 * 93 * 值: 0x02000c08 94 * 95 * 解决方案: 同步队列超时时间配置为无等待或者使用异步队列。 96 */ 97 #define OS_ERRNO_QUEUE_IN_INTERRUPT OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x08) 98 99 /* 100 * 队列错误码：队列未创建。 101 * 102 * 值: 0x02000c09 103 * 104 * 解决方案: 输入正确的入参。 105 */ 106 #define OS_ERRNO_QUEUE_NOT_CREATE OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x09) 107 108 /* 109 * 队列错误码：阻塞在任务上的队列被激活，但没有得到调度，不能删除 110 * 111 * 值: 0x02000c0a 112 * 113 * 解决方案: 等待任务被调度后，就可以删除。 114 */ 115 #define OS_ERRNO_QUEUE_BUSY OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0a) 116 117 /* 118 * 队列错误码：队列创建时输入的指针为空。 119 * 120 * 值: 0x02000c0b 121 * 122 * 解决方案: 查看队列创建时输入的指针是否为空。 123 */ 124 #define OS_ERRNO_QUEUE_CREAT_PTR_NULL OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0b) 125 126 /* 127 * 队列错误码：队列创建时入参队列长度或者队列消息结点大小为0。 128 * 129 * 值: 0x02000c0c 130 * 131 * 解决方案: 输入正确的入参。 132 */ 133 #define OS_ERRNO_QUEUE_PARA_ZERO OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0c) 134 135 /* 136 * 队列错误码：队列句柄非法，错误或超出队列句柄范围。 137 * 138 * 值: 0x02000c0d 139 * 140 * 解决方案: 查看输入的队列句柄值是否有效。 141 */ 142 #define OS_ERRNO_QUEUE_INVALID OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0d) 143 144 /* 145 * 队列错误码：指针为空。 146 * 147 * 值: 0x02000c0e 148 * 149 * 解决方案: 查看输入的指针是否输入为空。 150 */ 151 #define OS_ERRNO_QUEUE_PTR_NULL OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0e) 152 153 /* 154 * 队列错误码：读写队列时buffer长度为0。 155 * 156 * 值: 0x02000c0f 157 * 158 * 解决方案: 输入正确的入参。 159 */ 160 #define OS_ERRNO_QUEUE_SIZE_ZERO OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x0f) 161 162 /* 163 * 队列错误码：写队列时，输入buffer的大小大于队列结点大小。 164 * 165 * 值: 0x02000c10 166 * 167 * 解决方案: 减少buffer的大小，或者使用更大结点大小的队列。 168 */ 169 #define OS_ERRNO_QUEUE_SIZE_TOO_BIG OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x10) 170 171 /* 172 * 队列错误码：读写队列时，没有资源。 173 * 174 * 值: 0x02000c11 175 * 176 * 解决方案: 写队列前需保证要有空闲的节点，读队列时需保证队列里有消息。 177 */ 178 #define OS_ERRNO_QUEUE_NO_SOURCE OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x11) 179 180 /* 181 * 队列错误码：队列优先级参数有误 182 * 183 * 值: 0x02000c12 184 * 185 * 解决方案: 请检查参数，参数只能是0或1 186 */ 187 #define OS_ERRNO_QUEUE_PRIO_INVALID OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x12) 188 189 /* 190 * 队列错误码：节点长度超过最大值 191 * 192 * 值: 0x02000c13 193 * 194 * 解决方案: 队列节点长度不能大于0XFFFA 195 */ 196 #define OS_ERRNO_QUEUE_NSIZE_INVALID OS_ERRNO_BUILD_ERROR(OS_MID_QUEUE, 0x13) 197 198 /* 199 * 队列优先级类型 200 */ 201 enum QueuePrio { 202 OS_QUEUE_NORMAL = 0, /* 普通消息队列 */ 203 OS_QUEUE_URGENT, /* 紧急消息队列 */ 204 OS_QUEUE_BUTT 205 }; 206 207 /* 208 * 队列等待时间设定：表示永久等待。 209 */ 210 #define OS_QUEUE_WAIT_FOREVER 0xFFFFFFFF 211 212 /* 213 * 队列等待时间设定：表示不等待。 214 */ 215 #define OS_QUEUE_NO_WAIT 0 216 217 /* 218 * 所有PID。 219 */ 220 #define OS_QUEUE_PID_ALL 0xFFFFFFFF 221 222 /* 223 * @brief 创建队列。 224 * 225 * @par 描述 226 * 创建一个队列，创建时可以设定队列长度和队列结点大小。 227 * @attention 228 * <ul> 229 * <li>每个队列节点的大小的单位是BYTE。</li> 230 * <li>每个队列节点的长度自动做2字节对齐。</li> 231 * <li>每个队列节点的长度不能大于0xFFFA。</li> 232 * </ul> 233 * @param nodeNum [IN] 类型#U16，队列节点个数，不能为0。 234 * @param maxNodeSize [IN] 类型#U16，每个队列结点的大小。 235 * @param queueId [OUT] 类型#U32 *，存储队列ID，ID从1开始。 236 * 237 * @retval #OS_OK 0x00000000，操作成功。 238 * @retval #其它值，操作失败。 239 * @par 依赖 240 * @li prt_queue.h：该接口声明所在的头文件。 241 * @see PRT_QueueDelete 242 */ 243 extern U32 PRT_QueueCreate(U16 nodeNum, U16 maxNodeSize, U32 *queueId); 244 245 /* 246 * @brief 读队列。 247 * 248 * @par 描述 249 * 读取指定队列中的数据。将读取到的数据存入bufferAddr地址，bufferAddr地址和读取数据大小由用户传入。 250 * @attention 251 * <ul> 252 * <li>队列读取才采用FIFO模式，即先入先出，读取队列中最早写入的数据(相对于队列节点是先后顺序)。</li> 253 * <li>如果bufferSize大于队列中实际消息的大小，则只返回实际大小的数据，否则只读取bufferSize大小的数据。</li> 254 * <li>bufferSize大小的单位是BYTE。</li> 255 * <li>阻塞模式不能在idle钩子使用，需用户保证。</li> 256 * <li>在osStart之前不能调用该接口，需用户保证。</li> 257 * </ul> 258 * @param queueId [IN] 类型#U32，队列ID。 259 * @param bufferAddr [OUT] 类型#void *，读取存放队列中数据的起始地址。 260 * @param len [I/O] 类型#U32 *，传入BUF的大小，输出实际消息的大小。 261 * @param timeOut [IN] 类型#U32，超时时间。 262 * 263 * @retval #OS_OK 0x00000000，操作成功。 264 * @retval #其它值，操作失败。 265 * 266 * @par 依赖 267 * @li prt_queue.h：该接口声明所在的头文件。 268 * @see PRT_QueueWrite 269 */ 270 extern U32 PRT_QueueRead(U32 queueId, void *bufferAddr, U32 *len, U32 timeOut); 271 272 /* 273 * @brief 写队列。 274 * 275 * @par 描述 276 * 向指定队列写数据。将bufferAddr地址中bufferSize大小的数据写入到队列中。 277 * @attention 278 * <ul> 279 * <li>需保证bufferSize大小小于或等于队列结点大小。</li> 280 * <li>bufferSize大小的单位是BYTE。 </li> 281 * <li>阻塞模式不能在idle钩子使用，需用户保证。 </li> 282 * <li>在osStart之前不能调用该接口，需用户保证。 </li> 283 * </ul> 284 * @param queueId [IN] 类型#U32，队列ID。 285 * @param bufferAddr [IN] 类型#void *，写到队列中数据的起始地址。 286 * @param bufferSize [IN] 类型#U32，写到队列中数据的大小。 287 * @param timeOut [IN] 类型#U32，超时时间。 288 * @param prio [IN] 类型#U32，优先级, 取值OS_QUEUE_NORMAL或OS_QUEUE_URGENT。 289 * 290 * @retval #OS_OK 0x00000000，操作成功。 291 * @retval #其它值，操作失败。 292 * 293 * @par 依赖 294 * @li prt_queue.h：该接口声明所在的头文件。 295 * @see PRT_QueueRead 296 */ 297 extern U32 PRT_QueueWrite(U32 queueId, void *bufferAddr, U32 bufferSize, U32 timeOut, U32 prio); 298 299 /* 300 * @brief 删除队列。 301 * 302 * @par 描述 303 * 删除一个消息队列。删除后队列资源被回收。 304 * @attention 305 * <ul> 306 * <li>不能删除未创建的队列。</li> 307 * <li>删除同步队列时，必须确保任务阻塞于该队列，且无被激活后还没及时操作队列的任务，否则删除队列失败。</li> 308 * </ul> 309 * @param queueId [IN] 类型#U32，队列ID。 310 * 311 * @retval #OS_OK 0x00000000，操作成功。 312 * @retval #其它值，操作失败。 313 * 314 * @par 依赖 315 * @li prt_queue.h：该接口声明所在的头文件。 316 * @see PRT_QueueCreate 317 */ 318 extern U32 PRT_QueueDelete(U32 queueId); 319 320 /* 321 * @brief 获取队列的历史最大使用长度。 322 * 323 * @par 描述 324 * 获取从队列创建到删除前的历史最大使用长度。 325 * @attention 326 * <ul> 327 * <li>峰值在队列删除前，不会被清零。</li> 328 * </ul> 329 * @param queueId [IN] 类型#U32，队列ID 330 * @param queueUsedNum [OUT] 类型#U32 *，队列节点使用峰值 331 * 332 * @retval #OS_OK 0x00000000，操作成功。 333 * @retval #其它值，操作失败。 334 * 335 * @par 依赖 336 * @li prt_queue.h：该接口声明所在的头文件。 337 * @see PRT_QueueGetNodeNum 338 */ 339 extern U32 PRT_QueueGetUsedPeak(U32 queueId, U32 *queueUsedNum); 340 341 /* 342 * @brief 获取指定源PID的待处理消息个数。 343 * 344 * @par 描述 345 * 从指定队列中，获取指定源PID的待处理消息个数。 346 * @attention 347 * <ul> 348 * <li>PID为OS_QUEUE_PID_ALL时，表示获取所有待处理的消息个数 </li> 349 * <li>PID的合法性不做判断，不合法的PID获取的消息个数为0 </li> 350 * </ul> 351 * @param queueId [IN] 类型#U32，队列ID。 352 * @param taskPid [IN] 类型#U32，线程PID。 353 * @param queueNum [OUT] 类型#U32 *，待处理的消息个数。 354 * 355 * @retval #OS_OK 0x00000000，操作成功。 356 * @retval #其它值，操作失败。 357 * 358 * @par 依赖 359 * @li prt_queue.h：该接口声明所在的头文件。 360 * @see PRT_QueueGetUsedPeak 361 */ 362 extern U32 PRT_QueueGetNodeNum(U32 queueId, U32 taskPid, U32 *queueNum); 363 364 #ifdef __cplusplus 365 #if __cplusplus 366 } 367 #endif /* __cpluscplus */ 368 #endif /* __cpluscplus */ 369 370 #endif /* PRT_QUEUE_H */ 371