begriffs open source - cmsis/blob - CMSIS/DoxyGen/Core_A/src/Ref_IRQCtrl.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== IRQ Controller API ====
   3 /**
   4 \defgroup irq_ctrl_gr Interrupts and Exceptions
   5 \brief Generic functions to access the Interrupt Controller.
   6
   7 \details This section describes the device agnostic interrupt API viable for a wide range of specific interrupt controllers.
   8 The IRQ Controller API allows interrupt dependend applications to be easily portable across a wide range of controllers.
   9
  10 \note The default implementation for \ref GIC_functions "Arm GIC (Generic Interrupt Controller)" can be found in \ref irq_ctrl_gic.c.
  11 It uses \c weak functions thus it can easily be overwritten by an alternative user implementation if needed.
  12
  13 The Armv7-A architecture defines a common set of first level exceptions, see table below.
  14
  15 | Exception                     | CMSIS Handler | Offset | Description                                                                 |
  16 |-------------------------------|---------------|--------|-----------------------------------------------------------------------------|
  17 | Reset                         | Reset_Handler | 0x0000 | First instruction executed after reset.                                     |
  18 | Undefined Instruction (Undef) | Undef_Handler | 0x0004 | Signals usage of an illegal instructions.                                   |
  19 | Supervisor Call (SVC)         | SVC_Handler   | 0x0008 | Issued by software using SVC instruction.                                   |
  20 | Prefetch Abort (PAbt)         | PAbt_Handler  | 0x000C | Signals a memory abort on istruction fetch.                                 |
  21 | Data Abort (DAbt)             | DAbt_Handler  | 0x0010 | Signals a memory abort on data read or write.                               |
  22 | Hyp Trap                      | (NOP)         | 0x0014 | Hypervisor instruction trap, only available with Virtualization Extensions. |
  23 | IRQ interrupt                 | IRQ_Handler   | 0x0018 | Interrupt Request (typically from Interrupt Controller)                     |
  24 | FIQ interrupt                 | FIQ_Handler   | 0x001C | Fast Interrupt Request (typically from Interrupt Controller)                |
  25
  26 By default those handlers are defined as weak empty functions by the \ref startup_c_sec "device specific startup code".
  27 Software and peripheral interrupts are all handled by one of the both central interrupt handlers (IRQ and FIQ). These needs to
  28 be implemented application specific. If an RTOS is used the interrupt handlers are typically provided by the RTOS, e.g. when using
  29 <a href="../../RTOS2/html/rtx5_impl.html">RTX5</a>.
  30
  31 The interrupts available depends on the actual device in use. According to CMSIS specification the interrupts are defined in \ref IRQn_Type in \ref device_h_pg. Using the generic IRQ API one can easily enable and disable interrupts, set up priorities, modes  and preemption rules, and register interrupt callbacks.
  32
  33 \b Example:
  34
  35 \code
  36 void SGI0_Handler() {
  37   /*
  38    * Handle Interrupt
  39    */
  40
  41   IRQ_ClearPending((IRQn_ID_t)SGI0_IRQn);
  42 }
  43
  44 void main() {
  45   /* Initialize the Interrupt Controller */
  46   IRQ_Initialize();
  47
  48   /* Register the user defined handler function */
  49   IRQ_SetHandler((IRQn_ID_t)SGI0_IRQn, SGI0_Handler);
  50
  51   /* Set the priority considering the priority grouping */
  52   const uint32_t subprio = IRQ_GetPriorityGroupBits();
  53   IRQ_SetPriority((IRQn_ID_t)SGI0_IRQn, 1u << subprio);
  54
  55   /* Set interrupt mode to falling edge */
  56   IRQ_SetMode((IRQn_ID_t)SGI0_IRQn, IRQ_MODE_TYPE_IRQ | IRQ_MODE_CPU_0 | IRQ_MODE_TRIG_EDGE | IRQ_MODE_TRIG_EDGE_FALLING);
  57
  58   IRQ_Enable((IRQn_ID_t)SGI0_IRQn);
  59
  60   /* Trigger interrupt */
  61   IRQ_SetPending((IRQn_ID_t)SGI0_IRQn);
  62
  63   IRQ_Disable((IRQn_ID_t)SGI0_IRQn);
  64 }
  65 \endcode
  66
  67 @{
  68 */
  69 /**************************************************************************************************/
  70 /** \brief  Definition of IRQn numbers
  71
  72
  73 The core exception enumeration names for IRQn values are defined in the \ref device_h_pg.
  74
  75 The table below describes the core exception names in Cortex-A core.
  76 */
  77
  78 typedef enum IRQn
  79 {
  80 /******  Cortex-A Specific Interrupt Numbers    **************************/
  81   /* Software Generated Interrupts */
  82   SGI0_IRQn                          =  0,  ///< Software Generated Interrupt  0
  83   SGI1_IRQn                          =  1,  ///< Software Generated Interrupt  1
  84   SGI2_IRQn                          =  2,  ///< Software Generated Interrupt  2
  85   SGI3_IRQn                          =  3,  ///< Software Generated Interrupt  3
  86   SGI4_IRQn                          =  4,  ///< Software Generated Interrupt  4
  87   SGI5_IRQn                          =  5,  ///< Software Generated Interrupt  5
  88   SGI6_IRQn                          =  6,  ///< Software Generated Interrupt  6
  89   SGI7_IRQn                          =  7,  ///< Software Generated Interrupt  7
  90   SGI8_IRQn                          =  8,  ///< Software Generated Interrupt  8
  91   SGI9_IRQn                          =  9,  ///< Software Generated Interrupt  9
  92   SGI10_IRQn                         = 10,  ///< Software Generated Interrupt 10
  93   SGI11_IRQn                         = 11,  ///< Software Generated Interrupt 11
  94   SGI12_IRQn                         = 12,  ///< Software Generated Interrupt 12
  95   SGI13_IRQn                         = 13,  ///< Software Generated Interrupt 13
  96   SGI14_IRQn                         = 14,  ///< Software Generated Interrupt 14
  97   SGI15_IRQn                         = 15,  ///< Software Generated Interrupt 15
  98
  99   VirtualMaintenanceInterrupt_IRQn   = 25,  ///< Virtual Maintenance Interrupt
 100   HypervisorTimer_IRQn               = 26,  ///< Hypervisor Timer Interrupt
 101   VirtualTimer_IRQn                  = 27,  ///< Virtual Timer Interrupt
 102   Legacy_nFIQ_IRQn                   = 28,  ///< Legacy nFIQ Interrupt
 103   SecurePhyTimer_IRQn                = 29,  ///< Secure Physical Timer Interrupt
 104   NonSecurePhyTimer_IRQn             = 30,  ///< Non-Secure Physical Timer Interrupt
 105   Legacy_nIRQ_IRQn                   = 31,  ///< Legacy nIRQ Interrupt
 106
 107  } IRQn_Type;
 108
 109 /**
 110 \defgroup irq_mode_defs IRQ Mode Bit-Masks
 111 \brief Configure interrupt line mode
 112 \details
 113 @{
 114 The following codes are used as values for the parameter \em mode of the function \ref IRQ_SetMode to configure interrupt line mode.
 115 They are also returned by the function \ref IRQ_GetMode when retrieving interrupt line mode.
 116
 117 The values of \b IRQ_MODE_TRIG_x definitions specify
 118 The values of \b IRQ_MODE_TYPE_x definitions specify
 119 The values of \b IRQ_MODE_DOMAIN_x definitions specify
 120 The values of \b IRQ_MODE_CPU_x definitions specify
 121
 122 // Interrupt mode bit-masks
 123 \def IRQ_MODE_TRIG_LEVEL
 124 \def IRQ_MODE_TRIG_LEVEL_LOW
 125 \def IRQ_MODE_TRIG_LEVEL_HIGH
 126 \def IRQ_MODE_TRIG_EDGE
 127 \def IRQ_MODE_TRIG_EDGE_RISING
 128 \def IRQ_MODE_TRIG_EDGE_FALLING
 129 \def IRQ_MODE_TRIG_EDGE_BOTH
 130
 131 \def IRQ_MODE_TYPE_IRQ
 132 \def IRQ_MODE_TYPE_FIQ
 133
 134 \def IRQ_MODE_DOMAIN_NONSECURE
 135 \def IRQ_MODE_DOMAIN_SECURE
 136
 137 \def IRQ_MODE_CPU_ALL
 138 \def IRQ_MODE_CPU_0
 139 \def IRQ_MODE_CPU_1
 140 \def IRQ_MODE_CPU_2
 141 \def IRQ_MODE_CPU_3
 142 \def IRQ_MODE_CPU_4
 143 \def IRQ_MODE_CPU_5
 144 \def IRQ_MODE_CPU_6
 145 \def IRQ_MODE_CPU_7
 146
 147 \def IRQ_MODE_ERROR
 148 @}
 149 */
 150
 151 /**
 152 \defgroup irq_priority_defs IRQ Priority Bit-Masks
 153 \brief Definitions used by interrupt priority functions.
 154 \details
 155 @{
 156 The following values are used by the interrupt priority functions.
 157
 158 The value of \b IRQ_PRIORITY_Msk specifies maximum interrupt priority value and can be used as parameter for the functions
 159 \ref IRQ_GetPriority and \ref IRQ_SetPriorityGroupBits to retrieve implementation specific priority values.
 160
 161 The value of \b IRQ_PRIORITY_ERROR is used by functions \ref IRQ_GetPriority, IRQ_GetPriorityMask and \ref IRQ_GetPriorityGroupBits
 162 to signal function execution error.
 163
 164 \def IRQ_PRIORITY_Msk
 165 \def IRQ_PRIORITY_ERROR
 166 @}
 167 */
 168
 169 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 170 /**
 171 \fn int32_t IRQ_Initialize (void)
 172 \details This function initializes interrupt controller.
 173
 174 It disables all interrupt sources, clears all pending interrupts, sets interrupt priorities to highest priority and
 175 configures priority mask to lowest priority. IRQ and FIQ signal lines should be enabled and all interrupt handlers should
 176 be set to NULL.
 177
 178 For Arm GIC the default implementation looks like the following example:
 179
 180 \code
 181 /// Number of implemented interrupt lines
 182 #ifndef IRQ_GIC_LINE_COUNT
 183 #define IRQ_GIC_LINE_COUNT      (1020U)
 184 #endif
 185
 186 static IRQHandler IRQTable[IRQ_GIC_LINE_COUNT] = { 0U };
 187
 188 int32_t IRQ_Initialize (void) {
 189   uint32_t i;
 190
 191   for (i = 0U; i < IRQ_GIC_LINE_COUNT; i++) {
 192     IRQTable[i] = (IRQHandler)NULL;
 193   }
 194   GIC_Enable();
 195   return (0);
 196 }
 197 \endcode
 198 */
 199
 200 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 201 /**
 202 \fn int32_t IRQ_SetHandler (IRQn_ID_t irqn, IRQHandler_t handler)
 203 \details This function registers address of the interrupt handler callback function corresponding to the specified interrupt
 204 ID number.
 205
 206 For Arm GIC the default implementation looks like the following example:
 207
 208 \code
 209 int32_t IRQ_SetHandler (IRQn_ID_t irqn, IRQHandler_t handler) {
 210   int32_t status;
 211
 212   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 213     IRQTable[irqn] = handler;
 214     status =  0;
 215   } else {
 216     status = -1;
 217   }
 218
 219   return (status);
 220 }
 221 \endcode
 222 */
 223
 224 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 225 /**
 226 \fn IRQHandler_t IRQ_GetHandler (IRQn_ID_t irqn)
 227 \details This function retrieves address of the interrupt handler callback function corresponding to the specified interrupt
 228 ID number.
 229
 230 For Arm GIC the default implementation looks like the following example:
 231
 232 \code
 233 IRQHandler_t IRQ_GetHandler (IRQn_ID_t irqn) {
 234   IRQHandler h;
 235
 236   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 237     h = IRQTable[irqn];
 238   } else {
 239     h = (IRQHandler_t)0;
 240   }
 241
 242   return (h);
 243 }
 244 \endcode
 245 */
 246
 247 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 248 /**
 249 \fn int32_t IRQ_Enable (IRQn_ID_t irqn)
 250 \details This function enables forwarding of the corresponding interrupt to the CPU.
 251
 252 For Arm GIC the default implementation looks like the following example:
 253
 254 \code
 255 int32_t IRQ_Enable (IRQn_ID_t irqn) {
 256   int32_t status;
 257
 258   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 259     GIC_EnableIRQ ((IRQn_Type)irqn);
 260     status = 0;
 261   } else {
 262     status = -1;
 263   }
 264
 265   return (status);
 266 }
 267 \endcode
 268 */
 269
 270 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 271 /**
 272 \fn int32_t IRQ_Disable (IRQn_ID_t irqn)
 273 \details This function disables forwarding of the corresponding interrupt to the CPU.
 274
 275 For Arm GIC the default implementation looks like the following example:
 276
 277 \code
 278 int32_t IRQ_Disable (IRQn_ID_t irqn) {
 279   int32_t status;
 280
 281   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 282     GIC_DisableIRQ ((IRQn_Type)irqn);
 283     status = 0;
 284   } else {
 285     status = -1;
 286   }
 287
 288   return (status);
 289 }
 290 \endcode
 291 */
 292
 293 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 294 /**
 295 \fn uint32_t IRQ_GetEnableState (IRQn_ID_t irqn)
 296 \details This function retrieves the interrupt enable status of the interrupt identified by the irqn parameter.
 297
 298 Interrupt enable status can be either disabled (0) or enabled (1). Disabled status is returned for interrupts
 299 which cannot be identified by irqn.
 300
 301 For Arm GIC the default implementation looks like the following example:
 302
 303 \code
 304 uint32_t IRQ_GetEnableState (IRQn_ID_t irqn) {
 305   uint32_t enable;
 306
 307   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 308     enable = GIC_GetEnableIRQ((IRQn_Type)irqn);
 309   } else {
 310     enable = 0U;
 311   }
 312
 313   return (enable);
 314 }
 315 \endcode
 316 */
 317
 318 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 319 /**
 320 \fn int32_t IRQ_SetMode (IRQn_ID_t irqn, uint32_t mode)
 321
 322 \details This function configures the interrupt triggering mode, type, secure access and target CPUs of the interrupt
 323 (see \ref irq_mode_defs) identified by the irqn parameter.
 324
 325 For Arm GIC the default implementation looks like the following example:
 326
 327 \code
 328 int32_t IRQ_SetMode (IRQn_ID_t irqn, uint32_t mode) {
 329   int32_t status;
 330   uint32_t val;
 331   uint8_t cfg;
 332   uint8_t secure;
 333   uint8_t cpu;
 334
 335   status = 0;
 336
 337   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 338     // Check triggering mode
 339     val = (mode & IRQ_MODE_TRIG_Msk);
 340
 341     if (val == IRQ_MODE_TRIG_LEVEL) {
 342       cfg = 0x00U;
 343     } else if (val == IRQ_MODE_TRIG_EDGE) {
 344       cfg = 0x02U;
 345     } else {
 346       status = -1;
 347     }
 348
 349     // Check interrupt type
 350     val = mode & IRQ_MODE_TYPE_Msk;
 351
 352     if (val != IRQ_MODE_TYPE_IRQ) {
 353       status = -1;
 354     }
 355
 356     // Check interrupt domain
 357     val = mode & IRQ_MODE_DOMAIN_Msk;
 358
 359     if (val == IRQ_MODE_DOMAIN_NONSECURE) {
 360       secure = 0;
 361     } else {
 362       // Check security extensions support
 363       val = GIC_DistributorInfo() & (1UL << 10U);
 364
 365       if (val != 0U) {
 366         // Security extensions are supported
 367         secure = 1;
 368       } else {
 369         status = -1;
 370       }
 371     }
 372
 373     // Check interrupt CPU targets
 374     val = mode & IRQ_MODE_CPU_Msk;
 375
 376     if (val == IRQ_MODE_CPU_ALL) {
 377       cpu = 0xFF;
 378     } else {
 379       cpu = val >> IRQ_MODE_CPU_Pos;
 380     }
 381
 382     // Apply configuration if no mode error
 383     if (status == 0) {
 384       GIC_SetConfiguration((IRQn_Type)irqn, cfg);
 385       GIC_SetTarget       ((IRQn_Type)irqn, cpu);
 386
 387       if (secure != 0U) {
 388         GIC_SetGroup ((IRQn_Type)irqn, secure);
 389       }
 390     }
 391   }
 392
 393   return (status);
 394 }
 395 \endcode
 396 */
 397
 398 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 399 /**
 400 \fn uint32_t IRQ_GetMode (IRQn_ID_t irqn)
 401 \details This function retrieves interrupt mode configuration of the interrupt identified by the irqn parameter.
 402 \ref IRQ_MODE_ERROR is returned for interrupts which cannot be identified by irqn.
 403
 404 For Arm GIC the default implementation looks like the following example:
 405
 406 \code
 407 uint32_t IRQ_GetMode (IRQn_ID_t irqn) {
 408   uint32_t mode;
 409   uint32_t val;
 410
 411   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 412     mode = IRQ_MODE_TYPE_IRQ;
 413
 414     // Get trigger mode
 415     val = GIC_GetConfiguration((IRQn_Type)irqn);
 416
 417     if ((val & 2U) != 0U) {
 418       // Corresponding interrupt is edge triggered
 419       mode |= IRQ_MODE_TRIG_EDGE;
 420     } else {
 421       // Corresponding interrupt is level triggered
 422       mode |= IRQ_MODE_TRIG_LEVEL;
 423     }
 424
 425     // Get interrupt CPU targets
 426     mode |= GIC_GetTarget ((IRQn_Type)irqn) << IRQ_MODE_CPU_Pos;
 427
 428   } else {
 429     mode = IRQ_MODE_ERROR;
 430   }
 431
 432   return (mode);
 433 }
 434 \endcode
 435 */
 436
 437 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 438 /**
 439 \fn IRQn_ID_t IRQ_GetActiveIRQ (void)
 440 \details This function retrieves the interrupt ID number of current IRQ source and acknowledges the interrupt.
 441
 442 For Arm GIC the default implementation looks like the following example:
 443
 444 \code
 445 IRQn_ID_t IRQ_GetActiveIRQ (void) {
 446   IRQn_ID_t irqn;
 447
 448   irqn = (IRQn_ID_t)GIC_AcknowledgePending();
 449
 450   return (irqn);
 451 }
 452 \endcode
 453 */
 454
 455 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 456 /**
 457 \fn IRQn_ID_t IRQ_GetActiveFIQ (void)
 458 \details This function retrieves the interrupt ID number of current FIQ source and acknowledges the interrupt.
 459
 460 For Arm GIC the default implementation looks like the following example:
 461
 462 \code
 463 IRQn_ID_t IRQ_GetActiveFIQ (void) {
 464   // FIQ is not supported, return invalid ID
 465   return ((IRQn_ID_t)-1);
 466 }
 467 \endcode
 468 */
 469
 470 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 471 /**
 472 \fn int32_t IRQ_EndOfInterrupt (IRQn_ID_t irqn)
 473 \details This function informs the interrupt controller that the interrupt service routine processing of the currently
 474 active interrupt request is completed.
 475
 476 The parameter irqn should specify the value previously returned by the \ref IRQ_GetActiveIRQ or \ref IRQ_GetActiveFIQ functions.
 477
 478 For Arm GIC the default implementation looks like the following example:
 479
 480 \code
 481 int32_t IRQ_EndOfInterrupt (IRQn_ID_t irqn) {
 482   int32_t status;
 483
 484   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 485     GIC_EndInterrupt ((IRQn_Type)irqn);
 486
 487     if (irqn == 0) {
 488       IRQ_ID0 = 0U;
 489     }
 490
 491     status = 0;
 492   } else {
 493     status = -1;
 494   }
 495
 496   return (status);
 497 }
 498 \endcode
 499 */
 500
 501 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 502 /**
 503 \fn int32_t IRQ_SetPending (IRQn_ID_t irqn)
 504 \details This function sets the pending status of the interrupt identified by the irqn parameter.
 505
 506 For Arm GIC the default implementation looks like the following example:
 507
 508 \code
 509 int32_t IRQ_SetPending (IRQn_ID_t irqn) {
 510   int32_t status;
 511
 512   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 513     GIC_SetPendingIRQ ((IRQn_Type)irqn);
 514     status = 0;
 515   } else {
 516     status = -1;
 517   }
 518
 519   return (status);
 520 }
 521 \endcode
 522 */
 523
 524 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 525 /**
 526 \fn uint32_t IRQ_GetPending (IRQn_ID_t irqn)
 527 \details This function retrieves the pending status of the interrupt identified by the irqn parameter.
 528
 529 Interrupt pending status can be either not pending (0) or pending (1). Not pending status is returned for interrupts which
 530 cannot be identified by irqn.
 531
 532 For Arm GIC the default implementation looks like the following example:
 533
 534 \code
 535 uint32_t IRQ_GetPending (IRQn_ID_t irqn) {
 536   uint32_t pending;
 537
 538   if ((irqn >= 16) && (irqn < IRQ_GIC_LINE_COUNT)) {
 539     pending = GIC_GetPendingIRQ ((IRQn_Type)irqn);
 540   } else {
 541     pending = 0U;
 542   }
 543
 544   return (pending & 1U);
 545 }
 546 \endcode
 547 */
 548
 549 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 550 /**
 551 \fn int32_t IRQ_ClearPending (IRQn_ID_t irqn)
 552 \details This function clears the pending status of the interrupt identified by the irqn parameter.
 553
 554 For Arm GIC the default implementation looks like the following example:
 555
 556 \code
 557 int32_t IRQ_ClearPending (IRQn_ID_t irqn) {
 558   int32_t status;
 559
 560   if ((irqn >= 16) && (irqn < IRQ_GIC_LINE_COUNT)) {
 561     GIC_ClearPendingIRQ ((IRQn_Type)irqn);
 562     status = 0;
 563   } else {
 564     status = -1;
 565   }
 566
 567   return (status);
 568 }
 569 \endcode
 570 */
 571
 572 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 573 /**
 574 \fn int32_t IRQ_SetPriority (IRQn_ID_t irqn, uint32_t priority)
 575 \details This function sets the priority of the interrupt identified by the irqn parameter.
 576
 577 Higher priority numbers have lower priority. The highest interrupt priority has priority value 0, while the lowest value
 578 depends on the number of implemented priority levels.
 579
 580 The number of implemented priority bits can be determined by setting value \ref IRQ_PRIORITY_Msk to arbitrary irqn and by
 581 retrieving the actual stored value with IRQ_GetPriority function.
 582
 583 For Arm GIC the default implementation looks like the following example:
 584
 585 \code
 586 int32_t IRQ_SetPriority (IRQn_ID_t irqn, uint32_t priority) {
 587   int32_t status;
 588
 589   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 590     GIC_SetPriority ((IRQn_Type)irqn, priority);
 591     status = 0;
 592   } else {
 593     status = -1;
 594   }
 595
 596   return (status);
 597 }
 598 \endcode
 599 */
 600
 601 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 602 /**
 603 \fn uint32_t IRQ_GetPriority (IRQn_ID_t irqn)
 604 \details This function retrieves the priority of the interrupt identified by the irqn parameter.
 605
 606 The valid priority value can be from zero (0) to the value of \ref IRQ_PRIORITY_Msk. \ref IRQ_PRIORITY_ERROR bit is set in
 607 returned value for interrupts which cannot be identified by irqn.
 608
 609 For Arm GIC the default implementation looks like the following example:
 610
 611 \code
 612 uint32_t IRQ_GetPriority (IRQn_ID_t irqn) {
 613   uint32_t priority;
 614
 615   if ((irqn >= 0) && (irqn < IRQ_GIC_LINE_COUNT)) {
 616     priority = GIC_GetPriority ((IRQn_Type)irqn);
 617   } else {
 618     priority = IRQ_PRIORITY_ERROR;
 619   }
 620
 621   return (priority);
 622 }
 623 \endcode
 624 */
 625
 626 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 627 /**
 628 \fn int32_t IRQ_SetPriorityMask (uint32_t priority)
 629 \details This function sets the priority masking threshold for the current processor.
 630
 631 It ensures that only interrupts with a higher priority than priority threshold value are signaled to the target processor.
 632 Function returns error status -1 if priority masking is not supported.
 633
 634 For Arm GIC the default implementation looks like the following example:
 635
 636 \code
 637 IRQ_SetPriorityMask (uint32_t priority) {
 638   GIC_SetInterfacePriorityMask (priority);
 639   return (0);
 640 }
 641 \endcode
 642 */
 643
 644 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 645 /**
 646 \fn uint32_t IRQ_GetPriorityMask (void)
 647 \details This function retrieves the priority masking threshold for the current processor.
 648
 649 \ref IRQ_PRIORITY_ERROR value is returned if priority masking is not supported.
 650
 651 For Arm GIC the default implementation looks like the following example:
 652
 653 \code
 654 uint32_t IRQ_GetPriorityMask (void) {
 655   return GIC_GetInterfacePriorityMask();
 656 }
 657 \endcode
 658 */
 659
 660 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 661 /**
 662 \fn int32_t IRQ_SetPriorityGroupBits (uint32_t bits)
 663 \details This function sets the number of MSB priority bits used to determine whether a pending interrupt has sufficient
 664 priority to preempt a currently active interrupt.
 665
 666 The number of implemented group priority bits can be determined by setting value \ref IRQ_PRIORITY_Msk and by retrieving the
 667 actual stored value with \ref IRQ_GetPriorityGroupBits function.
 668 Function returns error status -1 if priority grouping is not supported.
 669
 670 For Arm GIC the default implementation looks like the following example:
 671
 672 \code
 673 int32_t IRQ_SetPriorityGroupBits (uint32_t bits) {
 674   int32_t status;
 675
 676   if (bits == IRQ_PRIORITY_Msk) {
 677     bits = 7U;
 678   }
 679
 680   if (bits < 8U) {
 681     GIC_SetBinaryPoint (7U - bits);
 682     status = 0;
 683   } else {
 684     status = -1;
 685   }
 686
 687   return (status);
 688 }
 689 \endcode
 690 */
 691
 692 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 693 /**
 694 \fn uint32_t IRQ_GetPriorityGroupBits (void)
 695 \details This function retrieves the number of MSB bits used to determine whether a pending interrupt has sufficient
 696 priority to preempt a currently active interrupt.
 697
 698 \ref IRQ_PRIORITY_ERROR value is returned when priority grouping is not supported.
 699
 700 For Arm GIC the default implementation looks like the following example:
 701
 702 \code
 703 uint32_t IRQ_GetPriorityGroupBits (void) {
 704   uint32_t bp;
 705
 706   bp = GIC_GetBinaryPoint() & 0x07U;
 707
 708   return (7U - bp);
 709 }
 710 \endcode
 711 */
 712
 713 /** @} */ /* group irq_ctrl_gr */