Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Frequency Meter (FREQM) Driver

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:

The following peripheral is used by this module:

The following devices can use this module:

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

Modules

 

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 for possible callback types for the FREQM module.

Enumerator
FREQM_CALLBACK_DONE 

Callback for measurement done.

FREQM callback type.

Enumerator
FREQM_CALLBACK_MEASURE_DONE 

Measurement done callback.

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]modulePointer to the FREQM software instance struct

References Assert.

Referenced by main().

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_instSoftware 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]modulePointer to the software instance struct
[in]typeCallback source type
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf 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_instSoftware instance for the Frequency Meter peripheral

References Assert, and freqm_is_syncing().

Referenced by main(), and 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]modulePointer to the software instance struct
[in]typeCallback source type
Returns
Status of the callback enable operation.
Return values
STATUS_OKThe callback was enabled successfully
STATUS_ERR_INVALID_ARGIf 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 configure_freqm_callback(), and 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]configConfiguration 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 configure_freqm(), and 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_instPointer to the FREQM software instance struct
[out]resultPointer to store the result value in
Returns
Status of the FREQM read request.
Return values
FREQM_STATUS_MEASURE_DONEMeasurement result was retrieved successfully
FREQM_STATUS_MEASURE_BUSYMeasurement result was not ready
FREQM_STATUS_CNT_OVERFLOWMeasurement 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 main(), 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_instPointer to the software module instance struct
[in]hwPointer to the FREQM hardware module
[in]configPointer to the FREQM configuration options struct
Returns
Status of the initialization procedure.
Return values
STATUS_OKThe module was initialized successfully

References _freqm_instance, Assert, FREQM_GCLK_ID_REF, freqm_is_syncing(), i, module_inst, freqm_config::msr_clock_source, NULL, 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 configure_freqm(), and 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
falseIf the module has completed synchronization
trueIf 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]modulePointer to FREQM software instance struct
[in]callback_funcPointer to callback function
[in]callback_typeCallback type given by an enum
Return values
STATUS_OKThe function exited successfully

References Assert, FREQM_CALLBACK_TYPE_NUM, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by configure_freqm_callback(), and run_freqm_callback_read_test().

static void freqm_start_measure ( struct freqm_module *const  module)
inlinestatic

Start a manual measurement process.

Parameters
[in]modulePointer to the FREQM software instance struct

References Assert.

Referenced by main(), 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]modulePointer to FREQM software instance struct
[in]callback_typeCallback type given by an enum
Return values
STATUS_OKThe function exited successfully

References Assert, FREQM_CALLBACK_TYPE_NUM, NULL, STATUS_ERR_INVALID_ARG, and STATUS_OK.

struct freqm_module* _freqm_instance

Referenced by FREQM_Handler(), and freqm_init().