bsp430/utility/uptime.h data structures and functions supporting conversion between civil time and the uptime facility. More...

Data Structures
struct	sBSP430uptimeNTPShortFormat

struct	sBSP430uptimeNTPTimestamp

struct	sBSP430uptimeNTPPacketHeader

Macros
#define	BSP430_UPTIME_POSIX_EPOCH_NTPIS 2208988800UL

#define	BSP430_UPTIME_BYPASS_EPOCH_NTP ((uint64_t)(BSP430_UPTIME_POSIX_EPOCH_NTPIS + 1388534400UL) << 32)

#define	BSP430_UPTIME_EPOCH_UPDATE_INTERVAL_UTT 0x40000000L

#define	BSP430_UPTIME_EPOCH_VALID_OFFSET_UTT 0x60000000L

Typedefs
typedef struct sBSP430uptimeNTPShortFormat	sBSP430uptimeNTPShortFormat

typedef struct sBSP430uptimeNTPTimestamp	sBSP430uptimeNTPTimestamp

typedef struct sBSP430uptimeNTPPacketHeader	sBSP430uptimeNTPPacketHeader

Functions
int	iBSP430uptimeCheckEpochValidity ()

unsigned long	ulBSP430uptimeLastEpochUpdate ()

long	lBSP430uptimeEpochAge ()

int	iBSP430uptimeEpochEra (unsigned long time_utt)

int	iBSP430uptimeInitializeNTPRequest (sBSP430uptimeNTPPacketHeader *ntpp)

int	iBSP430uptimeSetNTPXmtField (sBSP430uptimeNTPPacketHeader ntpp, unsigned long putt)

int	iBSP430uptimeSetEpochFromNTP (uint64_t epoch_ntp)

int	iBSP430uptimeAdjustEpochFromNTP (int64_t adjustment_ntp)

int	iBSP430uptimeSetEpochFromTimeval (const struct timeval *tv, unsigned long when_utt)

int	iBSP430uptimeAsNTP (unsigned long utt, uint64_t *ntpp, int bypass_validation)

int	iBSP430uptimeAsTimeval (unsigned long utt, struct timeval *tv)

time_t	xBSP430uptimeAsPOSIXTime (unsigned long utt)

int	iBSP430uptimeProcessNTPResponse (const sBSP430uptimeNTPPacketHeader req, const sBSP430uptimeNTPPacketHeader resp, uint64_t rec_ntp, int64_t adjustment_ntp, long adjustment_ms, unsigned long *rtt_us)

Detailed Description

bsp430/utility/uptime.h data structures and functions supporting conversion between civil time and the uptime facility.

Note: This functionality depends on configBSP430_UPTIME_EPOCH.

The uptime clock in BSP430 supports a 32-bit monotonically non-decreasing fixed-frequency counter used for low-resolution timing. Normally the clock is based on a 32 kiHz crystal; this can be divided, or the clock may be based on VLOCLK at roughly 10 kHz. Thus the minimum duration representable without wrapping is about 36 hours. The era of the uptime clock is the number of times it has wrapped since the system started. (For your amusement, the era can be found in the upper 16 bits of the overflow counter of the associated timer, but it is not used in this feature.)

In some applications it's necessary to correlate the internal time with a time standard such as UTC. While many MSP430s have a real-time clock that can assist in representing long durations, the key issue is registering the internal clock with a time standard. BSP430 supports this with the concept of an (uptime) epoch, being a representation of a time that corresponds to the start of an era, accurate to the resolution of the uptime clock.

As the era can change asynchronously to epoch updates, the following expectation affect use of the uptime epoch facility:

There is no valid epoch until the application provides one, through iBSP430uptimeSetEpochFromNTP() or iBSP430uptimeSetEpochFromTimeval().

If there is no valid epoch, the functions that convert to time standards (e.g., iBSP430uptimeAsTimeval(), xBSP430uptimeAsPOSIXTime()) return an error.

The epoch must be explicitly updated at least once every BSP430_UPTIME_EPOCH_UPDATE_INTERVAL_UTT ticks (1/4 era, or about nine hours at 32 kiHz).

Times that are to be converted must be within BSP430_UPTIME_EPOCH_VALID_OFFSET_UTT ticks (3/8 era, or about 13 hours at 32 kiHz) before or after the time the epoch was last updated.
Warning
Conversion of a time outside this range will invalidate the epoch.
The uptime epoch is invalidated when the uptime clock is suspended .

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

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

Macro Definition Documentation

#define BSP430_UPTIME_BYPASS_EPOCH_NTP ((uint64_t)(BSP430_UPTIME_POSIX_EPOCH_NTPIS + 1388534400UL) << 32)

An NTP timestamp for a time known to be within 34 years of any current server. The calculations of offset and round trip in section 8 "On-wire Protocol" of RFC5905 are valid only when the client and server are no more than 34 years apart. This is the epoch used when bypass_validity is used in iBSP430uptimeAsNTP(), as is the case when doing NTP client/server communications prior to obtaining a valid epoch.

Dependency:: configBSP430_UPTIME_EPOCH

#define BSP430_UPTIME_EPOCH_UPDATE_INTERVAL_UTT 0x40000000L

The maximum number of uptime ticks between updates to the epoch, if epoch consistency is to be maintained.

Dependency:: configBSP430_UPTIME_EPOCH

#define BSP430_UPTIME_EPOCH_VALID_OFFSET_UTT 0x60000000L

The maximum number of uptime ticks between an uptime value and the last time the epoch was updated that will not cause epoch invalidation if used to convert the uptime value.

Dependency:: configBSP430_UPTIME_EPOCH

#define BSP430_UPTIME_POSIX_EPOCH_NTPIS 2208988800UL

The time of the POSIX epoch (1970-01-01T00:00:00Z) as represented in integral seconds since the NTP epoch (1900-01-01T00:00:00Z).

Dependency:: configBSP430_UPTIME_EPOCH

Typedef Documentation

typedef struct sBSP430uptimeNTPPacketHeader sBSP430uptimeNTPPacketHeader

RFC5905 (NTP v4) packet header. Extension fields are not supported in this implementation.

Note: In almost no situations does a user need to inspect or mutate the fields of this structure. Use iBSP430uptimeInitializeNTPRequest() to initialize the structure, and iBSP430uptimeSetNTPXmtField() to set the transmission time.

Dependency:: configBSP430_UPTIME_EPOCH

typedef struct sBSP430uptimeNTPShortFormat sBSP430uptimeNTPShortFormat

RFC5905 (NTP v4) structure to represent a short-format time (more accurately, a duration, as there is no epoch).

Dependency:: configBSP430_UPTIME_EPOCH

typedef struct sBSP430uptimeNTPTimestamp sBSP430uptimeNTPTimestamp

RFC5905 (NTP v4) structure to represent a timestamp, measured in 2^32 Hz ticks since the NTP epoch 1900-01-01T00:00:00Z.

Dependency:: configBSP430_UPTIME_EPOCH

Function Documentation

int iBSP430uptimeAdjustEpochFromNTP ( int64_t adjustment_ntp )

Adjust the uptime epoch using a relative NTP timestamp.

Parameters

adjustment_ntp the number of ticks of a 2^32 Hz clock that must be added to the epoch to cause the local time to coincide with a reference clock.

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeAsNTP	(	unsigned long	utt,
		uint64_t *	ntpp,
		int	bypass_validation
	)

Convert a time to an NTP timestamp.

Parameters

utt	count of ticks since the last time the uptime clock rolled over.
ntpp	where to store the time represented by `utt` as the number of 2^32 Hz ticks since the NTP epoch (1900-01-01T00:00:00Z).
bypass_validation	a flag that bypasses the normal check to see that the epoch is valid. When set to a true value and the epoch is invalid, a pseudo-epoch corresponding to 2014-01-01T00:00:00Z is used so that a client NTP request packet can be formed with a valid transmission timestamp. You will need to set this flag when obtaining the `rec_ntp` parameter to iBSP430uptimeProcessNTPResponse() when the epoch is invalid. If the epoch is valid, this flag is ignored.

Returns: 0 if conversion is successful, otherwise a negative error code.

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeAsTimeval	(	unsigned long	utt,
		struct timeval *	tv
	)

Determine the current time to microsecond resolution by adding the uptime clock time in utt to a configured offset.

Parameters

utt	the uptime clock value
tv	where to store the converted time. The referenced object is left unchanged if the conversion fails.

Returns: 0 on success, a negative error code if the epoch is not valid or something else went wrong.

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeCheckEpochValidity ( )

Return 0 if there is an epoch that is presumed to be valid, or a negative error if no epoch is available.

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeEpochEra ( unsigned long time_utt )

Determine which era time_utt belongs to for the purposes of conversion using the current epoch.

Reasons for invalidity include:

There is no valid epoch at all (iBSP430uptimeCheckEpochValidity())

time_utt is more than BSP430_UPTIME_EPOCH_VALID_OFFSET_UTT ticks earlier or later than the time the epoch was last updated

Parameters

time_utt the time at which conversion is being proposed.

Returns: a negative code if time_utt cannot be converted. Non-negative results indicate the era, relative to the era the epoch was set for, in which time_utt lies (0 for the preceding, 1 for the same, 2 for the next).

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeInitializeNTPRequest ( sBSP430uptimeNTPPacketHeader * ntpp )

Initialize an NTP packet to serve as a request for the current time.

This initializes the leap-information, version, and mode flags, and sets the precision based on the local uptime clock. No timestamps are stored; see iBSP430uptimeNTPUpdateXmtField().

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

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeProcessNTPResponse	(	const sBSP430uptimeNTPPacketHeader *	req,
		const sBSP430uptimeNTPPacketHeader *	resp,
		uint64_t	rec_ntp,
		int64_t *	adjustment_ntp,
		long *	adjustment_ms,
		unsigned long *	rtt_us
	)

Process an NTP response.

This calculates the offset between the local uptime clock and the time provided by an external server.

The request and response packets are validated for server stratum, mismatched, and duplicate/bogus/replayed packets. Failure of these checks results in an error return.

Warning: On successful processing, the internally-stored uptime epoch is adjusted to account for the difference between local and server times.

Parameters

req	pointer to the locally-generated request packet. This may be null if you don't care to (or cannot) validate that the response origin time matches the request transmit time.
resp	pointer to the response packet. This must be provided and must be valid.
rec_ntp	the time when the response packet was received locally, in NTP 2^32 Hz ticks since the NTP epoch. Use iBSP430uptimeAsNTP() to convert from a local uptime measurement.
adjustment_ntp	optional (but recommended) location into which the delta between the local time and the server will be stored (a positive value indicates that the local time is behind the server). When a valid epoch is already available, this value is suitable for passing unmodified to iBSP430uptimeAdjustEpochFromNTP(). When a valid epoch is not available, this value should be added to BSP430_UPTIME_BYPASS_EPOCH_NTP and the result passed to iBSP430uptimeSetEpochFromNTP().
adjustment_ms	optional location in which the adjustment, converted to milliseconds, will be stored. This is primarily intended for diagnostics, as a value in milliseconds is more useful than the 2^32 Hz tick count provided by `adjustment_ntp`. If the offset cannot be represented in the space available, the signed maximum value will be stored. If the offset is not of interest, pass a null pointer. The value is not stored if this function returns an error.
rtt_us	optional location in which to store the estimated round-trip time for request and response. If the round-trip time cannot be represented (which should never happen), the maximum representable value will be stored. If the round-trip time is not of interest, pass a null pointer. The value is not stored if this function returns an error.

Returns: 0 on success, a negative error code on failure

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeSetEpochFromNTP ( uint64_t epoch_ntp )

Set the uptime epoch using an absolute NTP timestamp.

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeSetEpochFromTimeval	(	const struct timeval *	tv,
		unsigned long	when_utt
	)

Set the uptime epoch using an absolute Unix time value.

Parameters

tv	a civil time value
when_utt	the time within the current era at which `tv` is current.

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

Dependency:: configBSP430_UPTIME_EPOCH

int iBSP430uptimeSetNTPXmtField	(	sBSP430uptimeNTPPacketHeader *	ntpp,
		unsigned long *	putt
	)

Update the sBSP430uptimeNTPPacketHeader::xmt field.

This should be called just prior to (or while) transmitting an NTP request to ensure it holds the most accurate estimate of transmission time available.

Parameters

ntpp	pointer to the NTP packet to be updated
putt	pointer to the uptime clock value to be stored as transmission time. If this is a null pointer, the current time is stored.