hires.h File Reference

nRF51-specific support for high-resolution timers More...

#include <bspacm/core.h>

Go to the source code of this file.

Macros
#define	BSPACM_HIRES_TIMER_BASE   NRF_TIMER1_BASE
#define	BSPACM_HIRES_TIMER   NRF_TIMER0

Functions
int	iBSPACMhiresInitialize (unsigned int freq_Hz)
bool	bBSPACMhiresEnabled (void)
int	iBSPACMhiresSetEnabled (bool enabled)
unsigned int	uiBSPACMhires (void)
unsigned int	uiBSPACMhiresConvert_hfclk_hrt (unsigned int dur_hfclk)
unsigned int	uiBSPACMhiresConvert_hrt_hfclk (unsigned int dur_hrt)
unsigned int	uiBSPACMhiresConvert_us_hfclk (unsigned int dur_us)
unsigned int	uiBSPACMhiresConvert_us_hrt (unsigned int dur_us)
unsigned int	uiBSPACMhiresConvert_hrt_us (unsigned int dur_hrt)
void	vBSPACMhiresSleep_us (unsigned long count_us)
void	vBSPACMhiresSleep_ms (unsigned long count_ms)

Detailed Description

nRF51-specific support for high-resolution timers

Timer BSPACM_HIRES_TIMER is reserved for use by BSPACM to support short-duration sleeps and high-precision timing.

Capture/compare register 0 is reserved for timed sleeps via vBSPACMhiresSleep_us().

Other capture/compare registers may be used for high-precision timing by the application by issuing a capture task then (at an appropriate time) reading the corresponding CC register.

Homepage

http://github.com/pabigot/bspacm

Copyright

Copyright 2015, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSPACM_HIRES_TIMER   NRF_TIMER0

One of the NRF TIMER peripherals reserved for use by BSPACM infrastructure.

Defaulted:

The value here is superseded by previously encountered definitions.

Dependency:

BSPACM_HIRES_TIMER_BASE

#define BSPACM_HIRES_TIMER_BASE   NRF_TIMER1_BASE

The integral address of the TIMER peripheral to be used for BSPACM high-resolution timing.

You probably don't want this to be NRF_TIMER0_BASE, because that's used by soft devices.

Function Documentation

bool bBSPACMhiresEnabled

(

void

)

Return true if and only if the high resolution timer has been initialized and is currently enabled.

int iBSPACMhiresInitialize

(

unsigned int

freq_Hz

)

Initialize BSPACM_HIRES_TIMER to run at the specified frequency.

Parameters

freq_Hz

the desired high-resolution frequency. The 16 MHz core system clock must be a power-of-two multiple of this value.

Returns

0 if clock configured successfully; a negative error code if freq_Hz is unacceptable or a hardware problem is detected.

Note

This only configures the timer; it does not enable it.

See also

vBSPACMhiresSetEnabled()

int iBSPACMhiresSetEnabled

(

bool

enabled

)

Enable or disable the high-resolution timer.

Parameters

enabled

if true, enable the timer; if false, disable it.

Returns

-1 if the high-resolution timer has not been initialized, otherwise the value of bBSPACMhiresEnabled() at the time of the call.

unsigned int uiBSPACMhires ( void  )

inline

Read the counter of the high-resolution timer.

Warning

When calculating durations, be aware that the timer may not support a 32-bit counter, resulting in unexpected behavior if unsigned integer arithmetic involves an underflow or overflow. You may get better results by casting operands to uint16_t before subtracting to obtain a duration.

unsigned int uiBSPACMhiresConvert_hfclk_hrt ( unsigned int  dur_hfclk )

inline

Convert from ticks of the 16 MHz core system clock to ticks of BSPACM_HIRES_TIMER

unsigned int uiBSPACMhiresConvert_hrt_hfclk ( unsigned int  dur_hrt )

inline

Convert from ticks of BSPACM_HIRES_TIMER to ticks of the 16 MHz core system clock.

unsigned int uiBSPACMhiresConvert_hrt_us ( unsigned int  dur_hrt )

inline

Convert from ticks of BSPACM_HIRES_TIMER to microseconds.

unsigned int uiBSPACMhiresConvert_us_hfclk ( unsigned int  dur_us )

inline

Convert from microseconds to ticks of the 16 MHz core system clock.

unsigned int uiBSPACMhiresConvert_us_hrt ( unsigned int  dur_us )

inline

Convert from microseconds to ticks of BSPACM_HIRES_TIMER.

void vBSPACMhiresSleep_ms ( unsigned long  count_ms )

inline

Sleep for the desired duration.

Thin wrapper around vBSPACMhiresSleep_us() that scales milliseconds to microseconds.

Note

These are true kHz milliseconds (1s / 1000) not KiHz "milliseconds" (1s / 1024).

Warning

The infrastructure does not check for overflow in converting count_ms to hires clock ticks. See delay limit discussion at vBSPACMhiresSleep_us().

void vBSPACMhiresSleep_us

(

unsigned long

count_us

)

Sleep for the desired duration.

This will enter basic sleep mode if the duration is long enough; otherwise it will busy-wait. The busy-wait solution is vulnerable to extending too long due to processed interrupts; the duration when sleeping will be more accurate.

Parameters

count_us

the duration to sleep, expressed in microseconds

Warning

The infrastructure does not check for overflow in converting count_us to hires clock ticks. Unless you are using TIMER0, the timer has only 16 bits and will overflow at divisor*4.096 ms. This means the maximum delay for a 1 MHz timer is 65.535 ms.

If you invoke this when bBSPACMhiresEnabled() returns false it will hang. This is a bigger clue that your program is incorrect than any other reasonable behavior.

Do not invoke this from first-level interrupt handlers. Even if PAN #6 is fixed in your hardware, you may be overwriting the deadline for a user-level delay.