GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > EMP / V1-3-5

Constituent: ascprint     Tag: linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » EMP » V1-3-5 » EMP

EMP_hdrdefs.h File Reference

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

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


Data Structures

struct  _EMP_hdrTimetone
 Defines the most general version of the timetone information. More...
struct  _EMP_hdrTimetones
 Captures the information needed to convert a GEM event clock register value into an absolute time. More...
struct  _EMP_hdrEvtSeq
 Hide the access to the long long to avoid alignment issues. More...
struct  _EMP_hdrEvt
 Captures the information needed to uniquely identify this event by sequence and time. More...
struct  _EMP_hdrEvtSpan
 The defining information about the first and last event that went into the sample. More...
struct  _EMP_hdr
 EMP standard header for event-based statistics. More...

Typedefs

typedef _EMP_hdrTimetone EMP_hdrTimetone
 Typedef for struct _EMP_hdrTimetone.
typedef _EMP_hdrTimetones EMP_hdrTimetones
 Typedef for struct _EMP_hdrTimetones.
typedef _EMP_hdrEvtSeq EMP_hdrEvtSeq
 Typedef for struct _EMP_hdrEvtSeq.
typedef _EMP_hdrEvt EMP_hdrEvt
 Typedef for _EMP_hdrEvt.
typedef _EMP_hdrEvtSpan EMP_hdrEvtSpan
 Typedef for struct _EMP_hdrEvtSpan.
typedef _EMP_hdr EMP_hdr
 Typedef for struct _EMP_hdr.

Functions

static __inline void EMP__hdrEvtSeqSet (EMP_hdrEvtSeq *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 		EMP__hdrEvtSeqGet (const EMP_hdrEvtSeq *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: EMP_hdrdefs.h,v 1.1 2006/03/01 01:44:38 russell Exp $

This defines a header common to all event-based statistics datagrams. The design goals were to
  1. Record the number of events examined to make the sample This is before any prescaling or event selection, i.e. the total number of events seen

  1. Uniquely identify the span of events encompassed by the sample. The span includes both the time and the event numbers that define the beginning and ending of the sample. The definition of the beginning and ending of a packet is somewhat ambiguious, but the decision is to, where possible, define the beginning of the packet as the time/event number of the last packet of the previous event and the ending of the packet as the time/event number of the last event of this packet. Note that the actual first or last event may have not contributed to the statistics. If this information is not available on the specified events. a counter is maintained that gives the relative event number from the beginning/ending of the packet for the nearest event for which the information is available. For example, the most common occurance is anticipated to be that the time of the last of event of the previous packet is unavailable. In this case, if the time of the first event examined by this packet is available, the beginning count would be set to 1, (0 being reserved to indicate the time is really from the last event of the previous packet.

  1. Avoid recording any information that was specific to a given event monitor. The idea was that the same header could be used to describe a collection of event monitors that would output their data as a group.

Note:
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

EMP_hdr
 

Typedef for struct _EMP_hdr.

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 events bracketing the opening and closing of this datagram. 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 
       beg_evt_sequence   = hdr->evt.beg.seq;
       end_evt_sequence   = hdr->evt.end.seq;
       beg_seconds        = hdr->evt.beg.timetones.cur.secs;
       end_seconds        = hdr->evt.end.timetones.cur.secs;
       elasped_seconds    = beg_seconds - end_seconds;
       events_seen        = end_evt_sequence - beg_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 EMP_hdrEvt *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->span.beg);
      end_time     = get_event_time (&hdr->span.end);
      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.

EMP_hdrEvt
 

Typedef for _EMP_hdrEvt.

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.

EMP_hdrTimetone
 

Typedef for struct _EMP_hdrTimetone.

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 EMP_hdrTimetoneAbv

Function Documentation

static __inline unsigned long long int EMP__hdrEvtSeqGet (  const EMP_hdrEvtSeq *  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

static __inline void EMP__hdrEvtSeqSet (  EMP_hdrEvtSeq *  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

Generated on Sun Jun 14 02:08:25 2009 by  doxygen 1.4.4