# Interrupt Module

The Interrupt API provides a set of functions for dealing with the Peripheral Interrupt Expansion (PIE) Controller as well as CPU-level interrupt configuration. Functions are provided to initialize interrupt-related registers, enable and disable interrupts, and register interrupt handlers.

Interrupt API functions rely on an interrupt number defined to specify which interrupt is being configured. These interrupt numbers are found in inc/hw_ints.h and are in the format INT_X. For example, INT_EPWM2_TZ would be used to specify the trip zone interrupt for EPWM2 wherever a function has an e interruptNumber parameter.

group `interrupt_api`

  Defines

  `INTERRUPT_CPU_INT1` 0x1U

    CPU Interrupt Number 1.

  `INTERRUPT_CPU_INT2` 0x2U

    CPU Interrupt Number 2.

  `INTERRUPT_CPU_INT3` 0x4U

    CPU Interrupt Number 3.

  `INTERRUPT_CPU_INT4` 0x8U

    CPU Interrupt Number 4.

  `INTERRUPT_CPU_INT5` 0x10U

    CPU Interrupt Number 5.

  `INTERRUPT_CPU_INT6` 0x20U

    CPU Interrupt Number 6.

  `INTERRUPT_CPU_INT7` 0x40U

    CPU Interrupt Number 7.

  `INTERRUPT_CPU_INT8` 0x80U

    CPU Interrupt Number 8.

  `INTERRUPT_CPU_INT9` 0x100U

    CPU Interrupt Number 9.

  `INTERRUPT_CPU_INT10` 0x200U

    CPU Interrupt Number 10.

  `INTERRUPT_CPU_INT11` 0x400U

    CPU Interrupt Number 11.

  `INTERRUPT_CPU_INT12` 0x800U

    CPU Interrupt Number 12.

  `INTERRUPT_CPU_INT13` 0x1000U

    CPU Interrupt Number 13.

  `INTERRUPT_CPU_INT14` 0x2000U

    CPU Interrupt Number 14.

  `INTERRUPT_CPU_DLOGINT` 0x4000U

    CPU Data Log Interrupt.

  `INTERRUPT_CPU_RTOSINT` 0x8000U

    CPU RTOS Interrupt.

  `INTERRUPT_ACK_GROUP1` 0x1U

    Acknowledge PIE Interrupt Group 1.

  `INTERRUPT_ACK_GROUP2` 0x2U

    Acknowledge PIE Interrupt Group 2.

  `INTERRUPT_ACK_GROUP3` 0x4U

    Acknowledge PIE Interrupt Group 3.

  `INTERRUPT_ACK_GROUP4` 0x8U

    Acknowledge PIE Interrupt Group 4.

  `INTERRUPT_ACK_GROUP5` 0x10U

    Acknowledge PIE Interrupt Group 5.

  `INTERRUPT_ACK_GROUP6` 0x20U

    Acknowledge PIE Interrupt Group 6.

  `INTERRUPT_ACK_GROUP7` 0x40U

    Acknowledge PIE Interrupt Group 7.

  `INTERRUPT_ACK_GROUP8` 0x80U

    Acknowledge PIE Interrupt Group 8.

  `INTERRUPT_ACK_GROUP9` 0x100U

    Acknowledge PIE Interrupt Group 9.

  `INTERRUPT_ACK_GROUP10` 0x200U

    Acknowledge PIE Interrupt Group 10.

  `INTERRUPT_ACK_GROUP11` 0x400U

    Acknowledge PIE Interrupt Group 11.

  `INTERRUPT_ACK_GROUP12` 0x800U

    Acknowledge PIE Interrupt Group 12.

  Functions

  void `Interrupt_defaultHandler`(void)
  void `Interrupt_illegalOperationHandler`(void)
  void `Interrupt_nmiHandler`(void)
  bool `Interrupt_enableMaster`(void)

    Allows the CPU to process interrupts.

    This function clears the global interrupt mask bit (INTM) in the CPU, allowing the processor to respond to interrupts.

    Return

      Returns true if interrupts were disabled when the function was called or false if they were initially enabled.

  bool `Interrupt_disableMaster`(void)

    Stops the CPU from processing interrupts.

    This function sets the global interrupt mask bit (INTM) in the CPU, preventing the processor from receiving maskable interrupts.

    Return

      Returns true if interrupts were already disabled when the function was called or false if they were initially enabled.

  void `Interrupt_register`(uint32_t interruptNumber, void (*handler)(void))

    Registers a function to be called when an interrupt occurs.

    This function is used to specify the handler function to be called when the given interrupt is asserted to the processor. When the interrupt occurs, if it is enabled (via

    Interrupt_enable()), the handler function will be called in interrupt context. Since the handler function can preempt other code, care must be taken to protect memory or peripherals that are accessed by the handler and other non-handler code.
    Parameters

      - `interruptNumber`: specifies the interrupt in question.

      - `handler`: is a pointer to the function to be called.

    The available interruptNumber values are supplied in `inc/hw_ints.h`.

    Note

      This function assumes that the PIE has been enabled. See Interrupt_initModule().

    Return

      None.

  void `Interrupt_unregister`(uint32_t interruptNumber)

    Unregisters the function to be called when an interrupt occurs.

    This function is used to indicate that a default handler

    Interrupt_defaultHandler() should be called when the given interrupt is asserted to the processor. Call Interrupt_disable() to disable the interrupt before calling this function.
    Parameters

      - `interruptNumber`: specifies the interrupt in question.

    The available interruptNumber values are supplied in `inc/hw_ints.h`.

    See

      Interrupt_register() for important information about registering interrupt handlers.

    Return

      None.

  void `Interrupt_enableInCPU`(uint16_t cpuInterrupt)

    Enables CPU interrupt channels

    This function enables the specified interrupts in the CPU. The

    cpuInterrupt parameter is a logical OR of the values INTERRUPT_CPU_INTx where x is the interrupt number between 1 and 14, INTERRUPT_CPU_DLOGINT, and INTERRUPT_CPU_RTOSINT.
    Parameters

      - `cpuInterrupt`: specifies the CPU interrupts to be enabled.

    Note

      Note that interrupts 1-12 correspond to the PIE groups with those same numbers.

    Return

      None.

  void `Interrupt_disableInCPU`(uint16_t cpuInterrupt)

    Disables CPU interrupt channels

    This function disables the specified interrupts in the CPU. The

    cpuInterrupt parameter is a logical OR of the values INTERRUPT_CPU_INTx where x is the interrupt number between 1 and 14, INTERRUPT_CPU_DLOGINT, and INTERRUPT_CPU_RTOSINT.
    Parameters

      - `cpuInterrupt`: specifies the CPU interrupts to be disabled.

    Note

      Note that interrupts 1-12 correspond to the PIE groups with those same numbers.

    Return

      None.

  void `Interrupt_clearACKGroup`(uint16_t group)

    Acknowledges PIE Interrupt Group

    The specified interrupt group is acknowledged and clears any interrupt flag within that respective group.

    Parameters

      - `group`: specifies the interrupt group to be acknowledged.

    The group parameter must be a logical OR of the following: INTERRUPT_ACK_GROUP1, INTERRUPT_ACK_GROUP2, INTERRUPT_ACK_GROUP3 INTERRUPT_ACK_GROUP4, INTERRUPT_ACK_GROUP5, INTERRUPT_ACK_GROUP6 INTERRUPT_ACK_GROUP7, INTERRUPT_ACK_GROUP8, INTERRUPT_ACK_GROUP9 INTERRUPT_ACK_GROUP10, INTERRUPT_ACK_GROUP11, INTERRUPT_ACK_GROUP12.

    Return

      None.

  void `Interrupt_enablePIE`(void)

    Enables the PIE block.

    This function enables the vector fetching for the peripheral interrupts by enabling the PIE block.

    Return

      None.

  void `Interrupt_disablePIE`(void)

    Disables the PIE block.

    This function disables the vector fetching for the peripheral interrupts by disabling the PIE block. PIEACK, PIEIFR, and PIEIER registers can be accessed even when the PIE block is disabled.

    Return

      None.

  void `Interrupt_initModule`(void)

    Initializes the PIE control registers by setting them to a known state.

    This function initializes the PIE control registers. After globally disabling interrupts and enabling the PIE, it clears all of the PIE interrupt enable bits and interrupt flags.

    Return

      None.

  void `Interrupt_initVectorTable`(void)

    Initializes the PIE vector table by setting all vectors to a default handler function.

    Return

      None.

  void `Interrupt_enable`(uint32_t interruptNumber)

    Enables an interrupt.

    The specified interrupt is enabled in the interrupt controller. Other enables for the interrupt (such as at the peripheral level) are unaffected by this function.

    Parameters

      - `interruptNumber`: specifies the interrupt to be enabled.

    The available interruptNumber values are supplied in `inc/hw_ints.h`.

    Return

      None.

  void `Interrupt_disable`(uint32_t interruptNumber)

    Disables an interrupt.

    The specified interrupt is disabled in the interrupt controller. Other enables for the interrupt (such as at the peripheral level) are unaffected by this function.

    Parameters

      - `interruptNumber`: specifies the interrupt to be disabled.

    The available interruptNumber values are supplied in `inc/hw_ints.h`.

    Return

      None.

  uint16_t `__disable_interrupts`(void)
  uint16_t `__enable_interrupts`(void)

The Interrupt API provides two functions to initialize the module, Interrupt_initModule() and Interrupt_initVectorTable(). The former puts the PIE registers and the interrupt-related registers in the CPU into a known state. It clears all flags, disables interrupts at all levels, and enables vector fetching from the PIE. The latter initializes the PIE Vector Table to a set of default handlers–Interrupt_nmiHandler() for non-maskable interrupts, Interrupt_illegalOperationHandler() for an ITRAP interrupt, and Interrupt_defaultHandler() for all others. These defaults are intended to help with debugging. They should be modified or replaced more appropriate ISRs by the user.

Each interrupt source can be individually enabled and disabled via Interrupt_enable() and Interrupt_disable(). These affect the interrupt both on the PIE and on the CPU’s IER register. The processor interrupt can be enabled and disabled via Interrupt_enableMaster() and Interrupt_disableMaster(); this does not affect the individual interrupt enable states. Masking of the processor interrupt can be utilized as a simple critical section (only NMI will interrupt the processor while the processor interrupt is disabled), though this will have adverse effects on the interrupt response time.

When an interrupt occurs, in order for further interrupts on its PIE group to be received, Interrupt_clearACKGroup() must be called. This is typically done at the end of the ISR.

The code for this module is contained in driverlib/interrupt.c, with driverlib/interrupt.h containing the API declarations for use by applications.