EDT Time Library

Detailed Description

EDT Time software functions include setting the board time to system time as UNIX time (seconds since January 1, 1970), retrieving the 64-bit time value, and adjusting for the errors between system time and EDT Time.

The clock on the EDT board can be adjusted to compensate for the drift between board time and system time, as well as adjusted to converge back to the desired system time without time values ever decreasing. Also, functions are provided to create a monitoring thread that periodically samples the error between EDT time and system time, then adjusts the board time accordingly.

EDT Time starts automatically as soon as the FPGA configuration file is loaded. The following table summarizs the most useful time functions:

Purpose Function

To set the time to current system time edt_sstm_set_to_sys

To retrieve the current time edt_sstm_timestamp

To get the current error between EDT time and system time edt_sstm_measure_drift

To measure the drift between EDT Time and system time edt_sstm_sys_error

To calculate the current error and revert to system time gradually edt_sstm_iterate_adjust

To create and start an adjustment thread edt_sstm_launch_adjuster

Note:: It doesn't matter which channel an application opens, as there's only one clock per board.

Below is a simple example to set the board time, then launch an adjustment thread that samples every five minutes:

    edt_p = edt_open(EDT_INTERFACE, unit);
    edt_sstm_set_to_sys(edt_p);
    adjuster = edt_sstm_launch_adjuster(edt_p,
                    300, // check every 5 minutes
                    20,  // # of adjustment_scalar of adjustment as error gets smaller
                    10,  // each iteration should take 10 secs.
                    200, // maximum 200 microsecond error allowed
                    20,  // try to get within 20 microseconds
                    0    // loop indefinitely
                    );
    // for this example just go to sleep
    while (1)
        edt_msleep(300000);

The sample program provided, edt_ss_time.c, implements the above code. To run it, enter:

edt_ss_time -T -L 300 20 200

It also exercises the other EDT Time functions.

Functions

void edt_sstm_adjuster_start (EdtTimeController *tm)

Start an adjuster thread.

void edt_sstm_adjuster_stop (EdtTimeController *tm)

Stop an adjuster thread.

void edt_sstm_disable_adjust (EdtTimeController *tm)

Turn off rate adjustment.

void edt_sstm_enable_adjust (EdtTimeController *tm)

Turn on rate adjustment.

int edt_sstm_get_adj_sample_secs ()

Get the current value of adj_sample_seconds.

int edt_sstm_get_adj_samples ()

Get the current value of adj_samples.

int edt_sstm_get_adjust_enabled (EdtTimeController *tm)

Returns 0 or 1 depending on EDT_SSTM_ADJ_EN bit.

int edt_sstm_get_adjust_sign (EdtTimeController *tm)

Returns -1 or 1 depending on EDT_SSTM_ADJ_PLUS bit.

u_int edt_sstm_get_adjust_ticks (EdtTimeController *tm)

Returns the signed value of the adjustment.

u_int edt_sstm_get_counts (EdtTimeController *tm)

Returns the # of ticks = (1<<20)/1000000 microseconds.

u_int edt_sstm_get_seconds (EdtTimeController *tm)

Returns the current value of seconds.

void edt_sstm_get_time_parts (EdtTimeController *tm, u_int *seconds, u_int *usecs)

Gets both integer parts (secs/usecs) of time values.

u_int edt_sstm_get_usecs (EdtTimeController *tm)

Returns the current # of usecs as an unsigned int.

void edt_sstm_latch_time (EdtTimeController *tm)

Latches the current time into registers.

EdtTimeController * edt_sstm_launch_adjuster (EdtTimeController *tm)

Start a thread to check and correct time against system time.

double edt_sstm_measure_drift (EdtTimeController *tm)

Calculate basic error rate between SS clock and sys clock.

void edt_sstm_set (EdtTimeController *tm, unsigned int second)

Set the current seconds value to second + 1, clears usecs, synched to system time.

void edt_sstm_set_adj_from_drift (EdtTimeController *tm, double drift)

Uses a drift value in usecs/sec to set the adjustment value on tm.

void edt_sstm_set_adj_sign (EdtTimeController *tm, int positive)

Sets the sign bit for rate adjustment.

void edt_sstm_set_adj_ticks (EdtTimeController *tm, int ticks, int positive)

Sets the time adjustment to tick counts between an adjustment.

void edt_sstm_set_drift_sampling (int seconds, int samples)

Sets the parameters used to measure drift.

void edt_sstm_set_secs (EdtTimeController *tm, unsigned int second)

Set the current seconds value, clears usecs.

void edt_sstm_set_to_sys (EdtTimeController *tm)

Sets the time to the current system time, by waiting for zero crossing, then half a second, then calling edt_sstm_set.

void edt_sstm_set_to_sys_error (EdtTimeController *tm, int error)

Sets the time to the current system time + an error in milliseconds.

void edt_sstm_setup (EdtTimeController *tm, char *bitfile)

Set the EDT timer - load the desired bitfile if necessary.

void edt_sstm_strobe (EdtTimeController *tm, unsigned int bits)

Execute strobed command in bits for EDT timer.

double edt_sstm_sys_error (EdtTimeController *tm)

Return the mean error between EDT time and sys time as a double (in seconds).

int edt_sstm_ticks_from_drift (double drift)

Compute the adjustment ticks from drift value in ppm.

double edt_sstm_timestamp (EdtTimeController *tm)

Returns EDT time as double - seconds and microseconds.

Function Documentation

void edt_sstm_adjuster_start ( EdtTimeController * tm )

Start an adjuster thread.

Starts a thread running with adjuster tm, by setting active to 1 and launching a new thread.

Parameters:

The adjuster structure originally created by edt_sstm_launch_adjuster.

Definition at line 1120 of file ss_time_lib.c.

void edt_sstm_adjuster_stop ( EdtTimeController * tm )

Stop an adjuster thread.

Stops the thread running with adjuster tm, by setting active to 0 and waiting until done goes true.

Parameters:

The adjuster structure originally created by edt_sstm_launch_adjuster.

Definition at line 1100 of file ss_time_lib.c.

void edt_sstm_disable_adjust ( EdtTimeController * tm )

Turn off rate adjustment.

Parameters:

The device handle for the SS/GS board.

Definition at line 593 of file ss_time_lib.c.

void edt_sstm_enable_adjust ( EdtTimeController * tm )

Turn on rate adjustment.

Parameters:

The device handle for the SS/GS board.

Definition at line 605 of file ss_time_lib.c.

int edt_sstm_get_adj_sample_secs ( )

Get the current value of adj_sample_seconds.

adj_sample_seconds is the total time sampled by the drift measure routine. Set using edt_sstm_set_drift_sampling.

Returns:: the current value of adj_samples;

Definition at line 804 of file ss_time_lib.c.

int edt_sstm_get_adj_samples ( )

Get the current value of adj_samples.

adj_samples is the number of samples used to compute drift Set using edt_sstm_set_drift_sampling.

Returns:: the current value of adj_samples;

Definition at line 818 of file ss_time_lib.c.

int edt_sstm_get_adjust_enabled ( EdtTimeController * tm )

Returns 0 or 1 depending on EDT_SSTM_ADJ_EN bit.

Parameters:

The device handle for the SS/GS board.

Returns:: 0 if adjustment not enabled, 1 if it is.

Definition at line 367 of file ss_time_lib.c.

int edt_sstm_get_adjust_sign ( EdtTimeController * tm )

Returns -1 or 1 depending on EDT_SSTM_ADJ_PLUS bit.

Parameters:

The device handle for the SS/GS board.

Returns:: -1 if positive adjustment not enabled, 1 if it is.

Definition at line 386 of file ss_time_lib.c.

u_int edt_sstm_get_adjust_ticks ( EdtTimeController * tm )

Returns the signed value of the adjustment.

Parameters:

The device handle for the SS/GS board.

Definition at line 403 of file ss_time_lib.c.

u_int edt_sstm_get_counts ( EdtTimeController * tm )

Returns the # of ticks = (1<<20)/1000000 microseconds.

Parameters:

The device handle for the SS/GS board.

Definition at line 429 of file ss_time_lib.c.

u_int edt_sstm_get_seconds ( EdtTimeController * tm )

Returns the current value of seconds.

Parameters:

The device handle for the SS/GS board.

Definition at line 417 of file ss_time_lib.c.

void edt_sstm_get_time_parts	(	EdtTimeController *	tm,
		u_int *	seconds,
		u_int *	usecs
	)

Gets both integer parts (secs/usecs) of time values.

This routine latches the current time, then returns the two 32 bit integers into the pointers passed in.

Parameters:

	tm	The device handle for the SS/GS board.
	seconds	Pointer to value returned for seconds.
	usecs	Pointer to value returned for microseconds.

Definition at line 467 of file ss_time_lib.c.

u_int edt_sstm_get_usecs ( EdtTimeController * tm )

Returns the current # of usecs as an unsigned int.

Parameters:

The device handle for the SS/GS board.

Returns:: The value calculated by multiplying the counts register by (1<<20)/1000000).

Definition at line 446 of file ss_time_lib.c.

void edt_sstm_latch_time ( EdtTimeController * tm )

Latches the current time into registers.

Parameters:

The device handle for the SS/GS board.

Definition at line 355 of file ss_time_lib.c.

EdtTimeController* edt_sstm_launch_adjuster ( EdtTimeController * tm )

Start a thread to check and correct time against system time.

Parameters:

The EdtTimeController

Returns:: A pointer to the EdtTimeController structure.

Definition at line 1073 of file ss_time_lib.c.

double edt_sstm_measure_drift ( EdtTimeController * tm )

Calculate basic error rate between SS clock and sys clock.

Take mean of adj_samples over sample_seconds

Parameters:

The device handle for the SS/GS board.

Returns:: Measured drift in usecs/sec.

Definition at line 875 of file ss_time_lib.c.

void edt_sstm_set	(	EdtTimeController *	tm,
		unsigned int	second
	)

Set the current seconds value to second + 1, clears usecs, synched to system time.

Calls edt_wait_for_zero before strobing value.

Parameters:

	tm	The device handle for the SS/GS board.
	second	The value for the seconds counter. Note that this ends up incremented by one, because of the wait for zero crossing in system time.

Definition at line 521 of file ss_time_lib.c.

void edt_sstm_set_adj_from_drift	(	EdtTimeController *	tm,
		double	drift
	)

Uses a drift value in usecs/sec to set the adjustment value on tm.

Parameters:

	tm	The device handle for the SS/GS board.
	drift	The drift in usecs/sec for which to compensate.

Definition at line 855 of file ss_time_lib.c.

void edt_sstm_set_adj_sign	(	EdtTimeController *	tm,
		int	positive
	)

Sets the sign bit for rate adjustment.

Parameters:

	tm	The device handle for the SS/GS board.
	positive	Set to 1 for positive adjustment, 0 for negative.

Definition at line 618 of file ss_time_lib.c.

void edt_sstm_set_adj_ticks	(	EdtTimeController *	tm,
		int	ticks,
		int	positive
	)

Sets the time adjustment to tick counts between an adjustment.

Positive indicates whether change is positive or negative. You can't use the sign of ticks itself because -0 is very different from 0.

Parameters:

	tm	The device handle for the SS/GS board.
	ticks	The number of adjustment ticks to set.
	positive	Whether the change is positive or negative

Definition at line 652 of file ss_time_lib.c.

void edt_sstm_set_drift_sampling	(	int	seconds,
		int	samples
	)

Sets the parameters used to measure drift.

Parameters:

	seconds	How many seconds to measure in total
	samples	How many samples to take over the time set by seconds

Definition at line 789 of file ss_time_lib.c.

void edt_sstm_set_secs	(	EdtTimeController *	tm,
		unsigned int	second
	)

Set the current seconds value, clears usecs.

This isn't in synch with system time - to do so use edt_sstm_set instead, which waits for system zero crossing.

Parameters:

	tm	The device handle for the SS/GS board.
	second	The value for the seconds counter

Definition at line 504 of file ss_time_lib.c.

void edt_sstm_set_to_sys ( EdtTimeController * tm )

Sets the time to the current system time, by waiting for zero crossing, then half a second, then calling edt_sstm_set.

Parameters:

The device handle for the SS/GS board.

Definition at line 538 of file ss_time_lib.c.

void edt_sstm_set_to_sys_error	(	EdtTimeController *	tm,
		int	error
	)

Sets the time to the current system time + an error in milliseconds.

Waits for zero crossing, then half a second, then calling edt_sstm_set. Attempts to add error milliseconds to time.

Parameters:

	tm	The device handle for the SS/GS board.
	error	Signed error in milliseconds.

Definition at line 557 of file ss_time_lib.c.

void edt_sstm_setup	(	EdtTimeController *	tm,
		char *	bitfile
	)

Set the EDT timer - load the desired bitfile if necessary.

Parameters:

	tm	The device handle for the SS/GS board.
	bitfile	Name of an optional bitfile. Null uses default "c3_demux.bit".

Definition at line 263 of file ss_time_lib.c.

void edt_sstm_strobe	(	EdtTimeController *	tm,
		unsigned int	bits
	)

Execute strobed command in bits for EDT timer.

Commands to the EDT timer are passed by strobing in to register 8f (tm->cmd). Possible values are:

EDT_SSTM_COPY     - This copies the value of register tm->set to timer
EDT_SSTM_LATCH    - This latches the current counter values into the EDT_SSTM_TIME registers
EDT_SSTM_COPY_ADJ - This copies the value of register tm->set to timer adjust register

The routine uses the top bit (7) as a "lock" to minimize contention

Bits 4, 5, and 6 are preserved.

Parameters:

	tm	The device handle for the SS/GS board.
	bits	Which bit to strobe.

Definition at line 292 of file ss_time_lib.c.

double edt_sstm_sys_error ( EdtTimeController * tm )

Return the mean error between EDT time and sys time as a double (in seconds).

The error is measured by getting the EDT time before and after the system time, then averages the difference.

Parameters:

The device handle for the SS/GS board.

Returns:: The difference in seconds between EDT time and system time, precise to microseconds.

Definition at line 679 of file ss_time_lib.c.

int edt_sstm_ticks_from_drift ( double drift )

Compute the adjustment ticks from drift value in ppm.

Parameters:

drift

The drift value in ppm or usecs/sec to correct.

Returns:: the integer value to set the adjustment.

Definition at line 832 of file ss_time_lib.c.

double edt_sstm_timestamp ( EdtTimeController * tm )

Returns EDT time as double - seconds and microseconds.

Parameters:

The device handle for the SS/GS board.

Returns:: The current time in seconds from the board, precise to microseconds.

Definition at line 484 of file ss_time_lib.c.

Generated on 19 Jun 2015 by

1.4.7

Purpose	Function
To set the time to current system time	edt_sstm_set_to_sys
To retrieve the current time	edt_sstm_timestamp
To get the current error between EDT time and system time	edt_sstm_measure_drift
To measure the drift between EDT Time and system time	edt_sstm_sys_error
To calculate the current error and revert to system time gradually	edt_sstm_iterate_adjust
To create and start an adjustment thread	edt_sstm_launch_adjuster


Functions
void	edt_sstm_adjuster_start (EdtTimeController *tm)
	Start an adjuster thread.
void	edt_sstm_adjuster_stop (EdtTimeController *tm)
	Stop an adjuster thread.
void	edt_sstm_disable_adjust (EdtTimeController *tm)
	Turn off rate adjustment.
void	edt_sstm_enable_adjust (EdtTimeController *tm)
	Turn on rate adjustment.
int	edt_sstm_get_adj_sample_secs ()
	Get the current value of adj_sample_seconds.
int	edt_sstm_get_adj_samples ()
	Get the current value of adj_samples.
int	edt_sstm_get_adjust_enabled (EdtTimeController *tm)
	Returns 0 or 1 depending on EDT_SSTM_ADJ_EN bit.
int	edt_sstm_get_adjust_sign (EdtTimeController *tm)
	Returns -1 or 1 depending on EDT_SSTM_ADJ_PLUS bit.
u_int	edt_sstm_get_adjust_ticks (EdtTimeController *tm)
	Returns the signed value of the adjustment.
u_int	edt_sstm_get_counts (EdtTimeController *tm)
	Returns the # of ticks = (1<<20)/1000000 microseconds.
u_int	edt_sstm_get_seconds (EdtTimeController *tm)
	Returns the current value of seconds.
void	edt_sstm_get_time_parts (EdtTimeController tm, u_int seconds, u_int *usecs)
	Gets both integer parts (secs/usecs) of time values.
u_int	edt_sstm_get_usecs (EdtTimeController *tm)
	Returns the current # of usecs as an unsigned int.
void	edt_sstm_latch_time (EdtTimeController *tm)
	Latches the current time into registers.
EdtTimeController *	edt_sstm_launch_adjuster (EdtTimeController *tm)
	Start a thread to check and correct time against system time.
double	edt_sstm_measure_drift (EdtTimeController *tm)
	Calculate basic error rate between SS clock and sys clock.
void	edt_sstm_set (EdtTimeController *tm, unsigned int second)
	Set the current seconds value to second + 1, clears usecs, synched to system time.
void	edt_sstm_set_adj_from_drift (EdtTimeController *tm, double drift)
	Uses a drift value in usecs/sec to set the adjustment value on tm.
void	edt_sstm_set_adj_sign (EdtTimeController *tm, int positive)
	Sets the sign bit for rate adjustment.
void	edt_sstm_set_adj_ticks (EdtTimeController *tm, int ticks, int positive)
	Sets the time adjustment to tick counts between an adjustment.
void	edt_sstm_set_drift_sampling (int seconds, int samples)
	Sets the parameters used to measure drift.
void	edt_sstm_set_secs (EdtTimeController *tm, unsigned int second)
	Set the current seconds value, clears usecs.
void	edt_sstm_set_to_sys (EdtTimeController *tm)
	Sets the time to the current system time, by waiting for zero crossing, then half a second, then calling edt_sstm_set.
void	edt_sstm_set_to_sys_error (EdtTimeController *tm, int error)
	Sets the time to the current system time + an error in milliseconds.
void	edt_sstm_setup (EdtTimeController tm, char bitfile)
	Set the EDT timer - load the desired bitfile if necessary.
void	edt_sstm_strobe (EdtTimeController *tm, unsigned int bits)
	Execute strobed command in bits for EDT timer.
double	edt_sstm_sys_error (EdtTimeController *tm)
	Return the mean error between EDT time and sys time as a double (in seconds).
int	edt_sstm_ticks_from_drift (double drift)
	Compute the adjustment ticks from drift value in ppm.
double	edt_sstm_timestamp (EdtTimeController *tm)
	Returns EDT time as double - seconds and microseconds.