Atmel Software Framework

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Oscillator Management

This group contains functions and definitions related to configuring and enabling/disabling on-chip oscillators.

Internal RC-oscillators, external crystal oscillators and external clock generators are supported by this module. What all of these have in common is that they swing at a fixed, nominal frequency which is normally not adjustable.

Example: Enabling an oscillator

The following example demonstrates how to enable the external oscillator on XMEGA A and wait for it to be ready to use. The oscillator identifiers are platform-specific, so while the same procedure is used on all platforms, the parameter to osc_enable() will be different from device to device.

osc_enable(OSC_ID_XOSC);
osc_wait_ready(OSC_ID_XOSC);

Board-specific Definitions

If external oscillators are used, the board code must provide the following definitions for each of those:

Macros

#define OSC0_MODE_VALUE   UNDEFINED
 Board-dependent value written to the MODE bitfield of PM_OSCCTRL(0) More...
 
#define OSC0_STARTUP_TIMEOUT   UNDEFINED
 Number of slow clock cycles to wait for OSC0 to start. More...
 
#define OSC0_STARTUP_VALUE   UNDEFINED
 Board-dependent value written to the STARTUP bitfield of PM_OSCCTRL(0) More...
 
#define OSC1_MODE_VALUE   UNDEFINED
 Board-dependent value written to the MODE bitfield of PM_OSCCTRL(1) More...
 
#define OSC1_STARTUP_TIMEOUT   UNDEFINED
 Number of slow clock cycles to wait for OSC1 to start. More...
 
#define OSC1_STARTUP_VALUE   UNDEFINED
 Board-dependent value written to the STARTUP bitfield of PM_OSCCTRL(1) More...
 
#define OSC32_MODE_VALUE   UNDEFINED
 
#define OSC32_STARTUP_TIMEOUT   UNDEFINED
 
#define OSC32_STARTUP_VALUE   UNDEFINED
 

Oscillator Management

static void osc_wait_ready (uint8_t id)
 Wait until the oscillator identified by id is ready. More...
 
static void osc_enable (uint8_t id)
 Enable oscillator id. More...
 
static void osc_disable (uint8_t id)
 Disable oscillator id. More...
 
static bool osc_is_ready (uint8_t id)
 Determine whether oscillator id is ready. More...
 
static uint32_t osc_get_rate (uint8_t id)
 Return the frequency of oscillator id in Hz. More...
 

Oscillator identifiers

#define OSC_ID_OSC0   0
 External Oscillator 0. More...
 
#define OSC_ID_OSC1   1
 External Oscillator 1. More...
 
#define OSC_ID_OSC32   2
 External 32 kHz oscillator. More...
 

OSC0/OSC1 mode values

#define OSC_MODE_EXTERNAL   AVR32_PM_MODE_EXT_CLOCK
 External clock connected to XIN. More...
 
#define OSC_MODE_XTAL_G0   AVR32_PM_MODE_CRYSTAL_G0
 Crystal connected to XIN/XOUT. Use oscillator gain G0 (400 kHz to 900 kHz) More...
 
#define OSC_MODE_XTAL_G1   AVR32_PM_MODE_CRYSTAL_G1
 Crystal connected to XIN/XOUT. Use oscillator gain G1 (900 kHz to 3 MHz) More...
 
#define OSC_MODE_XTAL_G2   AVR32_PM_MODE_CRYSTAL_G2
 Crystal connected to XIN/XOUT. Use oscillator gain G2 (3 MHz to 8 MHz) More...
 
#define OSC_MODE_XTAL_G3   AVR32_PM_MODE_CRYSTAL_G3
 Crystal connected to XIN/XOUT. Use oscillator gain G3 (8 MHz and higher) More...
 

OSC32 mode values

#define OSC32_MODE_EXTERNAL   AVR32_PM_OSCCTRL32_MODE_EXT_CLOCK
 External clock connected to XIN32. More...
 
#define OSC32_MODE_XTAL   AVR32_PM_OSCCTRL32_MODE_CRYSTAL
 Crystal connected to XIN32/XOUT32. Use automatic gain control. More...
 

OSC0/OSC1 startup values

#define OSC_STARTUP_0   AVR32_PM_OSCCTRL0_STARTUP_0_RCOSC
 0 cycles More...
 
#define OSC_STARTUP_64   AVR32_PM_OSCCTRL0_STARTUP_64_RCOSC
 64 cycles (560 us) More...
 
#define OSC_STARTUP_128   AVR32_PM_OSCCTRL0_STARTUP_128_RCOSC
 128 cycles (1.1 ms) More...
 
#define OSC_STARTUP_2048   AVR32_PM_OSCCTRL0_STARTUP_2048_RCOSC
 2048 cycles (18 ms) More...
 
#define OSC_STARTUP_4096   AVR32_PM_OSCCTRL0_STARTUP_4096_RCOSC
 4096 cycles (36 ms) More...
 
#define OSC_STARTUP_8192   AVR32_PM_OSCCTRL0_STARTUP_8192_RCOSC
 8192 cycles (71 ms) More...
 
#define OSC_STARTUP_16384   AVR32_PM_OSCCTRL0_STARTUP_16384_RCOSC
 16384 cycles (142 ms) More...
 

OSC32 startup values

#define OSC32_STARTUP_0   AVR32_PM_OSCCTRL32_STARTUP_0_RCOSC
 0 cycles More...
 
#define OSC32_STARTUP_128   AVR32_PM_OSCCTRL32_STARTUP_128_RCOSC
 128 cycles (1.1 ms) More...
 
#define OSC32_STARTUP_8192   AVR32_PM_OSCCTRL32_STARTUP_8192_RCOSC
 8192 cycles (72.3 ms) More...
 
#define OSC32_STARTUP_16384   AVR32_PM_OSCCTRL32_STARTUP_16384_RCOSC
 16384 cycles (143 ms) More...
 
#define OSC32_STARTUP_65536   AVR32_PM_OSCCTRL32_STARTUP_65536_RCOSC
 65536 cycles (570 ms) More...
 
#define OSC32_STARTUP_131072   AVR32_PM_OSCCTRL32_STARTUP_131072_RCOSC
 131072 cycles (1.1 s) More...
 
#define OSC32_STARTUP_262144   AVR32_PM_OSCCTRL32_STARTUP_262144_RCOSC
 262144 cycles (2.3 s) More...
 
#define OSC32_STARTUP_524288   AVR32_PM_OSCCTRL32_STARTUP_524288_RCOSC
 524288 cycles (4.6 s) More...
 

Board-specific configuration parameters

The following definitions must be provided by the board code for all working oscillators on the board.

#define BOARD_OSC0_HZ   UNDEFINED
 Clock frequency of OSC0 in Hz. More...
 
#define BOARD_OSC0_STARTUP_US   UNDEFINED
 Startup time of OSC0 in microseconds. More...
 
#define BOARD_OSC0_IS_XTAL   UNDEFINED
 OSC0 uses a crystal, not an external clock. More...
 
#define BOARD_OSC1_HZ   UNDEFINED
 Clock frequency of OSC1 in Hz. More...
 
#define BOARD_OSC1_STARTUP_US   UNDEFINED
 Startup time of OSC1 in microseconds. More...
 
#define BOARD_OSC1_IS_XTAL   UNDEFINED
 OSC1 uses a crystal, not an external clock. More...
 
#define BOARD_OSC32_HZ   UNDEFINED
 Clock frequency of OSC32 in Hz. More...
 
#define BOARD_OSC32_STARTUP_US   UNDEFINED
 Startup time of OSC32 in microseconds. More...
 
#define BOARD_OSC32_IS_XTAL   UNDEFINED
 OSC32 uses a crystal, not an external clock. More...
 

Slow clock frequency limits

The slow clock is an internal RC oscillator whose frequency may drift a bit as a result of temperature changes.

These definitions provide upper and lower limits which may be used to calculate upper and lower limits of timeouts, derived clock frequencies, etc.

#define OSC_SLOW_NOMINAL_HZ   AVR32_PM_RCOSC_FREQUENCY
 Nominal frequency of the slow clock in Hz. More...
 
#define OSC_SLOW_MIN_HZ   100000
 Minimum frequency of the slow clock in Hz. More...
 
#define OSC_SLOW_MAX_HZ   120000
 Maximum frequency of the slow clock in Hz. More...
 

#define BOARD_OSC0_HZ   UNDEFINED

Clock frequency of OSC0 in Hz.

Referenced by main(), osc_get_rate(), sysclk_get_main_hz(), and sysclk_init().

#define BOARD_OSC0_IS_XTAL   UNDEFINED

OSC0 uses a crystal, not an external clock.

#define BOARD_OSC0_STARTUP_US   UNDEFINED

Startup time of OSC0 in microseconds.

#define BOARD_OSC1_HZ   UNDEFINED

Clock frequency of OSC1 in Hz.

Referenced by osc_get_rate().

#define BOARD_OSC1_IS_XTAL   UNDEFINED

OSC1 uses a crystal, not an external clock.

#define BOARD_OSC1_STARTUP_US   UNDEFINED

Startup time of OSC1 in microseconds.

#define BOARD_OSC32_HZ   UNDEFINED

Clock frequency of OSC32 in Hz.

Referenced by osc_get_rate().

#define BOARD_OSC32_IS_XTAL   UNDEFINED

OSC32 uses a crystal, not an external clock.

#define BOARD_OSC32_STARTUP_US   UNDEFINED

Startup time of OSC32 in microseconds.

#define OSC0_MODE_VALUE   UNDEFINED

Board-dependent value written to the MODE bitfield of PM_OSCCTRL(0)

Referenced by osc_enable().

#define OSC0_STARTUP_TIMEOUT   UNDEFINED

Number of slow clock cycles to wait for OSC0 to start.

This is the number of slow clock cycles corresponding to OSC0_STARTUP_VALUE with an additional 25% safety margin. If the oscillator isn't running when this timeout has expired, it is assumed to have failed to start.

Referenced by run_osc_test().

#define OSC0_STARTUP_VALUE   UNDEFINED

Board-dependent value written to the STARTUP bitfield of PM_OSCCTRL(0)

Referenced by osc_enable().

#define OSC1_MODE_VALUE   UNDEFINED

Board-dependent value written to the MODE bitfield of PM_OSCCTRL(1)

Referenced by osc_enable().

#define OSC1_STARTUP_TIMEOUT   UNDEFINED

Number of slow clock cycles to wait for OSC1 to start.

This is the number of slow clock cycles corresponding to OSC1_STARTUP_VALUE with an additional 25% safety margin. If the oscillator isn't running when this timeout has expired, it is assumed to have failed to start.

Referenced by run_osc_test().

#define OSC1_STARTUP_VALUE   UNDEFINED

Board-dependent value written to the STARTUP bitfield of PM_OSCCTRL(1)

Referenced by osc_enable().

#define OSC32_MODE_EXTERNAL   AVR32_PM_OSCCTRL32_MODE_EXT_CLOCK

External clock connected to XIN32.

#define OSC32_MODE_VALUE   UNDEFINED

Referenced by osc_enable().

#define OSC32_MODE_XTAL   AVR32_PM_OSCCTRL32_MODE_CRYSTAL

Crystal connected to XIN32/XOUT32. Use automatic gain control.

#define OSC32_STARTUP_0   AVR32_PM_OSCCTRL32_STARTUP_0_RCOSC

0 cycles

#define OSC32_STARTUP_128   AVR32_PM_OSCCTRL32_STARTUP_128_RCOSC

128 cycles (1.1 ms)

#define OSC32_STARTUP_131072   AVR32_PM_OSCCTRL32_STARTUP_131072_RCOSC

131072 cycles (1.1 s)

#define OSC32_STARTUP_16384   AVR32_PM_OSCCTRL32_STARTUP_16384_RCOSC

16384 cycles (143 ms)

#define OSC32_STARTUP_262144   AVR32_PM_OSCCTRL32_STARTUP_262144_RCOSC

262144 cycles (2.3 s)

#define OSC32_STARTUP_524288   AVR32_PM_OSCCTRL32_STARTUP_524288_RCOSC

524288 cycles (4.6 s)

#define OSC32_STARTUP_65536   AVR32_PM_OSCCTRL32_STARTUP_65536_RCOSC

65536 cycles (570 ms)

#define OSC32_STARTUP_8192   AVR32_PM_OSCCTRL32_STARTUP_8192_RCOSC

8192 cycles (72.3 ms)

#define OSC32_STARTUP_TIMEOUT   UNDEFINED
#define OSC32_STARTUP_VALUE   UNDEFINED

Referenced by osc_enable().

#define OSC_ID_OSC1   1
#define OSC_ID_OSC32   2
#define OSC_MODE_EXTERNAL   AVR32_PM_MODE_EXT_CLOCK

External clock connected to XIN.

#define OSC_MODE_XTAL_G0   AVR32_PM_MODE_CRYSTAL_G0

Crystal connected to XIN/XOUT. Use oscillator gain G0 (400 kHz to 900 kHz)

#define OSC_MODE_XTAL_G1   AVR32_PM_MODE_CRYSTAL_G1

Crystal connected to XIN/XOUT. Use oscillator gain G1 (900 kHz to 3 MHz)

#define OSC_MODE_XTAL_G2   AVR32_PM_MODE_CRYSTAL_G2

Crystal connected to XIN/XOUT. Use oscillator gain G2 (3 MHz to 8 MHz)

#define OSC_MODE_XTAL_G3   AVR32_PM_MODE_CRYSTAL_G3

Crystal connected to XIN/XOUT. Use oscillator gain G3 (8 MHz and higher)

#define OSC_SLOW_MAX_HZ   120000

Maximum frequency of the slow clock in Hz.

#define OSC_SLOW_MIN_HZ   100000

Minimum frequency of the slow clock in Hz.

#define OSC_SLOW_NOMINAL_HZ   AVR32_PM_RCOSC_FREQUENCY

Nominal frequency of the slow clock in Hz.

Referenced by sysclk_get_main_hz().

#define OSC_STARTUP_0   AVR32_PM_OSCCTRL0_STARTUP_0_RCOSC

0 cycles

#define OSC_STARTUP_128   AVR32_PM_OSCCTRL0_STARTUP_128_RCOSC

128 cycles (1.1 ms)

#define OSC_STARTUP_16384   AVR32_PM_OSCCTRL0_STARTUP_16384_RCOSC

16384 cycles (142 ms)

#define OSC_STARTUP_2048   AVR32_PM_OSCCTRL0_STARTUP_2048_RCOSC

2048 cycles (18 ms)

#define OSC_STARTUP_4096   AVR32_PM_OSCCTRL0_STARTUP_4096_RCOSC

4096 cycles (36 ms)

#define OSC_STARTUP_64   AVR32_PM_OSCCTRL0_STARTUP_64_RCOSC

64 cycles (560 us)

#define OSC_STARTUP_8192   AVR32_PM_OSCCTRL0_STARTUP_8192_RCOSC

8192 cycles (71 ms)

void osc_disable ( uint8_t  id)
inlinestatic
void osc_enable ( uint8_t  id)
inlinestatic

Enable oscillator id.

The startup time and mode value is automatically determined based on definitions in the board code.

References cpu_irq_restore(), cpu_irq_save(), OSC0_MODE_VALUE, OSC0_STARTUP_VALUE, OSC1_MODE_VALUE, OSC1_STARTUP_VALUE, OSC32_MODE_VALUE, OSC32_STARTUP_VALUE, OSC_ID_OSC0, OSC_ID_OSC1, and OSC_ID_OSC32.

Referenced by genclk_enable_source(), pll_enable_source(), run_osc32_test(), run_osc_test(), run_pll_dfll_test(), and sysclk_init().

uint32_t osc_get_rate ( uint8_t  id)
inlinestatic

Return the frequency of oscillator id in Hz.

References BOARD_OSC0_HZ, BOARD_OSC1_HZ, BOARD_OSC32_HZ, OSC_ID_OSC0, OSC_ID_OSC1, and OSC_ID_OSC32.

Referenced by pll_config_init().

osc_is_ready ( uint8_t  id)
inlinestatic

Determine whether oscillator id is ready.

Return values
trueOscillator id is running and ready to use as a clock source.
falseOscillator id is not running.

References OSC_ID_OSC0, OSC_ID_OSC1, and OSC_ID_OSC32.

Referenced by genclk_enable_source(), osc_wait_ready(), pll_enable_source(), run_osc32_test(), and run_osc_test().

static void osc_wait_ready ( uint8_t  id)
inlinestatic

Wait until the oscillator identified by id is ready.

This function will busy-wait for the oscillator identified by id to become stable and ready to use as a clock source.

Parameters
idA number identifying the oscillator to wait for.

References osc_is_ready().

Referenced by genclk_enable_source(), pll_enable_source(), run_pll_dfll_test(), and sysclk_init().