LSF_statsHdr.h File Reference

Defines a header common to all event-based statistics datagrams. More...

Classes
struct	_LSF_statsHdrTimetone
	Defines the most general version of the timetone information. More...
struct	_LSF_statsHdrTimetones
	Captures the information needed to convert a GEM event clock register value into an absolute time. More...
struct	_LSF_statsHdrEvtSeq
	Hide the access to the long long to avoid alignment issues. More...
struct	_LSF_statsHdrEvt
	Captures the information needed to uniquely identify this event by sequence and time. More...
struct	_LSF_statsHdrEvtSpan
	The defining information about the first and last event that went into the sample. More...
struct	_LSF_statsHdr
	The standard header for event-based statistics. More...
Typedefs
typedef struct _LSF_statsHdrTimetone	LSF_statsHdrTimetone
	Typedef for struct _LSF_statsHdrTimetone.
typedef struct _LSF_statsHdrTimetones	LSF_statsHdrTimetones
	Typedef for struct _LSF_statsHdrTimetones.
typedef struct _LSF_statsHdrEvtSeq	LSF_statsHdrEvtSeq
	Typedef for struct _LSF_statsHdrEvtSeq.
typedef struct _LSF_statsHdrEvt	LSF_statsHdrEvt
	Typedef for _LSF_statsHdrEvt.
typedef struct _LSF_statsHdrEvtSpan	LSF_statsHdrEvtSpan
	Typedef for struct _LSF_statsHdrEvtSpan.
typedef struct _LSF_statsHdr	LSF_statsHdr
	Typedef for struct _LSF_statsHdr LSF_statsHdr.
Functions
static __inline void	LSF__statsHdrEvtSeqSet (LSF_statsHdrEvtSeq *dst, unsigned long long int src)
	Hide access to the long long sequence number to avoid big/little endian and alignment issues.
static __inline unsigned long long int	LSF__statsHdrEvtSeqGet (const LSF_statsHdrEvtSeq *seq)
	Hide access to the long long sequence number to avoid big/little endian and alignment issues.

---

Detailed Description

Defines a header common to all event-based statistics datagrams.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: LSF_statsHdr.h,v 1.4 2005/11/17 20:53:18 russell Exp $

This defines a header common to all event-based statistics datagrams. The design goals were to

1. Uniquely identify the time and event number of the first event used in the sample
2. Uniquely identify the time and event number of the last event used in the sample

Note that the actual first or last event may have not contributed to the statistics.

Note:

Putting this file in LSF is somewhat of a stretch, but LSF has all the right attributes, namely

1. It is low enough in the package heirarchy that all clients can safely get access to it
2. It is a package that is exported for ground usage.

I have left an out for defining a full and abbreviated version. The abbreviated version would omit the flags and and previous GPS clock value if the flags where identically 0 and the difference in the time was precisely 1. This is the usual state of affairs and could make the header considerably smaller. The size of header is not thought to be a problem at this time.

Another thing to keep in mind, this is really the definition of the information that needs to be presented to ground consumer. The creator of a statistics datagram is free to pack this information anyway he chooses as long as when one presents the information to the consumer this structure can be filled out in a meaning way. To that end, a Q version of this structure should be created (in the appropriate Q package) which is the official interface to the ground consumer.

---

Typedef Documentation

LSF_statsHdr

Typedef for struct _LSF_statsHdr LSF_statsHdr.

Goals

This structure attempts to provide two pieces of information

1. The number of events that were used to accumulate this sample
2. Unique identification, both by time and event sequence number, of the first and last events. This defines the span of the accumulated statistics.

Accessing Information

The depth of the structure definitions makes the pathnames to individual field members somewhat unwieldy. However, binding information into well-defined structures, allows one to write utility programs that consume these structures as single arguments. This is the preferred usage.

Usage, Direct Access

A sample usage is

       first_evt_sequence = hdr->evt.first.seq;
       last_evt_sequence  = hdr->evt.last.seq;
       beg_seconds        = hdr->evt.first.timetones.cur.secs;
       end_seconds        = hdr->evt.last.timetones.cur.secs;
       elasped_seconds    = beg_seconds - end_seconds;
       events_seen        = last_evt_sequence - first_evt_sequence;
       events_accumulated = hdr->nevts;

Usage, Utility Access

Discovering the absolute time beyond the second accurary requires using the all information in the timetone structures. The full treatment, covering error cases, is beyond the scope of a simple example. The following example assumes, no errors and no overflows. The easies way to code a utility function

    unsigned long long int get_event_time (const LSF_statsHdrEvt *evt)
    {
       unsigned int curGemStrobe  = evt->timetones.cur.gemStrobe & TICKS;
       unsigned int prvGemStrobe  = evt->timetones.cur.gemStrobe & TICKS;
       unsigned int deltaTicks   = curGemStrobe - prvGemStrobe;

       unsigned int curGemSecs    = evt->timetones.cur.secs;
       unsigned int prvGemSecs    = evt->timetones.prv.secs;
       unsigned int deltaNsecs    = ONE_BILLION * (curGemSecs - prvGemSecs);

       unsigned int curGemClock   = evt->gemClock & TICKS;
       unsigned int elapsedTicks  = curGemClock - curGemStrobe;

       unsigned long long int time;

       // One needs to exercise caution to make sure the arithmetic
       // is done properly. In particular the mulitplication,
       // elapsedTicks * deltaNsecs, should yield an unsigned long long int
       // while the division by deltaTicks should be considered a 64/32 bit
       // division.
       time = ONE_BILLION * secs + (elapsedTicks * deltaNsecs) / deltaTicks;

       return time;

Armed with this utility one then does

      beg_time     = get_event_time (&hdr->evt.first);
      end_time     = get_event_time (&hdr->evt.last);
      elapsed_time = end_time - beg_time;

Warning:

The above piece of code is for purposes of illustration only. It assumes

1. No error conditions,
2. No overflows
3. That an extrapolation using the frequency/period of the last 1PPS interval (versus an interpolation or some other fancier method of predicting the period for this interval) is adequate.

LSF_statsHdrEvt

Typedef for _LSF_statsHdrEvt.

This structure is used to uniquely identify an event in both time and sequence. As such, it contains enough information to calculate the absolute time of the event. To do this one needs the GEM clock frequency which can be got in an assumption free fashion by capturing the GEM clock value on two successive timetone/1PPS hacks. The difference in the GPS timetone messages gives one the elapsed seconds and the difference in the GEM clock register values gives how many clock ticks have passed during this period.

The event sequence number is merely the GEM sequence number extended by watching how many times this sequence counter overflows. (Overflow is defined as going from a given value to a lower value.) While this is an easy enough value to compute, the writer is encouraged to use the value from EDS_fwIxb. This will ensure agreement when readers examine data from different statistics blocks.

Note:

This structure exists so that it may passed to a convenience routine (likley within THS) for easy filling.

LSF_statsHdrTimetone

Typedef for struct _LSF_statsHdrTimetone.

This version captures all the available information associated with a timetone/1PPS time strobe. It includes the standard word of error flags, which, in general, will be zero. Therefore, there is an opportunity to cut down on the number of bytes consumed by defining a structure that omits the flags word. One then simply needs a bit to indicate that the flags word is 0. If the need for such a structure arises it should be called LSF_statsHdrTimetoneAbv

---

Function Documentation

static __inline unsigned long long int LSF__statsHdrEvtSeqGet

(

const LSF_statsHdrEvtSeq *

seq

)

[static]

Hide access to the long long sequence number to avoid big/little endian and alignment issues.

Parameters:

seq

Address of the event sequence number to fetch

References _LSF_statsHdrEvtSeq::hi, and _LSF_statsHdrEvtSeq::lo.

static __inline void LSF__statsHdrEvtSeqSet	(	LSF_statsHdrEvtSeq *	dst,
		unsigned long long int	src
	)			[static]

Hide access to the long long sequence number to avoid big/little endian and alignment issues.

Parameters:

	dst	The destintation address
	src	The source event sequence number

References _LSF_statsHdrEvtSeq::hi, and _LSF_statsHdrEvtSeq::lo.