GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-6

Constituent: pbs     Tag: linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  

WCT.h File Reference

Wall Clock Time, function prototypes and public data structures. More...

#include "PBI/Endianness.h"

Include dependency graph for WCT.h:

Include dependency graph

This graph shows which files directly or indirectly include this file:

Included by dependency graph

Data Structures

struct  _WCT_time_sat_s
 This defines Spectrum Astro Standard Time (SAT) as a structure. More...

union  _WCT_time_sat_u
 This defines Spectrum Astro Standard Time (SAT) as a union between the structure and the long long representation. More...


Defines

#define WCT_K_NSECS_IN_A_SEC   1000000000
 Convenience symbol for 1,000,000,000.

#define WCT_K_NSECS_IN_A_MSEC   1000000
 Convenience symbol for 1,000,000, could come in handy; besides it completes the suite.

#define WCT_K_NSECS_IN_A_USEC   1000
 Convenience symbol for 1000, used when converting time specified in seconds.usecs to nanoseconds.

#define WCT_EXTRACT_SECS_NSECS(_wct, _secs, _nsecs)
 Extracts the number of seconds/nanoseconds.

#define WCT_SECS(_wct)   ( (_wct) / WCT_K_NSECS_IN_A_SEC)
 Returns the number of full seconds in the specified time.

#define WCT_NSECS(_wct)   ( (_wct) % WCT_K_NSECS_IN_A_SEC)
 Returns the fractional number of nanoseconds in the specified time.

#define WCT_USECS(_wct)   (WCT_NSECS(_wct) / WCT_K_NSECS_IN_A_USEC)
 Returns the fractional number of microseconds in the specified time.

#define WCT_MSECS(_wct)   (WCT_NSECS(_wct) / WCT_K_NSECS_IN_A_MSEC)
 Returns the fractional number of milliseconds in the specified time.

#define WCT_K_UTB_OFFSET_IN_SECS   0x3a4fc880
 The difference, in seconds, of the LAT epoch (Jan 1, 2001) and the traditional UNIX epoch (Jan 1, 1970).

#define WCT_K_UTB_OFFSET_IN_NSECS
 The difference, in nanoseconds, of the LAT epoch (Jan 1, 2001) and the traditional UNIX epoch (Jan 1, 1970).


Typedefs

typedef int WCT_tick
 Typedef for differential time in Wall Clock Time units.

typedef signed long long WCT_time
 Representation for an absolute Wall Clock Time time.

typedef signed long long int WCT_time_sat
 The Spectrum-Astro time as a long long int.

typedef _WCT_time_sat_s WCT_time_sat_s
 Typedef for struct _WCT_time_sat_s.

typedef _WCT_time_sat_u WCT_time_sat_u
 Typedef for struct _WCT_time_sat_u.


Functions

long long int WCT_set (register WCT_time atime, unsigned int ptime, unsigned int aticks, unsigned int pticks)
 Sets both the absolute time and the information needed to convert back and forth from WCT_atick and WCT_ptick.

WCT_time WCT_get (void)
 Retrieves the current time in absolute time units.

unsigned int WCT_update (void)
 Reset the time bases that tie the PTIME and ATIME.

WCT_time WCT_utb_get (void)
 Retrieves the current time in absolute time units.

WCT_time WCT_to_utb (WCT_time lat_epoch_time)
 Converts a wall clock time specified with a base of the LAT epoch to a wall clock time specified with a base of the tradional UNIX epoch.

WCT_time WCT_from_utb (WCT_time unix_epoch_time)
 Converts a wall clock time specified with a base of the LAT epoch to a wall clock time specified with a base of the tradional UNIX epoch.

WCT_time_sat WCT_sat_get (void)
 Retrieves the current time in absolute time units. The format is in Spectrum-Astro Standard Time format.

WCT_time_sat WCT_to_sat (WCT_time lat_epoch_time)
 Converts a wall clock time specified with Spectrum-Astro Standard Format.

WCT_time WCT_from_sat (WCT_time_sat sat_time)
 Converts a Spectrum Astro Time Format to LAT format.

Detailed Description

Wall Clock Time, function prototypes and public data structures.

Author:
JJRussell - russell@slac.stanford.edu

    CVS $Id: WCT.h,v 1.6 2005/05/04 20:53:04 russell Exp $

Define Documentation

#define WCT_EXTRACT_SECS_NSECS (  _wct,
_secs,
_nsecs   ) 
 

Value:

{                                                    \
   _secs  = (_wct) / WCT_K_NSECS_IN_A_SEC;           \
   _nsecs = (_wct) - WCT_K_NSECS_IN_A_SEC * (_secs); \
}
Extracts the number of seconds/nanoseconds.

(_wct, _secs, _nsecs)

Parameters:
_wct The WCT_time to break down
_secs The number of full seconds in the specified time
_nsecs The number of nanoseconds remaining after the full seconds
The implementation of this macro is platform dependent.

#define WCT_K_UTB_OFFSET_IN_NSECS
 

Value:

((unsigned long long)(WCT_K_UTB_OFFSET_IN_SECS) *                 \
         (unsigned long long)(WCT_K_NSECS_IN_A_SEC))
The difference, in nanoseconds, of the LAT epoch (Jan 1, 2001) and the traditional UNIX epoch (Jan 1, 1970).

#define WCT_MSECS (  _wct   )     (WCT_NSECS(_wct) / WCT_K_NSECS_IN_A_MSEC)
 

Returns the fractional number of milliseconds in the specified time.

Returns:
the number of milliseconds in the specified time
Parameters:
_wct The time

#define WCT_NSECS (  _wct   )     ( (_wct) % WCT_K_NSECS_IN_A_SEC)
 

Returns the fractional number of nanoseconds in the specified time.

Returns:
the number of nanoseconds in the specified time
Parameters:
_wct The time

#define WCT_SECS (  _wct   )     ( (_wct) / WCT_K_NSECS_IN_A_SEC)
 

Returns the number of full seconds in the specified time.

Returns:
The number of full seconds in the specified time
Parameters:
_wct The time

#define WCT_USECS (  _wct   )     (WCT_NSECS(_wct) / WCT_K_NSECS_IN_A_USEC)
 

Returns the fractional number of microseconds in the specified time.

Returns:
the number of microseconds in the specified time
Parameters:
_wct The time

Typedef Documentation

WCT_tick
 

Typedef for differential time in Wall Clock Time units.

Absolute units are typically nanoseconds, but the WCT facility does not impose this. The representation is 32 bits, so with nanoseconds one can specify a delta time of +/- 2*31 nanoseconds or approximately +/- 2 seconds.

WCT_time
 

Representation for an absolute Wall Clock Time time.

Resolution
This is a 64 bit representation of absolute time. WCT originally did not say anything about the resolution, but slowly and surely a resolution of nanoseconds has crept in as a defacto standard. This gives WCT_time a range of +/- 68 years.
Base
Internally the base value, i.e. 0, represents Jan 1, 2001. Note that this is matches the S/C definition of the epoch, but not the usual UNIX definition of Jan 1, 1970. Since WCT_time is a signed quantity, negative times represent dates before the epoch. It is not expected that these will be used, but for completeness it is described here.
Common Utilities
Routines exist to fetch the current time in terms of traditional the UNIX epoch, WCT_utb_get (), for Unix Time Base Get, and to convert to and from UTB WCT_to_utb () and WCT_from_utb().

Function Documentation

WCT_time WCT_from_sat (  WCT_time_sat  sat_time  ) 
 

Converts a Spectrum Astro Time Format to LAT format.

Parameters:
sat_time The wall clock time in Spectrum-Astro Format
Returns:
The wall clock time in LAT format

WCT_time WCT_from_utb (  WCT_time  unix_epoch_time  ) 
 

Converts a wall clock time specified with a base of the LAT epoch to a wall clock time specified with a base of the tradional UNIX epoch.

Parameters:
unix_epoch_time The wall clock time using the LAT epoch as a base
Returns:
The wall clock time using the UNIX epoch as a base

WCT_time WCT_get (  void   ) 
 

Retrieves the current time in absolute time units.

This routine is coded to be a cheap call on the PowerPC, involving less than 20 cycles. Other implementations may be more expensive.

long long int WCT_set (  register WCT_time  atime,
unsigned int  ptime,
unsigned int  aticks,
unsigned int  pticks
) 
 

Sets both the absolute time and the information needed to convert back and forth from WCT_atick and WCT_ptick.

Returns:
The adjustment time in absolute ticks.
This is a call-back routine to announce a precise time and the provide the numbers needed to convert absolute ticks to and from processor ticks. It is expected that this routine will be called from an ISR routine and, so is coded to obey the rules of an ISR.
The natural example is in the context of the 1 PPS interrupt. When the 1 PPS interrupt is received, the processor clock is read and the absolute time is retrieved from the most recent GPS message. The elapsed time in both absolute ticks and processor ticks since the last 1PPS message are the last two arguments.
Note that this routine does not assume that it being called at 1 second intervals or even regular intervals. The interface does not prohibit the caller from violating the three rules of a good clock. It is the responsibility of the caller to be a good citizen. Arthimetic limitations make it unsafe to call it at intervals longer than this.
If the time shift is very large, as in the case when the system has been running a while before the absolute time can be established, one may wish to use the return value to adjust times in other components of the system. The most notable example would be to adjust the expiration time in the WUT timer que entries.

WCT_time_sat WCT_to_sat (  WCT_time  lat_epoch_time  ) 
 

Converts a wall clock time specified with Spectrum-Astro Standard Format.

Parameters:
lat_epoch_time The wall clock time using the LAT epoch as a base
Returns:
The wall clock time using in Spectrum-Astro Standard Format.

WCT_time WCT_to_utb (  WCT_time  lat_epoch_time  ) 
 

Converts a wall clock time specified with a base of the LAT epoch to a wall clock time specified with a base of the tradional UNIX epoch.

Parameters:
lat_epoch_time The wall clock time using the LAT epoch as a base
Returns:
The wall clock time using the UNIX epoch as a base

unsigned WCT_update (  void   ) 
 

Reset the time bases that tie the PTIME and ATIME.

This is a simplified version of WCT_set. However, whereas WCT_set adjusts both the time base and the frequency, this routine only adjusts the only time bases to the current time without changing the frequency. It is primarily meant to be used in an environment where there is no external clock/time source and is needed to keep the time conversion scaling parameters from causing an overflow.
Warning:
Since this routine resets the scaling parameters, it must be called under conditions which ensure that the scaling parameters are not being modified by another thread of execution. Typically the easiest way to ensure this condition is to lock the interrupts around the call to WCT_update. A design choice was made to not have this routine do the locking for two reasons
  1. The user may have a better way to ensure this
  2. The most natural calling of this routine will occur within the context of a WUT ISR, i.e. interrrupts are already locked.

WCT_time WCT_utb_get (  void   ) 
 

Retrieves the current time in absolute time units.

This routine is coded to be a cheap call on the PowerPC, involving less than 20 cycles. Other implementations may be more expensive.

Generated on Fri Sep 30 22:53:19 2005 by doxygen 1.3.3