LUFA/Platform/UC3/InterruptManagement.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2012.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2012  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief Interrupt Controller Driver for the AVR32 UC3 microcontrollers.
  33  *
  34  *  Interrupt controller driver for the AVR32 UC3 microcontrollers, for the configuration of interrupt
  35  *  handlers within the device.
  36  */
  37
  38 /** \ingroup Group_PlatformDrivers_UC3
  39  *  \defgroup Group_PlatformDrivers_UC3Interrupts Interrupt Controller Driver - LUFA/Platform/UC3/InterruptManagement.h
  40  *  \brief Interrupt Controller Driver for the AVR32 UC3 microcontrollers.
  41  *
  42  *  \section Sec_Dependencies Module Source Dependencies
  43  *  The following files must be built with any user project that uses this module:
  44  *    - LUFA/Platform/UC3/InterruptManagement.c <i>(Makefile source module name: LUFA_SRC_PLATFORM)</i>
  45  *    - LUFA/Platform/UC3/Exception.S <i>(Makefile source module name: LUFA_SRC_PLATFORM)</i>
  46  *
  47  *  \section Sec_ModDescription Module Description
  48  *  Interrupt controller driver for the AVR32 UC3 microcontrollers, for the configuration of interrupt
  49  *  handlers within the device.
  50  *
  51  *  Usage Example:
  52  *  \code
  53  *              #include <LUFA/Platform/UC3/InterruptManagement.h>
  54  *
  55  *              ISR(USB_Group_IRQ_Handler)
  56  *              {
  57  *                      // USB group handler code here
  58  *              }
  59  *
  60  *              void main(void)
  61  *              {
  62  *                      INTC_Init();
  63  *                      INTC_RegisterGroupHandler(INTC_IRQ_GROUP(AVR32_USBB_IRQ), AVR32_INTC_INT0, USB_Group_IRQ_Handler);
  64  *              }
  65  *  \endcode
  66  *
  67  *  @{
  68  */
  69
  70 #ifndef _UC3_INTERRUPT_MANAGEMENT_H_
  71 #define _UC3_INTERRUPT_MANAGEMENT_H_
  72
  73         /* Includes: */
  74                 #include <LUFA/Common/Common.h>
  75
  76         /* Enable C linkage for C++ Compilers: */
  77                 #if defined(__cplusplus)
  78                         extern "C" {
  79                 #endif
  80
  81         /* Private Interface - For use in library only: */
  82         #if !defined(__DOXYGEN__)
  83                 /* Type Defines: */
  84                         typedef void (*InterruptHandlerPtr_t)(void);
  85
  86                 /* External Variables: */
  87                         #if defined(__INCLUDE_FROM_INTMANAGEMENT_C)
  88                                 extern const void        EVBA_Table;
  89                         #endif
  90                         extern InterruptHandlerPtr_t InterruptHandlers[AVR32_INTC_NUM_INT_GRPS];
  91                         extern const uint32_t        Autovector_Table[];
  92         #endif
  93
  94         /* Public Interface - May be used in end-application: */
  95                 /* Macros: */
  96                         /** Converts a given interrupt index into its associated interrupt group.
  97                          *
  98                          *  \param[in] IRQIndex  Index of the interrupt request to convert.
  99                          *
 100                          *  \return Interrupt group number associated with the interrupt index.
 101                          */
 102                         #define INTC_IRQ_GROUP(IRQIndex)  (IRQIndex / 32)
 103
 104                         /** Converts a given interrupt index into its associated interrupt line.
 105                          *
 106                          *  \param[in] IRQIndex  Index of the interrupt request to convert.
 107                          *
 108                          *  \return Interrupt line number associated with the interrupt index.
 109                          */
 110                         #define INTC_IRQ_LINE(IRQIndex)   (IRQIndex % 32)
 111
 112                 /* Function Prototypes: */
 113                         /** Initializes the interrupt controller, nulling out all interrupt handlers ready for new registration. This
 114                          *  function should be called once on startup to ensure the interrupt controller is ready for use.
 115                          */
 116                         void INTC_Init(void);
 117
 118                 /* Inline Functions: */
 119                         /** Registers a handler for a given interrupt group. On the AVR32 UC3 devices, interrupts are grouped by
 120                          *  peripheral. To save on SRAM used, a single ISR handles all interrupt lines within a single group - to
 121                          *  determine the exact line that has interrupted within the group ISR handler, use \ref INTC_GetGroupInterrupts().
 122                          *
 123                          *  If multiple interrupts with the same group are registered, the last registered handler will become the
 124                          *  handler called for interrupts raised within that group.
 125                          *
 126                          *  To obtain the group number of a specific interrupt index, use the \ref INTC_IRQ_GROUP() macro.
 127                          *
 128                          *  \param[in] GroupNumber       Group number of the interrupt group to register a handler for.
 129                          *  \param[in] InterruptLevel    Priority level for the specified interrupt, a \c AVR32_INTC_INT* mask.
 130                          *  \param[in] Handler           Address of the ISR handler for the interrupt group.
 131                          */
 132                         static inline void INTC_RegisterGroupHandler(const uint16_t GroupNumber,
 133                                                                      const uint8_t InterruptLevel,
 134                                                                      const InterruptHandlerPtr_t Handler) ATTR_ALWAYS_INLINE;
 135                         static inline void INTC_RegisterGroupHandler(const uint16_t GroupNumber,
 136                                                                      const uint8_t InterruptLevel,
 137                                                                      const InterruptHandlerPtr_t Handler)
 138                         {
 139                                 InterruptHandlers[GroupNumber] = Handler;
 140                                 AVR32_INTC.ipr[GroupNumber]    = Autovector_Table[InterruptLevel];
 141                         }
 142
 143                         /** Retrieves the pending interrupts for a given interrupt group. The result of this function should be masked
 144                          *  against interrupt request indexes converted to a request line number via the \ref INTC_IRQ_LINE() macro. To
 145                          *  obtain the group number of a given interrupt request, use the \ref INTC_IRQ_GROUP() macro.
 146                          *
 147                          *  \param[in] GroupNumber Group number of the interrupt group to check.
 148                          *
 149                          *  \return Mask of pending interrupt lines for the given interrupt group.
 150                          */
 151                         static inline uint_reg_t INTC_GetGroupInterrupts(const uint16_t GroupNumber) ATTR_ALWAYS_INLINE;
 152                         static inline uint_reg_t INTC_GetGroupInterrupts(const uint16_t GroupNumber)
 153                         {
 154                                 return AVR32_INTC.irr[GroupNumber];
 155                         }
 156
 157         /* Disable C linkage for C++ Compilers: */
 158                 #if defined(__cplusplus)
 159                         }
 160                 #endif
 161
 162 #endif
 163
 164 /** @} */
 165