uptime.h File Reference

nRF51-specific support for low-resolution uptime clock More...

#include <bspacm/core.h>

Go to the source code of this file.

Data Structures
struct	sBSPACMuptimeAlarm
struct	sBSPACMuptimeState

Macros
#define	BSPACM_UPTIME_RTC_BASE   NRF_RTC1_BASE
#define	BSPACM_UPTIME_RTC   NRF_RTC0
#define	BSPACM_UPTIME_CC_COUNT   3
#define	BSPACM_UPTIME_Hz   32768U
#define	BSPACM_UPTIME_SLEEP_MINIMUM   2

Typedefs
typedef void(*	vBSPACMuptimeAlarmCallback_flih) (int ccidx, struct sBSPACMuptimeAlarm *ap)
typedef struct sBSPACMuptimeAlarm	sBSPACMuptimeAlarm
typedef sBSPACMuptimeAlarm *	hBSPACMuptimeAlarm
typedef struct sBSPACMuptimeState	sBSPACMuptimeState

Functions
unsigned int	uiBSPACMuptimeConvert_us_utt (unsigned int dur_us)
unsigned int	uiBSPACMuptimeConvert_ms_utt (unsigned int dur_ms)
unsigned int	uiBSPACMuptimeConvert_utt_us (unsigned int dur_utt)
unsigned int	uiBSPACMuptimeConvert_utt_ms (unsigned int dur_utt)
int	iBSPACMuptimeAlarmSet (int ccidx, unsigned int when_utt, hBSPACMuptimeAlarm ap)
hBSPACMuptimeAlarm	hBSPACMuptimeAlarmClear (int ccidx, bool *pendingp)
unsigned long long	ullBSPACMuptime ()
unsigned int	uiBSPACMuptime ()
void	vBSPACMuptimeStart ()
bool	bBSPACMuptimeEnabled ()
void	vBSPACMuptimeSleepCancel (void)
bool	bBSPACMuptimeSleep (unsigned int duration_utt)

Detailed Description

nRF51-specific support for low-resolution uptime clock

RTC peripheral BSPACM_UPTIME_RTC is reserved for use by BSPACM to support long-duration sleeps and user-defined alarms.

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

Other capture/compare registers may be used for user alarms via iBSPACMuptimeAlarmSet().

Homepage

http://github.com/pabigot/bspacm

Copyright

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

Macro Definition Documentation

#define BSPACM_UPTIME_CC_COUNT   3

The number of capture/compare registers available on the selected RTC peripheral.

Defaulted:

The value here is superseded by previously encountered definitions.

Dependency:

BSPACM_UPTIME_RTC_BASE

#define BSPACM_UPTIME_Hz   32768U

The frequency of the BSPACM_UPTIME_RTC peripheral in Hz.

#define BSPACM_UPTIME_RTC   NRF_RTC0

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

Defaulted:

The value here is superseded by previously encountered definitions.

Dependency:

BSPACM_UPTIME_RTC_BASE

#define BSPACM_UPTIME_RTC_BASE   NRF_RTC1_BASE

The integral address of the RTC peripheral to be used for BSPACM uptime clock.

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

#define BSPACM_UPTIME_SLEEP_MINIMUM   2

The minimum duration in uptime ticks that will cause bBSPACMuptimeSleep() to actually sleep.

Typedef Documentation

typedef sBSPACMuptimeAlarm* hBSPACMuptimeAlarm

A handle to an uptime alarm structure

typedef struct sBSPACMuptimeAlarm sBSPACMuptimeAlarm

State for an alarm driven by the uptime clock.

typedef struct sBSPACMuptimeState sBSPACMuptimeState

The current state of the uptime clock.

This is global to allow access to pieces of it from inline functions. User application should never inspect nor mutate any of these fields.

typedef void(* vBSPACMuptimeAlarmCallback_flih) (int ccidx, struct sBSPACMuptimeAlarm *ap)

Type for an alarm callback function.

It is explicitly permitted to invoke iBSPACMuptimeAlarmSet() and iBSPACMuptimeAlarmCancel() from within the callback.

Parameters

ap	pointer to the alarm structure. This may be embedded in a larger structure to pass context to the callback.

Note

The callback is invoked from the first level interrupt handler and is subject to all the usual caveats about what should be done in that context.

If the registered alarm is scheduled for repeated invocation, the corresponding compare register will have been updated to the next alarm time prior to invoking the callback.

Function Documentation

bool bBSPACMuptimeEnabled ( )

inline

Return true if and only if the uptime clock has been started and is still running.

bool bBSPACMuptimeSleep

(

unsigned int

duration_utt

)

Function to sleep for a given duration.

This allows sleeps up to 512 s (24 bits of a 32 KiHz timer), much longer than vBSPACMhiresSleep_us().

Warning

If this function is invoked while bBSPACMuptimeEnabled() returns false, it will hang. This is a bigger clue that your program is incorrect than any other reasonable behavior.

Parameters

duration_utt

duration of the sleep, in BSPACM_UPTIME_Hz ticks. Values are taken modulo 2^24. Values less than BSPACM_UPTIME_SLEEP_MINIMUM cause immediate return true.

Returns

true if the sleep ran to completion or was shorter than BSPACM_UPTIME_SLEEP_MINIMUM; false if vBSPACMuptimeSleepCancel() was invoked during an interrupt handler to force an early wakeup.

hBSPACMuptimeAlarm hBSPACMuptimeAlarmClear	(	int	ccidx,
		bool *	pendingp
	)

Remove an alarm from the uptime clock

Parameters

ccidx	the capture/compare register from which the alarm should be removed. If this register is not valid for the RTC peripheral an error is returned.
pendingp	optional pointer to a record of whether the alarm was pending when it was removed. Pass a null pointer if this information is not relevant.

Returns

the handle for the alarm that was removed, or a null pointer if no alarm was present or the ccidx was invalid.

int iBSPACMuptimeAlarmSet	(	int	ccidx,
		unsigned int	when_utt,
		hBSPACMuptimeAlarm	ap
	)

Schedule an alarm on the uptime clock.

Parameters

ccidx	the capture/compare register to use for the alarm. If the passed value is not valid for the RTC peripheral being used as BSPACM_UPTIME_RTC, or if there is already an alarm attached to the register, the call returns an error. Note that ccidx 0 is reserved.
when_utt	the absolute time at which the alarm should go off.

Note

Alarm times are limited by the 24-bit resolution of the RTC.

Parameters

ap	a pointer to the alarm structure

Returns

0 if successfully scheduled, or a negative error code. Attempting to schedule an alarm on an unstarted/disabled clock is an error.

unsigned int uiBSPACMuptime ( )

inline

Return the current uptime truncated to the lowest 32 bits

unsigned int uiBSPACMuptimeConvert_ms_utt ( unsigned int  dur_ms )

inline

Convert a time from milliseconds to uptime ticks, rounding up.

unsigned int uiBSPACMuptimeConvert_us_utt ( unsigned int  dur_us )

inline

Convert a time from microseconds to uptime ticks, rounding up.

unsigned int uiBSPACMuptimeConvert_utt_ms ( unsigned int  dur_utt )

inline

Convert a time from uptime ticks to milliseconds, rounding up.

unsigned int uiBSPACMuptimeConvert_utt_us ( unsigned int  dur_utt )

inline

Convert a time from uptime ticks to microseconds, rounding up.

unsigned long long ullBSPACMuptime ( )

inline

Return the absolute uptime in its highest available precision

void vBSPACMuptimeSleepCancel

(

void

)

Function to cancel any in-progress bBSPACMuptimeSleep().

This may be called from interrupt handlers to force an early wakeup when a situation requires the application to react early.

void vBSPACMuptimeStart

(

)

Configure and enable the uptime clock.