Xmega Application Note


clksys_driver.h File Reference

XMEGA Clock System driver header file. More...

#include "avr_compiler.h"

Include dependency graph for clksys_driver.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines

#define CLKSYS_AutoCalibration_Disable(_clk)   ( (_clk).CTRL &= ~DFLL_ENABLE_bm )
 This macro disables the automatic calibration of the selected internal oscillator.
#define CLKSYS_Enable(_oscSel)   ( OSC.CTRL |= (_oscSel) )
 This macro enables the selected oscillator.
#define CLKSYS_IsReady(_oscSel)   ( OSC.STATUS & (_oscSel) )
 This macro check if selected oscillator is ready.
#define CLKSYS_RTC_ClockSource_Disable()   ( CLK.RTCCTRL &= ~CLK_RTCEN_bm )
 This macro disables routing of clock signals to the Real-Time Counter (RTC).

Functions

void CCPWrite (volatile uint8_t *address, uint8_t value)
 CCP write helper function written in assembly.
void CLKSYS_AutoCalibration_Enable (uint8_t clkSource, bool extReference)
 This function enables automatic calibration of the selected internal oscillator.
void CLKSYS_Configuration_Lock (void)
 This function lock the entire clock system configuration.
uint8_t CLKSYS_Disable (uint8_t oscSel)
 This function disables the selected oscillator.
uint8_t CLKSYS_Main_ClockSource_Select (CLK_SCLKSEL_t clockSource)
 This function selects the main system clock source.
void CLKSYS_PLL_Config (OSC_PLLSRC_t clockSource, uint8_t factor)
 This function configures the internal high-frequency PLL.
void CLKSYS_Prescalers_Config (CLK_PSADIV_t PSAfactor, CLK_PSBCDIV_t PSBCfactor)
 This function changes the prescaler configuration.
void CLKSYS_RTC_ClockSource_Enable (CLK_RTCSRC_t clockSource)
 This function selects a Real-Time Counter clock source.
void CLKSYS_XOSC_Config (OSC_FRQRANGE_t freqRange, bool lowPower32kHz, OSC_XOSCSEL_t xoscModeSelection)
 This function configures the external oscillator.
void CLKSYS_XOSC_FailureDetection_Enable (void)
 This function enables the External Oscillator Failure Detection (XOSCFD) feature.


Detailed Description

XMEGA Clock System driver header file.

This file contains the function prototypes and enumerator definitions for various configuration parameters for the XMEGA Clock System driver.

The driver is not intended for size and/or speed critical code, since most functions are just a few lines of code, and the function call overhead would decrease code performance. The driver is intended for rapid prototyping and documentation purposes for getting started with the XMEGA Clock System.

For size and/or speed critical code, it is recommended to copy the function contents directly into your application instead of making a function call.

Application note:
AVR1003: Using the XMEGA Clock System
Documentation
For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html
Author:
Atmel Corporation: http://www.atmel.com
Support email: avr@atmel.com
Revision
1665
Date
2008-06-05 09:21:50 +0200 (to, 05 jun 2008)

Copyright (c) 2008, Atmel Corporation All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of ATMEL may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file clksys_driver.h.


Define Documentation

#define CLKSYS_AutoCalibration_Disable ( _clk   )     ( (_clk).CTRL &= ~DFLL_ENABLE_bm )

This macro disables the automatic calibration of the selected internal oscillator.

Parameters:
_clk Clock source calibration to disable, either DFLLRC2M or DFLLRC32M.

Definition at line 105 of file clksys_driver.h.

#define CLKSYS_Enable ( _oscSel   )     ( OSC.CTRL |= (_oscSel) )

This macro enables the selected oscillator.

Note:
Note that the oscillator cannot be used as a main system clock source without being enabled and stable first. Check the ready flag before using the clock. The function CLKSYS_IsReady( _oscSel ) can be used to check this.
Parameters:
_oscSel Bitmask of selected clock. Can be one of the following OSC_RC2MEN_bm, OSC_RC32MEN_bm, OSC_RC32KEN_bm, OSC_XOSCEN_bm, OSC_PLLEN_bm.

Definition at line 78 of file clksys_driver.h.

Referenced by main().

#define CLKSYS_IsReady ( _oscSel   )     ( OSC.STATUS & (_oscSel) )

This macro check if selected oscillator is ready.

This macro will return non-zero if is is running, regardless if it is used as a main clock source or not.

Parameters:
_oscSel Bitmask of selected clock. Can be one of the following OSC_RC2MEN_bm, OSC_RC32MEN_bm, OSC_RC32KEN_bm, OSC_XOSCEN_bm, OSC_PLLEN_bm.
Returns:
Non-zero if oscillator is ready and running.

Definition at line 91 of file clksys_driver.h.

Referenced by main().

 
#define CLKSYS_RTC_ClockSource_Disable (  )     ( CLK.RTCCTRL &= ~CLK_RTCEN_bm )

This macro disables routing of clock signals to the Real-Time Counter (RTC).

Disabling the RTC saves power if the RTC is not in use.

Definition at line 98 of file clksys_driver.h.


Function Documentation

void CCPWrite ( volatile uint8_t *  address,
uint8_t  value 
)

CCP write helper function written in assembly.

This function is written in assembly because of the timecritial operation of writing to the registers.

Parameters:
address A pointer to the address to write to.
value The value to put in to the register.

Definition at line 77 of file clksys_driver.c.

References AVR_ENTER_CRITICAL_REGION, and AVR_LEAVE_CRITICAL_REGION.

Referenced by CLKSYS_Configuration_Lock(), CLKSYS_Main_ClockSource_Select(), CLKSYS_Prescalers_Config(), and CLKSYS_XOSC_FailureDetection_Enable().

00078 {
00079 #ifdef __ICCAVR__
00080 
00081         // Store global interrupt setting in scratch register and disable interrupts.
00082         asm("in  R1, 0x3F \n"
00083             "cli"
00084             );
00085 
00086         // Move destination address pointer to Z pointer registers.
00087         asm("movw r30, r16");
00088 #ifdef RAMPZ
00089         asm("ldi  R16, 0 \n"
00090             "out  0x3B, R16"
00091             );
00092 
00093 #endif
00094         asm("ldi  r16,  0xD8 \n"
00095             "out  0x34, r16  \n"
00096 #if (__MEMORY_MODEL__ == 1)
00097             "st     Z,  r17  \n");
00098 #elif (__MEMORY_MODEL__ == 2)
00099             "st     Z,  r18  \n");
00100 #else /* (__MEMORY_MODEL__ == 3) || (__MEMORY_MODEL__ == 5) */
00101             "st     Z,  r19  \n");
00102 #endif /* __MEMORY_MODEL__ */
00103 
00104         // Restore global interrupt setting from scratch register.
00105         asm("out  0x3F, R1");
00106 
00107 #elif defined __GNUC__
00108         AVR_ENTER_CRITICAL_REGION( );
00109         volatile uint8_t * tmpAddr = address;
00110 #ifdef RAMPZ
00111         RAMPZ = 0;
00112 #endif
00113         asm volatile(
00114                 "movw r30,  %0"       "\n\t"
00115                 "ldi  r16,  %2"       "\n\t"
00116                 "out   %3, r16"       "\n\t"
00117                 "st     Z,  %1"       "\n\t"
00118                 :
00119                 : "r" (tmpAddr), "r" (value), "M" (CCP_IOREG_gc), "i" (&CCP)
00120                 : "r16", "r30", "r31"
00121                 );
00122 
00123         AVR_LEAVE_CRITICAL_REGION( );
00124 #endif
00125 }

void CLKSYS_AutoCalibration_Enable ( uint8_t  clkSource,
bool  extReference 
)

This function enables automatic calibration of the selected internal oscillator.

Either the internal 32kHz RC oscillator or an external 32kHz crystal can be used as a calibration reference. The user must make sure that the selected reference is ready and running.

Parameters:
clkSource Clock source to calibrate, either OSC_RC2MCREF_bm or OSC_RC32MCREF_bm.
extReference True if external crystal should be used as reference.

Definition at line 260 of file clksys_driver.c.

00261 {
00262         OSC.DFLLCTRL = ( OSC.DFLLCTRL & ~clkSource ) |
00263                        ( extReference ? clkSource : 0 );
00264         if (clkSource == OSC_RC2MCREF_bm) {
00265                 DFLLRC2M.CTRL |= DFLL_ENABLE_bm;
00266         } else if (clkSource == OSC_RC32MCREF_bm) {
00267                 DFLLRC32M.CTRL |= DFLL_ENABLE_bm;
00268         }
00269 }

void CLKSYS_Configuration_Lock ( void   ) 

This function lock the entire clock system configuration.

This will lock the configuration until the next reset, or until the External Oscillator Failure Detections (XOSCFD) feature detects a failure and switches to internal 2MHz RC oscillator.

Definition at line 292 of file clksys_driver.c.

References CCPWrite().

00293 {
00294         CCPWrite( &CLK.LOCK, CLK_LOCK_bm );
00295 }

Here is the call graph for this function:

uint8_t CLKSYS_Disable ( uint8_t  oscSel  ) 

This function disables the selected oscillator.

This function will disable the selected oscillator if possible. If it is currently used as a main system clock source, hardware will disregard the disable attempt, and this function will return zero. If it fails, change to another main system clock source and try again.

Parameters:
oscSel Bitmask of selected clock. Can be one of the following OSC_RC2MEN_bm, OSC_RC32MEN_bm, OSC_RC32KEN_bm, OSC_XOSCEN_bm, OSC_PLLEN_bm.
Returns:
Non-zero if oscillator was disabled successfully.

Definition at line 187 of file clksys_driver.c.

Referenced by main().

00188 {
00189         OSC.CTRL &= ~oscSel;
00190         uint8_t clkEnabled = OSC.CTRL & oscSel;
00191         return clkEnabled;
00192 }

uint8_t CLKSYS_Main_ClockSource_Select ( CLK_SCLKSEL_t  clockSource  ) 

This function selects the main system clock source.

Hardware will disregard any attempts to select a clock source that is not enabled or not stable. If the change fails, make sure the source is ready and running and try again.

Parameters:
clockSource Clock source to use as input for the system clock prescaler block.
Returns:
Non-zero if change was successful.

Definition at line 225 of file clksys_driver.c.

References CCPWrite().

Referenced by main().

00226 {
00227         uint8_t clkCtrl = ( CLK.CTRL & ~CLK_SCLKSEL_gm ) | clockSource;
00228         CCPWrite( &CLK.CTRL, clkCtrl );
00229         clkCtrl = ( CLK.CTRL & clockSource );
00230         return clkCtrl;
00231 }

Here is the call graph for this function:

void CLKSYS_PLL_Config ( OSC_PLLSRC_t  clockSource,
uint8_t  factor 
)

This function configures the internal high-frequency PLL.

Configuration of the internal high-frequency PLL to the correct values. It is used to define the input of the PLL and the factor of multiplication of the input clock source.

Note:
Note that the oscillator cannot be used as a main system clock source without being enabled and stable first. Check the ready flag before using the clock. The macro CLKSYS_IsReady( _oscSel ) can be used to check this.
Parameters:
clockSource Reference clock source for the PLL, must be above 0.4MHz.
factor PLL multiplication factor, must be from 1 to 31, inclusive.

Definition at line 167 of file clksys_driver.c.

Referenced by main().

00168 {
00169         factor &= OSC_PLLFAC_gm;
00170         OSC.PLLCTRL = (uint8_t) clockSource | ( factor << OSC_PLLFAC_gp );
00171 }

void CLKSYS_Prescalers_Config ( CLK_PSADIV_t  PSAfactor,
CLK_PSBCDIV_t  PSBCfactor 
)

This function changes the prescaler configuration.

Change the configuration of the three system clock prescaler is one single operation. The user must make sure that the main CPU clock does not exceed recommended limits.

Parameters:
PSAfactor Prescaler A division factor, OFF or 2 to 512 in powers of two.
PSBCfactor Prescaler B and C division factor, in the combination of (1,1), (1,2), (4,1) or (2,2).

Definition at line 206 of file clksys_driver.c.

References CCPWrite().

Referenced by main().

00208 {
00209         uint8_t PSconfig = (uint8_t) PSAfactor | PSBCfactor;
00210         CCPWrite( &CLK.PSCTRL, PSconfig );
00211 }

Here is the call graph for this function:

void CLKSYS_RTC_ClockSource_Enable ( CLK_RTCSRC_t  clockSource  ) 

This function selects a Real-Time Counter clock source.

Selects the clock source for use by the Real-Time Counter (RTC) and enables clock signal routing to the RTC module.

Parameters:
clockSource Clock source to use for the RTC.

Definition at line 241 of file clksys_driver.c.

00242 {
00243         CLK.RTCCTRL = ( CLK.RTCCTRL & ~CLK_RTCSRC_gm ) |
00244                       clockSource |
00245                       CLK_RTCEN_bm;
00246 }

void CLKSYS_XOSC_Config ( OSC_FRQRANGE_t  freqRange,
bool  lowPower32kHz,
OSC_XOSCSEL_t  xoscModeSelection 
)

This function configures the external oscillator.

Note:
Note that the oscillator cannot be used as a main system clock source without being enabled and stable first. Check the ready flag before using the clock. The macro CLKSYS_IsReady( _oscSel ) can be used to check this.
Parameters:
freqRange Frequency range for high-frequency crystal, does not apply for external clock or 32kHz crystals.
lowPower32kHz True of high-quality watch crystals are used and low-power oscillator is desired.
xoscModeSelection Combined selection of oscillator type (or external clock) and startup times.

Definition at line 141 of file clksys_driver.c.

Referenced by main().

00144 {
00145         OSC.XOSCCTRL = (uint8_t) freqRange |
00146                        ( lowPower32kHz ? OSC_X32KLPM_bm : 0 ) |
00147                        xoscModeSelection;
00148 }

void CLKSYS_XOSC_FailureDetection_Enable ( void   ) 

This function enables the External Oscillator Failure Detection (XOSCFD) feature.

The feature will stay enabled until next reset. Note that the XOSCFD _will_ issue the XOSCF Non-maskable Interrupt (NMI) regardless of any interrupt priorities and settings. Therefore, make sure that a handler is implemented for the XOSCF NMI when you enable it.

Definition at line 280 of file clksys_driver.c.

References CCPWrite().

00281 {
00282         CCPWrite( &OSC.XOSCFAIL, ( OSC_XOSCFDIF_bm | OSC_XOSCFDEN_bm ) );
00283 }

Here is the call graph for this function:

@DOC_TITLE@
Generated on Mon Sep 14 09:48:10 2009 for AVR1003 Using the XMEGA Clock System by doxygen 1.5.8