1# UniProton 接口描述说明书 2## 1 简介 3 本文描述了UniProton对外提供的接口设计，重点描述了接口原型和字段定义等。本文档作为UniProton接口设计的基线文档，能够长期维护与使用。本文档将主要用于指导UniProton和所有使用UniProton接口的子系统的相关开发，也帮助测试人员了解UniProton提供的对外接口设计，支持相关开发和测试人员其完成UniProton及其内部各模块的开发和测试。 4### 1.1目的 5 本文主要用于指导UniProton的开发和测试人员了解UniProton对外提供的接口设计，以支持其完成UniProton各模块的开发和测试。该文档为UniProton接口设计的基线文档，长期维护与使用。 6### 1.2全量范围 7 本文档所列接口用于嵌入式产品。 8## 2 总体描述 9### 2.1 公共设计约定 10#### 2.1.1 处理器平台支持 11 UniProton支持各类处理器平台，当前仅支持cortex_m4芯片等，定义两个宏来识别一个确定的处理器平台： 12 OS_HARDWARE_PLATFORM：代表当前UniProton版本支持的处理器内核，它被赋值为以下枚举值之一： 13 OS_CORTEX_M4 14 基于各类处理器平台，UniProton向各类用户软件提供的基本统一的接口集合。对于一些具有特殊硬件功能的处理器，UniProton还为其提供相关的应用解决方案，相应地增加一些用户接口。 15 本文主要描述基于cortex_m4处理器硬件平台的UniProton接口。 16 17 #define OS_HARDWARE_PLATFORM OS_CORTEX_M4 18 #define OS_CPU_TYPE OS_STM32F407 19 20#### 2.1.2 功能裁剪 21 UniProton支持各项功能的裁减。其中，对于裁减与否不影响实时运行效率的功能，UniProton通过配置文件prt_config.h里的裁减宏来实现功能裁减，这种方式不要求重新编译UniProton库文件。 22 UniProton还有部分功能的裁减会影响实时运行效率，对此，UniProton在prt_buildef.h文件中提供裁减宏，改变裁减宏的值需要重新编译UniProton库文件。 23 24 25#### 2.1.3 基本数据类型 26 为了屏蔽各种处理器平台在数据类型定义上的差异，UniProton对C语言基本数据类型进行统一定义，供UniProton各功能模块及业务使用。基本数据类型定义为： 27 28 typedef unsigned char U8; 29 typedef unsigned short U16; 30 typedef unsigned int U32; 31 typedef unsigned long long U64; 32 typedef signed char S8; 33 typedef signed short S16; 34 typedef signed int S32; 35 typedef signed long long S64; 36 37#### 2.1.4 常用宏 38 UniProton还提供以下常用宏定义。 39 prt_typedef.h 40 #ifndef OS_SEC_ALW_INLINE 41 #define OS_SEC_ALW_INLINE 42 #endif 43 #ifndef INLINE 44 #define INLINE static __inline __attribute__((always_inline)) 45 #endif 46 #ifndef OS_EMBED_ASM 47 #define OS_EMBED_ASM __asm__ __volatile__ 48 #endif 49 #define ALIGN(addr, boundary) (((uintptr_t)(addr) + (boundary) - 1) & ~((uintptr_t)(boundary) - 1)) 50 #define TRUNCATE(addr, size) ((addr) & ~((uintptr_t)(size) - 1)) 51 #endif 52 #define YES 1 53 #endif 54 #define NO 0 55 #ifndef FALSE 56 #define FALSE ((bool)0) 57 #endif 58 #ifndef TRUE 59 #define TRUE ((bool)1) 60 #endif 61 #ifndef NULL 62 #define NULL ((void *)0) 63 #endif 64 #define OS_ERROR (U32)(-1) 65 #define OS_INVALID (-1) 66 #ifndef OS_OK 67 #define OS_OK 0 68 #endif 69 #ifndef LIKELY 70 #define LIKELY(x) __builtin_expect(!!(x), 1) 71 #endif 72 #ifndef UNLIKELY 73 #define UNLIKELY(x) __builtin_expect(!!(x), 0) 74 #endif 75## 3 接口定义 76### 3.1 prt接口 77#### 3.1.1 时钟模块 78##### 3.1.1.1 获取当前的64位time stamp计数(即系统运行的cycles) 79 【接口原型】 80 U64 PRT_ClkGetCycleCount64(void) 81 【功能描述】 82 获取当前的64位time stamp计数(即系统运行的cycles)。 83 【返回值】 84 [0,0xFFFFFFFFFFFFFFFF] 系统当前的cycle数 85 【参数说明】 86 无。 87 【注意事项】 88 获取的是64bit cycles 数据。 89 90##### 3.1.1.2 转换cycle为毫秒 91 【接口原型】 92 U64 PRT_ClkCycle2Ms(U64 cycle) 93 【功能描述】 94 转换cycle为毫秒。 95 【返回值】 96 [0,0xFFFFFFFFFFFFFFFF] 转换后的毫秒数。 97 【参数说明】 98 cycle [IN] 类型#U64，cycle数。 99 【注意事项】 100 None 101 102##### 3.1.1.3 转换cycle为微秒 103 【接口原型】 104 U64 PRT_ClkCycle2Us(U64 cycle) 105 【功能描述】 106 转换cycle为微秒。 107 【返回值】 108 [0,0xFFFFFFFFFFFFFFFF] 转换后的微秒数。 109 【参数说明】 110 cycle [IN] 类型#U64，cycle数。 111 【注意事项】 112 None 113 114##### 3.1.1.4 延迟时间(单位微秒) 115 【接口原型】 116 void PRT_ClkDelayUs(U32 delay) 117 【功能描述】 118 延迟时间(单位微秒)。 119 【返回值】 120 无 121 【参数说明】 122 delay [IN] 类型#U32，延迟微秒数。 123 【注意事项】 124 None 125 126##### 3.1.1.5 延迟时间(单位毫秒) 127 【接口原型】 128 void PRT_ClkDelayMs(U32 delay) 129 【功能描述】 130 延迟时间(单位毫秒)。 131 @param delay [IN] 类型#U32，延迟毫秒数。 132 @retval 无 133 【返回值】 134 无 135 【参数说明】 136 delay [IN] 类型#U32，延迟微秒数。 137 【注意事项】 138 None 139 140#### 3.1.2 硬中断模块 141##### 3.1.2.1 激活指定核号内的硬中断 142 【接口原型】 143 U32 PRT_HwiTrigger(U32 dstCore, HwiHandle hwiNum) 144 【功能描述】 145 激活指定核号内的软件可触发的硬中断 146 【返回值】 147 #OS_OK 0x00000000，硬中断激活成功。 148 #其它值，激活失败。 149 【参数说明】 150 dstCore [IN] 类型#U32，目标核号。目前只支持指定为本核。 151 hwiNum [IN] 类型#HwiHandle，硬中断号，只支持软件可触发的中断号。 152 【注意事项】 153 None 154 155##### 3.1.2.2 清空中断请求位 156 【接口原型】 157 void PRT_HwiClearAllPending(void) 158 【功能描述】 159 清除所有的中断请求位。即放弃当前已触发中断的的响应。 160 【返回值】 161 无。 162 【参数说明】 163 无。 164 【注意事项】 165 None 166 167##### 3.1.2.3 清除硬中断的Pending位 168 【接口原型】 169 U32 PRT_HwiClearPendingBit(HwiHandle hwiNum) 170 【功能描述】 171 显式清除硬中断或事件的请求位，因为有的硬件响应中断后不会自动清Pending位。 172 【返回值】 173 #OS_OK 0x00000000，硬中断请求位清除成功。 174 #其它值，清除失败。 175 【参数说明】 176 hwiNum [IN] 类型#HwiHandle，硬中断号。 177 【注意事项】 178 None 179 180##### 3.1.2.4 屏蔽指定的硬中断 181 【接口原型】 182 U32 PRT_HwiDisable(HwiHandle hwiNum) 183 【功能描述】 184 禁止核响应指定硬中断的请求。 185 【返回值】 186 #OS_OK 0x00000000，硬中断去使能成功。 187 #其它值，硬中断去使能失败。 188 【参数说明】 189 hwiNum [IN] 类型#HwiHandle，依据不同的芯片，硬中断号或中断向量号，见注意事项。 190 【注意事项】 191 None 192 193##### 3.1.2.5 使能指定的硬中断 194 【接口原型】 195 U32 PRT_HwiEnable(HwiHandle hwiNum) 196 【功能描述】 197 允许核响应指定硬中断的请求。 198 【返回值】 199 #OS_OK 0x00000000，硬中断使能成功。 200 #其它值，硬中断使能失败。 201 【参数说明】 202 hwiNum [IN] 类型#HwiHandle，依据不同的芯片，硬中断号或中断向量号，见注意事项。 203 【注意事项】 204 对于不同芯片，此返回值代表的意义有所差异，差异细节见下面返回值说明 205 206##### 3.1.2.6 添加硬中断进入钩子 207 【接口原型】 208 U32 PRT_HwiAddEntryHook(HwiEntryHook hook) 209 【功能描述】 210 添加硬中断进入钩子。该钩子函数在进入硬中断ISR前被调用。 211 【返回值】 212 #OS_OK 0x00000000，硬中断使能成功。 213 #其它值，硬中断使能失败。 214 【参数说明】 215 hook [IN] 类型#HwiEntryHook，中断进入钩子函数。 216 【注意事项】 217 不同钩子函数间执行的先后顺序，不应当存在依赖关系。 218 不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。 219 最大支持钩子数需静态配置 220 221##### 3.1.2.7 删除硬中断进入钩子 222 【接口原型】 223 U32 PRT_HwiDelEntryHook(HwiEntryHook hook) 224 【功能描述】 225 删除硬中断进入钩子。该钩子函数将停止在进入硬中断ISR前的调用。 226 【返回值】 227 #OS_OK 0x00000000，硬中断使能成功。 228 #其它值，硬中断使能失败。 229 【参数说明】 230 hook [IN] 类型#HwiEntryHook，中断进入钩子函数。 231 【注意事项】 232 不同钩子函数间执行的先后顺序，不应当存在依赖关系。 233 不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。 234 最大支持钩子数需静态配置 235 236##### 3.1.2.8 添加硬中断退出钩子 237 【接口原型】 238 U32 PRT_HwiAddExitHook(HwiExitHook hook) 239 【功能描述】 240 添加硬中断退出钩子。该钩子函数在退出硬中断ISR后被调用。 241 【返回值】 242 #OS_OK 0x00000000，硬中断使能成功。 243 #其它值，硬中断使能失败。 244 【参数说明】 245 hook [IN] 类型#HwiExitHook，中断退出钩子函数。 246 【注意事项】 247 不同钩子函数间执行的先后顺序，不应当存在依赖关系。 248 不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。 249 最大支持钩子数需静态配置 250 251##### 3.1.2.9 删除硬中断退出钩子 252 【接口原型】 253 U32 PRT_HwiDelExitHook(HwiExitHook hook) 254 【功能描述】 255 删除硬中断退出钩子。该钩子函数将停止在退出硬中断ISR后的调用。 256 【返回值】 257 #OS_OK 0x00000000，硬中断使能成功。 258 #其它值，硬中断使能失败。 259 【参数说明】 260 hook [IN] 类型#HwiExitHook，中断退出钩子函数。 261 【注意事项】 262 不同钩子函数间执行的先后顺序，不应当存在依赖关系。 263 不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。 264 最大支持钩子数需静态配置 265 266##### 3.1.2.10 开中断 267 【接口原型】 268 uintptr_t PRT_HwiUnLock(void) 269 【功能描述】 270 开启全局可屏蔽中断。 271 【返回值】 272 开启全局中断前的中断状态值。 273 【参数说明】 274 无。 275 【注意事项】 276 None 277 278##### 3.1.2.11 关中断 279 【接口原型】 280 uintptr_t PRT_HwiLock(void) 281 【功能描述】 282 关闭全局可屏蔽中断。 283 【返回值】 284 关闭全局中断前的中断状态值。 285 【参数说明】 286 无。 287 【注意事项】 288 None 289 290##### 3.1.2.12 恢复中断状态接口 291 【接口原型】 292 void PRT_HwiRestore(uintptr_t intSave) 293 【功能描述】 294 恢复原中断状态寄存器。 295 【返回值】 296 无 297 【参数说明】 298 intSave [IN] 类型#uintptr_t，关全局中断PRT_IntLock和开全局中断PRT_IntUnLock的返回值。 299 【注意事项】 300 该接口必须和关闭全局中断或者是开启全局中断接口成对使用，以关全局中断或者开全局中断操作的返回值为入参 301 以保证中断可以恢复到关全局中断或者开全局中断操作前的状态 302 303##### 3.1.2.13 设置硬中断属性接口 304 【接口原型】 305 U32 PRT_HwiSetAttr(HwiHandle hwiNum, HwiPrior hwiPrio, HwiMode mode) 306 【功能描述】 307 在创建硬中断前，必须要配置好硬中断的优先级和模式，包括独立型（#OS_HWI_MODE_ENGROSS）和 308 组合型（#OS_HWI_MODE_COMBINE）两种配置模式。 309 【返回值】 310 #OS_OK 0x00000000，硬中断属性设置成功。 311 #其它值，属性设置失败。 312 【参数说明】 313 hwiNum [IN] 类型#HwiHandle，硬中断号。 314 hwiPrio [IN] 类型#HwiPrior，硬中断优先级。 315 mode [IN] 类型#HwiMode，设置的中断模式，为独立型(#OS_HWI_MODE_ENGROSS)或者组合型(#OS_HWI_MODE_COMBINE)。 316 【注意事项】 317 OS已经占用的不能被使用 318 319##### 3.1.2.14 创建硬中断函数 320 【接口原型】 321 U32 PRT_HwiCreate(HwiHandle hwiNum, HwiProcFunc handler, HwiArg arg) 322 【功能描述】 323 注册硬中断的处理函数。 324 【返回值】 325 #OS_OK 0x00000000，硬中断创建成功。 326 #其它值，创建失败。 327 【参数说明】 328 hwiNum [IN] 类型#HwiHandle，硬中断号。 329 handler [IN] 类型#HwiProcFunc，硬中断触发时的处理函数。 330 arg [IN] 类型#HwiArg，调用硬中断处理函数时传递的参数。 331 【注意事项】 332 在调用该函数之前，请先确保已经设置了中断属性。 333 硬中断创建成功后，并不使能相应向量的中断，需要显式调用#PRT_HwiEnable单独使能。 334 335##### 3.1.2.15 删除硬中断函数 336 【接口原型】 337 U32 PRT_HwiDelete(HwiHandle hwiNum) 338 【功能描述】 339 屏蔽相应硬中断或事件，取消硬中断处理函数的注册。 340 【返回值】 341 #OS_OK 0x00000000，硬中断删除成功。 342 #其它值，删除失败。 343 【参数说明】 344 hwiNum [IN] 类型#HwiHandle，硬中断号。 345 【注意事项】 346 不能删除OS占用的中断号。 347 348#### 3.1.3 事件模块 349##### 3.1.3.1 读事件 350 【接口原型】 351 U32 PRT_EventRead(U32 eventMask, U32 flags, U32 timeOut, U32 *events) 352 【功能描述】 353 读取当前任务的指定掩码为eventMask的事件，可以一次性读取多个事件。事件读取成功后，被读取的事件将被清除。 354 【返回值】 355 #OS_OK 0x00000000，操作成功。 356 #其它值，操作失败。 357 【参数说明】 358 eventMask [IN] 类型#U32，设置要读取的事件掩码，每个bit位对应一个事件，1表示要读取。该入参不能为0。 359 flags [IN] 类型#U32，读取事件所采取的策略, 为（OS_EVENT_ANY，OS_EVENT_ALL）中一个和（OS_EVENT_WAIT， 360 OS_EVENT_NOWAIT）中的一个标识或的结果。#OS_EVENT_ALL表示期望接收eventMask中的所有事件， 361 #OS_EVENT_ANY表示等待eventMask中的任何一个事件。#OS_EVENT_WAIT表示若期望事件没有发生，等待接收， 362 #OS_EVENT_NOWAIT表示若期望事件没有发生，将不会等待接收。 363 timeOut [IN] 类型#U32，等待超时时间，单位为tick，取值(0~0xFFFFFFFF]。当flags标志为OS_EVENT_WAIT， 364 这个参数才有效。若值为#OS_EVENT_WAIT_FOREVER，则表示永久等待。 365 events [OUT] 类型#U32 *，用于保存接收到的事件的指针。如果不需要输出，可以填写NULL。 366 【注意事项】 367 读取模式可以选择读取任意事件和读取所有事件。 368 等待模式可以选择等待和不等待，可等待指定时间、永久等待。 369 当读取事件没有发生且为等待模式时，会发生任务调度，锁任务状态除外。 370 不能在IDLE任务中读事件，需要用户自行保证。 371 不能在系统初始化之前调用读事件接口。 372 373##### 3.1.3.2 写事件 374 【接口原型】 375 U32 PRT_EventWrite(U32 taskId, U32 events) 376 【功能描述】 377 写任务ID为taskId的指定事件，可以一次性写多个事件，可以在UniProton接管的中断中调用。 378 【返回值】 379 #OS_OK 0x00000000，操作成功。 380 #其它值，操作失败。 381 【参数说明】 382 taskId [IN] 类型#U32，任务ID，表示要对某个任务进行写事件操作。 383 events [IN] 类型#U32，事件号，每个bit对应一个事件。 384 【注意事项】 385 若指定任务正在等待读取写入的事件，则会激活指定任务，并发生任务调度。 386 不能向IDLE任务写事件，需要用户自行保证。 387 388#### 3.1.4 异常模块 389##### 3.1.4.1 用户注册异常处理钩子 390 【接口原型】 391 U32 PRT_ExcRegHook(ExcProcFunc hook) 392 【功能描述】 393 注册异常处理钩子。 394 【返回值】 395 #OS_OK 0x00000000，注册失败。 396 #其它值，注册失败。 397 【参数说明】 398 hook [IN] 类型#ExcProcFunc，钩子函数。 399 【注意事项】 400 当多次注册该钩子时，最后一次注册的钩子生效。 401 注册的钩子函数不能为空，即一旦注册钩子函数，不能通过注册空函数将其取消。 402 403#### 3.1.5 背景任务模块 404##### 3.1.5.1 注册IDLE循环中调用的钩子 405 【接口原型】 406 U32 PRT_IdleAddHook(IdleHook hook) 407 【功能描述】 408 注册在IDLE任务中调用的钩子函数。 409 【返回值】 410 #OS_OK 0x00000000，操作成功。 411 #其它值，操作失败。 412 【参数说明】 413 hook [OUT] 类型#IdleHook，IDLE钩子函数，该参数不能为空。 414 【注意事项】 415 钩子中不能调用引起任务阻塞或切换的函数。 416 417##### 3.1.5.2 删除IDLE循环中调用的钩子 418 【接口原型】 419 U32 PRT_IdleDelHook(IdleHook hook) 420 【功能描述】 421 删除在IDLE任务中调用的钩子函数。 422 【返回值】 423 #OS_OK 0x00000000，操作成功。 424 #其它值，操作失败。 425 【参数说明】 426 hook [OUT] 类型#IdleHook，IDLE钩子函数，该参数不能为空。 427 【注意事项】 428 None 429 430##### 3.1.5.3 注册IDLE循环进入前调用的钩子 431 【接口原型】 432 U32 PRT_IdleAddPrefixHook(IdleHook hook) 433 【功能描述】 434 为本核注册IDLE循环进入前调用的钩子，该钩子只会被调用一次。 435 【返回值】 436 #OS_OK 0x00000000，操作成功。 437 【参数说明】 438 hook [IN] 类型#IdleHook，钩子函数。 439 【注意事项】 440 注册的钩子只在进入IDLE循环前执行一次。 441 若任务未裁剪，则作用的是任务IDLE循环。 442 IDLE任务钩子中使用矢量寄存器需要在前置钩子中调用#PRT_TaskCpSaveCfg接口设置矢量操作上下文保护区。 443 444#### 3.1.6 队列模块 445##### 3.1.6.1 创建队列 446 【接口原型】 447 U32 PRT_QueueCreate(U16 nodeNum, U16 maxNodeSize, U32 *queueId) 448 【功能描述】 449 创建一个队列，创建时可以设定队列长度和队列结点大小。 450 【返回值】 451 #OS_OK 0x00000000，操作成功。 452 #其它值，操作失败。 453 【参数说明】 454 nodeNum [IN] 类型#U16，队列节点个数，不能为0。 455 maxNodeSize [IN] 类型#U16，每个队列结点的大小。 456 queueId [OUT] 类型#U32 *，存储队列ID，ID从1开始。 457 【注意事项】 458 每个队列节点的大小的单位是BYTE。 459 每个队列节点的长度自动做2字节对齐。 460 每个队列节点的长度不能大于0xFFFA。 461 462##### 3.1.6.2 读队列 463 【接口原型】 464 U32 PRT_QueueRead(U32 queueId, void *bufferAddr, U32 *len, U32 timeOut) 465 【功能描述】 466 读取指定队列中的数据。将读取到的数据存入bufferAddr地址，bufferAddr地址和读取数据大小由用户传入。 467 【返回值】 468 #OS_OK 0x00000000，操作成功。 469 #其它值，操作失败。 470 【参数说明】 471 queueId [IN] 类型#U32，队列ID。 472 bufferAddr [OUT] 类型#void *，读取存放队列中数据的起始地址。 473 len [I/O] 类型#U32 *，传入BUF的大小，输出实际消息的大小。 474 timeOut [IN] 类型#U32，超时时间。 475 【注意事项】 476 队列读取才采用FIFO模式，即先入先出，读取队列中最早写入的数据(相对于队列节点是先后顺序)。 477 如果bufferSize大于队列中实际消息的大小，则只返回实际大小的数据，否则只读取bufferSize大小的数据。 478 bufferSize大小的单位是BYTE。 479 阻塞模式不能在idle钩子使用，需用户保证。 480 在osStart之前不能调用该接口，需用户保证。 481 482##### 3.1.6.3 写队列 483 【接口原型】 484 U32 PRT_QueueWrite(U32 queueId, void *bufferAddr, U32 bufferSize, U32 timeOut, U32 prio) 485 【功能描述】 486 向指定队列写数据。将bufferAddr地址中bufferSize大小的数据写入到队列中。 487 【返回值】 488 #OS_OK 0x00000000，操作成功。 489 #其它值，操作失败。 490 【参数说明】 491 queueId [IN] 类型#U32，队列ID。 492 bufferAddr [IN] 类型#void *，写到队列中数据的起始地址。 493 bufferSize [IN] 类型#U32，写到队列中数据的大小。 494 timeOut [IN] 类型#U32，超时时间。 495 prio [IN] 类型#U32，优先级, 取值OS_QUEUE_NORMAL或OS_QUEUE_URGENT。 496 【注意事项】 497 需保证bufferSize大小小于或等于队列结点大小。 498 bufferSize大小的单位是BYTE。 499 阻塞模式不能在idle钩子使用，需用户保证。 500 在osStart之前不能调用该接口，需用户保证。 501 502##### 3.1.6.4 删除队列 503 【接口原型】 504 U32 PRT_QueueDelete(U32 queueId) 505 【功能描述】 506 删除一个消息队列。删除后队列资源被回收。 507 【返回值】 508 #OS_OK 0x00000000，操作成功。 509 #其它值，操作失败。 510 【参数说明】 511 queueId [IN] 类型#U32，队列ID。 512 【注意事项】 513 不能删除未创建的队列。 514 删除同步队列时，必须确保任务阻塞于该队列，且无被激活后还没及时操作队列的任务，否则删除队列失败。 515 516##### 3.1.6.5 获取队列的历史最大使用长度 517 【接口原型】 518 U32 PRT_QueueGetUsedPeak(U32 queueId, U32 *queueUsedNum) 519 【功能描述】 520 获取从队列创建到删除前的历史最大使用长度。 521 【返回值】 522 #OS_OK 0x00000000，操作成功。 523 #其它值，操作失败。 524 【参数说明】 525 queueId [IN] 类型#U32，队列ID 526 queueUsedNum [OUT] 类型#U32 *，队列节点使用峰值 527 【注意事项】 528 峰值在队列删除前，不会被清零。 529 530##### 3.1.6.6 获取指定源PID的待处理消息个数 531 【接口原型】 532 U32 PRT_QueueGetNodeNum(U32 queueId, U32 taskPid, U32 *queueNum) 533 【功能描述】 534 从指定队列中，获取指定源PID的待处理消息个数。 535 【返回值】 536 #OS_OK 0x00000000，操作成功。 537 #其它值，操作失败。 538 【参数说明】 539 queueId [IN] 类型#U32，队列ID。 540 taskPid [IN] 类型#U32，线程PID。 541 queueNum [OUT] 类型#U32 *，待处理的消息个数。 542 【注意事项】 543 PID为OS_QUEUE_PID_ALL时，表示获取所有待处理的消息个数 544 PID的合法性不做判断，不合法的PID获取的消息个数为0 545 546#### 3.1.7 信号量模块 547##### 3.1.7.1 创建一个计数型信号量 548 【接口原型】 549 U32 PRT_SemCreate(U32 count, SemHandle *semHandle) 550 【功能描述】 551 根据用户指定的计数值，创建一个计数型信号量，设定初始计数器数值，唤醒方式为FIFO。 552 【返回值】 553 #OS_OK 0x00000000，操作成功。 554 #其它值，操作失败。 555 【参数说明】 556 count [IN] 类型#U32，计数器初始值，取值范围为[0, 0xFFFFFFFE]。 557 semHandle [OUT] 类型#SemHandle *，输出信号量句柄。 558 【注意事项】 559 创建是否成功会受到"核内信号量裁剪开关"和"最大支持信号量"配置项的限制。 560 561##### 3.1.7.2 删除一个信号量 562 【接口原型】 563 U32 PRT_SemDelete(SemHandle semHandle) 564 【功能描述】 565 删除用户传入的信号量句柄指定的信号量，如果有任务阻塞于该信号量，则删除失败。 566 【返回值】 567 #OS_OK 0x00000000，操作成功。 568 #其它值，操作失败。 569 【参数说明】 570 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 571 【注意事项】 572 None 573 574##### 3.1.7.3 获取信号量计数器数值 575 【接口原型】 576 U32 PRT_SemGetCount(SemHandle semHandle, U32 *semCnt) 577 【功能描述】 578 根据用户输入信号量句柄和计数值，获取信号量计数器数值。 579 【返回值】 580 #OS_OK 0x00000000，获取信号量计数器值成功。 581 #其它值，获取失败。 582 【参数说明】 583 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 584 semCnt [OUT] 类型#U32 *，保存信号量计数值指针。 585 【注意事项】 586 None 587 588##### 3.1.7.4 等待一个信号量 589 【接口原型】 590 U32 PRT_SemPend(SemHandle semHandle, U32 timeout) 591 【功能描述】 592 等待用户传入信号量句柄指定的信号量，若其计数器值大于0，则直接减1返回成功。否则任务阻塞， 593 等待其他线程发布该信号量，等待超时时间可设定。 594 【返回值】 595 #OS_OK 0x00000000，操作成功。 596 #其它值，操作失败。 597 【参数说明】 598 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 599 timeout [IN] 类型#U32，等待时间限制，单位为tick，取值范围为[0, 0xffffffff]。#OS_NO_WAIT或0表示不等待， 600 #OS_WAIT_FOREVER或0xffffffff表示永久等待。 601 【注意事项】 602 在osStart之前不能调用该接口。 603 等待时间可以选择零等待、等待特定时间、永久等待。 604 该接口只能被任务调用。 605 在锁任务情况下，用户要PEND信号量，要保证当前有可用信号量资源。 606 607##### 3.1.7.5 发布指定的信号量 608 【接口原型】 609 U32 PRT_SemPost(SemHandle semHandle) 610 【功能描述】 611 发布指定的信号量，若没有任务等待该信号量，则直接将计数器加1返回。 612 否则根据唤醒方式唤醒相应的阻塞任务，FIFO方式唤醒最早阻塞的任务，优先级方式唤醒阻塞在此信号量的最高优先级任务。 613 【返回值】 614 #OS_OK 0x00000000，操作成功。 615 #其它值，操作失败。 616 【参数说明】 617 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 618 【注意事项】 619 在osStart之前不能调用该接口。 620 在未锁任务的情况下，如果唤醒的任务优先级高于当前任务，则会立刻发生任务切换。 621 发生任务切换时，如果支持优先级唤醒方式，且创建信号量时指定唤醒方式为优先级， 622 623##### 3.1.7.6 获取阻塞在指定核内信号量上的任务PID清单 624 【接口原型】 625 U32 PRT_SemGetPendList(SemHandle semHandle, U32 *tskCnt, U32 *pidBuf, U32 bufLen) 626 【功能描述】 627 根据用户指定的核内信号量句柄，获取阻塞在指定核内信号量上的任务PID清单。 628 若有任务阻塞于该核内信号量，则返回阻塞于该核内信号量的任务数目，以及相应任务的PID。 629 若没有任务阻塞于该核内信号量，则返回阻塞于该核内信号量的任务数目为0。 630 【返回值】 631 #OS_OK 0x00000000，操作成功。 632 #其它值，操作失败。 633 【参数说明】 634 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 635 tskCnt [OUT] 类型#U32 *，阻塞于该核内信号量的任务数。 636 pidBuf [OUT] 类型#U32 *，由用户指定的内存区域首地址，用于存储阻塞于指定核内信号量的任务PID。 637 bufLen [IN] 类型#U32，用户指定的内存区域的长度（单位：字节）。 638 【注意事项】 639 用户应保证存储任务PID清单的内存空间足够大，建议将bufLen配置为(#OS_TSK_MAX_SUPPORT_NUM + 1) 640 641##### 3.1.7.7 获取信号量详细信息:信号量当前计数值，信号量持有者(最后一次pend成功的线程ID)，信号量唤醒方式，信号量类型 642 【接口原型】 643 U32 PRT_SemGetInfo(SemHandle semHandle, struct SemInfo *semInfo) 644 【功能描述】 645 根据用户输入信号量句柄获取信号量详细信息。 646 【返回值】 647 #OS_OK 0x00000000，获取信号量计数器值成功。 648 #其它值，获取失败。 649 【参数说明】 650 semHandle [IN] 类型#SemHandle，信号量句柄，来源于信号量创建成功的输出值。 651 semInfo [OUT] 类型#struct SemInfo *，信号量详细信息:count--信号量计数，owner--信号量占用者， 652 mode--信号量唤醒方式，type--信号量类型。 653 【注意事项】 654 None 655 656#### 3.1.8 系统模块 657##### 3.1.8.1 复位单板 658 【接口原型】 659 void PRT_SysReboot(void) 660 【功能描述】 661 复位单板，程序重新加载执行。 662 【返回值】 663 无 664 【参数说明】 665 无。 666 【注意事项】 667 并非直接复位单板，而是关中断，等待看门狗复位。 668 用户可以通过配置项OS_SYS_REBOOT_HOOK挂接复位函数。 669 670##### 3.1.8.2 获取当前核ID 671 【接口原型】 672 U32 PRT_SysGetCoreId(void) 673 【功能描述】 674 获取当前核ID。 675 【返回值】 676 物理核ID。 677 【参数说明】 678 无。 679 【注意事项】 680 获取的核ID为硬件寄存器中的ID号。 681 682##### 3.1.8.3 业务给OS传递RND值，用作后续相关功能模块的保护 683 【接口原型】 684 U32 PRT_SysSetRndNum(enum SysRndNumType type, U32 rndNum) 685 【功能描述】 686 None 687 【返回值】 688 #OS_OK 0x00000000，操作成功。 689 #其它值，操作失败。 690 【参数说明】 691 type [IN] 类型#enum SysRndNumType，设置的目标RND值的类型。 692 rndNum [IN] 类型#U32，传递的RND值。 693 【注意事项】 694 栈保护随机值设置必须在PRT_HardBootInit中调用。 695 696##### 3.1.8.4 获取OS的版本号 697 【接口原型】 698 char *PRT_SysGetOsVersion(void) 699 【功能描述】 700 获取OS的版本号。版本编号格式为UniProton xx.xx VERSIONID(XXX)。 701 【返回值】 702 指向OS版本号的字符串指针。 703 【参数说明】 704 无。 705 【注意事项】 706 None 707 708#### 3.1.9 任务模块 709##### 3.1.9.1 创建任务，但不激活任务 710 【接口原型】 711 U32 PRT_TaskCreate(TskHandle *taskPid, struct TskInitParam *initParam) 712 【功能描述】 713 创建一个任务。该任务不加入就绪队列，只处于挂起状态，用户需要激活该任务需要通过调用PRT_TaskResume函数将其激活。 714 【返回值】 715 #OS_OK 0x00000000，任务创建成功。 716 #其它值，创建失败。 717 【参数说明】 718 taskPid [OUT] 类型#TskHandle *，保存任务PID。 719 initParam [IN] 类型#struct TskInitParam *，任务创建参数， 720 其结构体中的成员参数stackAddr传入时必须进行初始化，若不采用用户配置的独立任务栈进行栈空间分配， 721 该成员必须初始化为0。 722 【注意事项】 723 任务创建时，会对之前自删除任务的任务控制块和任务栈进行回收，用户独立配置的任务栈除外。 724 任务名的最大长度为16字节，含结束符。 725 同一核内任务名不允许重复。 726 若指定的任务栈大小为0，则使用配置项#OS_TSK_DEFAULT_STACK_SIZE指定的默认的任务栈大小。 727 任务栈的大小必须按16字节大小对齐。确定任务栈大小的原则是，够用就行：多了浪费，少了任务栈溢出。 728 具体多少取决于需要消耗多少的栈内存，视情况而定：函数调用层次越深，栈内存开销越大， 729 局部数组越大，局部变量越多，栈内存开销也越大。 730 用户配置的任务栈首地址需16字节对齐。 731 用户配置的任务栈空间需由用户保证其合法性，即对可cache空间的地址用户需要保证其任务栈首地址及栈大小cache line对齐，系统不做对齐处理，并在使用后需由用户进行释放。 732 任务创建时，任务创建参数中的任务栈大小配置建议不要使用最小任务栈大小OS_TSK_MIN_STACK_SIZE， 733 该项只是包含任务上下文预留的栈空间，任务调度时额外的任务开销需要由用户自行保证足够的任务栈空间配置。 734 735##### 3.1.9.2 恢复任务 736 【接口原型】 737 U32 PRT_TaskResume(TskHandle taskPid) 738 【功能描述】 739 恢复挂起的任务。 740 【返回值】 741 #OS_OK 0x00000000，恢复任务成功。 742 #其它值，恢复任务失败。 743 【参数说明】 744 taskPid [IN] 类型#TskHandle，任务PID。 745 【注意事项】 746 在osStart之前不能调用该接口。 747 若任务仍处于延时、阻塞态，则只是取消挂起态，并不加入就绪队列。 748 749##### 3.1.9.3 挂起任务 750 【接口原型】 751 U32 PRT_TaskSuspend(TskHandle taskPid) 752 【功能描述】 753 挂起指定的任务，任务将从就绪队列中被删除。 754 【返回值】 755 #OS_OK 0x00000000，挂起任务成功。 756 #其它值，挂起任务失败。 757 【参数说明】 758 taskPid [IN] 类型#TskHandle，任务PID。 759 【注意事项】 760 在osStart之前不能调用该接口。 761 若为当前任务且已锁任务，则不能被挂起。 762 IDLE任务不能被挂起。 763 764##### 3.1.9.4 删除任务 765 【接口原型】 766 U32 PRT_TaskDelete(TskHandle taskPid) 767 【功能描述】 768 删除指定的任务，释放任务栈和任务控制块资源。 769 【返回值】 770 #OS_OK 0x00000000，删除任务成功。 771 #其它值，删除任务失败。 772 【参数说明】 773 taskPid [IN] 类型#TskHandle，任务PID。 774 【注意事项】 775 若为自删除，则任务控制块和任务栈在下一次创建任务时才回收。 776 对于任务自删除，处理该任务相关的信号量和接收到的消息会强制删除。 777 任务自删除时，删除钩子不允许进行pend信号量、挂起等操作。 778 779##### 3.1.9.5 延迟正在运行的任务 780 【接口原型】 781 U32 PRT_TaskDelay(U32 tick) 782 【功能描述】 783 延迟当前运行任务的执行。任务延时等待指定的Tick数后，重新参与调度。 784 【返回值】 785 #OS_OK 0x00000000，任务延时成功。 786 #其它值，延时任务失败。 787 【参数说明】 788 tick [IN] 类型#U32，延迟的Tick数。 789 【注意事项】 790 在osStart之前不能调用该接口。 791 硬中断处理中，或已锁任务，则延时操作失败。 792 若传入参数0，且未锁任务调度，则顺取同优先级队列中的下一个任务执行。如没有同级的就绪任务， 793 则不发生任务调度，继续执行原任务。 794 795##### 3.1.9.6 锁任务调度 796 【接口原型】 797 void PRT_TaskLock(void) 798 【功能描述】 799 锁任务调度。若任务调度被锁，则不发生任务切换。 800 【返回值】 801 无 802 【参数说明】 803 无。 804 【注意事项】 805 只是锁任务调度，并不关中断，因此任务仍可被中断打断。 806 执行此函数则锁计数值加1，解锁则锁计数值减1。因此，必须与#PRT_TaskUnlock配对使用。 807 808##### 3.1.9.7 解锁任务调度 809 【接口原型】 810 void PRT_TaskUnlock(void) 811 【功能描述】 812 任务锁计数值减1。若嵌套加锁，则只有锁计数值减为0才真正的解锁了任务调度。 813 【返回值】 814 无 815 【参数说明】 816 无。 817 【注意事项】 818 在osStart之前不能调用该接口。 819 执行此函数则锁计数值加1，解锁则锁计数值减1。因此，必须与#PRT_TaskLock配对使用。 820 821##### 3.1.9.8 获取当前任务PID 822 【接口原型】 823 U32 PRT_TaskSelf(TskHandle *taskPid) 824 【功能描述】 825 获取处于运行态的任务PID。 826 【返回值】 827 #OS_OK 0x00000000，获取成功。 828 #其它值，获取失败。 829 【参数说明】 830 taskPid [OUT] 类型#TskHandle *，保存任务PID。 831 【注意事项】 832 硬中断处理中，也可获取当前任务PID，即被中断打断的任务。 833 在任务切换钩子处理中调用时，获取的是切入任务的ID。 834 835##### 3.1.9.9 获取任务状态 836 【接口原型】 837 TskStatus PRT_TaskGetStatus(TskHandle taskPid) 838 【功能描述】 839 获取指定任务的状态。 840 【返回值】 841 #(TskStatus)OS_INVALID 返回失败。 842 #任务状态 返回成功。 843 【参数说明】 844 taskPid [IN] 类型#TskHandle，任务PID。 845 【注意事项】 846 None 847 848##### 3.1.9.10 获取任务信息 849 【接口原型】 850 U32 PRT_TaskGetInfo(TskHandle taskPid, struct TskInfo *taskInfo) 851 【功能描述】 852 获取指定任务的信息。 853 【返回值】 854 #OS_OK 0x00000000，获取成功。 855 #其它值，获取失败。 856 【参数说明】 857 taskPid [IN] 类型#TskHandle，任务PID。 858 taskInfo [OUT] 类型#struct TskInfo *，保存任务信息。 859 【注意事项】 860 若获取当前任务的信息，则只在硬中断、异常的处理中才有意义， 861 由于任务切换时，上下文信息也保存在任务栈中，因此任务信息中的SP是保存上下文之后的实际的SP值。 862 863##### 3.1.9.11 获取优先级 864 【接口原型】 865 U32 PRT_TaskGetPriority(TskHandle taskPid, TskPrior *taskPrio) 866 【功能描述】 867 获取指定任务的优先级。 868 【返回值】 869 #OS_OK 0x00000000，获取成功。 870 #其它值，获取失败。 871 【参数说明】 872 taskPid [IN] 类型#TskHandle，任务PID。 873 taskPrio [OUT] 类型#TskPrior *，保存任务优先级指针。 874 【注意事项】 875 None 876 877##### 3.1.9.12 设置优先级 878 【接口原型】 879 U32 PRT_TaskSetPriority(TskHandle taskPid, TskPrior taskPrio) 880 【功能描述】 881 设置指定任务的优先级。 882 【返回值】 883 #OS_OK 0x00000000，设置成功。 884 #其它值，设置失败。 885 【参数说明】 886 taskPid [IN] 类型#TskHandle，任务PID。 887 taskPrio [IN] 类型#TskPrior，任务优先级。 888 【注意事项】 889 在osStart之前不能调用该接口。 890 若设置的优先级高于当前运行的任务，则可能引发任务调度。 891 若调整当前运行任务的优先级，同样可能引发任务调度。 892 若任务发生优先级继承，或者任务阻塞在互斥信号量或优先级唤醒模式的信号量上，不可以设置任务的优先级。 893 894##### 3.1.9.13 查询本核指定任务正在PEND的信号量 895 【接口原型】 896 U32 PRT_TaskGetPendSem(TskHandle taskId, U16 *semId, U16 *pendState) 897 【功能描述】 898 根据任务状态和任务控制块，判断任务是否在PEND信号量，以及PEND的信号量ID。 899 【返回值】 900 #OS_OK 0x00000000，查询成功。 901 #其它值，查询失败。 902 【参数说明】 903 taskId [IN] 类型#TskHandle，任务PID。 904 semId [OUT] 类型#U16 *，任务PEND的信号量ID或者#OS_INVALID。 905 pendState [OUT] 类型#U16 *，任务的PEND状态：0，#OS_TSK_FSEM_PEND，#OS_TSK_PEND, #OS_TSK_MCSEM_PEND。 906 【注意事项】 907 用户应先判断PEND状态，状态为0表明任务没有被信号量阻塞。 908 909##### 3.1.9.14 查询任务名 910 【接口原型】 911 U32 PRT_TaskGetName(TskHandle taskId, char **name) 912 【功能描述】 913 根据任务PID，查询任务名。 914 【返回值】 915 #OS_OK 0x00000000，查询成功。 916 #其它值，查询失败。 917 【参数说明】 918 taskId [IN] 类型#TskHandle，任务ID。 919 name [OUT] 类型#char **，保存任务名字符串的首地址。 920 【注意事项】 921 在osStart之前不能调用该接口。 922 不能查询ID不合法的任务名。 923 若查询没有创建的任务名，查询失败。 924 925##### 3.1.9.15 注册任务切换钩子 926 【接口原型】 927 U32 PRT_TaskAddSwitchHook(TskSwitchHook hook) 928 【功能描述】 929 注册任务切换钩子函数。钩子函数在切入新任务前被调用。 930 【返回值】 931 #OS_OK 0x00000000，查询成功。 932 #其它值，查询失败。 933 【参数说明】 934 hook [IN] 类型#TskSwitchHook，任务切换钩子函数。 935 【注意事项】 936 不同钩子函数间执行的先后顺序，不应当存在依赖关系。 937 不应在任务切换钩子里进行可能引起任务调度的处理，如：任务延时、P信号量等。 938 939##### 3.1.9.16 取消任务切换钩子 940 【接口原型】 941 U32 PRT_TaskDelSwitchHook(TskSwitchHook hook) 942 【功能描述】 943 取消指定的任务切换钩子。钩子函数在切入新任务前被调用。 944 【返回值】 945 #OS_OK 0x00000000，查询成功。 946 #其它值，查询失败。 947 【参数说明】 948 hook [IN] 类型#TskSwitchHook，任务切换钩子函数。 949 【注意事项】 950 None 951 952#### 3.1.10 Tick中断 953##### 3.1.10.1 获取每秒钟对应的Tick数 954 【接口原型】 955 U64 PRT_TickGetCount(void) 956 【功能描述】 957 获取当前的tick计数。 958 【返回值】 959 [0,0xFFFFFFFFFFFFFFFF] 当前的tick计数。 960 【参数说明】 961 无。 962 【注意事项】 963 None 964 965#### 3.1.11 定时器模块 966##### 3.1.11.1 创建定时器 967 【接口原型】 968 U32 PRT_TimerCreate(struct TimerCreatePara *createPara, TimerHandle *tmrHandle) 969 【功能描述】 970 创建一个属性为createPara的定时器，返回定时器逻辑ID tmrHandle。 971 【返回值】 972 #OS_OK 0x00000000，定时器创建成功。 973 #其它值，创建失败。 974 【参数说明】 975 createPara [IN] 类型#struct TimerCreatePara *，定时器创建参数 976 tmrHandle [OUT] 类型#TimerHandle *，定时器句柄 977 【注意事项】 978 如果用户打开Tick开关则可创建硬件定时器个数少一个。 979 中断处理函数handler的第一个参数是创建的定时器的逻辑编号。 980 定时器创建成功后并不立即开始计数，需显式调用#PRT_TimerStart或者#PRT_TimerRestart启动。 981 对于周期定时模式的定时器，建议用户不要把定时间隔设置的过低，避免一直触发定时器的处理函数。 982 struct TimerCreatePara参数里面的interval元素表示定时器周期，软件定时器单位是ms， 983 984##### 3.1.11.2 删除定时器 985 【接口原型】 986 U32 PRT_TimerDelete(U32 mid, TimerHandle tmrHandle) 987 【功能描述】 988 释放一个定时器逻辑ID为tmrHandle的定时器资源。 989 【返回值】 990 #OS_OK 0x00000000，定时器删除成功。 991 #其它值，删除失败。 992 【参数说明】 993 mid [IN] 类型#U32，模块号，当前未使用，忽略 994 tmrHandle [IN] 类型#TimerHandle，定时器句柄，通过PRT_TimerCreate接口获取 995 【注意事项】 996 硬件定时器删除后将停止计数。 997 删除处于超时状态下的软件定时器时，OS采用延时删除的方式。详细说明请见手册注意事项。 998 999##### 3.1.11.3 启动定时器 1000 【接口原型】 1001 U32 PRT_TimerStart(U32 mid, TimerHandle tmrHandle) 1002 【功能描述】 1003 将定时器逻辑ID为tmrHandle的定时器由创建状态变成启动状态。 1004 【返回值】 1005 #OS_OK 0x00000000，定时器启动成功。 1006 #其它值，启动失败。 1007 【参数说明】 1008 mid [IN] 类型#U32，模块号，当前未使用，忽略 1009 tmrHandle [IN] 类型#TimerHandle，定时器句柄，通过#PRT_TimerCreate接口获取 1010 【注意事项】 1011 创建后初次启动定时器时，从设置的值开始计数；如果重复启动或者启动后停止然后再启动， 1012 对于全局硬件定时器，无论是第一次启动还是重复启动，下一次启动都从初始值开始计时。 1013 对于单次触发模式，触发一次后，可以调用启动接口再次启动该定时器，时间间隔为设置的时间间隔。 1014 启动处于超时状态下的软件定时器时，OS采用延时启动的方式。详细说明请见手册注意事项。 1015 1016##### 3.1.11.4 停止定时器 1017 【接口原型】 1018 U32 PRT_TimerStop(U32 mid, TimerHandle tmrHandle) 1019 【功能描述】 1020 停止定时器逻辑ID为tmrHandle的定时器计数，使定时器由计时状态变成创建状态。 1021 【返回值】 1022 #OS_OK 0x00000000，定时器停止成功。 1023 #其它值，停止失败。 1024 【参数说明】 1025 mid [IN] 类型#U32，模块号，当前未使用，忽略 1026 tmrHandle [IN] 类型#TimerHandle，定时器句柄，通过#PRT_TimerCreate接口获取 1027 【注意事项】 1028 定时器停止后，下一次启动将重新从停止点的计数值开始计数。 1029 不能停止未启动的定时器。 1030 停止处于超时状态下的软件定时器时，OS采用延时停止的方式。详细说明请见手册注意事项。 1031 核内硬件定时器在停止过程中如果发生超时，则剩余时间为0，但不会响应定时器处理函数。 1032 1033##### 3.1.11.5 重启定时器 1034 【接口原型】 1035 U32 PRT_TimerRestart(U32 mid, TimerHandle tmrHandle) 1036 【功能描述】 1037 重启定时器逻辑ID为tmrHandle的定时器计数，对于停止过的定时器，相当于恢复到刚创建时的定时时长开始计时。 1038 【返回值】 1039 #OS_OK 0x00000000，定时器重启成功。 1040 #其它值，重启失败。 1041 【参数说明】 1042 mid [IN] 类型#U32，模块号，当前未使用，忽略 1043 tmrHandle [IN] 类型#TimerHandle，定时器句柄，通过#PRT_TimerCreate接口获取 1044 【注意事项】 1045 重启处于超时状态下的软件定时器时，OS采用延时重启的方式。详细说明请见手册注意事项。 1046 1047##### 3.1.11.6 定时器剩余超时时间查询 1048 【接口原型】 1049 U32 PRT_TimerQuery(U32 mid, TimerHandle tmrHandle, U32 *expireTime) 1050 【功能描述】 1051 输入定时器句柄tmrHandle，获得对应定时器超时剩余时间expireTime。 1052 【返回值】 1053 #OS_OK 0x00000000，定时器剩余超时时间查询成功。 1054 #其它值，查询失败。 1055 【参数说明】 1056 mid [IN] 类型#U32，模块号，当前未使用，忽略 1057 tmrHandle [IN] 类型#TimerHandle，定时器句柄，通过#PRT_TimerCreate接口获取 1058 expireTime [OUT] 类型#U32 *，定时器的剩余的超时时间，共享和私有硬件定时器单位us，软件定时器单位ms 1059 【注意事项】 1060 软件定时器单位毫秒，核内和全局硬件定时器单位微秒。 1061 由于OS内部软件定时器采用Tick作为计时单位，硬件定时器采用Cycle作为计时单位， 1062 1063#### 3.1.12 内存基本功能 1064##### 3.1.12.1 向已创建的指定分区申请内存 1065 【接口原型】 1066 void *PRT_MemAlloc(U32 mid, U8 ptNo, uintptr_t size) 1067 【功能描述】 1068 <li>在分区号为ptNo的分区中，申请大小为size的内存。</li> 1069 【返回值】 1070 #NULL 0，申请失败。 1071 #!NULL 内存首地址值。 1072 【参数说明】 1073 mid [IN] 类型#U32，申请的模块号。 1074 ptNo [IN] 类型#U8，分区号，范围[0,#OS_MEM_MAX_PT_NUM+2)，当前未使用，选择默认分区。 1075 size [IN] 类型#uintptr_t，申请的大小。 1076 【注意事项】 1077 申请内存时的分区号，根据实际创建的分区号来使用。 1078 调用函数后，注意判断返回的地址是否为空以避免后续访问空指针。 1079 对于FSC内存算法，申请到的内存首地址是按4字节对齐的 1080 如果内存申请失败，返回值为NULL，而导致失败的原因将记录在错误处理空间中。 1081 1082##### 3.1.12.2 释放申请的内存 1083 【接口原型】 1084 U32 PRT_MemFree(U32 mid, void *addr) 1085 【功能描述】 1086 该接口根据内存块的地址addr，找到该内存块所属的内存分区，再根据分区号和用户使用的地址addr释放该内存。 1087 【返回值】 1088 #OS_OK 0x00000000，内存释放成功。 1089 #其它值，释放失败。 1090 【参数说明】 1091 mid [IN] 类型#U32，要释放的模块号。 1092 addr [IN] 类型#void *，释放的地址。 1093 【注意事项】 1094 如果返回值不是#OS_OK，则内存不会被释放。 1095 被破坏的内存不能被释放。 1096 对于入参addr，OS已做基本校验，无法校验所有非法地址，其合法性由业务保证。 1097 1098#### 3.1.13 CPU占用率模块 1099##### 3.1.13.1 获取当前cpu占用率 1100 【接口原型】 1101 U32 PRT_CpupNow(void) 1102 【功能描述】 1103 通过本接口获取当前cpu占用率。 1104 【返回值】 1105 #0xffffffff 获取失败，CPUP裁剪开关未打开，或未初始化，或者在osStart之前调用。 1106 #[0,10000] 返回当前cpu占用率。 1107 【参数说明】 1108 无。 1109 【注意事项】 1110 该接口必须在CPUP模块裁剪开关打开，并在osStart之后才能调用此接口，否则返回0xffffffff。 1111 精度为万分之一。 1112 为了减小CPUP统计对线程调度的性能影响，OS采用了基于IDLE计数的统计算法， 1113 1114##### 3.1.13.2 获取指定个数的线程的CPU占用率 1115 【接口原型】 1116 U32 PRT_CpupThread(U32 inNum, struct CpupThread *cpup, U32 *outNum) 1117 【功能描述】 1118 根据用户输入的线程个数，获取指定个数的线程CPU占用率。 1119 【返回值】 1120 #OS_OK 0x00000000，获取成功。 1121 #其它值，获取失败。 1122 【参数说明】 1123 inNum [IN] 类型#U32，输入的线程个数。 1124 cpup [OUT] 类型#struct CpupThread *，缓冲区，输出参数，用于填写输出个数线程的CPUP信息。 1125 outNum [OUT] 类型#U32 *，保存输出的实际线程个数指针。 1126 【注意事项】 1127 当且仅当CPUP模式配置为线程级时，该接口有效。 1128 当配置项中的采样周期值等于0时，线程级CPUP采样周期为两次调用该接口或者PRT_CpupNow之间 1129 输出的实际线程个数不大于系统中实际的线程个数(任务个数和一个中断线程)。 1130 若输入的线程个数为1，则仅输出中断线程(除任务线程以外的线程统称)的CPUP信息。 1131 若在一个采样周期内有任务被删除，则统计的任务线程和中断线程CPUP总和小于10000。 1132 1133##### 3.1.13.3 设置CPU占用率告警阈值 1134 【接口原型】 1135 U32 PRT_CpupSetWarnValue(U32 warn, U32 resume) 1136 【功能描述】 1137 根据用户配置的CPU占用率告警阈值warn和告警恢复阈值resume，设置告警和恢复阈值。 1138 【返回值】 1139 #OS_OK 0x00000000，阈值设定成功。 1140 #其它值，阈值设定失败。 1141 【参数说明】 1142 warn [IN] 类型#U32，CPUP告警阈值。 1143 resume [IN] 类型#U32，CPUP恢复阈值。 1144 【注意事项】 1145 OsStart之前不能调用此接口。 1146 1147##### 3.1.13.4 查询CPUP告警阈值和告警恢复阈值 1148 【接口原型】 1149 U32 PRT_CpupGetWarnValue(U32 *warn, U32 *resume) 1150 【功能描述】 1151 根据用户配置的告警阈值指针warn和告警恢复阈值指针resume，查询告警阈值和告警恢复阈值 1152 【返回值】 1153 #OS_OK 0x00000000，获取成功。 1154 #其它值，获取失败。 1155 【参数说明】 1156 warn [OUT] 类型#U32 *，CPUP告警阈值。 1157 resume [OUT] 类型#U32 *，CPUP恢复阈值。 1158 【注意事项】 1159 OsStart之前不能调用此接口。 1160 1161##### 3.1.13.5 注册CPUP告警回调函数 1162 【接口原型】 1163 U32 PRT_CpupRegWarnHook(CpupHookFunc hook) 1164 【功能描述】 1165 根据用户配置的回调函数hook，注册CPUP告警回调函数 1166 【返回值】 1167 #OS_OK 0x00000000，注册成功。 1168 #其它值，注册失败。 1169 【参数说明】 1170 hook [IN] 类型#CpupHookFunc，CPU告警回调函数。 1171 【注意事项】 1172 不允许重复或覆盖注册钩子。 1173 hook为NULL时，表示删除该钩子。 1174 1175#### 3.1.14 错误处理 1176##### 3.1.14.1 处理错误 1177 【接口原型】 1178 U32 PRT_ErrHandle(const char *fileName, U32 lineNo, U32 errorNo, U32 paraLen, void *para) 1179 【功能描述】 1180 用户或者OS内部使用该函数回调#PRT_ErrRegHook中注册的钩子函数。另外，OS内部使用此接口时，还会记录相关错误码。 1181 【返回值】 1182 #OS_OK 0x00000000，处理错误成功。 1183 【参数说明】 1184 fileName [IN] 类型#const char *，错误发生的文件名，可以用__FILE__作为输入。 1185 lineNo [IN] 类型#U32，错误发生所在的行号，可以用__LINE__作为输入。 1186 errorNo [IN] 类型#U32，用户输入的错误码。 1187 paraLen [IN] 类型#U32，入参para的长度。 1188 para [OUT] 类型#void *，记录用户对于错误的描述或其他(地址)。 1189 【注意事项】 1190 系统不会做入参检测，用户PRT_ErrHandle会全部当做钩子入参输入。 1191 用户调用PRT_ErrHandle接口时，只会回调用户注册钩子函数，不会进行错误码记录 1192 1193##### 3.1.14.2 注册用户错误处理的钩子函数 1194 【接口原型】 1195 U32 PRT_ErrRegHook(ErrHandleFunc hook) 1196 【功能描述】 1197 注册hook作为用户钩子函数，在调用PRT_ErrHandle接口进行错误处理时对该钩子进行调用。 1198 【返回值】 1199 #OS_OK 0x00000000，注册成功。 1200 #其它值，注册失败。 1201 【参数说明】 1202 hook [IN] 类型#ErrHandleFunc，用户钩子函数的宏定义。 1203 【注意事项】 1204 若入参hook为NULL,则为取消钩子。 1205 不允许重复或覆盖注册。 1206 用户定义的钩子函数必须符合#PRT_ERRORHANDLE_FUNC定义的形式，而且只能定义一个钩子函数。 1207 用户调用PRT_ErrRegHook注册回调钩子函数时，钩子函数里面不能有调用PRT_ErrHandle 1208 用户调用PRT_ErrRegHook注册回调钩子函数时，钩子函数里面如有单次上报的错误信息（只有第一次调用会执行） 1209 1210### 3.2 config接口 1211 【接口原型】 1212 OS_SYS_CLOCK 1213 【功能描述】 1214 芯片主频 1215 【接口原型】 1216 OS_HWI_MAX_NUM_CONFIG 1217 【功能描述】 1218 硬中断最大支持个数 1219 【接口原型】 1220 OS_INCLUDE_TICK 1221 【功能描述】 1222 Tick中断模块裁剪开关 1223 【接口原型】 1224 OS_TICK_PER_SECOND 1225 【功能描述】 1226 Tick中断时间间隔，tick处理时间不能超过1/OS_TICK_PER_SECOND(s) 1227 【接口原型】 1228 OS_INCLUDE_TICK_SWTMER 1229 【功能描述】 1230 基于TICK的软件定时器裁剪开关 1231 【接口原型】 1232 OS_TICK_SWITIMER_MAX_NUM 1233 【功能描述】 1234 基于TICK的软件定时器最大个数 1235 【接口原型】 1236 OS_INCLUDE_TASK 1237 【功能描述】 1238 任务模块裁剪开关 1239 【接口原型】 1240 OS_TSK_MAX_SUPPORT_NUM 1241 【功能描述】 1242 最大支持的任务数,最大共支持254个 1243 【接口原型】 1244 OS_TSK_DEFAULT_STACK_SIZE 1245 【功能描述】 1246 缺省的任务栈大小 1247 【接口原型】 1248 OS_TSK_IDLE_STACK_SIZE 1249 【功能描述】 1250 IDLE任务栈的大小 1251 【接口原型】 1252 OS_TSK_STACK_MAGIC_WORD 1253 【功能描述】 1254 任务栈初始化魔术字，默认是0xCA，只支持配置一个字节 1255 【接口原型】 1256 OS_INCLUDE_CPUP 1257 【功能描述】 1258 CPU占用率模块裁剪开关 1259 【接口原型】 1260 OS_CPUP_SAMPLE_INTERVAL 1261 【功能描述】 1262 采样时间间隔(单位tick)，若其值大于0，则作为采样周期，否则两次调用PRT_CpupNow或PRT_CpupThread间隔作为周期 1263 【接口原型】 1264 OS_CONFIG_CPUP_WARN 1265 【功能描述】 1266 CPU占用率告警动态配置项 1267 【接口原型】 1268 OS_CPUP_SHORT_WARN 1269 【功能描述】 1270 CPU占用率告警阈值(精度为万分比) 1271 【接口原型】 1272 OS_CPUP_SHORT_RESUME 1273 【功能描述】 1274 CPU占用率告警恢复阈值(精度为万分比) 1275 【接口原型】 1276 OS_MEM_MAX_PT_NUM 1277 【功能描述】 1278 用户可以创建的最大分区数，取值范围[0,253] 1279 【接口原型】 1280 OS_MEM_FSC_PT_ADDR 1281 【功能描述】 1282 私有FSC内存分区起始地址 1283 【接口原型】 1284 OS_MEM_FSC_PT_SIZE 1285 【功能描述】 1286 私有FSC内存分区大小 1287 【接口原型】 1288 OS_INCLUDE_SEM 1289 【功能描述】 1290 信号量模块裁剪开关 1291 【接口原型】 1292 OS_SEM_MAX_SUPPORT_NUM 1293 【功能描述】 1294 最大支持的信号量数 1295 【接口原型】 1296 OS_INCLUDE_QUEUE 1297 【功能描述】 1298 队列模块裁剪开关 1299 【接口原型】 1300 OS_QUEUE_MAX_SUPPORT_NUM 1301 【功能描述】 1302 最大支持的队列数,范围(0,0xFFFF] 1303 【接口原型】 1304 OS_HOOK_HWI_ENTRY_NUM 1305 【功能描述】 1306 硬中断进入钩子最大支持个数, 范围[0, 255] 1307 【接口原型】 1308 OS_HOOK_HWI_EXIT_NUM 1309 【功能描述】 1310 硬中断退出钩子最大支持个数, 范围[0, 255] 1311 【接口原型】 1312 OS_HOOK_TSK_SWITCH_NUM 1313 【功能描述】 1314 任务切换钩子最大支持个数, 范围[0, 255] 1315 【接口原型】 1316 OS_HOOK_IDLE_NUM 1317 【功能描述】 1318 IDLE钩子最大支持个数, 范围[0, 255] 1319