Hardware presentation/abstraction for generic timers (Timer_A/Timer_B) More...

#include <bsp430/periph.h>
#include <bsp430/clock.h>

Data Structures
struct	sBSP430hplTIMER

struct	sBSP430halTIMER

struct	sBSP430timerAlarm

struct	sBSP430timerMuxSharedAlarm

struct	sBSP430timerMuxAlarm

struct	sBSP430timerPulseCapture

Macros
#define	BSP430_MODULE_TIMER_A

#define	BSP430_MODULE_TIMER_B

#define	BSP430_MODULE_TIMER (BSP430_MODULE_TIMER_A \|\| BSP430_MODULE_TIMER_B)

#define	configBSP430_TIMER_CCACLK 0

#define	BSP430_TIMER_CCACLK include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_PERIPH_CPPID include "bsp430_config.h"

#define	BSP430_TIMER_CCACLK_PERIPH_HANDLE derived platform or application specific

#define	configBSP430_TIMER_CCACLK_HAL indirectly defaulted

#define	configBSP430_TIMER_CCACLK_HAL_ISR indirectly defaulted

#define	configBSP430_TIMER_CCACLK_HAL_CC0_ISR indirectly defaulted

#define	configBSP430_TIMER_CCACLK_CLK_PORT indirectly defaulted

#define	configBSP430_TIMER_CCACLK_CLK_PORT_HAL indirectly defaulted 0

#define	configBSP430_TIMER_CCACLK_CC0_PORT indirectly defaulted

#define	configBSP430_TIMER_CCACLK_CC0_PORT_HAL indirectly defaulted 0

#define	configBSP430_TIMER_CCACLK_CC1_PORT indirectly defaulted

#define	configBSP430_TIMER_CCACLK_CC1_PORT_HAL indirectly defaulted 0

#define	BSP430_TIMER_CCACLK_ACLK_CCIDX include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_ACLK_CCIS include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_CLK_PORT_PERIPH_CPPID platform or application specific

#define	BSP430_TIMER_CCACLK_CLK_PORT_PERIPH_HANDLE derived platform or application specific

#define	BSP430_TIMER_CCACLK_CLK_PORT_BIT include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_CC0_PORT_PERIPH_CPPID platform or application specific

#define	BSP430_TIMER_CCACLK_CC0_PORT_PERIPH_HANDLE derived platform or application specific

#define	BSP430_TIMER_CCACLK_CC0_PORT_BIT include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_CC0_CCIS CCIS_0

#define	BSP430_TIMER_CCACLK_CC1_PORT_PERIPH_CPPID platform or application specific

#define	BSP430_TIMER_CCACLK_CC1_PORT_PERIPH_HANDLE derived platform or application specific

#define	BSP430_TIMER_CCACLK_CC1_PORT_BIT include <bsp430/platform.h>

#define	BSP430_TIMER_CCACLK_CC1_CCIS CCIS_0

#define	configBSP430_TIMER_VALID_COUNTER_READ 1

#define	BSP430_TIMER_VALID_COUNTER_READ_CCIDX 2

#define	BSP430_TIMER_HAL_HPL_VARIANT_TIMER 1

#define	BSP430_TIMER_FLAG_MCLKSYNC 0x01

#define	BSP430_TIMER_FLAG_SLOW 0x02

#define	BSP430_TIMER_ALARM_FLAG_SET 0x01

#define	BSP430_TIMER_ALARM_FLAG_ENABLED 0x02

#define	BSP430_TIMER_ALARM_FUTURE_LIMIT 3UL

#define	BSP430_TIMER_ALARM_SET_NOW 1

#define	BSP430_TIMER_ALARM_SET_PAST 2

#define	BSP430_TIMER_ALARM_SET_ALREADY -2

#define	BSP430_TIMER_PULSECAP_START_VALID 0x01

#define	BSP430_TIMER_PULSECAP_END_VALID 0x02

#define	BSP430_TIMER_PULSECAP_OVERFLOW 0x04

#define	BSP430_TIMER_PULSECAP_ACTIVE_HIGH 0x08

#define	BSP430_TIMER_PULSECAP_START_CALLBACK 0x100

#define	BSP430_TIMER_PULSECAP_END_CALLBACK 0x200

#define	BSP430_TIMER_PULSECAP_CALLBACK_ACTIVE 0x0400

#define	BSP430_TIMER_PULSECAP_ENABLED 0x1000

#define	BSP430_TIMER_PULSECAP_ACTIVE 0x2000

#define	configBSP430_HAL_TA0 0

#define	BSP430_HAL_TA0 (&xBSP430hal_TA0_)

#define	configBSP430_HAL_TA1 0

#define	BSP430_HAL_TA1 (&xBSP430hal_TA1_)

#define	configBSP430_HAL_TA2 0

#define	BSP430_HAL_TA2 (&xBSP430hal_TA2_)

#define	configBSP430_HAL_TA3 0

#define	BSP430_HAL_TA3 (&xBSP430hal_TA3_)

#define	configBSP430_HAL_TB0 0

#define	BSP430_HAL_TB0 (&xBSP430hal_TB0_)

#define	configBSP430_HAL_TB1 0

#define	BSP430_HAL_TB1 (&xBSP430hal_TB1_)

#define	configBSP430_HAL_TB2 0

#define	BSP430_HAL_TB2 (&xBSP430hal_TB2_)

#define	configBSP430_HPL_TA0 (configBSP430_HAL_TA0 - 0)

#define	BSP430_PERIPH_TA0 ((tBSP430periphHandle)(BSP430_PERIPH_TA0_BASEADDRESS_))

#define	configBSP430_HPL_TA1 (configBSP430_HAL_TA1 - 0)

#define	BSP430_PERIPH_TA1 ((tBSP430periphHandle)(BSP430_PERIPH_TA1_BASEADDRESS_))

#define	configBSP430_HPL_TA2 (configBSP430_HAL_TA2 - 0)

#define	BSP430_PERIPH_TA2 ((tBSP430periphHandle)(BSP430_PERIPH_TA2_BASEADDRESS_))

#define	configBSP430_HPL_TA3 (configBSP430_HAL_TA3 - 0)

#define	BSP430_PERIPH_TA3 ((tBSP430periphHandle)(BSP430_PERIPH_TA3_BASEADDRESS_))

#define	configBSP430_HPL_TB0 (configBSP430_HAL_TB0 - 0)

#define	BSP430_PERIPH_TB0 ((tBSP430periphHandle)(BSP430_PERIPH_TB0_BASEADDRESS_))

#define	configBSP430_HPL_TB1 (configBSP430_HAL_TB1 - 0)

#define	BSP430_PERIPH_TB1 ((tBSP430periphHandle)(BSP430_PERIPH_TB1_BASEADDRESS_))

#define	configBSP430_HPL_TB2 (configBSP430_HAL_TB2 - 0)

#define	BSP430_PERIPH_TB2 ((tBSP430periphHandle)(BSP430_PERIPH_TB2_BASEADDRESS_))

#define	BSP430_HPL_TA0 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA0)

#define	BSP430_HPL_TA1 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA1)

#define	BSP430_HPL_TA2 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA2)

#define	BSP430_HPL_TA3 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA3)

#define	BSP430_HPL_TB0 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB0)

#define	BSP430_HPL_TB1 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB1)

#define	BSP430_HPL_TB2 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB2)

#define	configBSP430_HAL_TA0_CC0_ISR 0

#define	configBSP430_HAL_TA0_ISR (configBSP430_HAL_TA0 - 0)

#define	configBSP430_HAL_TA1_CC0_ISR 0

#define	configBSP430_HAL_TA1_ISR (configBSP430_HAL_TA1 - 0)

#define	configBSP430_HAL_TA2_CC0_ISR 0

#define	configBSP430_HAL_TA2_ISR (configBSP430_HAL_TA2 - 0)

#define	configBSP430_HAL_TA3_CC0_ISR 0

#define	configBSP430_HAL_TA3_ISR (configBSP430_HAL_TA3 - 0)

#define	configBSP430_HAL_TB0_CC0_ISR 0

#define	configBSP430_HAL_TB0_ISR (configBSP430_HAL_TB0 - 0)

#define	configBSP430_HAL_TB1_CC0_ISR 0

#define	configBSP430_HAL_TB1_ISR (configBSP430_HAL_TB1 - 0)

#define	configBSP430_HAL_TB2_CC0_ISR 0

#define	configBSP430_HAL_TB2_ISR (configBSP430_HAL_TB2 - 0)

Typedefs
typedef struct sBSP430hplTIMER	sBSP430hplTIMER

typedef struct sBSP430halTIMER	sBSP430halTIMER

typedef struct sBSP430halTIMER *	hBSP430halTIMER

typedef const struct sBSP430timerAlarm *	hBSP430timerAlarm

typedef int(*	iBSP430timerAlarmCallback_ni) (hBSP430timerAlarm alarm)

typedef struct sBSP430timerAlarm	sBSP430timerAlarm

typedef int(*	iBSP430timerMuxAlarmCallback_ni) (struct sBSP430timerMuxSharedAlarm shared, struct sBSP430timerMuxAlarm alarm)

typedef struct sBSP430timerMuxSharedAlarm	sBSP430timerMuxSharedAlarm

typedef sBSP430timerMuxSharedAlarm *	hBSP430timerMuxSharedAlarm

typedef struct sBSP430timerMuxAlarm	sBSP430timerMuxAlarm

typedef sBSP430timerMuxAlarm *	hBSP430timerMuxAlarm

typedef int(*	iBSP430timerPulseCaptureCallback_ni) (struct sBSP430timerPulseCapture *state)

typedef struct sBSP430timerPulseCapture	sBSP430timerPulseCapture

typedef struct sBSP430timerPulseCapture *	hBSP430timerPulseCapture

Functions
unsigned int	uiBSP430timerCaptureDelta_ni (tBSP430periphHandle periph, int ccidx, unsigned int capture_mode, unsigned int ccis, unsigned int count)

void	vBSP430timerInferHints_ni (hBSP430halTIMER timer)

eBSP430clockSource	xBSP430timerClockSource (volatile sBSP430hplTIMER *hpl)

unsigned long	ulBSP430timerFrequency_Hz_ni (tBSP430periphHandle periph)

unsigned long	ulBSP430timerOverflowAdjusted_ni (hBSP430halTIMER timer, unsigned int ctr)

unsigned long	ulBSP430timerCounter_ni (hBSP430halTIMER timer, unsigned int *overflowp)

static BSP430_CORE_INLINE unsigned long	ulBSP430timerCounter (hBSP430halTIMER timer, unsigned int *overflowp)

static BSP430_CORE_INLINE unsigned long long	ullBSP430timerCorrected (hBSP430halTIMER timer, unsigned int ctr)

unsigned long	ulBSP430timerCaptureCounter_ni (hBSP430halTIMER timer, unsigned int ccidx)

void	vBSP430timerResetCounter_ni (hBSP430halTIMER timer)

void	vBSP430timerSetCounter_ni (hBSP430halTIMER timer, unsigned int overflow, unsigned long counter)

hBSP430timerAlarm	hBSP430timerAlarmInitialize (sBSP430timerAlarm *alarm, tBSP430periphHandle periph, int ccidx, iBSP430timerAlarmCallback_ni callback)

int	iBSP430timerAlarmSetEnabled_ni (hBSP430timerAlarm alarm, int enablep)

static BSP430_CORE_INLINE int	iBSP430timerAlarmEnable (hBSP430timerAlarm alarm)

static BSP430_CORE_INLINE int	iBSP430timerAlarmDisable (hBSP430timerAlarm alarm)

int	iBSP430timerAlarmSet_ni (hBSP430timerAlarm alarm, unsigned long setting_tck)

int	iBSP430timerAlarmSetForced_ni (hBSP430timerAlarm alarm, unsigned long setting_tck)

static BSP430_CORE_INLINE int	iBSP430timerAlarmSet (hBSP430timerAlarm alarm, unsigned long setting_tck)

int	iBSP430timerAlarmCancel_ni (hBSP430timerAlarm alarm)

static BSP430_CORE_INLINE int	iBSP430timerAlarmCancel (hBSP430timerAlarm alarm)

hBSP430timerMuxSharedAlarm	hBSP430timerMuxAlarmStartup (sBSP430timerMuxSharedAlarm *shared, tBSP430periphHandle periph, int ccidx)

int	iBSP430timerMuxAlarmShutdown (sBSP430timerMuxSharedAlarm *shared)

static BSP430_CORE_INLINE unsigned long	ulBSP430timerMuxSharedAlarmCounter (sBSP430timerMuxSharedAlarm *shared)

int	iBSP430timerMuxAlarmAdd_ni (hBSP430timerMuxSharedAlarm shared, hBSP430timerMuxAlarm alarm)

int	iBSP430timerMuxAlarmRemove_ni (hBSP430timerMuxSharedAlarm shared, hBSP430timerMuxAlarm alarm)

hBSP430timerPulseCapture	hBSP430timerPulseCaptureInitialize (hBSP430timerPulseCapture pulsecap, tBSP430periphHandle periph, int ccidx, unsigned int ccis, unsigned int flags, iBSP430timerPulseCaptureCallback_ni callback)

int	iBSP430timerPulseCaptureSetEnabled_ni (hBSP430timerPulseCapture pulsecap, int enablep)

int	iBSP430timerPulseCaptureSetActive_ni (hBSP430timerPulseCapture pulsecap, int activep)

static BSP430_CORE_INLINE void	vBSP430timerPulseCaptureClear_ni (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE int	iBSP430timerPulseCaptureDisable (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE int	iBSP430timerPulseCaptureEnable (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE int	iBSP430timerPulseCaptureActivate (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE int	iBSP430timerPulseCaptureDeactivate (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE void	vBSP430timerPulseCaptureInvertSense_ni (hBSP430timerPulseCapture pulsecap)

static BSP430_CORE_INLINE volatile sBSP430hplTIMER *	xBSP430hplLookupTIMER (tBSP430periphHandle periph)

static BSP430_CORE_INLINE hBSP430halTIMER	hBSP430timerLookup (tBSP430periphHandle periph)

const char *	xBSP430timerName (tBSP430periphHandle periph)

int	iBSP430timerSupportedCCs (tBSP430periphHandle periph)

static BSP430_CORE_INLINE_FORCED unsigned int	uiBSP430timerSyncCounterRead_ni (volatile sBSP430hplTIMER *const hpl)

static BSP430_CORE_INLINE_FORCED unsigned int	uiBSP430timerAsyncCounterRead_ni (volatile sBSP430hplTIMER *const hpl)

static BSP430_CORE_INLINE_FORCED void	vBSP430timerLatchedCounterInitialize_ni (volatile sBSP430hplTIMER *const hpl, int ccidx)

static BSP430_CORE_INLINE_FORCED unsigned int	uiBSP430timerLatchedCounterRead_ni (volatile sBSP430hplTIMER *const hpl, int ccidx)

static BSP430_CORE_INLINE void	vBSP430timerSafeCounterInitialize_ni (volatile sBSP430hplTIMER *const hpl)

static BSP430_CORE_INLINE_FORCED unsigned int	uiBSP430timerSafeCounterRead_ni (volatile sBSP430hplTIMER *const hpl)

static BSP430_CORE_INLINE_FORCED unsigned int	uiBSP430timerBestCounterRead_ni (volatile sBSP430hplTIMER *const hpl, int flags)

Detailed Description

Hardware presentation/abstraction for generic timers (Timer_A/Timer_B)

Timer functionality exists on most MSP430 MCUs. This module supports both Timer_A and Timer_B, but does not provide any distinction between them. At this time, Timer_D is not supported by BSP430.

Conventional peripheral handles are BSP430_PERIPH_TA0 and BSP430_PERIPH_TB0. The handles are available only when the corresponding HPL is requested. The number of capture/compare blocks supported by the MCU is not an identifying characteristic of the peripheral instance.

Note: The original nomenclature for MSP430 timers in MSP430 has proven to be inconsistent as the number of instances grew. While the identifier TA3 in early MCUs specified the presence of a Timer_A instance with 3 CCs, this led to the need to denote a second Timer_A instance with 5 CCs as T1A5 within the MCU-specific headers. The data sheets, however, refer to that same instance as TA1, with a dot-separated CC number where necessary (e.g., TA1.4 refers to the fifth CC on the second Timer_A instance, and is controlled via TA1CCTL4).; In BSP430 timer instance names uniformly begin with instance zero, even on MCUs where the documented peripheral name does not include an instance. For example, peripheral called TA2 on the MSP430G2231 is simply the first Timer_A instance and has 2 CCs. It is identified here as TA0, with the number of CCs left implicit.

Module Configuration Options

configBSP430_HPL_TA0 to enable the HPL handle declarations

configBSP430_HAL_TA0 to enable the HAL infrastructure

configBSP430_HAL_TA0_ISR to enable the HAL ISR for overflow and capture/compare blocks 1 and higher

configBSP430_HAL_TA0_CC0_ISR to enable the HAL ISR for capture/compare block 0

configBSP430_TIMER_CCACLK to request a platform-specific clock with certain capture/compare capabilities be identified

Substitute other instance names (e.g., TB1) as necessary.

Hardware Presentation Layer

Though Timer_A and Timer_B have distinct capabilities, their underlying register maps are compatible and sBSP430hplTIMER is used for both. The structure includes space for all eight potential capture/compare registers, but only the ones supported by the device should be accessed.

For convenience several alternative methods of accessing a timer counter are provided:

uiBSP430timerSyncCounterRead_ni() reads the peripheral counter register without validating it. It is the fastest approach, but can produce invalid results when the timer clock is asynchronous to the CPU clock.

uiBSP430timerAsyncCounterRead_ni() repeatedly reads the counter until the same value is read twice. It is appropriate when the timer is asynchronous to the CPU clock (e.g., timers using ACLK derived from LFXT1). Calls to it may hang if the timer runs so fast that the counter changes between successive reads.

uiBSP430timerLatchedCounterRead_ni() reserves a capture/compare register to be used to latch the counter value and return it. It is safe and valid for synchronous and asynchronous timers at any rate, but requires a capture/compare register be identified and pre-configured using vBSP430timerLatchedCounterInitialize_ni().

uiBSP430timerSafeCounterRead_ni() selects between uiBSP430timerSyncCounterRead_ni() and uiBSP430timerLatchedCounterRead_ni() depending on how the application has configured configBSP430_TIMER_VALID_COUNTER_READ. Here "safe" means it will return the best counter value that can be found in constant time. Validity of the returned value is guaranteed only when configBSP430_TIMER_VALID_COUNTER_READ is enabled. This routine also does some validation on the configuration of the capture/compare register if BSP430_CORE_NDEBUG is false. It is the slowest but also the most reliable absent information about how the timer is configured, so is the solution underlying ulBSP430timerCounter_ni().

Hardware Adaptation Layer

The timer HAL uses the sBSP430halTIMER structure.

Enabling configBSP430_HAL_TA0 also enables configBSP430_HAL_TA0_ISR unless previously disabled. When this primary ISR is enabled an interrupt service routine is provided supporting interrupts related to timer overflow and capture/compare events in CC blocks 1 and higher. The corresponding interrupts must be enabled by the application. On an overflow interrupt, the sBSP430halTIMER.overflow_count is incremented and the sBSP430halTIMER.overflow_cbchain_ni callback chain is invoked. On a capture/compare interrupt, the corresponding chain from sBSP430halTIMER.cc_cbchain_ni is invoked. (Note that the index in this array is the CC number.)

The secondary ISR controlled by configBSP430_HAL_TA0_CC0_ISR is left disabled unless explicitly enabled. If enabled, an interrupt service routine is provided supporting capture/compare interrupts related to CC0. The first chain in the sBSP430halTIMER.cc_cbchain_ni array is invoked by this ISR. The interrupt enable bit is controlled by the application.

Additional Capabilities

Some of the material provided by this header is documented in separate sections:

Homepage: http://github.com/pabigot/bsp430

Copyright: Copyright 2012-2014, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSP430_HAL_TA0 (&xBSP430hal_TA0_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TA0.

This pointer may be used only if configBSP430_HAL_TA0 is defined to a true value.

Dependency:: configBSP430_HAL_TA0

#define BSP430_HAL_TA1 (&xBSP430hal_TA1_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TA1.

This pointer may be used only if configBSP430_HAL_TA1 is defined to a true value.

Dependency:: configBSP430_HAL_TA1

#define BSP430_HAL_TA2 (&xBSP430hal_TA2_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TA2.

This pointer may be used only if configBSP430_HAL_TA2 is defined to a true value.

Dependency:: configBSP430_HAL_TA2

#define BSP430_HAL_TA3 (&xBSP430hal_TA3_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TA3.

This pointer may be used only if configBSP430_HAL_TA3 is defined to a true value.

Dependency:: configBSP430_HAL_TA3

#define BSP430_HAL_TB0 (&xBSP430hal_TB0_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TB0.

This pointer may be used only if configBSP430_HAL_TB0 is defined to a true value.

Dependency:: configBSP430_HAL_TB0

#define BSP430_HAL_TB1 (&xBSP430hal_TB1_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TB1.

This pointer may be used only if configBSP430_HAL_TB1 is defined to a true value.

Dependency:: configBSP430_HAL_TB1

#define BSP430_HAL_TB2 (&xBSP430hal_TB2_)

sBSP430halTIMER HAL handle for BSP430_PERIPH_TB2.

This pointer may be used only if configBSP430_HAL_TB2 is defined to a true value.

Dependency:: configBSP430_HAL_TB2

#define BSP430_HPL_TA0 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA0)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TA0.

This pointer to a volatile structure overlaying the TA0 peripheral register map may be used only if configBSP430_HPL_TA0 is defined to a true value.

Dependency:: configBSP430_HPL_TA0

#define BSP430_HPL_TA1 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA1)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TA1.

This pointer to a volatile structure overlaying the TA1 peripheral register map may be used only if configBSP430_HPL_TA1 is defined to a true value.

Dependency:: configBSP430_HPL_TA1

#define BSP430_HPL_TA2 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA2)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TA2.

This pointer to a volatile structure overlaying the TA2 peripheral register map may be used only if configBSP430_HPL_TA2 is defined to a true value.

Dependency:: configBSP430_HPL_TA2

#define BSP430_HPL_TA3 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TA3)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TA3.

This pointer to a volatile structure overlaying the TA3 peripheral register map may be used only if configBSP430_HPL_TA3 is defined to a true value.

Dependency:: configBSP430_HPL_TA3

#define BSP430_HPL_TB0 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB0)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TB0.

This pointer to a volatile structure overlaying the TB0 peripheral register map may be used only if configBSP430_HPL_TB0 is defined to a true value.

Dependency:: configBSP430_HPL_TB0

#define BSP430_HPL_TB1 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB1)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TB1.

This pointer to a volatile structure overlaying the TB1 peripheral register map may be used only if configBSP430_HPL_TB1 is defined to a true value.

Dependency:: configBSP430_HPL_TB1

#define BSP430_HPL_TB2 ((volatile sBSP430hplTIMER *)BSP430_PERIPH_TB2)

sBSP430hplTIMER HPL pointer for BSP430_PERIPH_TB2.

This pointer to a volatile structure overlaying the TB2 peripheral register map may be used only if configBSP430_HPL_TB2 is defined to a true value.

Dependency:: configBSP430_HPL_TB2

#define BSP430_MODULE_TIMER (BSP430_MODULE_TIMER_A || BSP430_MODULE_TIMER_B)

Defined on inclusion of <bsp430/periph/timer.h>. The value evaluates to true if the target MCU supports the Timer_A or Timer_B, and false if it does not.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

#define BSP430_MODULE_TIMER_A

Value:

(defined(__MSP430_HAS_TA2__)      \
                               || defined(__MSP430_HAS_TA3__)   \
                               || defined(__MSP430_HAS_TA5__)   \
                               || defined(__MSP430_HAS_T0A3__)  \
                               || defined(__MSP430_HAS_T0A5__))

Defined on inclusion of <bsp430/periph/timer.h>. The value evaluates to true if the target MCU supports the Timer_A Module, and false if it does not.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

#define BSP430_MODULE_TIMER_B

Value:

(defined(__MSP430_HAS_TB3__)      \
                               || defined(__MSP430_HAS_TB7__)   \
                               || defined(__MSP430_HAS_T0B3__)  \
                               || defined(__MSP430_HAS_T0B7__))

Defined on inclusion of <bsp430/periph/timer.h>. The value evaluates to true if the target MCU supports the Timer_B Module, and false if it does not.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

#define BSP430_PERIPH_TA0 ((tBSP430periphHandle)(BSP430_PERIPH_TA0_BASEADDRESS_))

Handle for the raw TA0 device.

The handle may be used only if configBSP430_HPL_TA0 is defined to a true value.

Dependency:: configBSP430_HPL_TA0

#define BSP430_PERIPH_TA1 ((tBSP430periphHandle)(BSP430_PERIPH_TA1_BASEADDRESS_))

Handle for the raw TA1 device.

The handle may be used only if configBSP430_HPL_TA1 is defined to a true value.

Dependency:: configBSP430_HPL_TA1

#define BSP430_PERIPH_TA2 ((tBSP430periphHandle)(BSP430_PERIPH_TA2_BASEADDRESS_))

Handle for the raw TA2 device.

The handle may be used only if configBSP430_HPL_TA2 is defined to a true value.

Dependency:: configBSP430_HPL_TA2

#define BSP430_PERIPH_TA3 ((tBSP430periphHandle)(BSP430_PERIPH_TA3_BASEADDRESS_))

Handle for the raw TA3 device.

The handle may be used only if configBSP430_HPL_TA3 is defined to a true value.

Dependency:: configBSP430_HPL_TA3

#define BSP430_PERIPH_TB0 ((tBSP430periphHandle)(BSP430_PERIPH_TB0_BASEADDRESS_))

Handle for the raw TB0 device.

The handle may be used only if configBSP430_HPL_TB0 is defined to a true value.

Dependency:: configBSP430_HPL_TB0

#define BSP430_PERIPH_TB1 ((tBSP430periphHandle)(BSP430_PERIPH_TB1_BASEADDRESS_))

Handle for the raw TB1 device.

The handle may be used only if configBSP430_HPL_TB1 is defined to a true value.

Dependency:: configBSP430_HPL_TB1

#define BSP430_PERIPH_TB2 ((tBSP430periphHandle)(BSP430_PERIPH_TB2_BASEADDRESS_))

Handle for the raw TB2 device.

The handle may be used only if configBSP430_HPL_TB2 is defined to a true value.

Dependency:: configBSP430_HPL_TB2

#define BSP430_TIMER_FLAG_MCLKSYNC 0x01

Bit set in sBSP430halTIMER::hal_state flags to indicate a timer is known to be synchronous to the system clock. In this case a faster counter read approach (uiBSP430timerSyncCounterRead_ni()) can be used.

Note

#define BSP430_TIMER_FLAG_SLOW 0x02

Bit set in sBSP430halTIMER::hal_state flags to indicate a timer is known to be significantly slower than the system clock. In this case a faster counter read approach (iBSP430timerAsyncCounterRead_ni()) can be used with asynchronous timers.

Note: The BSP430 infrastructure infers this flag only if the clock is at least a factor of 64x slower than MCLK.

#define BSP430_TIMER_HAL_HPL_VARIANT_TIMER 1

Field value for variant stored in sBSP430halTIMER field hal_state.cflags when HPL reference is to an sBSP430hplTIMER.

#define BSP430_TIMER_PULSECAP_ACTIVE 0x2000

Bit set in sBSP430timerPulseCapture::flags_ni if the pulse capture infrastructure is active (i.e., the interrupt is enabled).

#define BSP430_TIMER_PULSECAP_ACTIVE_HIGH 0x08

Bit set in sBSP430timerPulseCapture::flags_ni if the captured start time corresponded to a low-to-high transition. The bit is cleared if the start corresponded to a high-to-low transition.

Note: This is not an input; if an active-high pulse is desired, the user must ensure the input signal is low prior to enabling the capture, or may choise to reset the state in callback_ni if the wrong transition was captured as the start of the pulse.

#define BSP430_TIMER_PULSECAP_CALLBACK_ACTIVE 0x0400

Bit set in sBSP430timerPulseCapture::flags_ni if the callback is being invoked. This is used for diagnostics and error checking.

#define BSP430_TIMER_PULSECAP_ENABLED 0x1000

Bit set in sBSP430timerPulseCapture::flags_ni if the pulse capture infrastructure is enabled (i.e., linked into the interrupt callback chains).

#define BSP430_TIMER_PULSECAP_END_CALLBACK 0x200

Bit set in sBSP430timerPulseCapture::flags_ni if the sBSP430timerPulseCapture::callback_ni is to be invoked when a pulse end is captured.

#define BSP430_TIMER_PULSECAP_END_VALID 0x02

Bit set in sBSP430timerPulseCapture::flags_ni if the sBSP430timerPulseCapture::end_tt timestamp corresponds to the end of a pulse on a timer input.

#define BSP430_TIMER_PULSECAP_OVERFLOW 0x04

Bit set in sBSP430timerPulseCapture::flags_ni if any of these conditions hold:

the underlying timer recorded an overflow event (hardware COV);
the underlying timer data was overwritten before the FLIH could extract it;
a new transition was detected after the pulse end before the state was reset via vBSP430timerPulseCaptureClear (software).

If this bit is set, neither counter values nor the BSP430_TIMER_PULSECAP_ACTIVE_HIGH bit are reliable.

#define BSP430_TIMER_PULSECAP_START_CALLBACK 0x100

Bit set in sBSP430timerPulseCapture::flags_ni if the sBSP430timerPulseCapture::callback_ni is to be invoked when a pulse start is captured.

#define BSP430_TIMER_PULSECAP_START_VALID 0x01

Bit set in sBSP430timerPulseCapture::flags_ni if the sBSP430timerPulseCapture::start_tt timestamp corresponds to the start of a pulse on a timer input.

#define BSP430_TIMER_VALID_COUNTER_READ_CCIDX 2

Capture/compare index reserved for valid reading of timer counters.

CC 0 is normally reserved for high-priority capture/compare operations or RTOS scheduling using the dedicated interrupt handler. It is also used with BSP430_TIMER_CCACLK_PERIPH_HANDLE by iBSP430ucsTrimDCOCLKDIV_ni().

CC 1 is normally reserved for use by configBSP430_TIMER_CCACLK_CC1_PORT functionality, and is the standard choice for BSP430_UPTIME_DELAY_CCIDX.

Therefore this functionality normally uses CC 2. To keep the infrastructure as simple as possible, the same index is used for all timers on which valid counter reading is required. If a timer does not support the requested index, the attempt to enable valid reading will hang.

Warning: Certain low-end value-line MCUS such as the MSP430G2231 do not have a third capture/compare register. Platforms targeting those MCUs should provide an alternative definition for this macro in their bsp430_config.h file.; If you assign the same value to BSP430_UPTIME_DELAY_CCIDX and BSP430_TIMER_VALID_COUNTER_READ_CCIDX, platform initialization will hang attempting to configure the delay alarm.; If you have selected configBSP430_TIMER_CCACLK, make sure your use of BSP430_TIMER_CCACLK_ACLK_CCIDX does not interfere with the expectation that the configuration of BSP430_TIMER_VALID_COUNTER_READ_CCIDX is never changed. Consider adding the following after any use of BSP430_TIMER_CCACLK_ACLK_CCIDX:
#if ((configBSP430_TIMER_VALID_COUNTER_READ - 0) \

&& (BSP430_TIMER_CCACLK_ACLK_CCIDX == BSP430_TIMER_VALID_COUNTER_READ_CCIDX))

vBSP430timerSafeCounterInitialize_ni(BSP430_TIMER_CCACLK_PERIPH_HANDLE);

#endif

Dependency:: configBSP430_TIMER_VALID_COUNTER_READ

Defaulted:: The value here is superseded by previously encountered definitions.

#define configBSP430_TIMER_VALID_COUNTER_READ 1

Provide valid counter reads for timers.

The MSP430 timer infrastructure does not guarantee that a read of a timer counter (e.g. using uiBSP430timerSyncCounterRead_ni_()) produces a valid result when the timer clock is asynchronous to MCLK. Where the timer is significantly slower than MCLK a majority vote approach (e.g. using uiBSP430timerAsyncCounterRead_ni_()) can ensure the result is valid, but if the timer runs at a similar speed this may fail.

The problem can be avoided by capturing the counter into a capture register instead of reading it directly. Doing this costs a couple cycles extra when reading the counter, and due to infrastructure limitations prevents use of that capture/compare register for other purposes.

Since most asynchronous reads involve access to an LFXT1-based timer while using a much-faster MCLK, and ulBSP430timerCounter_ni() depends on uiBSP430timerSafeCounterRead_ni(), this defaults to enabled so that safe reads are also valid reads.

See also: BSP430_TIMER_VALID_COUNTER_READ_CCIDX

Defaulted:: The value here is superseded by previously encountered definitions.

Typedef Documentation

typedef struct sBSP430halTIMER* hBSP430halTIMER

The timer internal state is protected.

typedef struct sBSP430timerPulseCapture* hBSP430timerPulseCapture

Handle for a structure used to capture the width of a pulse

typedef int(* iBSP430timerPulseCaptureCallback_ni) (struct sBSP430timerPulseCapture *state)

Callback invoked on state changes related to a pulse capture.

Parameters

state the state of the pulse capture. The callback is permitted to mutate this state.

Returns: a value conformant with Interrupt Callback Return Values that is used as the return value from the interrupt callback handling pulse capture events.

typedef struct sBSP430halTIMER sBSP430halTIMER

Structure holding hardware abstraction layer state for Timer_A and Timer_B.

typedef struct sBSP430hplTIMER sBSP430hplTIMER

Layout for Timer_A and Timer_B peripherals.

typedef struct sBSP430timerPulseCapture sBSP430timerPulseCapture

Structure containing data related to measuring the duration of a pulse.

Function Documentation

static BSP430_CORE_INLINE hBSP430halTIMER hBSP430timerLookup ( tBSP430periphHandle periph )

static

Get the HAL handle for a specific timer.

Parameters

periph The handle identifier, such as BSP430_PERIPH_TA0.

Returns: the HAL handle for the timer. A null pointer is returned if the handle does not correspond to a timer for which the HAL interface has been enabled (e.g., with configBSP430_HAL_TA0).

Examples:: periph/timer/alarm/main.c.

hBSP430timerPulseCapture hBSP430timerPulseCaptureInitialize	(	hBSP430timerPulseCapture	pulsecap,
		tBSP430periphHandle	periph,
		int	ccidx,
		unsigned int	ccis,
		unsigned int	flags,
		iBSP430timerPulseCaptureCallback_ni	callback
	)

Configure the pulsecap structure to capture pulse widths.

Capture/compare register ccidx in periph is configured to capture both rising and falling edges on input ccis. The capture interrupt is not enabled by this function.

It is the user's responsibility to ensure that ccidx exists on periph and that ccis is correct for the pulse signal. The user must also separately configure periph to count continuously.

Parameters

pulsecap	the structure holding the information about the pulse capture timer.
periph	the timer that is to be used for capturing the pulse, such as BSP430_UPTIME_TIMER_PERIPH_HANDLE
ccidx	the capture/compare index within the timer.
ccis	the capture/compare input source on which the pulse will arrive
flags	the initial flags to be used to control event notification. Only the BSP430_TIMER_PULSECAP_START_CALLBACK and BSP430_TIMER_PULSECAP_END_CALLBACK fields are used.
callback	the callback to be invoked on pulse capture events. This may be a NULL pointer.

Returns: The pulse capture handle if successful. A null handle will be returned if initialization failed, e.g. because periph could not be located.

int iBSP430timerAlarmSetForced_ni	(	hBSP430timerAlarm	alarm,
		unsigned long	setting_tck
	)

Forced an alarm at the specified time even if it is late.

Like iBSP430timerAlarmSet_ni() except that a positive error (BSP430_TIMER_ALARM_SET_NOW or BSP430_TIMER_ALARM_SET_PAST) forces the alarm to be configured and the interrupt set to execute as soon as possible.

This is useful when:

initially configuring an alarm for system timeslices, where the underlying timer has already been started and what would normally be the first tick may have already passed; or

using a high-speed (MCLK-rate) timer when intervening activity may delay the scheduling.

Note: The alarm is set only if the return value is non-negative. For positive return values the alarm interrupt may already be pending.

Parameters

alarm	a pointer to an alarm structure initialized using iBSP430timerAlarmInitialize().
setting_tck	the time at which the alarm should go off.

Returns

Zero to indicate the alarm was successfully scheduled

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE int iBSP430timerPulseCaptureActivate ( hBSP430timerPulseCapture pulsecap )

static

Short-hand to re-activate an enabled pulse capture even if interrupts are enabled.

Note: This operation will clear the pulse state using vBSP430timerPulseCaptureClear_ni() prior to activating the interrupt.

Parameters

pulsecap a pulse capture structure initialized via hBSP430timerPulseCaptureInitialize() and enabled via iBSP430timerPulseCaptureSetEnabled_ni().

Returns: 0 if successful, or a negative error code

See also: iBSP430timerPulseCaptureSetActive_ni()

static BSP430_CORE_INLINE int iBSP430timerPulseCaptureDeactivate ( hBSP430timerPulseCapture pulsecap )

static

Short-hand to disable an active pulse capture even if interrupts are enabled

Parameters

pulsecap a pulse capture structure initialized via hBSP430timerPulseCaptureInitialize() and enabled via iBSP430timerPulseCaptureSetEnabled_ni().

Returns: 0 if successful, or a negative error code

See also: iBSP430timerPulseCaptureSetActive_ni()

static BSP430_CORE_INLINE int iBSP430timerPulseCaptureDisable ( hBSP430timerPulseCapture pulsecap )

static

Short-hand to disable a pulse capture using iBSP430timerPulseCaptureSetEnabled_ni() even if interrupts are enabled.

Parameters

pulsecap a pulse capture structure initialized via hBSP430timerPulseCaptureInitialize().

Returns: 0 if successful, or a negative error code

static BSP430_CORE_INLINE int iBSP430timerPulseCaptureEnable ( hBSP430timerPulseCapture pulsecap )

static

Short-hand to enable a pulse capture using iBSP430timerPulseCaptureSetEnabled_ni() even if interrupts are enabled.

Note: This does not activate the capture.

Parameters

pulsecap a pulse capture structure initialized via hBSP430timerPulseCaptureInitialize().

Returns: 0 if successful, or a negative error code

int iBSP430timerPulseCaptureSetActive_ni	(	hBSP430timerPulseCapture	pulsecap,
		int	activep
	)

Activate or deactivate an enabled pulse capture structure.

This does not inspect or modify the timer capture configuration; it only affects the CCIE and CCIFG flags of the peripheral interrupt. If invoked when the capture infrastructure is not enabled it returns an error code.

It is permitted to invoke this function from within an iBSP430timerPulseCaptureCallback_ni(), and in fact doing so is preferable to setting BSP430_HAL_ISR_CALLBACK_DISABLE_INTERRUPT.

Parameters

pulsecap	a pulse capture structure initialized using hBSP430timerPulseCaptureInitialize() and enabled by iBSP430timerPulseCaptureSetEnabled_ni().
activep	If true, the underlying timer peripheral interrupt is enabled; if false the interrupt is disabled.

Returns: 0 on success, or a negative error code.

See also: iBSP430timerPulseCaptureSetEnabled_ni()

int iBSP430timerPulseCaptureSetEnabled_ni	(	hBSP430timerPulseCapture	pulsecap,
		int	enablep
	)

Enable or disable an initialized pulse capture structure.

Warning: This function must not be invoked from within an iBSP430timerPulseCaptureCallback_ni() as it manipulates the interrupt callback chains.

Note: If enablep is false, the capture will be deactivated before being disabled. If enablep is true the capture will not be activated after being enabled.

Parameters

pulsecap	a pulse capture structure initialized using hBSP430timerPulseCaptureInitialize().
enablep	If true, the `pulsecal` controlling callback is linked into the callback chain for the configured capture/compare register of the pulse timer peripheral. If false, the callback is removed from that chain.

Returns: 0 on success, or a negative error code.

See also: iBSP430timerPulseCaptureSetActive_ni()

int iBSP430timerSupportedCCs ( tBSP430periphHandle periph )

Get the number of capture/compare registers supported by the timer.

Parameters

periph The handle identifier, such as BSP430_PERIPH_TA0.

Returns: the number of CCs on the timer. -1 is returned if the timer does not exist or the resource was not configured.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE_FORCED unsigned int uiBSP430timerAsyncCounterRead_ni ( volatile sBSP430hplTIMER *const hpl )

static

Inline function to read the counter of a timer not synchronous to MCLK.

This approach reads the counter repeatedly until the same value is read twice. The technique is appropriate when the counter is asynchronous to MCLK, but it is safe to use only when the counter update rate is significantly slower than MCLK, e.g. when the timer is driven by LFXT1.

This call takes about 9 clock cycles on a CPUX MCU if the first two reads are equal.

Warning: The time taken by this function is only probabilistically constant.; If the timer frequency is not at least a factor of 10 slower than MCLK, this routine may hang since two counter values read consecutively may never be equal.

Parameters

hpl	reference to the underlying timer.

Returns: the instantaneous counter value.

See also: uiBSP430timerSyncCounterRead_ni(); uiBSP430timerLatchedCounterRead_ni(); uiBSP430timerSafeCounterRead_ni()

static BSP430_CORE_INLINE_FORCED unsigned int uiBSP430timerBestCounterRead_ni	(	volatile sBSP430hplTIMER *const	hpl,
		int	flags
	)

static

Select the best counter read solution based on a hint.

When the application knows exactly how the timer is configured at the point the counter is read, it can select the optimal counter read function and use it directly for the least overhead. When the application or infrastructure can record information about how the timer is configured but the counter is read in shared code the hints may be used to get a better or faster answer than would be obtained from uiBSP430timerSafeCounterRead_ni(), which is the only solution when no information is available.

If BSP430_TIMER_FLAG_MCLKSYNC is set in flags, uiBSP430timerSyncCounterRead_ni() is used. There's about an 8 cycle overhead to select this case at runtime, resulting in a measurement cost of 11 cycles.

Otherwise, if BSP430_TIMER_FLAG_SLOW is set in flags, uiBSP430timerAsyncCounterRead_ni() is used. There's about an 11 cycle overhead to select this case at runtime, resulting in a measurement cost of 20 cycles.

Otherwise, uiBSP430timerSafeCounterRead_ni() is used.

Parameters

hpl	reference to the underlying timer
flags	bit mask including potentially BSP430_TIMER_FLAG_MCLKSYNC and BSP430_TIMER_FLAG_SLOW. This can be obtained from the `flags` field of the corresponding sBSP430halTIMER::hal_state field, if something updated that when the timer was configured.

Returns: the instantaneous counter value.

unsigned int uiBSP430timerCaptureDelta_ni	(	tBSP430periphHandle	periph,
		int	ccidx,
		unsigned int	capture_mode,
		unsigned int	ccis,
		unsigned int	count
	)

Count number of timer transitions over a span of ACLK ticks

This function uses the timer capture/compare infrastructure to count clock cycles. The source for a timer is configured externally (for example, to SMCLK, or to an external source). The capture/control block ccidx is configured based on capture_mode. The code synchronizes with a capture, then loops for period captures. The timer counter is recorded at the start of the first and end of the last cycle. The capture/control block control is reset, and the difference between first and last counters is returned.

The expectation is that the events triggered by the input selection are slow relative to the MCLK and timer sources. If the timer is slower than the input, the use of the SCS flag in the implementation will result in the function returning count.

Note: The function does not modify the timer-level configuration; the timer source must be assigned and the timer started prior to invoking this function.; If configBSP430_TIMER_VALID_COUNTER_READ is enabled and ccidx is equal to BSP430_TIMER_VALID_COUNTER_READ_CCIDX this function will invoke vBSP430timerSafeCounterInitialize_ni(periph) prior to returning.

Parameters

periph	the peripheral identifier for the timer on which the capture is to be made.
ccidx	the capture/compare block index to use. No validity checks on this are made; you must be sure the index is in range for the provided timer.
capture_mode	the edge detection capture specification. The appropriate value is given by constants in the <msp430.h> header, such as CM_1. The passed value is masked to eliminate extraneous bits; if the resulting value does not identify a capture, the function returns immediately with a value of -1.
ccis	the capture/compare input selection. The appropriate value is a constant from the <msp430.h> header, such as CCIS_1. Consult the MCU-specific datasheet to determine the functions of the input alternatives for each timer/CC-block pair.
count	the number of capture events over which the delta is measured.

Returns: -1 (cast to unsigned int) if capture_mode is not valid or the timer is unrecognized or stopped. Otherwise the delta in the counter of the timer over count captures.

Examples:: bootstrap/clocks/main.c.

static BSP430_CORE_INLINE_FORCED unsigned int uiBSP430timerLatchedCounterRead_ni	(	volatile sBSP430hplTIMER *const	hpl,
		int	ccidx
	)

static

Inline function to read a timer counter using a capture register.

This approach uses a pre-configured capture/compare register to latch the counter value, which is then returned. It is generally slower than uiBSP430timerSyncCounterRead_ni(), but is faster than uiBSP430timerAsyncCounterRead_ni() and is also safe to use regardless of the relationship between MCLK and the accessed timer.

This call takes about 8 clock cycles on a CPUX MCU.

Warning: If the selected capture/compare register has not been configured using vBSP430timerLatchedCounterInitialize_ni() the return value will not represent the timer counter.

Parameters

hpl	reference to the underlying timer
ccidx	the index of the capture/compare register to be used for latched timer reads

Returns: the instantaneous counter value.

See also: uiBSP430timerAsyncCounterRead_ni(); uiBSP430timerSyncCounterRead_ni(); uiBSP430timerLatchedCounterRead_ni(); uiBSP430timerSafeCounterRead_ni()

static BSP430_CORE_INLINE_FORCED unsigned int uiBSP430timerSafeCounterRead_ni ( volatile sBSP430hplTIMER *const hpl )

static

Inline function to read the timer counter.

Note: Here "safe" means that call will return a counter value regardless of how the timer clock is related to MCLK. When configBSP430_TIMER_VALID_COUNTER_READ is disabled this function is equivalent to uiBSP430timerSyncCounterRead_ni(); in that case, the counter value may not be valid if the timer clock is asynchronous to MCLK. The remainder of this description assumes that configBSP430_TIMER_VALID_COUNTER_READ is enabled.

This function uses uiBSP430timerLatchedCounterRead_ni() along with BSP430_TIMER_VALID_COUNTER_READ_CCIDX to read the timer.

This call takes about 21 clock cycles on a CPUX MCU when configBSP430_TIMER_VALID_COUNTER_READ is enabled.

When BSP430_CORE_NDEBUG is false (default) this function validates that the capture/compare register is properly configured to read the counter. When that requirement is not met, the CPU will spin in place allowing the developer to see what has gone wrong, instead of continuing to process invalid counter values.

Parameters

hpl	reference to the underlying timer

Returns: the instantaneous counter value.

Dependency:: configBSP430_TIMER_VALID_COUNTER_READ

Dependency:: BSP430_CORE_NDEBUG

See also: uiBSP430timerAsyncCounterRead_ni(); uiBSP430timerSyncCounterRead_ni(); uiBSP430timerLatchedCounterRead_ni()

static BSP430_CORE_INLINE_FORCED unsigned int uiBSP430timerSyncCounterRead_ni ( volatile sBSP430hplTIMER *const hpl )

static

Inline function to read the counter of a timer synchronous to MCLK.

This simply reads and returns the counter register of the underlying peripheral.

This call takes about 3 clock cycles on a CPUX MCU.

Warning: If the clock source for the timer is asynchronous to the CPU clock there is a chance that the counter value read will be corrupt. Consider using uiBSP430timerAsyncCounterRead_ni() in that situation.

Parameters

hpl	reference to the underlying timer.

Returns: the instantaneous counter value.

See also: uiBSP430timerAsyncCounterRead_ni(); uiBSP430timerLatchedCounterRead_ni(); uiBSP430timerSafeCounterRead_ni()

unsigned long ulBSP430timerCaptureCounter_ni	(	hBSP430halTIMER	timer,
		unsigned int	ccidx
	)

Read a timer capture register.

Capture/compare registers may be set to record the time of an external event. The 16-bit captured value is held in sBSP430hplTIMER::ccr, but for many cases a 32-bit counter value is needed. This function combines the 16-bit value with the result of ulBSP430timerOverflowAdjusted_ni() to produce a 32-bit value under the assumption that the combination is calculated less than 32768 ticks past the capture event.

Parameters

timer	The timer for which the count is desired.
ccidx	The capture/compare register from which the low 16 bits are taken.

Returns: A 32-bit unsigned count of the number of clock ticks at the point where the capture register was set.

static BSP430_CORE_INLINE unsigned long ulBSP430timerCounter	(	hBSP430halTIMER	timer,
		unsigned int *	overflowp
	)

static

Read timer counter regardless of interrupt enable state.

This wraps ulBSP430timerCounter_ni with code that saves the interrupt state, reads the timer, then restores the entry interrupt state prior to returning the timer counts.

Warning: See warnings at ulBSP430timerCounter_ni().

Examples:: periph/timer/alarm/main.c.

unsigned long ulBSP430timerCounter_ni	(	hBSP430halTIMER	timer,
		unsigned int *	overflowp
	)

Read the timer counter assuming interrupts are disabled.

Note: This routine accounts for the possibility of a single pending overflow event in the timer by adjusting the returned value to account for that. However, it does not clear the overflow event because there may be overflow callbacks that must be invoked through the interrupt handler, and it only detects a single pending overflow event. Times will be wrong if interrupts remain disabled so long that a second overflow occurs before the first is processed by the interrupt handler.

Warning: This routine uses uiBSP430timerSafeCounterRead_ni() underneath. For timers that are asynchronous to the CPU clock the returned value may be incorrect unless configBSP430_TIMER_VALID_COUNTER_READ is enabled.; If configBSP430_TIMER_VALID_COUNTER_READ is enabled this call will hang if vBSP430timerSafeCounterInitialize_ni() has not been invoked on the underlying timer or if the BSP430_TIMER_VALID_COUNTER_READ_CCIDX capture/compare register has been reconfigured since that was done. BSP430 will invoke this method at configuration time for all timers that it configures (including the uptime infrastructure and hBSP430timerAlarmInitialize()).

Parameters

timer	The timer for which the count is desired.
overflowp	An optional pointer in which the high word of the overflow counter is stored, supporting a 48-bit counter.

Returns: A 32-bit unsigned count of the number of clock ticks observed since the timer was last reset.

Examples:: periph/timer/alarm/main.c, and utility/cli/main.c.

unsigned long ulBSP430timerFrequency_Hz_ni ( tBSP430periphHandle periph )

Provide the frequency of the timer source, if that can be determined.

Parameters

periph The handle identifier, such as BSP430_PERIPH_TA0.

Returns: 0 if the timer is stopped; -1 (cast to unsigned long) if the frequency cannot be determined; otherwise the frequency of the source scaled by any relevant dividers.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE unsigned long ulBSP430timerMuxSharedAlarmCounter ( sBSP430timerMuxSharedAlarm * shared )

static

Get the current time of the underlying shared alarm.

This makes it easier to schedule multiplexed alarms at a relative time.

Parameters

shared a pointer to the structure used for multiplexed alarms

Returns: the counter value of the timer used for the alarm

unsigned long ulBSP430timerOverflowAdjusted_ni	(	hBSP430halTIMER	timer,
		unsigned int	ctr
	)

Return the adjusted overflow counter for the timer and a 16-bit counter value.

This is timer->overflow_count, adjusted to account for any registered but unhandled overflow event. If ctr is greater than 32767 it is assumed the unhandled overflow event occurred after the counter was read and no adjustment is made.

Parameters

timer	the timer for which the overflow counter is desired.
ctr	A recently obtained 16-bit counter value from the timer. Interrupts must not have been enabled at any point since the counter was read, and this function must be invoked with one half of the timer's period.

Returns: the adjusted overflow counter for timer

static BSP430_CORE_INLINE unsigned long long ullBSP430timerCorrected	(	hBSP430halTIMER	timer,
		unsigned int	ctr
	)

static

Return the full-precision counter at the point the timer produced ctr

MSP430 capture registers hold only the low 16 bits of the BSP430 timer counter. Overflow at both the 16 and 32 bit counter levels must be accounted for when reconstructing the full captured counter value. That's done by this function, which must be invoked within one 16-bit timer cycle of the time that ctr was recorded.

timer The timer for which the count is desired

ctr An underlying timer counter value captured within the last 2^16 ticks of timer

Returns: the reconstructed full-precision timer corresponding to ctr

void vBSP430timerInferHints_ni ( hBSP430halTIMER timer )

Infer the appropriate hints about timer configuration

Some timer operations such as safe and valid reading of the counter can be optimized by selecting between alternative techniques based on configuration hints including BSP430_TIMER_FLAG_MCLKSYNC and BSP430_TIMER_FLAG_SLOW.

Invoking this function will determine the appropriate value of the flags field of the timer's sBSP430hplHALStatePrefix::hal_state structure:

The function infers BSP430_TIMER_FLAG_MCLKSYNC when the clock source for the timer is equal to the clock source for MCLK, based on xBSP430timerClockSource() and xBSP430clockMCLKSource(). Be aware that eBSP430clockSRC_DCOCLK is not considered synchronous with eBSP430clockSRC_DCOCLKDIV under this rule.

The function infers BSP430_TIMER_FLAG_SLOW when MCLK frequency is at least 16 times faster than timer frequency.

Parameters

timer the timer for which flags are to be determined

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE_FORCED void vBSP430timerLatchedCounterInitialize_ni	(	volatile sBSP430hplTIMER *const	hpl,
		int	ccidx
	)

static

Configure a timer CC to support uiBSP430timerLatchedCounterRead_ni().

Latched counter reads rely on a pre-configured capture/compare register. This routine configures that register.

Parameters

hpl	reference to the underlying timer
ccidx	the index of the capture/compare register to be used for latched timer reads, often BSP430_TIMER_VALID_COUNTER_READ_CCIDX

static BSP430_CORE_INLINE void vBSP430timerPulseCaptureClear_ni ( hBSP430timerPulseCapture pulsecap )

static

Clear state in pulsecal so the next transition begins a new pulse.

Bits BSP430_TIMER_PULSECAP_START_VALID, BSP430_TIMER_PULSECAP_END_VALID, BSP430_TIMER_PULSECAP_OVERFLOW, and BSP430_TIMER_PULSECAP_ACTIVE_HIGH are cleared. All other bits remain unchanged.

Note: This does not re-activate an inactive pulse capture.

Parameters

pulsecap the pulse capture structure. The pointer must not be null.

static BSP430_CORE_INLINE void vBSP430timerPulseCaptureInvertSense_ni ( hBSP430timerPulseCapture pulsecap )

static

Invert the sense of a partial or full pulse capture.

BSP430_TIMER_PULSECAP_ACTIVE_HIGH is inverted in sBSP430timerPulseCapture::flags_ni

If the provided capture has a valid end timestamp it is copied into sBSP430timerPulseCapture::start_tt_ni and BSP430_TIMER_PULSECAP_END_VALID is cleared.

Otherwise, if the provided capture has a valid start timestamp it is cleared.

Parameters

pulsecap the structure to be updated.

void vBSP430timerResetCounter_ni ( hBSP430halTIMER timer )

Reset the timer counter.

This clears both the overflow count and the timer internal counter. If the timer is running it is stopped while the internal counter is updated, then is restarted.

Examples:: periph/timer/alarm/main.c.

static BSP430_CORE_INLINE void vBSP430timerSafeCounterInitialize_ni ( volatile sBSP430hplTIMER *const hpl )

static

Configure the timer for safe reads.

Note: Here "safe" means that call will return a counter value regardless of how the timer clock is related to MCLK. When configBSP430_TIMER_VALID_COUNTER_READ is disabled this function has no effect.

This function must be invoked before any other function that might attempt to invoke uiBSP430timerSafeCounterRead_ni() on the peripheral. This includes ulBSP430timerCounter_ni().

Note: It is safe to call this function multiple times, and in fact it must be called again if you need to use BSP430_TIMER_VALID_COUNTER_READ_CCIDX for some other purpose.

Parameters

hpl	reference to the underlying timer

Warning: If BSP430_TIMER_VALID_COUNTER_READ_CCIDX does not exist on periph and BSP430_CORE_NDEBUG is false this call will hang. Since this is a configuration error, the situation should be detected during development.

Dependency:: configBSP430_TIMER_VALID_COUNTER_READ

Dependency:: BSP430_CORE_NDEBUG

Examples:: sensors/hh10d/main.c.

void vBSP430timerSetCounter_ni	(	hBSP430halTIMER	timer,
		unsigned int	overflow,
		unsigned long	counter
	)

Set the timer counter.

This sets both the overflow count and the timer internal counter. If the timer is running it is stopped while the internal counter is updated, then is restarted.

Parameters

timer	the timer to be modified
overflow	the overflow value as would be returned though a pointer assignment by vBSP430timerCounter_ni().
counter	the counter value that would be returned as a value by vBSP430timerCounter_ni().

static BSP430_CORE_INLINE volatile sBSP430hplTIMER* xBSP430hplLookupTIMER ( tBSP430periphHandle periph )

static

Get the HPL handle for a specific timer.

Parameters

periph The handle identifier, such as BSP430_PERIPH_TA0.

Returns: A typed pointer that can be used to manipulate the timer. A null pointer is returned if the handle does not correspond to a timer for which the HPL interface been enabled (e.g., with configBSP430_HPL_TA0).

Examples:: bootstrap/clocks/main.c, and sensors/hh10d/main.c.

eBSP430clockSource xBSP430timerClockSource ( volatile sBSP430hplTIMER * hpl )

Return a reconstructed source for the timer.

Note: This should be used only in equality tests to determine whether the source for a timer is the same as the source for a system clock or another timer. Do not interpret the value as identifying a specific source. For example, sometimes eBSP430clockSRC_XT2CLK will mean a crystal and sometimes it will mean an external clock or VLOCLK, depending on the MCU and its supporting hardware.

const char* xBSP430timerName ( tBSP430periphHandle periph )

Get a human-readable identifier for the timer

Parameters

periph The handle identifier, such as BSP430_PERIPH_TA0.

Returns: The name of the timer, e.g. "TA0". If the peripheral is not recognized as a timer, a null pointer is returned.

Examples:: periph/timer/alarm/main.c, sensors/hh10d/main.c, and sensors/venus6pps/main.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Module Configuration Options

Hardware Presentation Layer

Hardware Adaptation Layer

Additional Capabilities

Macro Definition Documentation

Typedef Documentation

Function Documentation