LUFA/Platform/XMEGA/ClockManagement.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 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_XMEGA
  39  *  \defgroup Group_PlatformDrivers_XMEGAClocks 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  *              // Start the PLL to multiply the 2MHz RC oscillator to 32MHz and switch the CPU core to run from it
  57  *              XMEGACLK_StartPLL(CLOCK_SRC_INT_RC2MHZ, 2000000, 32000000);
  58  *              XMEGACLK_SetCPUClockSource(CLOCK_SRC_PLL, F_CPU);
  59  *
  60  *              // Start the 32MHz internal RC oscillator and start the DFLL to increase it to 48MHz using the USB SOF as a reference
  61  *              XMEGACLK_StartInternalOscillator(CLOCK_SRC_INT_RC32MHZ);
  62  *              XMEGACLK_StartDFLL(CLOCK_SRC_INT_RC32MHZ, DFLL_REF_INT_USBSOF, 48000000);
  63  *      }
  64  *  \endcode
  65  *
  66  *  @{
  67  */
  68
  69 #ifndef _XMEGA_CLOCK_MANAGEMENT_H_
  70 #define _XMEGA_CLOCK_MANAGEMENT_H_
  71
  72         /* Includes: */
  73                 #include <LUFA/Common/Common.h>
  74
  75         /* Enable C linkage for C++ Compilers: */
  76                 #if defined(__cplusplus)
  77                         extern "C" {
  78                 #endif
  79
  80         /* Public Interface - May be used in end-application: */
  81                 /* Macros: */
  82                         /** Enum for the possible external oscillator frequency ranges. */
  83                         enum XMEGA_Extern_OSC_ClockFrequency_t
  84                         {
  85                                 EXOSC_FREQ_2MHZ_MAX      = OSC_FRQRANGE_04TO2_gc,  /**< External crystal oscillator equal to or slower than 2MHz. */
  86                                 EXOSC_FREQ_9MHZ_MAX      = OSC_FRQRANGE_2TO9_gc,   /**< External crystal oscillator equal to or slower than 9MHz. */
  87                                 EXOSC_FREQ_12MHZ_MAX     = OSC_FRQRANGE_9TO12_gc,  /**< External crystal oscillator equal to or slower than 12MHz. */
  88                                 EXOSC_FREQ_16MHZ_MAX     = OSC_FRQRANGE_12TO16_gc, /**< External crystal oscillator equal to or slower than 16MHz. */
  89                         };
  90
  91                         /** Enum for the possible external oscillator statup times. */
  92                         enum XMEGA_Extern_OSC_ClockStartup_t
  93                         {
  94                                 EXOSC_START_6CLK         = OSC_XOSCSEL_EXTCLK_gc,      /**< Wait 6 clock cycles before startup (external clock). */
  95                                 EXOSC_START_32KCLK       = OSC_XOSCSEL_32KHz_gc,       /**< Wait 32K clock cycles before startup (32.768KHz crystal). */
  96                                 EXOSC_START_256CLK       = OSC_XOSCSEL_XTAL_256CLK_gc, /**< Wait 256 clock cycles before startup. */
  97                                 EXOSC_START_1KCLK        = OSC_XOSCSEL_XTAL_1KCLK_gc,  /**< Wait 1K clock cycles before startup. */
  98                                 EXOSC_START_16KCLK       = OSC_XOSCSEL_XTAL_16KCLK_gc, /**< Wait 16K clock cycles before startup. */
  99                         };
 100
 101                         /** Enum for the possible module clock sources. */
 102                         enum XMEGA_System_ClockSource_t
 103                         {
 104                                 CLOCK_SRC_INT_RC2MHZ    = 0, /**< Clock sourced from the Internal 2MHz RC Oscillator clock. */
 105                                 CLOCK_SRC_INT_RC32MHZ   = 1, /**< Clock sourced from the Internal 32MHz RC Oscillator clock. */
 106                                 CLOCK_SRC_INT_RC32KHZ   = 2, /**< Clock sourced from the Internal 32KHz RC Oscillator clock. */
 107                                 CLOCK_SRC_XOSC          = 3, /**< Clock sourced from the External Oscillator clock. */
 108                                 CLOCK_SRC_PLL           = 4, /**< Clock sourced from the Internal PLL clock. */
 109                         };
 110
 111                         /** Enum for the possible DFLL clock reference sources. */
 112                         enum XMEGA_System_DFLLReference_t
 113                         {
 114                                 DFLL_REF_INT_RC32KHZ   = 0, /**< Reference clock sourced from the Internal 32KHz RC Oscillator clock. */
 115                                 DFLL_REF_EXT_RC32KHZ   = 1, /**< Reference clock sourced from the External 32KHz RC Oscillator clock connected to TOSC pins. */
 116                                 DFLL_REF_INT_USBSOF    = 2, /**< Reference clock sourced from the USB Start Of Frame packets. */
 117                         };
 118
 119                 /* Inline Functions: */
 120                         /** Starts the external oscillator of the XMEGA microcontroller, with the given options. This routine blocks until
 121                          *  the oscillator is ready for use.
 122                          *
 123                          *  \param[in] FreqRange  Frequency range of the external oscillator, a value from \ref XMEGA_Extern_OSC_ClockFrequency_t.
 124                          *  \param[in] Startup    Statup time of the external oscillator, a value from \ref XMEGA_Extern_OSC_ClockStartup_t.
 125                          *
 126                          *  \return Boolean \c true if the external oscillator was successfully started, \c false if invalid parameters specified.
 127                          */
 128                         static inline bool XMEGACLK_StartExternalOscillator(const uint8_t FreqRange,
 129                                                                             const uint8_t Startup) ATTR_ALWAYS_INLINE;
 130                         static inline bool XMEGACLK_StartExternalOscillator(const uint8_t FreqRange,
 131                                                                             const uint8_t Startup)
 132                         {
 133                                 OSC.XOSCCTRL  = (FreqRange | ((Startup == EXOSC_START_32KCLK) ? OSC_X32KLPM_bm : 0) | Startup);
 134                                 OSC.CTRL     |= OSC_XOSCEN_bm;
 135
 136                                 while (!(OSC.STATUS & OSC_XOSCRDY_bm));
 137                                 return true;
 138                         }
 139
 140                         /** Stops the external oscillator of the XMEGA microcontroller. */
 141                         static inline void XMEGACLK_StopExternalOscillator(void) ATTR_ALWAYS_INLINE;
 142                         static inline void XMEGACLK_StopExternalOscillator(void)
 143                         {
 144                                 OSC.CTRL     &= ~OSC_XOSCEN_bm;
 145                         }
 146
 147                         /** Starts the given internal oscillator of the XMEGA microcontroller, with the given options. This routine blocks until
 148                          *  the oscillator is ready for use.
 149                          *
 150                          *  \param[in] Source  Internal oscillator to start, a value from \ref XMEGA_System_ClockSource_t.
 151                          *
 152                          *  \return Boolean \c true if the internal oscillator was successfully started, \c false if invalid parameters specified.
 153                          */
 154                         static inline uint8_t XMEGACLK_StartInternalOscillator(const uint8_t Source) ATTR_ALWAYS_INLINE;
 155                         static inline uint8_t XMEGACLK_StartInternalOscillator(const uint8_t Source)
 156                         {
 157                                 switch (Source)
 158                                 {
 159                                         case CLOCK_SRC_INT_RC2MHZ:
 160                                                 OSC.CTRL |= OSC_RC2MEN_bm;
 161                                                 while (!(OSC.STATUS & OSC_RC2MRDY_bm));
 162                                                 return true;
 163                                         case CLOCK_SRC_INT_RC32MHZ:
 164                                                 OSC.CTRL |= OSC_RC32MEN_bm;
 165                                                 while (!(OSC.STATUS & OSC_RC32MRDY_bm));
 166                                                 return true;
 167                                         case CLOCK_SRC_INT_RC32KHZ:
 168                                                 OSC.CTRL |= OSC_RC32KEN_bm;
 169                                                 while (!(OSC.STATUS & OSC_RC32KRDY_bm));
 170                                                 return true;
 171                                 }
 172
 173                                 return false;
 174                         }
 175
 176                         /** Stops the given internal oscillator of the XMEGA microcontroller.
 177                          *
 178                          *  \param[in] Source  Internal oscillator to stop, a value from \ref XMEGA_System_ClockSource_t.
 179                          *
 180                          *  \return Boolean \c true if the internal oscillator was successfully stopped, \c false if invalid parameters specified.
 181                          */
 182                         static inline bool XMEGACLK_StopInternalOscillator(const uint8_t Source) ATTR_ALWAYS_INLINE;
 183                         static inline bool XMEGACLK_StopInternalOscillator(const uint8_t Source)
 184                         {
 185                                 switch (Source)
 186                                 {
 187                                         case CLOCK_SRC_INT_RC2MHZ:
 188                                                 OSC.CTRL &= ~OSC_RC2MEN_bm;
 189                                                 return true;
 190                                         case CLOCK_SRC_INT_RC32MHZ:
 191                                                 OSC.CTRL &= ~OSC_RC32MEN_bm;
 192                                                 return true;
 193                                         case CLOCK_SRC_INT_RC32KHZ:
 194                                                 OSC.CTRL &= ~OSC_RC32KEN_bm;
 195                                                 return true;
 196                                 }
 197
 198                                 return false;
 199                         }
 200
 201                         /** Starts the PLL of the XMEGA microcontroller, with the given options. This routine blocks until the PLL is ready for use.
 202                          *
 203                          *  \note The output frequency must be equal to or greater than the source frequency.
 204                          *
 205                          *  \param[in] Source       Clock source for the PLL, a value from \ref XMEGA_System_ClockSource_t.
 206                          *  \param[in] SourceFreq   Frequency of the PLL's clock source, in Hz.
 207                          *  \param[in] Frequency    Target frequency of the PLL's output.
 208                          *
 209                          *  \return Boolean \c true if the PLL was successfully started, \c false if invalid parameters specified.
 210                          */
 211                         static inline bool XMEGACLK_StartPLL(const uint8_t Source,
 212                                                              const uint32_t SourceFreq,
 213                                                              const uint32_t Frequency) ATTR_ALWAYS_INLINE;
 214                         static inline bool XMEGACLK_StartPLL(const uint8_t Source,
 215                                                              const uint32_t SourceFreq,
 216                                                              const uint32_t Frequency)
 217                         {
 218                                 uint8_t MulFactor = (Frequency / SourceFreq);
 219
 220                                 if (SourceFreq > Frequency)
 221                                   return false;
 222
 223                                 switch (Source)
 224                                 {
 225                                         case CLOCK_SRC_INT_RC2MHZ:
 226                                                 OSC.PLLCTRL = (OSC_PLLSRC_RC2M_gc  | MulFactor);
 227                                                 break;
 228                                         case CLOCK_SRC_INT_RC32MHZ:
 229                                                 OSC.PLLCTRL = (OSC_PLLSRC_RC32M_gc | MulFactor);
 230                                                 break;
 231                                         case CLOCK_SRC_XOSC:
 232                                                 OSC.PLLCTRL = (OSC_PLLSRC_XOSC_gc  | MulFactor);
 233                                                 break;
 234                                         default:
 235                                                 return false;
 236                                 }
 237
 238                                 OSC.CTRL |= OSC_PLLEN_bm;
 239
 240                                 while (!(OSC.STATUS & OSC_PLLRDY_bm));
 241                                 return true;
 242                         }
 243
 244                         /** Stops the PLL of the XMEGA microcontroller. */
 245                         static inline void XMEGACLK_StopPLL(void) ATTR_ALWAYS_INLINE;
 246                         static inline void XMEGACLK_StopPLL(void)
 247                         {
 248                                 OSC.CTRL &= ~OSC_PLLEN_bm;
 249                         }
 250
 251                         /** Starts the DFLL of the XMEGA microcontroller, with the given options.
 252                          *
 253                          *  \param[in] Source     RC Clock source for the DFLL, a value from \ref XMEGA_System_ClockSource_t.
 254                          *  \param[in] Reference  Reference clock source for the DFLL, an value from \ref XMEGA_System_DFLLReference_t
 255                          *  \param[in] Frequency  Target frequency of the DFLL's output.
 256                          *
 257                          *  \return Boolean \c true if the DFLL was successfully started, \c false if invalid parameters specified.
 258                          */
 259                         static inline bool XMEGACLK_StartDFLL(const uint8_t Source,
 260                                                               const uint8_t Reference,
 261                                                               const uint32_t Frequency) ATTR_ALWAYS_INLINE;
 262                         static inline bool XMEGACLK_StartDFLL(const uint8_t Source,
 263                                                               const uint8_t Reference,
 264                                                               const uint32_t Frequency)
 265                         {
 266                                 uint16_t DFLLCompare = (Frequency / 1000);
 267
 268                                 switch (Source)
 269                                 {
 270                                         case CLOCK_SRC_INT_RC2MHZ:
 271                                                 OSC.DFLLCTRL   |= (Reference << OSC_RC2MCREF_bp);
 272                                                 DFLLRC2M.COMP1  = (DFLLCompare & 0xFF);
 273                                                 DFLLRC2M.COMP2  = (DFLLCompare >> 8);
 274                                                 DFLLRC2M.CTRL   = DFLL_ENABLE_bm;
 275                                                 break;
 276                                         case CLOCK_SRC_INT_RC32MHZ:
 277                                                 OSC.DFLLCTRL   |= (Reference << OSC_RC32MCREF_gp);
 278                                                 DFLLRC32M.COMP1 = (DFLLCompare & 0xFF);
 279                                                 DFLLRC32M.COMP2 = (DFLLCompare >> 8);
 280
 281                                                 if (Reference == DFLL_REF_INT_USBSOF)
 282                                                 {
 283                                                         NVM.CMD        = NVM_CMD_READ_CALIB_ROW_gc;
 284                                                         DFLLRC32M.CALA = pgm_read_byte(offsetof(NVM_PROD_SIGNATURES_t, USBRCOSCA));
 285                                                         DFLLRC32M.CALB = pgm_read_byte(offsetof(NVM_PROD_SIGNATURES_t, USBRCOSC));
 286                                                         NVM.CMD        = 0;
 287                                                 }
 288
 289                                                 DFLLRC32M.CTRL  = DFLL_ENABLE_bm;
 290                                                 break;
 291                                         default:
 292                                                 return false;
 293                                 }
 294
 295                                 return true;
 296                         }
 297
 298                         /** Stops the given DFLL of the XMEGA microcontroller.
 299                          *
 300                          *  \param[in] Source  RC Clock source for the DFLL to be stopped, a value from \ref XMEGA_System_ClockSource_t.
 301                          *
 302                          *  \return Boolean \c true if the DFLL was successfully stopped, \c false if invalid parameters specified.
 303                          */
 304                         static inline bool XMEGACLK_StopDFLL(const uint8_t Source) ATTR_ALWAYS_INLINE;
 305                         static inline bool XMEGACLK_StopDFLL(const uint8_t Source)
 306                         {
 307                                 switch (Source)
 308                                 {
 309                                         case CLOCK_SRC_INT_RC2MHZ:
 310                                                 DFLLRC2M.CTRL = 0;
 311                                                 break;
 312                                         case CLOCK_SRC_INT_RC32MHZ:
 313                                                 DFLLRC32M.CTRL = 0;
 314                                                 break;
 315                                         default:
 316                                                 return false;
 317                                 }
 318
 319                                 return true;
 320                         }
 321
 322                         /** Sets the clock source for the main microcontroller core. The given clock source should be configured
 323                          *  and ready for use before this function is called.
 324                          *
 325                          *  \param[in] Source      Clock source for the CPU core, a value from \ref XMEGA_System_ClockSource_t.
 326                          *
 327                          *  \return Boolean \c true if the CPU core clock was sucessfully altered, \c false if invalid parameters specified.
 328                          */
 329                         static inline bool XMEGACLK_SetCPUClockSource(const uint8_t Source) ATTR_ALWAYS_INLINE;
 330                         static inline bool XMEGACLK_SetCPUClockSource(const uint8_t Source)
 331                         {
 332                                 uint8_t ClockSourceMask = 0;
 333
 334                                 switch (Source)
 335                                 {
 336                                         case CLOCK_SRC_INT_RC2MHZ:
 337                                                 ClockSourceMask = CLK_SCLKSEL_RC2M_gc;
 338                                                 break;
 339                                         case CLOCK_SRC_INT_RC32MHZ:
 340                                                 ClockSourceMask = CLK_SCLKSEL_RC32M_gc;
 341                                                 break;
 342                                         case CLOCK_SRC_INT_RC32KHZ:
 343                                                 ClockSourceMask = CLK_SCLKSEL_RC32K_gc;
 344                                                 break;
 345                                         case CLOCK_SRC_XOSC:
 346                                                 ClockSourceMask = CLK_SCLKSEL_XOSC_gc;
 347                                                 break;
 348                                         case CLOCK_SRC_PLL:
 349                                                 ClockSourceMask = CLK_SCLKSEL_PLL_gc;
 350                                                 break;
 351                                         default:
 352                                                 return false;
 353                                 }
 354
 355                                 uint_reg_t CurrentGlobalInt = GetGlobalInterruptMask();
 356                                 GlobalInterruptDisable();
 357
 358                                 CCP      = CCP_IOREG_gc;
 359                                 CLK_CTRL = ClockSourceMask;
 360
 361                                 SetGlobalInterruptMask(CurrentGlobalInt);
 362
 363                                 Delay_MS(1);
 364                                 return (CLK.CTRL == ClockSourceMask);
 365                         }
 366
 367         /* Disable C linkage for C++ Compilers: */
 368                 #if defined(__cplusplus)
 369                         }
 370                 #endif
 371
 372 #endif
 373
 374 /** @} */
 375