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:

BOARD_<osc name>_HZ: The nominal frequency of the oscillator.
BOARD_<osc name>_STARTUP_US: The startup time of the oscillator in microseconds.
BOARD_<osc name>_TYPE: The type of oscillator connected, i.e. whether it's a crystal or external clock, and sometimes what kind of crystal it is. The meaning of this value is platform-specific.

Errata

Auto-calibration does not work on XMEGA A1 revision H and earlier.

Macros
#define	CONFIG_XOSC_32KHZ_LPM
	Define for enabling Low Power Mode for 32 kHz external oscillator. More...

Functions
static void	osc_enable_external (uint8_t id)
	Enable external oscillator id. More...

static void	osc_enable_internal (uint8_t id)
	Enable internal oscillator id. More...

Oscillator Management
static void	osc_wait_ready (uint8_t id)
	Wait until the oscillator identified by id is ready. More...

static void	osc_disable (uint8_t id)
	Disable oscillator id. More...

static void	osc_enable (uint8_t id)
	Enable 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_RC2MHZ OSC_RC2MEN_bm
	2 MHz Internal RC Oscillator More...

#define	OSC_ID_RC32MHZ OSC_RC32MEN_bm
	32 MHz Internal RC Oscillator More...

#define	OSC_ID_RC32KHZ OSC_RC32KEN_bm
	32 KHz Internal RC Oscillator More...

#define	OSC_ID_XOSC OSC_XOSCEN_bm
	External Oscillator. More...

#define	OSC_ID_USBSOF 0xff
	Reference from USB Start Of Frame. More...

External oscillator types
#define	XOSC_TYPE_EXTERNAL 0
	External clock signal. More...

#define	XOSC_TYPE_32KHZ 2
	32.768 kHz resonator on TOSC More...

#define	XOSC_TYPE_XTAL 3
	0.4 to 16 MHz resonator on XTAL More...

XTAL resonator start-up cycles
#define	XOSC_STARTUP_256 0
	256 cycle start-up time More...

#define	XOSC_STARTUP_1024 1
	1 k cycle start-up time More...

#define	XOSC_STARTUP_16384 2
	16 k cycle start-up time More...

XTAL resonator frequency range
#define	XOSC_RANGE_04TO2 OSC_FRQRANGE_04TO2_gc
	0.4 to 2 MHz frequency range More...

#define	XOSC_RANGE_2TO9 OSC_FRQRANGE_2TO9_gc
	2 to 9 MHz frequency range More...

#define	XOSC_RANGE_9TO12 OSC_FRQRANGE_9TO12_gc
	9 to 12 MHz frequency range More...

#define	XOSC_RANGE_12TO16 OSC_FRQRANGE_12TO16_gc
	12 to 16 MHz frequency range More...

XMEGA-Specific Oscillator Features
static void	osc_enable_autocalibration (uint8_t id, uint8_t ref_id)
	Enable DFLL-based automatic calibration of an internal oscillator. More...

static void	osc_disable_autocalibration (uint8_t id)
	Disable DFLL-based automatic calibration of an internal oscillator. More...

static void	osc_user_calibration (uint8_t id, uint16_t calib)
	Load a specific calibration value for the specified oscillator. More...

#define CONFIG_XOSC_32KHZ_LPM

Define for enabling Low Power Mode for 32 kHz external oscillator.

#define OSC_ID_RC2MHZ OSC_RC2MEN_bm

2 MHz Internal RC Oscillator

Referenced by main(), osc_disable_autocalibration(), osc_enable_autocalibration(), osc_get_rate(), osc_user_calibration(), and sysclk_init().

#define OSC_ID_RC32KHZ OSC_RC32KEN_bm

32 KHz Internal RC Oscillator

Referenced by osc_enable_autocalibration(), osc_get_rate(), sysclk_init(), and sysclk_rtcsrc_enable().

#define OSC_ID_RC32MHZ OSC_RC32MEN_bm

32 MHz Internal RC Oscillator

Referenced by main(), osc_disable_autocalibration(), osc_enable_autocalibration(), osc_get_rate(), osc_user_calibration(), pll_enable_source(), sysclk_enable_usb(), and sysclk_init().

#define OSC_ID_USBSOF 0xff

Reference from USB Start Of Frame.

Note: This cannot be enabled or disabled, but can be used as a reference for the autocalibration (DFLL).

Referenced by osc_disable(), osc_enable_autocalibration(), osc_enable_internal(), osc_get_rate(), osc_is_ready(), pll_enable_source(), sysclk_enable_usb(), and sysclk_init().

#define OSC_ID_XOSC OSC_XOSCEN_bm

External Oscillator.

Referenced by osc_enable(), osc_enable_autocalibration(), osc_enable_external(), osc_get_rate(), pll_enable_source(), pll_get_default_rate_priv(), sysclk_init(), and sysclk_rtcsrc_enable().

#define XOSC_RANGE_04TO2 OSC_FRQRANGE_04TO2_gc

0.4 to 2 MHz frequency range

#define XOSC_RANGE_12TO16 OSC_FRQRANGE_12TO16_gc

12 to 16 MHz frequency range

#define XOSC_RANGE_2TO9 OSC_FRQRANGE_2TO9_gc

2 to 9 MHz frequency range

#define XOSC_RANGE_9TO12 OSC_FRQRANGE_9TO12_gc

9 to 12 MHz frequency range

#define XOSC_STARTUP_1024 1

1 k cycle start-up time

#define XOSC_STARTUP_16384 2

16 k cycle start-up time

#define XOSC_STARTUP_256 0

256 cycle start-up time

#define XOSC_TYPE_32KHZ 2

32.768 kHz resonator on TOSC

#define XOSC_TYPE_EXTERNAL 0

External clock signal.

#define XOSC_TYPE_XTAL 3

0.4 to 16 MHz resonator on XTAL

void osc_disable ( uint8_t id )

inlinestatic

Disable oscillator id.

References Assert, cpu_irq_restore(), cpu_irq_save(), and OSC_ID_USBSOF.

Referenced by main(), and sysclk_init().

static void osc_disable_autocalibration ( uint8_t id )

inlinestatic

Disable DFLL-based automatic calibration of an internal oscillator.

See Also: osc_enable_autocalibration

Parameters

id	The ID of the oscillator for which to disable auto-calibration: `OSC_ID_RC2MHZ` or `OSC_ID_RC32MHZ`.

References Assert, OSC_ID_RC2MHZ, and OSC_ID_RC32MHZ.

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 osc_enable_external(), osc_enable_internal(), and OSC_ID_XOSC.

Referenced by main(), osc_enable_autocalibration(), pll_enable_source(), sysclk_enable_usb(), sysclk_init(), and sysclk_rtcsrc_enable().

static void osc_enable_autocalibration	(	uint8_t	id,
		uint8_t	ref_id
	)

inlinestatic

Enable DFLL-based automatic calibration of an internal oscillator.

The XMEGA features two Digital Frequency Locked Loops (DFLLs) which can be used to improve the accuracy of the 2 MHz and 32 MHz internal RC oscillators. The DFLL compares the oscillator frequency with a more accurate reference clock to do automatic run-time calibration of the oscillator.

This function enables auto-calibration for either the 2 MHz or 32 MHz internal oscillator using either the 32.768 kHz calibrated internal oscillator or an external crystal oscillator as a reference. If the latter option is used, the crystal must be connected to the TOSC pins and run at 32.768 kHz.

Parameters

id	The ID of the oscillator for which to enable auto-calibration: `OSC_ID_RC2MHZ` or `OSC_ID_RC32MHZ`.
ref_id	The ID of the oscillator to use as a reference: `OSC_ID_RC32KHZ` or `OSC_ID_XOSC` for internal or external 32 kHz reference, respectively. `OSC_ID_USBSOF` for 32 MHz only when USB is available and running.

References Assert, cpu_irq_restore(), cpu_irq_save(), osc_enable(), OSC_ID_RC2MHZ, OSC_ID_RC32KHZ, OSC_ID_RC32MHZ, OSC_ID_USBSOF, OSC_ID_XOSC, and XMEGA_E.

Referenced by pll_enable_source(), sysclk_enable_usb(), and sysclk_init().

static void osc_enable_external ( uint8_t id )

inlinestatic

Enable external oscillator id.

Do not call this function directly. Use osc_enable() instead. Also note that this function is only available if the board actually has an external oscillator crystal.

References Assert, cpu_irq_restore(), cpu_irq_save(), and OSC_ID_XOSC.

Referenced by osc_enable().

static void osc_enable_internal ( uint8_t id )

inlinestatic

Enable internal oscillator id.

Do not call this function directly. Use osc_enable() instead.

References Assert, cpu_irq_restore(), cpu_irq_save(), and OSC_ID_USBSOF.

Referenced by osc_enable().

uint32_t osc_get_rate ( uint8_t id )

inlinestatic

Return the frequency of oscillator id in Hz.

References Assert, OSC_ID_RC2MHZ, OSC_ID_RC32KHZ, OSC_ID_RC32MHZ, OSC_ID_USBSOF, and OSC_ID_XOSC.