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

The following driver API modes are covered by this manual:

Polled APIs
Callback APIs

The following peripheral is used by this module:

FREQM (Frequency Meter)

The following devices can use this module:

Atmel | SMART SAM L22
Atmel | SMART SAM C20
Atmel | SMART SAM C21

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The module accurately measures the frequency of a clock by comparing it to a known reference clock as soon as the FREQM is enabled. Two generic clocks are used by the FREQM. The frequency of the measured clock is:

\[ f_{CLK\_MSR} = \frac{VALUE}{REFNUM} \times f_{CLK\_REF} \]

Ratio can be measured with 24-bit accuracy.

The FREQM has one interrupt source, which generates when a frequency measurement is done. It can be used to wake up the device from sleep modes.

This driver provides an interface for the FREQM functions on the device.

Special Considerations

There are no special considerations for this module.

Extra Information

For extra information see Extra Information for FREQM Driver. This includes:

Examples

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

API Overview

Data Structures
struct	freqm_config
	FREQM module configuration structure. More...

struct	freqm_module
	FREQM software device instance structure. More...

Typedefs
typedef void(*	freqm_callback_t )(void)
	Type definition for a FREQM module callback function. More...

Enumerations
enum	freqm_callback { FREQM_CALLBACK_DONE = 0 }
	Enum for possible callback types for the FREQM module. More...

enum	freqm_callback_type { FREQM_CALLBACK_MEASURE_DONE = 0 }
	FREQM callback type. More...

enum	freqm_status { FREQM_STATUS_MEASURE_DONE = 0, FREQM_STATUS_MEASURE_BUSY = 1, FREQM_STATUS_CNT_OVERFLOW = 2 }
	Enum for the possible status types for the FREQM module. More...

Functions
static bool	freqm_is_syncing (void)
	Determines if the hardware module(s) are currently synchronizing to the bus. More...

Variables
struct freqm_module *	_freqm_instance

Driver Initialization and Configuration
enum status_code	freqm_init (struct freqm_module const module_inst, Freqm const hw, struct freqm_config *const config)
	Initializes a hardware FREQM module instance. More...

static void	freqm_get_config_defaults (struct freqm_config *const config)
	Initializes all members of a FREQM configuration structure to safe defaults. More...

static void	freqm_enable (struct freqm_module *const module_inst)
	Enables a FREQM that was previously configured. More...

static void	freqm_disable (struct freqm_module *const module_inst)
	Disables a FREQM that was previously enabled. More...

Read FREQM Result
static void	freqm_start_measure (struct freqm_module *const module)
	Start a manual measurement process. More...

static void	freqm_clear_overflow (struct freqm_module *const module)
	Clears module overflow flag. More...

enum freqm_status	freqm_get_result_value (struct freqm_module const module_inst, uint32_t result)
	Read the measurement data result. More...

Callback Configuration and Initialization
enum status_code	freqm_register_callback (struct freqm_module *const module, freqm_callback_t callback_func, enum freqm_callback callback_type)
	Registers a callback. More...

enum status_code	freqm_unregister_callback (struct freqm_module *module, enum freqm_callback callback_type)
	Unregisters a callback. More...

Callback Enabling and Disabling
static enum status_code	freqm_enable_callback (struct freqm_module *const module, const enum freqm_callback_type type)
	Enable an FREQM callback. More...

static enum status_code	freqm_disable_callback (struct freqm_module *const module, const enum freqm_callback_type type)
	Disable an FREQM callback. More...

typedef void(* freqm_callback_t)(void)

Type definition for a FREQM module callback function.

enum freqm_callback

Enum for possible callback types for the FREQM module.

Enumerator
FREQM_CALLBACK_DONE	Callback for measurement done.

enum freqm_callback_type

FREQM callback type.

Enumerator
FREQM_CALLBACK_MEASURE_DONE	Measurement done callback.

enum freqm_status

Enum for the possible status types for the FREQM module.

Enumerator
FREQM_STATUS_MEASURE_DONE	FREQM measurement is finish.
FREQM_STATUS_MEASURE_BUSY	FREQM measurement is ongoing or not.
FREQM_STATUS_CNT_OVERFLOW	FREQM sticky count value overflow.

static void freqm_clear_overflow ( struct freqm_module *const module )

inlinestatic

Clears module overflow flag.

Clears the overflow flag of the module.

Parameters

[in] module Pointer to the FREQM software instance struct

References Assert.

static void freqm_disable ( struct freqm_module *const module_inst )

inlinestatic

Disables a FREQM that was previously enabled.

Disables Frequency Meter that was previously started via a call to freqm_enable().

Parameters

[in] module_inst Software instance for the Frequency Meter peripheral

References Assert, and freqm_is_syncing().

Referenced by run_freqm_callback_read_test().

static enum status_code freqm_disable_callback	(	struct freqm_module *const	module,
		const enum freqm_callback_type	type
	)

inlinestatic

Disable an FREQM callback.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	type	Callback source type

Returns: Status of the callback enable operation.

Return values

STATUS_OK	The callback was enabled successfully
STATUS_ERR_INVALID_ARG	If an invalid callback type was supplied

References Assert, FREQM_CALLBACK_MEASURE_DONE, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_disable(), and SYSTEM_INTERRUPT_MODULE_FREQM.

Referenced by run_freqm_callback_read_test().

static void freqm_enable ( struct freqm_module *const module_inst )

inlinestatic

Enables a FREQM that was previously configured.

Enables Frequency Meter that was previously configured via a call to freqm_init().

Parameters

[in] module_inst Software instance for the Frequency Meter peripheral

References Assert, and freqm_is_syncing().

Referenced by run_freqm_polling_read_test().

static enum status_code freqm_enable_callback	(	struct freqm_module *const	module,
		const enum freqm_callback_type	type
	)

inlinestatic

Enable an FREQM callback.

Parameters

[in,out]	module	Pointer to the software instance struct
[in]	type	Callback source type

Returns: Status of the callback enable operation.

Return values

STATUS_OK	The callback was enabled successfully
STATUS_ERR_INVALID_ARG	If an invalid callback type was supplied

References Assert, FREQM_CALLBACK_MEASURE_DONE, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_enable(), and SYSTEM_INTERRUPT_MODULE_FREQM.

Referenced by run_freqm_callback_read_test().

static void freqm_get_config_defaults ( struct freqm_config *const config )

inlinestatic

Initializes all members of a FREQM configuration structure to safe defaults.

Initializes all members of a given Frequency Meter configuration structure to safe known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

Measurement clock source is GCLK0
Reference clock source is GCLK1
Frequency Meter Reference Clock Cycles 127

Parameters

[in] config Configuration structure to initialize to default values

References Assert, GCLK_GENERATOR_0, GCLK_GENERATOR_1, freqm_config::msr_clock_source, freqm_config::ref_clock_circles, and freqm_config::ref_clock_source.

Referenced by run_freqm_polling_read_test().

enum freqm_status freqm_get_result_value	(	struct freqm_module *const	module_inst,
		uint32_t *	result
	)

Read the measurement data result.

Reads the measurement data result.

Parameters

[in]	module_inst	Pointer to the FREQM software instance struct
[out]	result	Pointer to store the result value in

Returns: Status of the FREQM read request.

Return values

FREQM_STATUS_MEASURE_DONE	Measurement result was retrieved successfully
FREQM_STATUS_MEASURE_BUSY	Measurement result was not ready
FREQM_STATUS_CNT_OVERFLOW	Measurement result was overflow

Note: If overflow occurred, configure faster reference clock or reduce reference clock cycles.

References Assert, FREQM_STATUS_CNT_OVERFLOW, FREQM_STATUS_MEASURE_BUSY, and FREQM_STATUS_MEASURE_DONE.

Referenced by run_freqm_callback_read_test(), and run_freqm_polling_read_test().

enum status_code freqm_init	(	struct freqm_module *const	module_inst,
		Freqm *const	hw,
		struct freqm_config *const	config
	)

Initializes a hardware FREQM module instance.

Enables the clock and initializes the FREQM module, based on the given configuration values.

Parameters

[in,out]	module_inst	Pointer to the software module instance struct
[in]	hw	Pointer to the FREQM hardware module
[in]	config	Pointer to the FREQM configuration options struct

Returns: Status of the initialization procedure.

Return values

STATUS_OK The module was initialized successfully

References _freqm_instance, Assert, FREQM_GCLK_ID_REF, freqm_is_syncing(), freqm_config::msr_clock_source, freqm_config::ref_clock_circles, freqm_config::ref_clock_source, system_gclk_chan_config::source_generator, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBA, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), system_gclk_chan_set_config(), and system_gclk_gen_get_hz().

Referenced by run_freqm_polling_read_test().

static bool freqm_is_syncing ( void )

inlinestatic

Determines if the hardware module(s) are currently synchronizing to the bus.

Checks to see if the underlying hardware peripheral module(s) are currently synchronizing across multiple clock domains to the hardware bus. This function can be used to delay further operations on a module until such time that it is ready, to prevent blocking delays for synchronization in the user application.

Returns: Synchronization status of the underlying hardware module(s).

Return values

false	If the module has completed synchronization
true	If the module synchronization is ongoing

Referenced by freqm_disable(), freqm_enable(), and freqm_init().

enum status_code freqm_register_callback	(	struct freqm_module *const	module,
		freqm_callback_t	callback_func,
		enum freqm_callback	callback_type
	)

Registers a callback.

Registers a callback function which is implemented by the user.

Note: The callback must be enabled by freqm_enable_callback, in order for the interrupt handler to call it when the conditions for the callback type is met.

Parameters

[in]	module	Pointer to FREQM software instance struct
[in]	callback_func	Pointer to callback function
[in]	callback_type	Callback type given by an enum

Return values

STATUS_OK The function exited successfully

References Assert, FREQM_CALLBACK_TYPE_NUM, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by run_freqm_callback_read_test().

static void freqm_start_measure ( struct freqm_module *const module )

inlinestatic

Start a manual measurement process.

Parameters

[in] module Pointer to the FREQM software instance struct

References Assert.

Referenced by run_freqm_callback_read_test(), and run_freqm_polling_read_test().

enum status_code freqm_unregister_callback	(	struct freqm_module *	module,
		enum freqm_callback	callback_type
	)

Unregisters a callback.

Unregisters a callback function implemented by the user. The callback should be disabled before it is unregistered.

Parameters

[in]	module	Pointer to FREQM software instance struct
[in]	callback_type	Callback type given by an enum

Return values

STATUS_OK The function exited successfully

References Assert, FREQM_CALLBACK_TYPE_NUM, STATUS_ERR_INVALID_ARG, and STATUS_OK.

struct freqm_module* _freqm_instance

Referenced by FREQM_Handler(), and freqm_init().

Microchip® Advanced Software Framework

Prerequisites

Module Overview

Special Considerations

Extra Information

Examples

API Overview

Data Structures

Typedefs

Enumerations

Functions

Variables

Driver Initialization and Configuration

Read FREQM Result

Callback Configuration and Initialization

Callback Enabling and Disabling