LUFA/Platform/XMEGA/ClockManagement.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  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 Module Clock Driver for the AVR USB XMEGA microcontrollers.
  33  *
  34  *  Clock management driver for the AVR USB XMEGA microcontrollers. This driver allows for the configuration
  35  *  of the various clocks within the device to clock the various peripherals.
  36  */
  37
  38 /** \ingroup Group_PlatformDrivers
  39  *  \defgroup Group_PlatformDrivers_XMEGAClocks AVR USB XMEGA Clock Management Driver - LUFA/Platform/XMEGA/ClockManagement.h
  40  *  \brief Module Clock Driver for the AVR USB XMEGA 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  *    - None
  45  *
  46  *  \section Sec_ModDescription Module Description
  47  *  Clock management driver for the AVR USB XMEGA microcontrollers. This driver allows for the configuration
  48  *  of the various clocks within the device to clock the various peripherals.
  49  *
  50  *  Usage Example:
  51  *  \code
  52  *              #include <LUFA/Platform/XMEGA/ClockManagement.h>
  53  *
  54  *              void main(void)
  55  *              {
  56  *                      [TODO]
  57  *              }
  58  *  \endcode
  59  *
  60  *  @{
  61  */
  62
  63 #ifndef _XMEGA_CLOCK_MANAGEMENT_H_
  64 #define _XMEGA_CLOCK_MANAGEMENT_H_
  65
  66         /* Includes: */
  67                 #include <LUFA/Common/Common.h>
  68
  69         /* Enable C linkage for C++ Compilers: */
  70                 #if defined(__cplusplus)
  71                         extern "C" {
  72                 #endif
  73
  74         /* Public Interface - May be used in end-application: */
  75                 /* Macros: */
  76                         /** Enum for the possible external oscillator types. */
  77                         enum XMEGA_Extern_OSC_ClockTypes_t
  78                         {
  79                                 EXOSC_MODE_2MHZ_MAX      = OSC_FRQRANGE_04TO2_gc,  /**< External crystal oscillator equal to or slower than 2MHz. */
  80                                 EXOSC_MODE_9MHZ_MAX      = OSC_FRQRANGE_2TO9_gc,   /**< External crystal oscillator equal to or slower than 9MHz. */
  81                                 EXOSC_MODE_12MHZ_MAX     = OSC_FRQRANGE_9TO12_gc,  /**< External crystal oscillator equal to or slower than 12MHz. */
  82                                 EXOSC_MODE_16MHZ_MAX     = OSC_FRQRANGE_12TO16_gc, /**< External crystal oscillator equal to or slower than 16MHz. */
  83                         };
  84
  85                         /** Enum for the possible external oscillator statup times. */
  86                         enum XMEGA_Extern_OSC_ClockStartup_t
  87                         {
  88                                 EXOSC_START_6CLK         = OSC_XOSCSEL_EXTCLK_gc,      /**< Wait 6 clock cycles before startup (external clock). */
  89                                 EXOSC_START_32KCLK       = OSC_XOSCSEL_32KHz_gc,       /**< Wait 32K clock cycles before startup (32.768KHz crystal). */
  90                                 EXOSC_START_256CLK       = OSC_XOSCSEL_XTAL_256CLK_gc, /**< Wait 256 clock cycles before startup. */
  91                                 EXOSC_START_1KCLK        = OSC_XOSCSEL_XTAL_1KCLK_gc,  /**< Wait 1K clock cycles before startup. */
  92                                 EXOSC_START_16KCLK       = OSC_XOSCSEL_XTAL_16KCLK_gc, /**< Wait 16K clock cycles before startup. */
  93                         };
  94
  95                         /** Enum for the possible module clock sources. */
  96                         enum XMEGA_System_ClockSource_t
  97                         {
  98                                 CLOCK_SRC_INT_RC2MHZ    = 0, /**< Clock sourced from the Internal 2MHz RC Oscillator clock. */
  99                                 CLOCK_SRC_INT_RC32MHZ   = 1, /**< Clock sourced from the Internal 32MHz RC Oscillator clock. */
 100                                 CLOCK_SRC_INT_RC32KHZ   = 2, /**< Clock sourced from the Internal 32KHz RC Oscillator clock. */
 101                                 CLOCK_SRC_XOSC          = 3, /**< Clock sourced from the External Oscillator clock. */
 102                                 CLOCK_SRC_PLL           = 4, /**< Clock sourced from the Internal PLL clock. */
 103                         };
 104
 105                 /* Inline Functions: */
 106                         /** Starts the given external oscillator of the UC3 microcontroller, with the given options. This routine blocks until
 107                          *  the oscillator is ready for use.
 108                          *
 109                          *  \param[in] Channel  Index of the external oscillator to start.
 110                          *  \param[in] Type     Type of clock attached to the given oscillator channel, a value from \ref XMEGA_Extern_OSC_ClockTypes_t.
 111                          *  \param[in] Startup  Statup time of the external oscillator, a value from \ref XMEGA_Extern_OSC_ClockStartup_t.
 112                          *
 113                          *  \return Boolean \c true if the external oscillator was successfully started, \c false if invalid parameters specified.
 114                          */
 115                         static inline uint8_t AVR32CLK_StartExternalOscillator(const uint8_t Channel,
 116                                                                                const uint8_t Type,
 117                                                                                const uint8_t Startup) ATTR_ALWAYS_INLINE;
 118                         static inline uint8_t AVR32CLK_StartExternalOscillator(const uint8_t Channel,
 119                                                                                const uint8_t Type,
 120                                                                                const uint8_t Startup)
 121                         {
 122                                 return false; // TODO
 123                         }
 124
 125                         /** Stops the given external oscillator of the UC3 microcontroller.
 126                          *
 127                          *  \param[in] Channel  Index of the external oscillator to stop.
 128                          */
 129                         static inline void AVR32CLK_StopExternalOscillator(const uint8_t Channel) ATTR_ALWAYS_INLINE;
 130                         static inline void AVR32CLK_StopExternalOscillator(const uint8_t Channel)
 131                         {
 132                                 return; // TODO
 133                         }
 134
 135                         /** Starts the given PLL of the UC3 microcontroller, with the given options. This routine blocks until the PLL is ready for use.
 136                          *
 137                          *  \param[in] Channel     Index of the PLL to start.
 138                          *  \param[in] Source      Clock source for the PLL, a value from \ref XMEGA_System_ClockSource_t.
 139                          *  \param[in] SourceFreq  Frequency of the PLL's clock source, in Hz.
 140                          *  \param[in] Frequency   Target frequency of the PLL's output.
 141                          *
 142                          *  \return Boolean \c true if the PLL was successfully started, \c false if invalid parameters specified.
 143                          */
 144                         static inline bool AVR32CLK_StartPLL(const uint8_t Channel,
 145                                                              const uint8_t Source,
 146                                                              const uint32_t SourceFreq,
 147                                                              const uint32_t Frequency) ATTR_ALWAYS_INLINE;
 148                         static inline bool AVR32CLK_StartPLL(const uint8_t Channel,
 149                                                              const uint8_t Source,
 150                                                              const uint32_t SourceFreq,
 151                                                              const uint32_t Frequency)
 152                         {
 153                                 return false; // TODO
 154                         }
 155
 156                         /** Stops the given PLL of the UC3 microcontroller.
 157                          *
 158                          *  \param[in] Channel  Index of the PLL to stop.
 159                          */
 160                         static inline void AVR32CLK_StopPLL(const uint8_t Channel) ATTR_ALWAYS_INLINE;
 161                         static inline void AVR32CLK_StopPLL(const uint8_t Channel)
 162                         {
 163                                 // TODO
 164                         }
 165
 166                         /** Starts the given Generic Clock of the UC3 microcontroller, with the given options.
 167                          *
 168                          *  \param[in] Channel     Index of the Generic Clock to start.
 169                          *  \param[in] Source      Clock source for the Generic Clock, a value from \ref XMEGA_System_ClockSource_t.
 170                          *  \param[in] SourceFreq  Frequency of the Generic Clock's clock source, in Hz.
 171                          *  \param[in] Frequency   Target frequency of the Generic Clock's output.
 172                          *
 173                          *  \return Boolean \c true if the Generic Clock was successfully started, \c false if invalid parameters specified.
 174                          */
 175                         static inline bool AVR32CLK_StartGenericClock(const uint8_t Channel,
 176                                                                       const uint8_t Source,
 177                                                                       const uint32_t SourceFreq,
 178                                                                       const uint32_t Frequency) ATTR_ALWAYS_INLINE;
 179                         static inline bool AVR32CLK_StartGenericClock(const uint8_t Channel,
 180                                                                       const uint8_t Source,
 181                                                                       const uint32_t SourceFreq,
 182                                                                       const uint32_t Frequency)
 183                         {
 184                                 return false; // TODO
 185                         }
 186
 187                         /** Stops the given generic clock of the UC3 microcontroller.
 188                          *
 189                          *  \param[in] Channel  Index of the generic clock to stop.
 190                          */
 191                         static inline void AVR32CLK_StopGenericClock(const uint8_t Channel) ATTR_ALWAYS_INLINE;
 192                         static inline void AVR32CLK_StopGenericClock(const uint8_t Channel)
 193                         {
 194                                 // TODO
 195                         }
 196
 197                         /** Sets the clock source for the main microcontroller core. The given clock source should be configured
 198                          *  and ready for use before this function is called.
 199                          *
 200                          *  This function will configure the FLASH controller's wait states automatically to suit the given clock source.
 201                          *
 202                          *  \param[in] Source      Clock source for the CPU core, a value from \ref XMEGA_System_ClockSource_t.
 203                          *  \param[in] SourceFreq  Frequency of the CPU core's clock source, in Hz.
 204                          *
 205                          *  \return Boolean \c true if the CPU core clock was sucessfully altered, \c false if invalid parameters specified.
 206                          */
 207                         static inline bool AVR32CLK_SetCPUClockSource(const uint8_t Source,
 208                                                                       const uint32_t SourceFreq) ATTR_ALWAYS_INLINE;
 209                         static inline bool AVR32CLK_SetCPUClockSource(const uint8_t Source,
 210                                                                       const uint32_t SourceFreq)
 211                         {
 212                                 return false // TODO
 213                         }
 214
 215         /* Disable C linkage for C++ Compilers: */
 216                 #if defined(__cplusplus)
 217                         }
 218                 #endif
 219
 220 #endif
 221
 222 /** @} */