Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Timer/Counter (TC) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of the timer modules within the device, for waveform generation and timing operations.

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 Timer/Counter (TC) module provides a set of timing and counting related functionality, such as the generation of periodic waveforms, the capturing of a periodic waveform's frequency/duty cycle, and software timekeeping for periodic operations. TC modules can be configured to use an 8-, 16-, or 32-bit counter size.

This TC module for the SAM is capable of the following functions:

The diagram below shows the overview of the TC module design.

overview.svg
Basic Overview of the TC Module

Driver Feature Macro Definition

Driver Feature Macro Supported devices
FEATURE_TC_DOUBLE_BUFFERED SAM L21/L22/C20/C21/R30/R34/R35
FEATURE_TC_SYNCBUSY_SCHEME_VERSION_2 SAM L21/L22/C20/C21/R30/R34/R35
FEATURE_TC_STAMP_PW_CAPTURE SAM L21/L22/C20/C21/R30/R34/R35
FEATURE_TC_READ_SYNC SAM L21/L22/C20/C21/R30/R34/R35
FEATURE_TC_IO_CAPTURE SAM L21/L22/C20/C21/R30/R34/R35
FEATURE_TC_GENERATE_DMA_TRIGGER SAM L21/L22/R30/R34/R35
Note
The specific features are only available in the driver when the selected device supports those features.

Functional Description

Independent of the configured counter size, each TC module can be set up in one of two different modes; capture and compare.

In capture mode, the counter value is stored when a configurable event occurs. This mode can be used to generate timestamps used in event capture, or it can be used for the measurement of a periodic input signal's frequency/duty cycle.

In compare mode, the counter value is compared against one or more of the configured channel compare values. When the counter value coincides with a compare value an action can be taken automatically by the module, such as generating an output event or toggling a pin when used for frequency or Pulse Width Modulation (PWM) signal generation.

Note
The connection of events between modules requires the use of the SAM Event System Driver (EVENTS) to route output event of one module to the input event of another. For more information on event routing, refer to the event driver documentation.

Timer/Counter Size

Each timer module can be configured in one of three different counter sizes; 8-, 16-, and 32-bit. The size of the counter determines the maximum value it can count to before an overflow occurs and the count is reset back to zero. The table below shows the maximum values for each of the possible counter sizes.

Timer Counter Sizes and Their Maximum Count Values
Counter size Max. (hexadecimal) Max. (decimal)
8-bit 0xFF 255
16-bit 0xFFFF 65,535
32-bit 0xFFFFFFFF 4,294,967,295

When using the counter in 16- or 32-bit count mode, Compare Capture register 0 (CC0) is used to store the period value when running in PWM generation match mode.

When using 32-bit counter size, two 16-bit counters are chained together in a cascade formation. Except in SAM D09/D10/D11. Even numbered TC modules (e.g. TC0, TC2) can be configured as 32-bit counters. The odd numbered counters will act as slaves to the even numbered masters, and will not be reconfigurable until the master timer is disabled. The pairing of timer modules for 32-bit mode is shown in the table below.

TC Master and Slave Module Pairings
Master TC module Slave TC module
TC0 TC1
TC2 TC3
... ...
TCn-1 TCn

In SAM D09/D10/D11, odd numbered TC modules (e.g. TC1) can be configured as 32-bit counters. The even numbered (e.g. TC2) counters will act as slaves to the odd numbered masters.

Clock Settings

Clock Selection

Each TC peripheral is clocked asynchronously to the system clock by a GCLK (Generic Clock) channel. The GCLK channel connects to any of the GCLK generators. The GCLK generators are configured to use one of the available clock sources on the system such as internal oscillator, external crystals, etc. See the Generic Clock driver for more information.

Prescaler

Each TC module in the SAM has its own individual clock prescaler, which can be used to divide the input clock frequency used in the counter. This prescaler only scales the clock used to provide clock pulses for the counter to count, and does not affect the digital register interface portion of the module, thus the timer registers will synchronize to the raw GCLK frequency input to the module.

As a result of this, when selecting a GCLK frequency and timer prescaler value the user application should consider both the timer resolution required and the synchronization frequency, to avoid lengthy synchronization times of the module if a very slow GCLK frequency is fed into the TC module. It is preferable to use a higher module GCLK frequency as the input to the timer, and prescale this down as much as possible to obtain a suitable counter frequency in latency-sensitive applications.

Reloading

Timer modules also contain a configurable reload action, used when a re-trigger event occurs. Examples of a re-trigger event are the counter reaching the maximum value when counting up, or when an event from the event system tells the counter to re-trigger. The reload action determines if the prescaler should be reset, and when this should happen. The counter will always be reloaded with the value it is set to start counting from. The user can choose between three different reload actions, described in the table below.

TC Module Reload Actions
Reload action Description
TC_RELOAD_ACTION_GCLK Reload TC counter value on next GCLK cycle. Leave prescaler as-is.
TC_RELOAD_ACTION_PRESC Reloads TC counter value on next prescaler clock. Leave prescaler as-is.
TC_RELOAD_ACTION_RESYNC Reload TC counter value on next GCLK cycle. Clear prescaler to zero.

The reload action to use will depend on the specific application being implemented. One example is when an external trigger for a reload occurs; if the TC uses the prescaler, the counter in the prescaler should not have a value between zero and the division factor. The TC counter and the counter in the prescaler should both start at zero. When the counter is set to re-trigger when it reaches the maximum value on the other hand, this is not the right option to use. In such a case it would be better if the prescaler is left unaltered when the re-trigger happens, letting the counter reset on the next GCLK cycle.

Compare Match Operations

In compare match operation, Compare/Capture registers are used in comparison with the counter value. When the timer's count value matches the value of a compare channel, a user defined action can be taken.

Basic Timer

A Basic Timer is a simple application where compare match operations are used to determine when a specific period has elapsed. In Basic Timer operations, one or more values in the module's Compare/Capture registers are used to specify the time (as a number of prescaled GCLK cycles) when an action should be taken by the microcontroller. This can be an Interrupt Service Routine (ISR), event generator via the event system, or a software flag that is polled via the user application.

Waveform Generation

Waveform generation enables the TC module to generate square waves, or if combined with an external passive low-pass filter; analog waveforms.

Waveform Generation - PWM

Pulse width modulation is a form of waveform generation and a signalling technique that can be useful in many situations. When PWM mode is used, a digital pulse train with a configurable frequency and duty cycle can be generated by the TC module and output to a GPIO pin of the device.

Often PWM is used to communicate a control or information parameter to an external circuit or component. Differing impedances of the source generator and sink receiver circuits are less of an issue when using PWM compared to using an analog voltage value, as noise will not generally affect the signal's integrity to a meaningful extent.

The figure below illustrates operations and different states of the counter and its output when running the counter in PWM normal mode. As can be seen, the TOP value is unchanged and is set to MAX. The compare match value is changed at several points to illustrate the resulting waveform output changes. The PWM output is set to normal (i.e. non-inverted) output mode.

pwm_normal_ex.svg
Example of PWM in Normal Mode, and Different Counter Operations

In the figure below, the counter is set to generate PWM in Match mode. The PWM output is inverted via the appropriate configuration option in the TC driver configuration structure. In this example, the counter value is changed once, but the compare match value is kept unchanged. As can be seen, it is possible to change the TOP value when running in PWM match mode.

pwm_match_ex.svg
Example of PWM in Match Mode and Different Counter Operations

Waveform Generation - Frequency

Frequency Generation mode is in many ways identical to PWM generation. However, in Frequency Generation a toggle only occurs on the output when a match on a capture channels occurs. When the match is made, the timer value is reset, resulting in a variable frequency square wave with a fixed 50% duty cycle.

Capture Operations

In capture operations, any event from the event system or a pin change can trigger a capture of the counter value. This captured counter value can be used as a timestamp for the event, or it can be used in frequency and pulse width capture.

Capture Operations - Event

Event capture is a simple use of the capture functionality, designed to create timestamps for specific events. When the TC module's input capture pin is externally toggled, the current timer count value is copied into a buffered register which can then be read out by the user application.

Note that when performing any capture operation, there is a risk that the counter reaches its top value (MAX) when counting up, or the bottom value (zero) when counting down, before the capture event occurs. This can distort the result, making event timestamps to appear shorter than reality; the user application should check for timer overflow when reading a capture result in order to detect this situation and perform an appropriate adjustment.

Before checking for a new capture, TC_STATUS_COUNT_OVERFLOW should be checked. The response to an overflow error is left to the user application, however it may be necessary to clear both the capture overflow flag and the capture flag upon each capture reading.

Capture Operations - Pulse Width

Pulse Width Capture mode makes it possible to measure the pulse width and period of PWM signals. This mode uses two capture channels of the counter. This means that the counter module used for Pulse Width Capture can not be used for any other purpose. There are two modes for pulse width capture; Pulse Width Period (PWP) and Period Pulse Width (PPW). In PWP mode, capture channel 0 is used for storing the pulse width and capture channel 1 stores the observed period. While in PPW mode, the roles of the two capture channels are reversed.

As in the above example it is necessary to poll on interrupt flags to see if a new capture has happened and check that a capture overflow error has not occurred.

One-shot Mode

TC modules can be configured into a one-shot mode. When configured in this manner, starting the timer will cause it to count until the next overflow or underflow condition before automatically halting, waiting to be manually triggered by the user application software or an event signal from the event system.

Wave Generation Output Inversion

The output of the wave generation can be inverted by hardware if desired, resulting in the logically inverted value being output to the configured device GPIO pin.

Special Considerations

The number of capture compare registers in each TC module is dependent on the specific SAM device being used, and in some cases the counter size.

The maximum amount of capture compare registers available in any SAM device is two when running in 32-bit mode and four in 8- and 16-bit modes.

Extra Information

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

Examples

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

API Overview

Modules

 

Data Structures

struct  tc_16bit_config
 Configuration struct for TC module in 16-bit size counter mode. More...
 
struct  tc_32bit_config
 Configuration struct for TC module in 32-bit size counter mode. More...
 
struct  tc_8bit_config
 Configuration struct for TC module in 8-bit size counter mode. More...
 
struct  tc_config
 TC configuration structure. More...
 
struct  tc_events
 TC event enable/disable structure. More...
 
struct  tc_module
 TC software device instance structure. More...
 
struct  tc_pwm_channel
 Configuration struct for TC module in 32-bit size counter mode. More...
 

Enumerations

enum  tc_callback {
  TC_CALLBACK_OVERFLOW,
  TC_CALLBACK_ERROR,
  TC_CALLBACK_CC_CHANNEL0,
  TC_CALLBACK_CC_CHANNEL1
}
 Enum for the possible callback types for the TC module. More...
 
enum  tc_clock_prescaler {
  TC_CLOCK_PRESCALER_DIV1 = TC_CTRLA_PRESCALER(0),
  TC_CLOCK_PRESCALER_DIV2 = TC_CTRLA_PRESCALER(1),
  TC_CLOCK_PRESCALER_DIV4 = TC_CTRLA_PRESCALER(2),
  TC_CLOCK_PRESCALER_DIV8 = TC_CTRLA_PRESCALER(3),
  TC_CLOCK_PRESCALER_DIV16 = TC_CTRLA_PRESCALER(4),
  TC_CLOCK_PRESCALER_DIV64 = TC_CTRLA_PRESCALER(5),
  TC_CLOCK_PRESCALER_DIV256 = TC_CTRLA_PRESCALER(6),
  TC_CLOCK_PRESCALER_DIV1024 = TC_CTRLA_PRESCALER(7)
}
 TC clock prescaler values. More...
 
enum  tc_compare_capture_channel {
  TC_COMPARE_CAPTURE_CHANNEL_0,
  TC_COMPARE_CAPTURE_CHANNEL_1
}
 Index of the compare capture channels. More...
 
enum  tc_count_direction {
  TC_COUNT_DIRECTION_UP,
  TC_COUNT_DIRECTION_DOWN
}
 TC module count direction. More...
 
enum  tc_counter_size {
  TC_COUNTER_SIZE_8BIT = TC_CTRLA_MODE_COUNT8,
  TC_COUNTER_SIZE_16BIT = TC_CTRLA_MODE_COUNT16,
  TC_COUNTER_SIZE_32BIT = TC_CTRLA_MODE_COUNT32
}
 Specifies if the counter is 8-, 16-, or 32-bit. More...
 
enum  tc_reload_action {
  TC_RELOAD_ACTION_GCLK = TC_CTRLA_PRESCSYNC_GCLK,
  TC_RELOAD_ACTION_PRESC = TC_CTRLA_PRESCSYNC_PRESC,
  TC_RELOAD_ACTION_RESYNC = TC_CTRLA_PRESCSYNC_RESYNC
}
 TC Counter reload action enum. More...
 
enum  tc_wave_generation {
  TC_WAVE_GENERATION_NORMAL_FREQ = TC_WAVE_GENERATION_NORMAL_FREQ_MODE,
  TC_WAVE_GENERATION_MATCH_FREQ = TC_WAVE_GENERATION_MATCH_FREQ_MODE,
  TC_WAVE_GENERATION_NORMAL_PWM = TC_WAVE_GENERATION_NORMAL_PWM_MODE,
  TC_WAVE_GENERATION_MATCH_PWM = TC_WAVE_GENERATION_MATCH_PWM_MODE
}
 TC wave generation mode enum. More...
 
#define FEATURE_TC_DOUBLE_BUFFERED
 Define port features set according to different device family. More...
 
#define FEATURE_TC_SYNCBUSY_SCHEME_VERSION_2
 SYNCBUSY scheme version 2. More...
 
#define FEATURE_TC_STAMP_PW_CAPTURE
 TC time stamp capture and pulse width capture. More...
 
#define FEATURE_TC_READ_SYNC
 Read synchronization of COUNT. More...
 
#define FEATURE_TC_IO_CAPTURE
 I/O pin edge capture. More...
 
#define FEATURE_TC_GENERATE_DMA_TRIGGER
 Generate Direct Memory Access (DMA) triggers. More...
 

Module Status Flags

TC status flags, returned by tc_get_status() and cleared by tc_clear_status().

#define TC_STATUS_CHANNEL_0_MATCH   (1UL << 0)
 Timer channel 0 has matched against its compare value, or has captured a new value. More...
 
#define TC_STATUS_CHANNEL_1_MATCH   (1UL << 1)
 Timer channel 1 has matched against its compare value, or has captured a new value. More...
 
#define TC_STATUS_SYNC_READY   (1UL << 2)
 Timer register synchronization has completed, and the synchronized count value may be read. More...
 
#define TC_STATUS_CAPTURE_OVERFLOW   (1UL << 3)
 A new value was captured before the previous value was read, resulting in lost data. More...
 
#define TC_STATUS_COUNT_OVERFLOW   (1UL << 4)
 The timer count value has overflowed from its maximum value to its minimum when counting upward, or from its minimum value to its maximum when counting downward. More...
 
#define TC_STATUS_CHN0_BUFFER_VALID   (1UL << 5)
 Channel 0 compare or capture buffer valid. More...
 
#define TC_STATUS_CHN1_BUFFER_VALID   (1UL << 6)
 Channel 1 compare or capture buffer valid. More...
 
#define TC_STATUS_PERIOD_BUFFER_VALID   (1UL << 7)
 Period buffer valid. More...
 

TC Wave Generation Mode

#define TC_WAVE_GENERATION_NORMAL_FREQ_MODE   TC_CTRLA_WAVEGEN_NFRQ
 TC wave generation mode: normal frequency. More...
 
#define TC_WAVE_GENERATION_MATCH_FREQ_MODE   TC_CTRLA_WAVEGEN_MFRQ
 TC wave generation mode: match frequency. More...
 
#define TC_WAVE_GENERATION_NORMAL_PWM_MODE   TC_CTRLA_WAVEGEN_NPWM
 TC wave generation mode: normal PWM. More...
 
#define TC_WAVE_GENERATION_MATCH_PWM_MODE   TC_CTRLA_WAVEGEN_MPWM
 TC wave generation mode: match PWM. More...
 

Waveform Inversion Mode

enum  tc_waveform_invert_output {
  TC_WAVEFORM_INVERT_OUTPUT_NONE = 0,
  TC_WAVEFORM_INVERT_OUTPUT_CHANNEL_0 = TC_WAVEFORM_INVERT_CC0_MODE,
  TC_WAVEFORM_INVERT_OUTPUT_CHANNEL_1 = TC_WAVEFORM_INVERT_CC1_MODE
}
 Waveform inversion mode. More...
 
enum  tc_event_action {
  TC_EVENT_ACTION_OFF = TC_EVCTRL_EVACT_OFF,
  TC_EVENT_ACTION_RETRIGGER = TC_EVCTRL_EVACT_RETRIGGER,
  TC_EVENT_ACTION_INCREMENT_COUNTER = TC_EVCTRL_EVACT_COUNT,
  TC_EVENT_ACTION_START = TC_EVCTRL_EVACT_START,
  TC_EVENT_ACTION_PPW = TC_EVCTRL_EVACT_PPW,
  TC_EVENT_ACTION_PWP = TC_EVCTRL_EVACT_PWP,
  TC_EVENT_ACTION_STAMP = TC_EVCTRL_EVACT_STAMP,
  TC_EVENT_ACTION_PW = TC_EVCTRL_EVACT_PW
}
 Action to perform when the TC module is triggered by an event. More...
 
typedef void(* tc_callback_t )(struct tc_module *const module)
 Type of the callback functions. More...
 
#define TC_WAVEFORM_INVERT_CC0_MODE   TC_CTRLC_INVEN(1)
 Waveform inversion CC0 mode. More...
 
#define TC_WAVEFORM_INVERT_CC1_MODE   TC_CTRLC_INVEN(2)
 Waveform inversion CC1 mode. More...
 

Driver Initialization and Configuration

static bool tc_is_syncing (const struct tc_module *const module_inst)
 Determines if the hardware module(s) are currently synchronizing to the bus. More...
 
static void tc_get_config_defaults (struct tc_config *const config)
 Initializes config with predefined default values. More...
 
enum status_code tc_init (struct tc_module *const module_inst, Tc *const hw, const struct tc_config *const config)
 Initializes a hardware TC module instance. More...
 

Event Management

static void tc_enable_events (struct tc_module *const module_inst, struct tc_events *const events)
 Enables a TC module event input or output. More...
 
static void tc_disable_events (struct tc_module *const module_inst, struct tc_events *const events)
 Disables a TC module event input or output. More...
 

Enable/Disable/Reset

enum status_code tc_reset (const struct tc_module *const module_inst)
 Resets the TC module. More...
 
static void tc_enable (const struct tc_module *const module_inst)
 Enable the TC module. More...
 
static void tc_disable (const struct tc_module *const module_inst)
 Disables the TC module. More...
 

Get/Set Count Value

uint32_t tc_get_count_value (const struct tc_module *const module_inst)
 Get TC module count value. More...
 
enum status_code tc_set_count_value (const struct tc_module *const module_inst, const uint32_t count)
 Sets TC module count value. More...
 

Start/Stop Counter

static void tc_stop_counter (const struct tc_module *const module_inst)
 Stops the counter. More...
 
static void tc_start_counter (const struct tc_module *const module_inst)
 Starts the counter. More...
 

Double Buffering

static void tc_update_double_buffer (const struct tc_module *const module_inst)
 Update double buffer. More...
 

Count Read Synchronization

static void tc_sync_read_count (const struct tc_module *const module_inst)
 Read synchronization of COUNT. More...
 

Generate TC DMA Triggers Command

static void tc_dma_trigger_command (const struct tc_module *const module_inst)
 TC DMA Trigger. More...
 

Get Capture Set Compare

uint32_t tc_get_capture_value (const struct tc_module *const module_inst, const enum tc_compare_capture_channel channel_index)
 Gets the TC module capture value. More...
 
enum status_code tc_set_compare_value (const struct tc_module *const module_inst, const enum tc_compare_capture_channel channel_index, const uint32_t compare_value)
 Sets a TC module compare value. More...
 

Set Top Value

enum status_code tc_set_top_value (const struct tc_module *const module_inst, const uint32_t top_value)
 Set the timer TOP/period value. More...
 

Status Management

static uint32_t tc_get_status (struct tc_module *const module_inst)
 Retrieves the current module status. More...
 
static void tc_clear_status (struct tc_module *const module_inst, const uint32_t status_flags)
 Clears a module status flag. More...
 

#define FEATURE_TC_DOUBLE_BUFFERED

Define port features set according to different device family.

TC double buffered.

#define FEATURE_TC_GENERATE_DMA_TRIGGER

Generate Direct Memory Access (DMA) triggers.

#define FEATURE_TC_IO_CAPTURE

I/O pin edge capture.

#define FEATURE_TC_READ_SYNC

Read synchronization of COUNT.

#define FEATURE_TC_STAMP_PW_CAPTURE

TC time stamp capture and pulse width capture.

#define FEATURE_TC_SYNCBUSY_SCHEME_VERSION_2

SYNCBUSY scheme version 2.

#define TC_STATUS_CAPTURE_OVERFLOW   (1UL << 3)

A new value was captured before the previous value was read, resulting in lost data.

Referenced by tc_clear_status(), and tc_get_status().

#define TC_STATUS_CHANNEL_0_MATCH   (1UL << 0)

Timer channel 0 has matched against its compare value, or has captured a new value.

Referenced by tc_clear_status(), and tc_get_status().

#define TC_STATUS_CHANNEL_1_MATCH   (1UL << 1)

Timer channel 1 has matched against its compare value, or has captured a new value.

Referenced by tc_clear_status(), and tc_get_status().

#define TC_STATUS_CHN0_BUFFER_VALID   (1UL << 5)

Channel 0 compare or capture buffer valid.

Referenced by tc_get_status().

#define TC_STATUS_CHN1_BUFFER_VALID   (1UL << 6)

Channel 1 compare or capture buffer valid.

Referenced by tc_get_status().

#define TC_STATUS_COUNT_OVERFLOW   (1UL << 4)

The timer count value has overflowed from its maximum value to its minimum when counting upward, or from its minimum value to its maximum when counting downward.

Referenced by run_callback_test(), tc_clear_status(), and tc_get_status().

#define TC_STATUS_PERIOD_BUFFER_VALID   (1UL << 7)

Period buffer valid.

Referenced by tc_get_status().

#define TC_STATUS_SYNC_READY   (1UL << 2)

Timer register synchronization has completed, and the synchronized count value may be read.

Referenced by tc_clear_status(), and tc_get_status().

#define TC_WAVE_GENERATION_MATCH_FREQ_MODE   TC_CTRLA_WAVEGEN_MFRQ

TC wave generation mode: match frequency.

#define TC_WAVE_GENERATION_MATCH_PWM_MODE   TC_CTRLA_WAVEGEN_MPWM

TC wave generation mode: match PWM.

#define TC_WAVE_GENERATION_NORMAL_FREQ_MODE   TC_CTRLA_WAVEGEN_NFRQ

TC wave generation mode: normal frequency.

#define TC_WAVE_GENERATION_NORMAL_PWM_MODE   TC_CTRLA_WAVEGEN_NPWM

TC wave generation mode: normal PWM.

#define TC_WAVEFORM_INVERT_CC0_MODE   TC_CTRLC_INVEN(1)

Waveform inversion CC0 mode.

#define TC_WAVEFORM_INVERT_CC1_MODE   TC_CTRLC_INVEN(2)

Waveform inversion CC1 mode.

typedef void(* tc_callback_t)(struct tc_module *const module)

Type of the callback functions.

Enum for the possible callback types for the TC module.

Enumerator
TC_CALLBACK_OVERFLOW 

Callback for TC overflow.

TC_CALLBACK_ERROR 

Callback for capture overflow error.

TC_CALLBACK_CC_CHANNEL0 

Callback for capture compare channel 0.

TC_CALLBACK_CC_CHANNEL1 

Callback for capture compare channel 1.

TC clock prescaler values.

This enum is used to choose the clock prescaler configuration. The prescaler divides the clock frequency of the TC module to make the counter count slower.

Enumerator
TC_CLOCK_PRESCALER_DIV1 

Divide clock by 1.

TC_CLOCK_PRESCALER_DIV2 

Divide clock by 2.

TC_CLOCK_PRESCALER_DIV4 

Divide clock by 4.

TC_CLOCK_PRESCALER_DIV8 

Divide clock by 8.

TC_CLOCK_PRESCALER_DIV16 

Divide clock by 16.

TC_CLOCK_PRESCALER_DIV64 

Divide clock by 64.

TC_CLOCK_PRESCALER_DIV256 

Divide clock by 256.

TC_CLOCK_PRESCALER_DIV1024 

Divide clock by 1024.

Index of the compare capture channels.

This enum is used to specify which capture/compare channel to do operations on.

Enumerator
TC_COMPARE_CAPTURE_CHANNEL_0 

Index of compare capture channel 0.

TC_COMPARE_CAPTURE_CHANNEL_1 

Index of compare capture channel 1.

TC module count direction.

Timer/Counter count direction.

Enumerator
TC_COUNT_DIRECTION_UP 

Timer should count upward from zero to MAX.

TC_COUNT_DIRECTION_DOWN 

Timer should count downward to zero from MAX.

Specifies if the counter is 8-, 16-, or 32-bit.

This enum specifies the maximum value it is possible to count to.

Enumerator
TC_COUNTER_SIZE_8BIT 

The counter's maximum value is 0xFF, the period register is available to be used as top value.

TC_COUNTER_SIZE_16BIT 

The counter's maximum value is 0xFFFF.

There is no separate period register, to modify top one of the capture compare registers has to be used. This limits the amount of available channels.

TC_COUNTER_SIZE_32BIT 

The counter's maximum value is 0xFFFFFFFF.

There is no separate period register, to modify top one of the capture compare registers has to be used. This limits the amount of available channels.

Action to perform when the TC module is triggered by an event.

Event action to perform when the module is triggered by an event.

Enumerator
TC_EVENT_ACTION_OFF 

No event action.

TC_EVENT_ACTION_RETRIGGER 

Re-trigger on event.

TC_EVENT_ACTION_INCREMENT_COUNTER 

Increment counter on event.

TC_EVENT_ACTION_START 

Start counter on event.

TC_EVENT_ACTION_PPW 

Store period in capture register 0, pulse width in capture register 1.

TC_EVENT_ACTION_PWP 

Store pulse width in capture register 0, period in capture register 1.

TC_EVENT_ACTION_STAMP 

Time stamp capture.

TC_EVENT_ACTION_PW 

Pulse width capture.

TC Counter reload action enum.

This enum specify how the counter and prescaler should reload.

Enumerator
TC_RELOAD_ACTION_GCLK 

The counter is reloaded/reset on the next GCLK and starts counting on the prescaler clock.

TC_RELOAD_ACTION_PRESC 

The counter is reloaded/reset on the next prescaler clock.

TC_RELOAD_ACTION_RESYNC 

The counter is reloaded/reset on the next GCLK, and the prescaler is restarted as well.

TC wave generation mode enum.

This enum is used to select which mode to run the wave generation in.

Enumerator
TC_WAVE_GENERATION_NORMAL_FREQ 

Top is maximum, except in 8-bit counter size where it is the PER register.

TC_WAVE_GENERATION_MATCH_FREQ 

Top is CC0, except in 8-bit counter size where it is the PER register.

TC_WAVE_GENERATION_NORMAL_PWM 

Top is maximum, except in 8-bit counter size where it is the PER register.

TC_WAVE_GENERATION_MATCH_PWM 

Top is CC0, except in 8-bit counter size where it is the PER register.

Waveform inversion mode.

Output waveform inversion mode.

Enumerator
TC_WAVEFORM_INVERT_OUTPUT_NONE 

No inversion of the waveform output.

TC_WAVEFORM_INVERT_OUTPUT_CHANNEL_0 

Invert output from compare channel 0.

TC_WAVEFORM_INVERT_OUTPUT_CHANNEL_1 

Invert output from compare channel 1.

static void tc_clear_status ( struct tc_module *const  module_inst,
const uint32_t  status_flags 
)
inlinestatic

Clears a module status flag.

Clears the given status flag of the module.

Parameters
[in]module_instPointer to the TC software instance struct
[in]status_flagsBitmask of TC_STATUS_* flags to clear

References Assert, TC_STATUS_CAPTURE_OVERFLOW, TC_STATUS_CHANNEL_0_MATCH, TC_STATUS_CHANNEL_1_MATCH, TC_STATUS_COUNT_OVERFLOW, and TC_STATUS_SYNC_READY.

Referenced by run_callback_test().

static void tc_disable ( const struct tc_module *const  module_inst)
inlinestatic

Disables the TC module.

Disables a TC module and stops the counter.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

Referenced by HwTimerStop(), run_callback_test(), and tc_reset().

static void tc_disable_events ( struct tc_module *const  module_inst,
struct tc_events *const  events 
)
inlinestatic

Disables a TC module event input or output.

Disables one or more input or output events to or from the TC module. See tc_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instPointer to the software module instance struct
[in]eventsStruct containing flags of events to disable

References Assert, tc_events::generate_event_on_compare_channel, tc_events::generate_event_on_overflow, i, tc_events::invert_event_input, and tc_events::on_event_perform_action.

static void tc_dma_trigger_command ( const struct tc_module *const  module_inst)
inlinestatic

TC DMA Trigger.

TC DMA trigger command.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

static void tc_enable ( const struct tc_module *const  module_inst)
inlinestatic

Enable the TC module.

Enables a TC module that has been previously initialized. The counter will start when the counter is enabled.

Note
When the counter is configured to re-trigger on an event, the counter will not start until the start function is used.
Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

Referenced by adp_example_tc_configure(), configure_tc(), hw_timer_init(), HwTimerStart(), init_xosc32k_fail_detector(), main(), platform_create_hw_timer(), run_16bit_capture_and_compare_test(), run_basic_functionality_test(), run_callback_test(), run_reset_32bit_master_test(), test_event_gen_user_init(), and vPortSetupTimerInterrupt().

static void tc_enable_events ( struct tc_module *const  module_inst,
struct tc_events *const  events 
)
inlinestatic

Enables a TC module event input or output.

Enables one or more input or output events to or from the TC module. See tc_events for a list of events this module supports.

Note
Events cannot be altered while the module is enabled.
Parameters
[in]module_instPointer to the software module instance struct
[in]eventsStruct containing flags of events to enable

References Assert, tc_events::event_action, tc_events::generate_event_on_compare_channel, tc_events::generate_event_on_overflow, i, tc_events::invert_event_input, and tc_events::on_event_perform_action.

Referenced by configure_tc(), configure_tc_alt(), configure_tc_def(), init_xosc32k_fail_detector(), run_16bit_capture_and_compare_test(), and test_event_gen_user_init().

uint32_t tc_get_capture_value ( const struct tc_module *const  module_inst,
const enum tc_compare_capture_channel  channel_index 
)

Gets the TC module capture value.

Retrieves the capture value in the indicated TC module capture channel.

Parameters
[in]module_instPointer to the software module instance struct
[in]channel_indexIndex of the Compare Capture channel to read
Returns
Capture value stored in the specified timer channel.

References Assert, TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, and tc_is_syncing().

Referenced by run_16bit_capture_and_compare_test().

static void tc_get_config_defaults ( struct tc_config *const  config)
inlinestatic

Initializes config with predefined default values.

This function will initialize a given TC configuration structure to a set of known default values. This function should be called on any new instance of the configuration structures before being modified by the user application.

The default configuration is as follows:

  • GCLK generator 0 (GCLK main) clock source
  • 16-bit counter size on the counter
  • No prescaler
  • Normal frequency wave generation
  • GCLK reload action
  • Don't run in standby
  • Don't run on demand for SAM L21/L22/C20/C21
  • No inversion of waveform output
  • No capture enabled
  • No I/O capture enabled for SAM L21/L22/C20/C21
  • No event input enabled
  • Count upward
  • Don't perform one-shot operations
  • No event action
  • No channel 0 PWM output
  • No channel 1 PWM output
  • Counter starts on 0
  • Capture compare channel 0 set to 0
  • Capture compare channel 1 set to 0
  • No PWM pin output enabled
  • Pin and MUX configuration not set
  • Double buffer disabled (if have this feature)
Parameters
[out]configPointer to a TC module configuration structure to set

References Assert, tc_config::clock_prescaler, tc_config::clock_source, tc_16bit_config::compare_capture_channel, tc_config::count_direction, tc_config::counter_16_bit, tc_config::counter_size, tc_config::double_buffering_enabled, tc_config::enable_capture_on_channel, tc_config::enable_capture_on_IO, tc_pwm_channel::enabled, GCLK_GENERATOR_0, tc_config::oneshot, tc_pwm_channel::pin_mux, tc_pwm_channel::pin_out, tc_config::pwm_channel, tc_config::reload_action, tc_config::run_in_standby, TC_CLOCK_PRESCALER_DIV1, TC_COMPARE_CAPTURE_CHANNEL_0, TC_COMPARE_CAPTURE_CHANNEL_1, TC_COUNT_DIRECTION_UP, TC_COUNTER_SIZE_16BIT, TC_RELOAD_ACTION_GCLK, TC_WAVE_GENERATION_NORMAL_FREQ, TC_WAVEFORM_INVERT_OUTPUT_NONE, tc_16bit_config::value, tc_config::wave_generation, and tc_config::waveform_invert_output.

Referenced by adp_example_tc_configure(), configure_tc(), configure_tc_alt(), configure_tc_def(), hw_timer_init(), HwTimerInit(), init_xosc32k_fail_detector(), platform_create_hw_timer(), run_16bit_capture_and_compare_test(), run_basic_functionality_test(), run_callback_test(), run_init_test(), run_reset_32bit_master_test(), test_event_gen_user_init(), and vPortSetupTimerInterrupt().

uint32_t tc_get_count_value ( const struct tc_module *const  module_inst)

Get TC module count value.

Retrieves the current count value of a TC module. The specified TC module may be started or stopped.

Parameters
[in]module_instPointer to the software module instance struct
Returns
Count value of the specified TC module.

References Assert, TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, and tc_is_syncing().

Referenced by HwTimerGetCount(), run_asynchronous_event_test(), run_basic_functionality_test(), run_resynchronous_event_test(), run_synchronous_event_test(), and vPortSuppressTicksAndSleep().

static uint32_t tc_get_status ( struct tc_module *const  module_inst)
inlinestatic

Retrieves the current module status.

Retrieves the status of the module, giving overall state information.

Parameters
[in]module_instPointer to the TC software instance struct
Returns
Bitmask of TC_STATUS_* flags.
Return values
TC_STATUS_CHANNEL_0_MATCHTimer channel 0 compare/capture match
TC_STATUS_CHANNEL_1_MATCHTimer channel 1 compare/capture match
TC_STATUS_SYNC_READYTimer read synchronization has completed
TC_STATUS_CAPTURE_OVERFLOWTimer capture data has overflowed
TC_STATUS_COUNT_OVERFLOWTimer count value has overflowed
TC_STATUS_CHN0_BUFFER_VALIDTimer count channel 0 compare/capture buffer valid
TC_STATUS_CHN1_BUFFER_VALIDTimer count channel 1 compare/capture buffer valid
TC_STATUS_PERIOD_BUFFER_VALIDTimer count period buffer valid

References Assert, TC_STATUS_CAPTURE_OVERFLOW, TC_STATUS_CHANNEL_0_MATCH, TC_STATUS_CHANNEL_1_MATCH, TC_STATUS_CHN0_BUFFER_VALID, TC_STATUS_CHN1_BUFFER_VALID, TC_STATUS_COUNT_OVERFLOW, TC_STATUS_PERIOD_BUFFER_VALID, and TC_STATUS_SYNC_READY.

Referenced by run_callback_test().

enum status_code tc_init ( struct tc_module *const  module_inst,
Tc *const  hw,
const struct tc_config *const  config 
)

Initializes a hardware TC module instance.

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

Parameters
[in,out]module_instPointer to the software module instance struct
[in]hwPointer to the TC hardware module
[in]configPointer to the TC configuration options struct
Returns
Status of the initialization procedure.
Return values
STATUS_OKThe module was initialized successfully
STATUS_BUSYHardware module was busy when the initialization procedure was attempted
STATUS_INVALID_ARGAn invalid configuration option or argument was supplied
STATUS_ERR_DENIEDHardware module was already enabled, or the hardware module is configured in 32-bit slave mode

References _tc_get_inst_index(), _tc_instances, Assert, tc_config::clock_prescaler, tc_config::clock_source, tc_8bit_config::compare_capture_channel, tc_16bit_config::compare_capture_channel, tc_32bit_config::compare_capture_channel, tc_config::count_direction, tc_config::counter_16_bit, tc_config::counter_32_bit, tc_config::counter_8_bit, tc_config::counter_size, system_pinmux_config::direction, tc_config::enable_capture_on_channel, tc_pwm_channel::enabled, i, module_inst, system_pinmux_config::mux_position, NULL, tc_config::oneshot, tc_8bit_config::period, tc_pwm_channel::pin_mux, tc_pwm_channel::pin_out, tc_config::pwm_channel, tc_config::reload_action, tc_config::run_in_standby, system_gclk_chan_config::source_generator, STATUS_BUSY, STATUS_ERR_DENIED, STATUS_ERR_INVALID_ARG, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBC, system_gclk_chan_enable(), system_gclk_chan_get_config_defaults(), system_gclk_chan_set_config(), system_pinmux_get_config_defaults(), SYSTEM_PINMUX_PIN_DIR_OUTPUT, system_pinmux_pin_set_config(), TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, tc_is_syncing(), tc_8bit_config::value, tc_16bit_config::value, tc_32bit_config::value, tc_config::wave_generation, and tc_config::waveform_invert_output.

Referenced by adp_example_tc_configure(), configure_tc(), configure_tc_alt(), configure_tc_def(), hw_timer_init(), HwTimerInit(), init_xosc32k_fail_detector(), platform_create_hw_timer(), run_16bit_capture_and_compare_test(), run_basic_functionality_test(), run_callback_test(), run_init_test(), run_reset_32bit_master_test(), test_event_gen_user_init(), and vPortSetupTimerInterrupt().

static bool tc_is_syncing ( const struct tc_module *const  module_inst)
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.

Parameters
[in]module_instPointer to the software module instance struct
Returns
Synchronization status of the underlying hardware module(s).
Return values
falseIf the module has completed synchronization
trueIf the module synchronization is ongoing

References Assert.

Referenced by run_reset_32bit_master_test(), tc_disable(), tc_dma_trigger_command(), tc_enable(), tc_get_capture_value(), tc_get_count_value(), tc_init(), tc_reset(), tc_set_compare_value(), tc_set_count_value(), tc_set_top_value(), tc_start_counter(), tc_stop_counter(), tc_sync_read_count(), and tc_update_double_buffer().

enum status_code tc_reset ( const struct tc_module *const  module_inst)

Resets the TC module.

Resets the TC module, restoring all hardware module registers to their default values and disabling the module. The TC module will not be accessible while the reset is being performed.

Note
When resetting a 32-bit counter only the master TC module's instance structure should be passed to the function.
Parameters
[in]module_instPointer to the software module instance struct
Returns
Status of the procedure.
Return values
STATUS_OKThe module was reset successfully
STATUS_ERR_UNSUPPORTED_DEVA 32-bit slave TC module was passed to the function. Only use reset on master TC

References Assert, STATUS_ERR_UNSUPPORTED_DEV, STATUS_OK, tc_disable(), and tc_is_syncing().

Referenced by main(), platform_delete_bus_timer(), run_16bit_capture_and_compare_test(), run_basic_functionality_test(), run_callback_test(), and run_reset_32bit_master_test().

enum status_code tc_set_compare_value ( const struct tc_module *const  module_inst,
const enum tc_compare_capture_channel  channel_index,
const uint32_t  compare 
)

Sets a TC module compare value.

Writes a compare value to the given TC module compare/capture channel.

Parameters
[in]module_instPointer to the software module instance struct
[in]channel_indexIndex of the compare channel to write to
[in]compareNew compare value to set
Returns
Status of the compare update procedure.
Return values
STATUS_OKThe compare value was updated successfully
STATUS_ERR_INVALID_ARGAn invalid channel index was supplied

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, and tc_is_syncing().

Referenced by HwTimerSetCompare(), and tc_callback_to_change_duty_cycle().

enum status_code tc_set_count_value ( const struct tc_module *const  module_inst,
const uint32_t  count 
)

Sets TC module count value.

Sets the current timer count value of a initialized TC module. The specified TC module may be started or stopped.

Parameters
[in]module_instPointer to the software module instance struct
[in]countNew timer count value to set
Returns
Status of the count update procedure.
Return values
STATUS_OKThe timer count was updated successfully
STATUS_ERR_INVALID_ARGAn invalid timer counter size was specified

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, and tc_is_syncing().

Referenced by hw_timer_start_ms(), HwTimerSetCount(), platform_create_hw_timer(), platform_start_bus_timer(), run_basic_functionality_test(), run_callback_test(), tc_callback_to_counter(), tc_cc0_cb(), and vPortSuppressTicksAndSleep().

enum status_code tc_set_top_value ( const struct tc_module *const  module_inst,
const uint32_t  top_value 
)

Set the timer TOP/period value.

For 8-bit counter size this function writes the top value to the period register.

For 16- and 32-bit counter size this function writes the top value to Capture Compare register 0. The value in this register can not be used for any other purpose.

Note
This function is designed to be used in PWM or frequency match modes only, when the counter is set to 16- or 32-bit counter size. In 8-bit counter size it will always be possible to change the top value even in normal mode.
Parameters
[in]module_instPointer to the software module instance struct
[in]top_valueNew timer TOP value to set
Returns
Status of the TOP set procedure.
Return values
STATUS_OKThe timer TOP value was updated successfully
STATUS_ERR_INVALID_ARGThe configured TC module counter size in the module instance is invalid

References Assert, STATUS_ERR_INVALID_ARG, STATUS_OK, TC_COUNTER_SIZE_16BIT, TC_COUNTER_SIZE_32BIT, TC_COUNTER_SIZE_8BIT, and tc_is_syncing().

Referenced by vPortSetupTimerInterrupt(), and vPortSuppressTicksAndSleep().

static void tc_start_counter ( const struct tc_module *const  module_inst)
inlinestatic

Starts the counter.

Starts or restarts an initialized TC module's counter.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

Referenced by main(), platform_create_hw_timer(), platform_start_bus_timer(), and run_basic_functionality_test().

static void tc_stop_counter ( const struct tc_module *const  module_inst)
inlinestatic

Stops the counter.

This function will stop the counter. When the counter is stopped the value in the count value is set to 0 if the counter was counting up, or maximum if the counter was counting down when stopped.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

Referenced by cleanup_asynchronous_event_test(), cleanup_resynchronous_event_test(), cleanup_synchronous_event_test(), platform_create_hw_timer(), platform_delete_bus_timer(), platform_stop_bus_timer(), platform_stop_stack_timers(), and run_basic_functionality_test().

static void tc_sync_read_count ( const struct tc_module *const  module_inst)
inlinestatic

Read synchronization of COUNT.

Read synchronization of COUNT.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().

static void tc_update_double_buffer ( const struct tc_module *const  module_inst)
inlinestatic

Update double buffer.

Update double buffer.

Parameters
[in]module_instPointer to the software module instance struct

References Assert, and tc_is_syncing().