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 iterations 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.

Data Structures
struct	EdtSSTimeAdjuster
Functions
double	edt_sstm_adjust (EdtDev *edt_p, double converge, double drift, int *active)
	Execute the time correction.
void	edt_sstm_adjuster_start (EdtSSTimeAdjuster *adj_p)
	Start an adjuster thread.
void	edt_sstm_adjuster_stop (EdtSSTimeAdjuster *adj_p)
	Stop an adjuster thread.
double	edt_sstm_calc_convergence (EdtDev *edt_p, int revert_secs, double drift_ticks)
	Calculate convergence value for auto time adjust.
void	edt_sstm_disable_adjust (EdtDev *edt_p)
	Turn off rate adjustment.
void	edt_sstm_enable_adjust (EdtDev *edt_p)
	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 (EdtDev *edt_p)
	Returns 0 or 1 depending on EDT_SSTM_ADJ_EN bit.
int	edt_sstm_get_adjust_sign (EdtDev *edt_p)
	Returns -1 or 1 depending on EDT_SSTM_ADJ_PLUS bit.
u_int	edt_sstm_get_adjust_ticks (EdtDev *edt_p)
	Returns the signed value of the adjustment.
u_int	edt_sstm_get_counts (EdtDev *edt_p)
	Returns the # of ticks = (1<<20)/1000000 microseconds.
u_int	edt_sstm_get_seconds (EdtDev *edt_p)
	Returns the current value of seconds.
void	edt_sstm_get_time_parts (EdtDev *edt_p, u_int *seconds, u_int *usecs)
	Gets both integer parts (secs/usecs) of time values.
u_int	edt_sstm_get_usecs (EdtDev *edt_p)
	Returns the current # of usecs as an unsigned int.
void	edt_sstm_iterate_adjust (EdtDev *edt_p, int revert_secs, int maxiterations, int tolerance, int *active)
	Calculate and execute automatic time correction.
void	edt_sstm_latch_time (EdtDev *edt_p)
	Latches the current time into registers.
EdtSSTimeAdjuster *	edt_sstm_launch_adjuster (EdtDev *edt_p, int check, int revert, int iterations, int max_usec_error, int tolerance, int loops)
	Start a thread to check and correct time against system time.
double	edt_sstm_measure_drift (EdtDev *edt_p)
	Calculate basic error rate between SS clock and sys clock.
void	edt_sstm_set (EdtDev *edt_p, unsigned int second)
	Set the current seconds value to second + 1, clears usecs, synched to system time.
void	edt_sstm_set_adj_from_drift (EdtDev *edt_p, double drift)
	Uses a drift value in usecs/sec to set the adjustment value on edt_p.
void	edt_sstm_set_adj_sign (EdtDev *edt_p, int positive)
	Sets the sign bit for rate adjustment.
void	edt_sstm_set_adj_ticks (EdtDev *edt_p, 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 (EdtDev *edt_p, unsigned int second)
	Set the current seconds value, clears usecs.
void	edt_sstm_set_to_sys (EdtDev *edt_p)
	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 (EdtDev *edt_p, int error)
	Sets the time to the current system time + an error in milliseconds.
void	edt_sstm_setup (EdtDev *edt_p, char *bitfile)
	Set the EDT timer - load the desired bitfile if necessary.
void	edt_sstm_strobe (EdtDev *edt_p, unsigned int bits)
	Execute strobed command in bits for EDT timer.
double	edt_sstm_sys_error (EdtDev *edt_p)
	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 (EdtDev *edt_p)
	Returns EDT time as double - seconds and microseconds.

---

Function Documentation

double edt_sstm_adjust	(	EdtDev *	edt_p,
		double	converge,
		double	drift,
		int *	active
	)

Execute the time correction.

Given two drift values, one to converge to zero error and a constant measured drift, block until as close as possible in this iteration. The stop value will be checked at 200 ms intervals to see whether to stop.

Parameters:

	edt_p	The device handle for the SS/GS board.
	converge	The error value in ppm to use to converge to sys time.
	drift	The measured drift rate in ppm.
	active	Points to a flag which can be cleared by another thread to interrupt the function.

Returns:

Returns the last error measured.

Definition at line 1017 of file ss_time_lib.c.

void edt_sstm_adjuster_start

(

EdtSSTimeAdjuster *

adj_p

)

Start an adjuster thread.

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

Parameters:

adj_p

The adjuster structure originally created by edt_sstm_launch_adjuster.

Definition at line 1258 of file ss_time_lib.c.

void edt_sstm_adjuster_stop

(

EdtSSTimeAdjuster *

adj_p

)

Stop an adjuster thread.

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

Parameters:

adj_p

The adjuster structure originally created by edt_sstm_launch_adjuster.

Definition at line 1241 of file ss_time_lib.c.

double edt_sstm_calc_convergence	(	EdtDev *	edt_p,
		int	revert_secs,
		double	drift
	)

Calculate convergence value for auto time adjust.

Finds total error and computes the drift adjustment to get to zero in revert_secs.

Parameters:

	edt_p	The device handle for the SS/GS board.
	revert_secs	How long in seconds before the EDT time converges to system time.
	drift	The measured drift in usecs/second.

Definition at line 980 of file ss_time_lib.c.

void edt_sstm_disable_adjust

(

EdtDev *

edt_p

)

Turn off rate adjustment.

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 578 of file ss_time_lib.c.

void edt_sstm_enable_adjust

(

EdtDev *

edt_p

)

Turn on rate adjustment.

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 590 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 773 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 787 of file ss_time_lib.c.

int edt_sstm_get_adjust_enabled

(

EdtDev *

edt_p

)

Returns 0 or 1 depending on EDT_SSTM_ADJ_EN bit.

Parameters:

edt_p

The device handle for the SS/GS board.

Returns:

0 if adjustment not enabled, 1 if it is.

Definition at line 354 of file ss_time_lib.c.

int edt_sstm_get_adjust_sign

(

EdtDev *

edt_p

)

Returns -1 or 1 depending on EDT_SSTM_ADJ_PLUS bit.

Parameters:

edt_p

The device handle for the SS/GS board.

Returns:

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

Definition at line 373 of file ss_time_lib.c.

u_int edt_sstm_get_adjust_ticks

(

EdtDev *

edt_p

)

Returns the signed value of the adjustment.

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 390 of file ss_time_lib.c.

u_int edt_sstm_get_counts

(

EdtDev *

edt_p

)

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

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 416 of file ss_time_lib.c.

u_int edt_sstm_get_seconds

(

EdtDev *

edt_p

)

Returns the current value of seconds.

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 404 of file ss_time_lib.c.

void edt_sstm_get_time_parts	(	EdtDev *	edt_p,
		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:

	edt_p	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 454 of file ss_time_lib.c.

u_int edt_sstm_get_usecs

(

EdtDev *

edt_p

)

Returns the current # of usecs as an unsigned int.

Parameters:

edt_p

The device handle for the SS/GS board.

Returns:

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

Definition at line 433 of file ss_time_lib.c.

void edt_sstm_iterate_adjust	(	EdtDev *	edt_p,
		int	revert_secs,
		int	maxiterations,
		int	tolerance,
		int *	active
	)

Calculate and execute automatic time correction.

This function attemts to get within tolerance microseconds of system time by repeatedly calculating the error and a convergence value, then calling edt_sstm_adjust.

Parameters:

	edt_p	The device handle for the SS/GS board.
	revert_secs	How long each iteration should take
	maxiterations	How many iterations to try to get within tolerance usecs
	tolerance	The target maximum error between system time and EDT time.
	active	Points to a flag which can be cleared by another thread to interrupt the function.

Definition at line 1083 of file ss_time_lib.c.

void edt_sstm_latch_time

(

EdtDev *

edt_p

)

Latches the current time into registers.

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 342 of file ss_time_lib.c.

EdtSSTimeAdjuster* edt_sstm_launch_adjuster	(	EdtDev *	edt_p,
		int	check,
		int	revert,
		int	iterations,
		int	max_usec_error,
		int	tolerance,
		int	loops
	)

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

Parameters:

	edt_p	The device handle for the SS/GS board.
	check	The interval between checking divergence in seconds.
	revert	How long a period in seconds for converging to 0 error.
	iterations	How many times to do the auto adjust if error exceeds max_usec_error.
	max_usec_error	The maximum error allowed in usecs before adjusting .
	tolerance	Microseconds to shoot for between EDT time and sys time.
	loops	How many times to run the check - 0 is indefinite.

Returns:

A pointer to the newly allocated EdtSSTimeAdjuster structure.

Definition at line 1199 of file ss_time_lib.c.

double edt_sstm_measure_drift

(

EdtDev *

edt_p

)

Calculate basic error rate between SS clock and sys clock.

Take mean of adj_samples over sample_seconds

Parameters:

edt_p

The device handle for the SS/GS board.

Returns:

Measured drift in usecs/sec.

Definition at line 842 of file ss_time_lib.c.

void edt_sstm_set	(	EdtDev *	edt_p,
		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:

	edt_p	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 508 of file ss_time_lib.c.

void edt_sstm_set_adj_from_drift	(	EdtDev *	edt_p,
		double	drift
	)

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

Parameters:

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

Definition at line 822 of file ss_time_lib.c.

void edt_sstm_set_adj_sign	(	EdtDev *	edt_p,
		int	positive
	)

Sets the sign bit for rate adjustment.

Parameters:

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

Definition at line 603 of file ss_time_lib.c.

void edt_sstm_set_adj_ticks	(	EdtDev *	edt_p,
		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:

	edt_p	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 623 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 758 of file ss_time_lib.c.

void edt_sstm_set_secs	(	EdtDev *	edt_p,
		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:

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

Definition at line 491 of file ss_time_lib.c.

void edt_sstm_set_to_sys

(

EdtDev *

edt_p

)

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

Parameters:

edt_p

The device handle for the SS/GS board.

Definition at line 523 of file ss_time_lib.c.

void edt_sstm_set_to_sys_error	(	EdtDev *	edt_p,
		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:

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

Definition at line 542 of file ss_time_lib.c.

void edt_sstm_setup	(	EdtDev *	edt_p,
		char *	bitfile
	)

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

Parameters:

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

Definition at line 250 of file ss_time_lib.c.

void edt_sstm_strobe	(	EdtDev *	edt_p,
		unsigned int	bits
	)

Execute strobed command in bits for EDT timer.

Commands to the EDT timer are passed by strobing in to register 8f (EDT_SSTM_CMD). Possible values are:

        EDT_SSTM_COPY     - This copies the value of register EDT_SSTM_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 EDT_SSTM_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:

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

Definition at line 279 of file ss_time_lib.c.

double edt_sstm_sys_error

(

EdtDev *

edt_p

)

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:

edt_p

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 648 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 801 of file ss_time_lib.c.

double edt_sstm_timestamp

(

EdtDev *

edt_p

)

Returns EDT time as double - seconds and microseconds.

Parameters:

edt_p

The device handle for the SS/GS board.

Returns:

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

Definition at line 471 of file ss_time_lib.c.

---