This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the device's Asynchronous Timer functionality.

The Asynchronous Timer can generate periodic interrupts and peripheral events from output from the prescaler, as well as alarm interrupts and peripheral events, which can trigger at any counter value.

Devices from the following series can use this module:

Atmel | SMART SAM4L

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The AST module in the SAM4L devices is a 32-bit counter, with a 32-bit programmable prescaler. Typically, the AST clock is run continuously, including in the device's low-power sleep modes, to track the current time and date information. The AST can also wake-up the system from backup mode using either the alarm wakeup, periodic wakeup, or overflow wake-up mechanisms.

The AST has been designed to meet the system tick and Real-Time Clock requirements of most embedded operating systems.

In this driver, the AST is operated in Calendar Mode. This allows for an easy integration of a Real-Time Clock and calendar into a user application to track the passing of time and/or perform scheduled tasks.

Whilst operating in Calendar Mode, the AST features:

Time tracking in seconds, minutes, and hours in 24 hour format
Date tracking in day, month, and year
Automatic leap year correction

Alarm Interrupt

The AST has a device dependent number of independent hardware alarms that can be configured by the user application. These alarms will be triggered on a match with the current clock value, and can be set up to trigger an interrupt, event, or both. The AST can also be configured to clear the clock value on alarm match which will generate an overflow interrupt.

Note: Refer to module configuration at the end of the AST section of the device datasheet for the number of alarms supported.

Whilst in Calendar Mode and using a nominal 1Hz input clock frequency, a register overflow will occur after 64 years.

Periodic Events

The AST can generate events at periodic intervals, allowing for direct peripheral actions without CPU intervention. The periodic events can be generated on an AST prescaler match, and will be generated on the rising edge transition of the specified bit. The resulting periodic frequency can be calculated by the following formula:

\[ f_{PERIODIC}=\frac{f_{ASY}}{2^{n+1}} \]

Where \(f_{ASY}\) refers to the asynchronous clock set up in the AST module configuration.

Note: The connection of events between modules requires the use of the SAM4L Peripheral Event Controller (PEVC) to route an output event of one module to the the input event of another. For more information on event routing, refer to the event driver documentation.

Digital Tuner

The AST module contains Digital Tuner logic to compensate for inaccurate source clock frequencies, which would otherwise result in skewed time measurements.

Special Considerations

Crystal Selection

The external crystal selection used by the AST module in the final system design must take into account:

Current consumption to achieve the best power savings in low power operating modes
Frequency drift (due to temperature effects on the circuit) for the best time accuracy

Year Limit

The AST module has a year range of 63 years from the starting year configured when the module is initialized. Dates outside the start to end year range described below will need software adjustment:

\[ [YEAR_{START}, YEAR_{START}+64] \]

Extra Information

For extra information, see Extra Information for Asynchronous Timer Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for Asynchronous Timer Driver.

API Overview

Modules
	Related Project(s)
	In this section you can find all the projects related to the SAM4L Asynchronous Timer (AST) Driver.

Data Structures
struct	ast_calendar

struct	ast_calv
	Description for Calendar Field. More...

struct	ast_config
	AST configuration. More...

Macros
#define	AST_POLL_TIMEOUT 10000
	Timeout to prevent code hang in clock initialization. More...

Typedefs
typedef void(*	ast_callback_t )(void)
	AST interrupt callback. More...

typedef enum ast_event_source	ast_event_source_t
	AST event source. More...

typedef enum ast_interrupt_source	ast_interrupt_source_t
	AST interrupt source. More...

typedef enum ast_mode	ast_mode_t
	AST Calendar Mode. More...

typedef enum ast_oscillator_type	ast_oscillator_type_t
	AST Oscillator type. More...

typedef enum ast_wakeup_source	ast_wakeup_source_t
	AST wake-up source. More...

Enumerations
enum	ast_event_source { AST_EVENT_ALARM = 0, AST_EVENT_PER, AST_EVENT_OVF }
	AST event source. More...

enum	ast_interrupt_source { AST_INTERRUPT_ALARM = 0, AST_INTERRUPT_PER, AST_INTERRUPT_OVF, AST_INTERRUPT_READY, AST_INTERRUPT_CLKREADY }
	AST interrupt source. More...

enum	ast_mode { AST_COUNTER_MODE = 0, AST_CALENDAR_MODE = 1 }
	AST Calendar Mode. More...

enum	ast_oscillator_type { AST_OSC_RC = 0, AST_OSC_32KHZ = 1, AST_OSC_PB = 2, AST_OSC_GCLK = 3, AST_OSC_1KHZ = 4 }
	AST Oscillator type. More...

enum	ast_wakeup_source { AST_WAKEUP_ALARM = 0, AST_WAKEUP_PER, AST_WAKEUP_OVF }
	AST wake-up source. More...

Functions
void	ast_clear_interrupt_flag (Ast *ast, ast_interrupt_source_t source)
	Clear an AST interrupt status flag. More...

void	ast_clear_prescalar (Ast *ast)
	Clear the AST periodic prescaler counter to zero. More...

uint32_t	ast_configure_digital_tuner (Ast *ast, uint32_t input_freq, uint32_t tuned_freq)
	Tune the AST prescaler frequency to the desired frequency. More...

void	ast_disable (Ast *ast)
	Disable the AST counter and module. More...

void	ast_disable_digital_tuner (Ast *ast)
	Disable the AST digital tuner. More...

void	ast_disable_event (Ast *ast, ast_event_source_t source)
	Disable an AST event. More...

void	ast_disable_interrupt (Ast *ast, ast_interrupt_source_t source)
	Disable an AST interrupt. More...

void	ast_disable_wakeup (Ast *ast, ast_wakeup_source_t source)
	Disable an AST asynchronous wake-up source. More...

void	ast_enable (Ast *ast)
	Enable the AST module. More...

void	ast_enable_counter_clear_on_alarm (Ast *ast, uint8_t alarm_channel)
	Enable the option to clear the counter on an AST alarm. More...

void	ast_enable_event (Ast *ast, ast_event_source_t source)
	Enable an AST event. More...

void	ast_enable_interrupt (Ast *ast, ast_interrupt_source_t source)
	Enable an AST interrupt. More...

void	ast_enable_wakeup (Ast *ast, ast_wakeup_source_t source)
	Enable an AST asynchronous wake-up source. More...

void	ast_init_digital_tuner (Ast *ast, bool add, uint8_t value, uint8_t exp)
	Initialize the AST digital tuner. More...

static bool	ast_is_busy (Ast *ast)
	Check the busy status of AST. More...

static bool	ast_is_clkbusy (Ast *ast)
	Check the busy status of the AST clock. More...

bool	ast_is_enabled (Ast *ast)
	Check the status of the AST module. More...

struct ast_calendar	ast_read_calendar_value (Ast *ast)
	Get the AST current calendar value. More...

static uint32_t	ast_read_counter_value (Ast *ast)
	Get the AST current counter value. More...

static uint32_t	ast_read_interrupt_mask (Ast *ast)
	Get the AST interrupt mask value. More...

static uint32_t	ast_read_status (Ast *ast)
	Get the status of AST. More...

void	ast_set_callback (Ast *ast, ast_interrupt_source_t source, ast_callback_t callback, uint8_t irq_line, uint8_t irq_level)
	Set callback for AST interrupts. More...

uint32_t	ast_set_config (Ast ast, struct ast_config ast_conf)
	Initialize and enable the AST module in Calendar Mode or Counter Mode. More...

static void	ast_start (Ast *ast)
	Start the AST counter. More...

static void	ast_stop (Ast *ast)
	Stop the AST counter. More...

void	ast_write_alarm0_value (Ast *ast, uint32_t alarm_value)
	Set the AST alarm0 value. More...

void	ast_write_calendar_value (Ast *ast, struct ast_calendar calendar)
	Set the AST current calendar value. More...

void	ast_write_counter_value (Ast *ast, uint32_t ast_counter)
	Set the AST current counter value. More...

void	ast_write_periodic0_value (Ast *ast, uint32_t pir)
	Set the AST periodic0 value. More...

Predefined PSEL Values
#define	AST_PSEL_32KHZ_1HZ 14
	The PSEL value to set the AST source clock (after the prescaler) to 1Hz, when using an external 32-kHz crystal. More...

#define	AST_PSEL_RC_1_76HZ 15
	The PSEL value to set the AST source clock (after the prescaler) to 1.76Hz when using the internal RC oscillator (~ 115kHz) More...

#define AST_POLL_TIMEOUT 10000

Timeout to prevent code hang in clock initialization.

Referenced by ast_set_config().

#define AST_PSEL_32KHZ_1HZ 14

The PSEL value to set the AST source clock (after the prescaler) to 1Hz, when using an external 32-kHz crystal.

Referenced by config_ast(), event_qtouch_init(), example_qtouch_init(), init_ast(), main(), run_alarm_test(), and run_periodic_test().

#define AST_PSEL_RC_1_76HZ 15

The PSEL value to set the AST source clock (after the prescaler) to 1.76Hz when using the internal RC oscillator (~ 115kHz)

typedef void(* ast_callback_t)(void)

AST interrupt callback.

typedef enum ast_event_source ast_event_source_t

AST event source.

typedef enum ast_interrupt_source ast_interrupt_source_t

AST interrupt source.

typedef enum ast_mode ast_mode_t

AST Calendar Mode.

typedef enum ast_oscillator_type ast_oscillator_type_t

AST Oscillator type.

typedef enum ast_wakeup_source ast_wakeup_source_t

AST wake-up source.

enum ast_event_source

AST event source.

Enumerator
AST_EVENT_ALARM	Alarm event generation.
AST_EVENT_PER	Peripheral event generation.
AST_EVENT_OVF	Counter overflow event generation.

enum ast_interrupt_source

AST interrupt source.

Enumerator
AST_INTERRUPT_ALARM	Alarm interrupt.
AST_INTERRUPT_PER	Periodic interrupt.
AST_INTERRUPT_OVF	Overflow interrupt.
AST_INTERRUPT_READY	Synchronization complete interrupt.
AST_INTERRUPT_CLKREADY	Clock synchronization complete interrupt.

enum ast_mode

AST Calendar Mode.

Enumerator
AST_COUNTER_MODE	Counter Mode.
AST_CALENDAR_MODE	Calendar Mode.

enum ast_oscillator_type

AST Oscillator type.

Enumerator
AST_OSC_RC	System RC oscillator (RCSYS)
AST_OSC_32KHZ	32kHz oscillator (OSC32 or RC32)
AST_OSC_PB	APB clock.
AST_OSC_GCLK	Generic clock (GCLK)
AST_OSC_1KHZ	1kHz clock from the 32kHz oscillator or 32kHz RC oscillator (CLK_1K)

enum ast_wakeup_source

AST wake-up source.

Enumerator
AST_WAKEUP_ALARM	Alarm wake-up source.
AST_WAKEUP_PER	Peripheral interrupt wake-up source.
AST_WAKEUP_OVF	Counter overflow wake-up source.

void ast_clear_interrupt_flag	(	Ast *	ast,
		ast_interrupt_source_t	source
	)

Clear an AST interrupt status flag.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST interrupt source for which the status is to be cleared

References AST_INTERRUPT_ALARM, AST_INTERRUPT_CLKREADY, AST_INTERRUPT_OVF, AST_INTERRUPT_PER, AST_INTERRUPT_READY, and ast_is_busy().

Referenced by ast_alarm_callback(), ast_per_callback(), ast_per_interrupt_callback(), config_ast(), event_qtouch_init(), example_qtouch_init(), main(), run_alarm_test(), and run_periodic_test().

void ast_clear_prescalar ( Ast * ast )

Clear the AST periodic prescaler counter to zero.

Parameters

[in,out] ast Module hardware register base address pointer

References ast_is_busy().

uint32_t ast_configure_digital_tuner	(	Ast *	ast,
		uint32_t	input_freq,
		uint32_t	tuned_freq
	)

Tune the AST prescaler frequency to the desired frequency.

Note: Refer to the section entitled "digital tuner" in the ast chapter of the device-specific datasheet for more information.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	input_freq	Prescaled AST Clock Frequency
[in]	tuned_freq	Desired AST frequency

References ast_init_digital_tuner(), and div_ceil.

void ast_disable ( Ast * ast )

Disable the AST counter and module.

Parameters

[in,out] ast Module hardware register base address pointer

References ast_is_busy(), SLEEPMGR_BACKUP, sleepmgr_unlock_mode(), and sysclk_disable_peripheral_clock().

Referenced by main(), run_alarm_test(), run_events_ast_test(), and run_periodic_test().

void ast_disable_digital_tuner ( Ast * ast )

Disable the AST digital tuner.

Parameters

[in,out] ast Module hardware register base address pointer

References ast_is_busy().

void ast_disable_event	(	Ast *	ast,
		ast_event_source_t	source
	)

Disable an AST event.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST event source to be disabled

References AST_EVENT_ALARM, AST_EVENT_OVF, AST_EVENT_PER, and ast_is_busy().

void ast_disable_interrupt	(	Ast *	ast,
		ast_interrupt_source_t	source
	)

Disable an AST interrupt.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST interrupt source to be disabled

References AST_INTERRUPT_ALARM, AST_INTERRUPT_CLKREADY, AST_INTERRUPT_OVF, AST_INTERRUPT_PER, AST_INTERRUPT_READY, and ast_is_busy().

Referenced by ast_alarm_callback(), ast_per_callback(), config_ast(), and run_periodic_test().

void ast_disable_wakeup	(	Ast *	ast,
		ast_wakeup_source_t	source
	)

Disable an AST asynchronous wake-up source.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST wake-up source to be disabled

References ast_is_busy(), AST_WAKEUP_ALARM, AST_WAKEUP_OVF, and AST_WAKEUP_PER.

Referenced by main().

void ast_enable ( Ast * ast )

Enable the AST module.

Parameters

[in] ast Module hardware register base address pointer

References SLEEPMGR_BACKUP, sleepmgr_lock_mode(), and sysclk_enable_peripheral_clock().

Referenced by config_ast(), event_qtouch_init(), example_qtouch_init(), init_ast(), main(), run_alarm_test(), and run_periodic_test().

void ast_enable_counter_clear_on_alarm	(	Ast *	ast,
		uint8_t	alarm_channel
	)

Enable the option to clear the counter on an AST alarm.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	alarm_channel	AST Alarm Channel

References ast_is_busy().

void ast_enable_event	(	Ast *	ast,
		ast_event_source_t	source
	)

Enable an AST event.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST event source to be enabled

References AST_EVENT_ALARM, AST_EVENT_OVF, AST_EVENT_PER, and ast_is_busy().

Referenced by init_ast(), and main().

void ast_enable_interrupt	(	Ast *	ast,
		ast_interrupt_source_t	source
	)

Enable an AST interrupt.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST interrupt source to be enabled

References AST_INTERRUPT_ALARM, AST_INTERRUPT_CLKREADY, AST_INTERRUPT_OVF, AST_INTERRUPT_PER, AST_INTERRUPT_READY, and ast_is_busy().

Referenced by ast_set_callback(), main(), run_alarm_test(), and run_periodic_test().

void ast_enable_wakeup	(	Ast *	ast,
		ast_wakeup_source_t	source
	)

Enable an AST asynchronous wake-up source.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST wake-up source to be enabled

References ast_is_busy(), AST_WAKEUP_ALARM, AST_WAKEUP_OVF, and AST_WAKEUP_PER.

Referenced by config_ast(), main(), run_alarm_test(), and run_periodic_test().

void ast_init_digital_tuner	(	Ast *	ast,
		bool	add,
		uint8_t	value,
		uint8_t	exp
	)

Initialize the AST digital tuner.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	add	Set to true if the frequency needs to be increased, false if it has to be decreased.
[in]	value	Parameter used in the formula
[in]	exp	Parameter used in the formula

References ast_is_busy().

Referenced by ast_configure_digital_tuner().

static bool ast_is_busy ( Ast * ast )

inlinestatic

Check the busy status of AST.

Parameters

[in] ast Module hardware register base address pointer

Returns: AST busy status.

Return values

false	AST is not busy
true	AST is busy

Referenced by ast_clear_interrupt_flag(), ast_clear_prescalar(), ast_disable(), ast_disable_digital_tuner(), ast_disable_event(), ast_disable_interrupt(), ast_disable_wakeup(), ast_enable_counter_clear_on_alarm(), ast_enable_event(), ast_enable_interrupt(), ast_enable_wakeup(), ast_init_digital_tuner(), ast_is_enabled(), ast_set_config(), ast_start(), ast_stop(), ast_write_alarm0_value(), ast_write_calendar_value(), ast_write_counter_value(), and ast_write_periodic0_value().

static bool ast_is_clkbusy ( Ast * ast )

inlinestatic

Check the busy status of the AST clock.

Parameters

[in] ast Module hardware register base address pointer

Returns: AST clock busy status.

Return values

false	AST clock is not busy
true	AST clock is busy

Referenced by ast_set_config().

bool ast_is_enabled ( Ast * ast )

Check the status of the AST module.

Parameters

[in,out] ast Module hardware register base address pointer

Return values

false	AST is not enabled
true	AST is enabled

References ast_is_busy().

struct ast_calendar ast_read_calendar_value ( Ast * ast )

Get the AST current calendar value.

Note: There maybe a compiler warning about returning a structure type value, however it is safe because ast_calendar is actually uint32_t type.

Parameters

[in] ast Module hardware register base address pointer

Returns: The AST current calendar value.

References ast_calendar::field.

Referenced by get_fattime(), and main().

static uint32_t ast_read_counter_value ( Ast * ast )

inlinestatic

Get the AST current counter value.

Parameters

[in] ast Module hardware register base address pointer

Returns: AST current counter value.

Referenced by main(), and run_alarm_test().

static uint32_t ast_read_interrupt_mask ( Ast * ast )

inlinestatic

Get the AST interrupt mask value.

Parameters

[in] ast Module hardware register base address pointer

Returns: AST Interrupt mask value.

Referenced by run_periodic_test().

static uint32_t ast_read_status ( Ast * ast )

inlinestatic

Get the status of AST.

Parameters

[in] ast Module hardware register base address pointer

Returns: AST status.

void ast_set_callback	(	Ast *	ast,
		ast_interrupt_source_t	source,
		ast_callback_t	callback,
		uint8_t	irq_line,
		uint8_t	irq_level
	)

Set callback for AST interrupts.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	source	AST interrupt source
[in]	callback	Callback function pointer
[in]	irq_line	Interrupt line
[in]	irq_level	Interrupt level

References ast_callback_pointer, ast_enable_interrupt(), and callback.

Referenced by config_ast(), event_qtouch_init(), example_qtouch_init(), main(), run_alarm_test(), and run_periodic_test().

uint32_t ast_set_config	(	Ast *	ast,
		struct ast_config *	ast_conf
	)

Initialize and enable the AST module in Calendar Mode or Counter Mode.

Note: If you use the 32kHz oscillator it will be enabled by this function.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	ast_conf	AST configuration structure pointer

Returns: Initialization result.

Return values

0	Initialization failed due to a software timeout
1	Initialization succeeded

References AST_CALENDAR_MODE, AST_COUNTER_MODE, ast_is_busy(), ast_is_clkbusy(), AST_POLL_TIMEOUT, ast_write_calendar_value(), ast_write_counter_value(), ast_config::calendar, ast_config::counter, ast_config::mode, ast_config::osc_type, and ast_config::psel.

Referenced by config_ast(), event_qtouch_init(), example_qtouch_init(), init_ast(), main(), run_alarm_test(), and run_periodic_test().

static void ast_start ( Ast * ast )

inlinestatic

Start the AST counter.

Parameters

[in,out] ast Module hardware register base address pointer

References ast_is_busy().

Referenced by main(), test_backup_mode(), test_retention_mode(), and test_wait_mode().

static void ast_stop ( Ast * ast )

inlinestatic

Stop the AST counter.

Parameters

[in,out] ast Module hardware register base address pointer

References ast_is_busy().

Referenced by ast_per_callback(), button_handler(), config_ast(), and eic_callback().

void ast_write_alarm0_value	(	Ast *	ast,
		uint32_t	alarm_value
	)

Set the AST alarm0 value.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	alarm_value	AST alarm0 value

References ast_is_busy().

Referenced by main(), and run_alarm_test().

void ast_write_calendar_value	(	Ast *	ast,
		struct ast_calendar	calendar
	)

Set the AST current calendar value.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	calendar	Startup date structure

References ast_is_busy(), and ast_calendar::field.

Referenced by ast_set_config().

void ast_write_counter_value	(	Ast *	ast,
		uint32_t	ast_counter
	)

Set the AST current counter value.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	ast_counter	Startup counter value

References ast_is_busy().

Referenced by ast_set_config(), button_handler(), and eic_callback().

void ast_write_periodic0_value	(	Ast *	ast,
		uint32_t	pir
	)

Set the AST periodic0 value.

Parameters

[in,out]	ast	Module hardware register base address pointer
[in]	pir	AST periodic0

References ast_is_busy().

Referenced by config_ast(), event_qtouch_init(), example_qtouch_init(), init_ast(), main(), and run_periodic_test().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Alarm Interrupt

Periodic Events

Digital Tuner

Special Considerations

Crystal Selection

Year Limit

Extra Information

Examples

API Overview

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Predefined PSEL Values