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_HWI_H 16 #define PRT_HWI_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 * 硬中断错误码：中断号非法。 29 * 30 * 值: 0x02000801 31 * 32 * 解决方案：确保中断号合法，中断号请查看硬件手册。 33 */ 34 #define OS_ERRNO_HWI_NUM_INVALID OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x01) 35 36 /* 37 * 硬中断错误码：优先级非法。 38 * 39 * 值: 0x02000802 40 * 41 * 解决方案：确保优先级合法。 42 */ 43 #define OS_ERRNO_HWI_PRI_ERROR OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x02) 44 45 /* 46 * 硬中断错误码：硬中断已被创建或相应中断向量号已被其它中断占用。 47 * 48 * 值: 0x02000803 49 * 50 * 解决方案：更换中断号 51 */ 52 #define OS_ERRNO_HWI_ALREADY_CREATED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x03) 53 54 /* 55 * 硬中断错误码：硬中断处理函数为空。 56 * 57 * 值: 0x02000804 58 * 59 * 解决方案：传入非空的有效处理函数 60 */ 61 #define OS_ERRNO_HWI_PROC_FUNC_NULL OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x04) 62 63 /* 64 * 硬中断错误码：未创建的硬中断被响应。 65 * 66 * 值: 0x03000805 67 * 68 * 解决方案：先创建硬中断，然后使能并触发该中断使其得到响应 69 */ 70 #define OS_ERRNO_HWI_UNCREATED OS_ERRNO_BUILD_FATAL(OS_MID_HWI, 0x05) 71 72 /* 73 * 硬中断错误码：设置硬中断属性时，属性设置与之前设置值不一致 74 * 75 * 值: 0x02000806 76 * 77 * 解决方案：确认当前设置属性值与之前是否一致。如果确需修改属性，请先删除该硬中断。 78 */ 79 #define OS_ERRNO_HWI_ATTR_CONFLICTED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x06) 80 81 /* 82 * 硬中断错误码：组合型中断创建失败，为组合型中断节点申请系统默认私有FSC内存失败，或申请中断描述信息失败。 83 * 84 * 值: 0x02000807 85 * 86 * 解决方案: 增大系统默认私有FSC分区大小 87 */ 88 #define OS_ERRNO_HWI_MEMORY_ALLOC_FAILED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x07) 89 90 /* 91 * 硬中断错误码：组合型中断函数注册失败，该组合型中断已创建了相同的中断处理函数。 92 * 93 * 值: 0x02000808 94 * 95 * 解决方案: 更换中断处理函数 96 */ 97 #define OS_ERRNO_HWI_COMBINEHOOK_ALREADY_CREATED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x08) 98 99 /* 100 * 硬中断错误码：创建的中断函数即不是独立型，也不是组合型 101 * 102 * 值: 0x02000809 103 * 104 * 解决方案: 硬中断模式只能设置为独立型或组合型 105 */ 106 #define OS_ERRNO_HWI_MODE_ERROR OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x09) 107 108 /* 109 * 硬中断错误码：删除未创建或者已经被删除的硬中断。 110 * 111 * 值: 0x0200080a 112 * 113 * 解决方案: 删除已创建并且未被删除的硬中断 114 */ 115 #define OS_ERRNO_HWI_DELETED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x0a) 116 117 /* 118 * 硬中断错误码：未进行硬中断模式设置。 119 * 120 * 值: 0x0200080b 121 * 122 * 解决方案: 调用中断创建函数前，需要先调用中断模式设置函数，进行模式参数设置 123 */ 124 #define OS_ERRNO_HWI_MODE_UNSET OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x0b) 125 126 /* 127 * 硬中断错误码：硬中断触发接口入参错误，输入无效的核号。 128 * 129 * 值: 0x0200080c 130 * 131 * 解决方案: 输入本核核号 132 */ 133 #define OS_ERRNO_HWI_CORE_ID_INVALID OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x0c) 134 135 /* 136 * 系统基本功能错误码：注册不可删除的中断失败 137 * 138 * 值: 0x0300141c 139 * 140 * 解决方案: 请确保传是独立型中断，或者修改OS_HWI_INTERNAL_NUM值 141 */ 142 #define OS_ERROR_HWI_INT_REGISTER_FAILED OS_ERRNO_BUILD_FATAL(OS_MID_HWI, 0x1c) 143 144 /* 145 * 硬中断错误码：中断内存资源申请失败 146 * 147 * 值: 0x0200080d 148 * 149 * 解决方案: 检查默认分区大小配置是否正确 150 */ 151 #define OS_ERRNO_HWI_RESOURCE_ALLOC_FAILED OS_ERRNO_BUILD_ERROR(OS_MID_HWI, 0x0d) 152 153 /* 154 * 硬中断优先级的类型定义。 155 */ 156 typedef U16 HwiPrior; 157 158 /* 159 * 硬中断模式配置信息的类型定义。 160 */ 161 typedef U16 HwiMode; 162 163 /* 164 * 硬中断处理函数的参数类型定义。 165 */ 166 typedef uintptr_t HwiArg; 167 168 /* 169 * 硬中断号的类型定义。 170 */ 171 typedef U32 HwiHandle; 172 173 /* 174 * 组合型硬中断。 175 */ 176 #define OS_HWI_MODE_COMBINE 0x8000 177 178 /* 179 * 独立型硬中断。 180 */ 181 #define OS_HWI_MODE_ENGROSS 0x4000 182 183 /* 184 * 缺省硬中断模式。 185 */ 186 #define OS_HWI_MODE_DEFAULT OS_HWI_MODE_ENGROSS 187 188 /* 189 * 普通硬中断。 190 */ 191 #define OS_HWI_TYPE_NORMAL 0x00 192 193 /* 194 * 中断属性组装宏(共8bit)。 195 */ 196 #define OS_HWI_ATTR(mode, type) (HwiMode)((HwiMode)(mode) | (HwiMode)(type)) 197 198 /* 199 * @brief 硬中断处理函数的类型定义。 200 * 201 * @par 描述 202 * 通过硬中断处理函数的类型定义硬中断处理函数，在硬中断触发时调用该中断处理函数。 203 * 204 * @attention 无。 205 * 206 * @param param1 [IN] 类型#HwiArg，硬中断处理函数的参数。 207 * 208 * @retval 无。 209 * @par 依赖 210 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 211 * @see 无。 212 */ 213 typedef void (*HwiProcFunc)(HwiArg); 214 215 /* 216 * @brief 硬中断调用处理函数钩子函数类型定义。 217 * 218 * @par 描述 219 * 用户通过硬中断调用钩子处理函数类型定义硬中断调用处理函数钩子，在硬中断调用处理函数时，调用该钩子。 220 * @attention 无。 221 * 222 * @param hwiNum [IN] 类型#U32，硬中断号。 223 * 224 * @retval 无。 225 * @par 依赖 226 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 227 */ 228 typedef void (*HwiEntryHook)(U32 hwiNum); 229 230 /* 231 * @brief 硬中断退出处理函数钩子函数类型定义。 232 * 233 * @par 描述 234 * 用户通过硬中断退出钩子处理函数类型定义硬中断退出处理函数钩子，在硬中断退出处理函数时，调用该钩子。 235 * @attention 无。 236 * 237 * @param hwiNum [IN] 类型#U32，硬中断号。 238 * 239 * @retval 无。 240 * @par 依赖 241 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 242 */ 243 typedef void (*HwiExitHook)(U32 hwiNum); 244 245 /* 246 * @brief 设置硬中断属性接口。 247 * 248 * @par 描述 249 * 在创建硬中断前，必须要配置好硬中断的优先级和模式，包括独立型（#OS_HWI_MODE_ENGROSS）和 250 * 组合型（#OS_HWI_MODE_COMBINE）两种配置模式。 251 * 252 * @attention 253 * <ul> 254 * <li>OS已经占用的不能被使用</li> 255 * </ul> 256 * 257 * @param hwiNum [IN] 类型#HwiHandle，硬中断号。 258 * @param hwiPrio [IN] 类型#HwiPrior，硬中断优先级。 259 * @param mode [IN] 类型#HwiMode，设置的中断模式，为独立型(#OS_HWI_MODE_ENGROSS)或者组合型(#OS_HWI_MODE_COMBINE)。 260 * 261 * @retval #OS_OK 0x00000000，硬中断属性设置成功。 262 * @retval #其它值，属性设置失败。 263 * @par 依赖 264 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 265 * @see PRT_HwiCreate 266 */ 267 extern U32 PRT_HwiSetAttr(HwiHandle hwiNum, HwiPrior hwiPrio, HwiMode mode); 268 269 /* 270 * @brief 创建硬中断函数。 271 * 272 * @par 描述 273 * 注册硬中断的处理函数。 274 * 275 * @attention 276 * <ul> 277 * <li>在调用该函数之前，请先确保已经设置了中断属性。</li> 278 * <li>硬中断创建成功后，并不使能相应向量的中断，需要显式调用#PRT_HwiEnable单独使能。</li> 279 * </ul> 280 * 281 * @param hwiNum [IN] 类型#HwiHandle，硬中断号。 282 * @param handler [IN] 类型#HwiProcFunc，硬中断触发时的处理函数。 283 * @param arg [IN] 类型#HwiArg，调用硬中断处理函数时传递的参数。 284 * 285 * @retval #OS_OK 0x00000000，硬中断创建成功。 286 * @retval #其它值，创建失败。 287 * @par 依赖 288 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 289 * @see PRT_HwiDelete 290 */ 291 extern U32 PRT_HwiCreate(HwiHandle hwiNum, HwiProcFunc handler, HwiArg arg); 292 293 /* 294 * @brief 删除硬中断函数。 295 * 296 * @par 描述 297 * 屏蔽相应硬中断或事件，取消硬中断处理函数的注册。 298 * 299 * @attention 300 * <ul> 301 * <li>不能删除OS占用的中断号。</li> 302 * </ul> 303 * 304 * @param hwiNum [IN] 类型#HwiHandle，硬中断号。 305 * 306 * @retval #OS_OK 0x00000000，硬中断删除成功。 307 * @retval #其它值，删除失败。 308 * @par 依赖 309 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 310 * @see PRT_HwiCreate 311 */ 312 extern U32 PRT_HwiDelete(HwiHandle hwiNum); 313 314 /* 315 * @brief 激活指定核号内的硬中断。 316 * 317 * @par 描述 318 * 激活指定核号内的软件可触发的硬中断 319 * 320 * @attention 321 * 322 * @param dstCore [IN] 类型#U32，目标核号。目前只支持指定为本核。 323 * @param hwiNum [IN] 类型#HwiHandle，硬中断号，只支持软件可触发的中断号。 324 * 325 * @retval #OS_OK 0x00000000，硬中断激活成功。 326 * @retval #其它值，激活失败。 327 * @par 依赖 328 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 329 */ 330 extern U32 PRT_HwiTrigger(U32 dstCore, HwiHandle hwiNum); 331 332 /* 333 * @brief 清空中断请求位。 334 * 335 * @par 描述 336 * 清除所有的中断请求位。即放弃当前已触发中断的的响应。 337 * 338 * @attention 339 * <ul> 340 * 清除所有的中断请求位(对于NMI中断无效)。 341 * </ul> 342 * 343 * @param 无。 344 * 345 * @retval 无。 346 * @par 依赖 347 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 348 * @see PRT_HwiClearPendingBit 349 */ 350 extern void PRT_HwiClearAllPending(void); 351 352 /* 353 * @brief 清除硬中断的Pending位。 354 * 355 * @par 描述 356 * 显式清除硬中断或事件的请求位，因为有的硬件响应中断后不会自动清Pending位。 357 * 358 * @attention 359 * 360 * @param hwiNum [IN] 类型#HwiHandle，硬中断号。 361 * 362 * @retval #OS_OK 0x00000000，硬中断请求位清除成功。 363 * @retval #其它值，清除失败。 364 * @par 依赖 365 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 366 * @see PRT_HwiCreate 367 */ 368 extern U32 PRT_HwiClearPendingBit(HwiHandle hwiNum); 369 370 /* 371 * @brief 屏蔽指定的硬中断。 372 * 373 * @par 描述 374 * 禁止核响应指定硬中断的请求。 375 * 376 * @attention 377 * 378 * @param hwiNum [IN] 类型#HwiHandle，依据不同的芯片，硬中断号或中断向量号，见注意事项。 379 * 380 * @retval #OS_OK 0x00000000，硬中断去使能成功。 381 * @retval #其它值，硬中断去使能失败。 382 * @par 依赖 383 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 384 * @see PRT_HwiEnable 385 */ 386 extern U32 PRT_HwiDisable(HwiHandle hwiNum); 387 388 /* 389 * @brief 使能指定的硬中断。 390 * 391 * @par 描述 392 * 允许核响应指定硬中断的请求。 393 * 394 * @attention 395 * <ul> 396 * <li>对于不同芯片，此返回值代表的意义有所差异，差异细节见下面返回值说明</li> 397 * </ul> 398 * 399 * @param hwiNum [IN] 类型#HwiHandle，依据不同的芯片，硬中断号或中断向量号，见注意事项。 400 * 401 * @retval #OS_OK 0x00000000，硬中断使能成功。 402 * @retval #其它值，硬中断使能失败。 403 * @par 依赖 404 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 405 * @see PRT_HwiDisable 406 */ 407 extern U32 PRT_HwiEnable(HwiHandle hwiNum); 408 409 /* 410 * @brief 添加硬中断进入钩子 411 * 412 * @par 描述 413 * 添加硬中断进入钩子。该钩子函数在进入硬中断ISR前被调用。 414 * 415 * @attention 416 * <ul> 417 * <li>不同钩子函数间执行的先后顺序，不应当存在依赖关系。</li> 418 * <li>不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。</li> 419 * <li>最大支持钩子数需静态配置</li> 420 * </ul> 421 * 422 * @param hook [IN] 类型#HwiEntryHook，中断进入钩子函数。 423 * 424 * @par 依赖 425 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 426 * @see PRT_HwiDelEntryHook | PRT_HookAdd | PRT_HwiAddExitHook 427 */ 428 extern U32 PRT_HwiAddEntryHook(HwiEntryHook hook); 429 430 /* 431 * @brief 删除硬中断进入钩子 432 * 433 * @par 描述 434 * 删除硬中断进入钩子。该钩子函数将停止在进入硬中断ISR前的调用。 435 * 436 * @attention 437 * <ul> 438 * <li>不同钩子函数间执行的先后顺序，不应当存在依赖关系。</li> 439 * <li>不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。</li> 440 * <li>最大支持钩子数需静态配置</li> 441 * </ul> 442 * 443 * @param hook [IN] 类型#HwiEntryHook，中断进入钩子函数。 444 * 445 * @par 依赖 446 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 447 * @see PRT_HwiAddEntryHook | PRT_HookDel 448 */ 449 extern U32 PRT_HwiDelEntryHook(HwiEntryHook hook); 450 451 /* 452 * @brief 添加硬中断退出钩子 453 * 454 * @par 描述 455 * 添加硬中断退出钩子。该钩子函数在退出硬中断ISR后被调用。 456 * 457 * @attention 458 * <ul> 459 * <li>不同钩子函数间执行的先后顺序，不应当存在依赖关系。</li> 460 * <li>不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。</li> 461 * <li>最大支持钩子数需静态配置</li> 462 * </ul> 463 * 464 * @param hook [IN] 类型#HwiExitHook，中断退出钩子函数。 465 * 466 * @par 依赖 467 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 468 * @see PRT_HwiDelExitHook | PRT_HookAdd | PRT_HwiAddEntryHook 469 */ 470 extern U32 PRT_HwiAddExitHook(HwiExitHook hook); 471 472 /* 473 * @brief 删除硬中断退出钩子 474 * 475 * @par 描述 476 * 删除硬中断退出钩子。该钩子函数将停止在退出硬中断ISR后的调用。 477 * 478 * @attention 479 * <ul> 480 * <li>不同钩子函数间执行的先后顺序，不应当存在依赖关系。</li> 481 * <li>不应在钩子函数里调用可能引起线程调度或阻塞的OS接口。</li> 482 * <li>最大支持钩子数需静态配置</li> 483 * </ul> 484 * 485 * @param hook [IN] 类型#HwiExitHook，中断退出钩子函数。 486 * 487 * @par 依赖 488 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 489 * @see PRT_HwiAddExitHook | PRT_HookDel 490 */ 491 extern U32 PRT_HwiDelExitHook(HwiExitHook hook); 492 493 /* 494 * @brief 开中断。 495 * 496 * @par 描述 497 * 开启全局可屏蔽中断。 498 * 499 * @attention 中断服务函数里慎用该接口，会引起中断优先级反转 500 * 501 * @param 无。 502 * 503 * @retval 开启全局中断前的中断状态值。 504 * @par 依赖 505 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 506 * @see PRT_HwiLock | PRT_HwiRestore 507 */ 508 extern uintptr_t PRT_HwiUnLock(void); 509 510 /* 511 * @brief 关中断。 512 * 513 * @par 描述 514 * 关闭全局可屏蔽中断。 515 * 516 * @attention 在关全局中断后，禁止调用引起内核调度的相关接口，如PRT_TaskDelay接口 517 * 518 * @param 无。 519 * 520 * @retval 关闭全局中断前的中断状态值。 521 * @par 依赖 522 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 523 * @see PRT_HwiUnLock | PRT_HwiRestore 524 */ 525 extern uintptr_t PRT_HwiLock(void); 526 527 /* 528 * @brief 恢复中断状态接口。 529 * 530 * @par 描述 531 * 恢复原中断状态寄存器。 532 * 533 * @attention 534 * <ul> 535 * <li>该接口必须和关闭全局中断或者是开启全局中断接口成对使用，以关全局中断或者开全局中断操作的返回值为入参</li> 536 * <li>以保证中断可以恢复到关全局中断或者开全局中断操作前的状态</li> 537 * </ul> 538 * @param intSave [IN] 类型#uintptr_t，关全局中断PRT_HwiLock和开全局中断PRT_HwiUnLock的返回值。 539 * 540 * @retval 无 541 * @par 依赖 542 * <ul><li>prt_hwi.h：该接口声明所在的头文件。</li></ul> 543 * @see PRT_HwiUnLock | PRT_HwiLock 544 */ 545 extern void PRT_HwiRestore(uintptr_t intSave); 546 547 #ifdef __cplusplus 548 #if __cplusplus 549 } 550 #endif /* __cpluscplus */ 551 #endif /* __cpluscplus */ 552 553 #endif /* PRT_HWI_H */ 554