GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > EMP / V1-2-0

Constituent: asc     Tag: mv2304

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » EMP » V1-2-0 » src

EMP_hdr.h File Reference

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

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


Typedefs

typedef _EMP_hdr EMP_hdr
 Typedef for struct _EMP_hdr.
typedef _EMP_hdrEvt EMP_hdrEvt
 Typedef for _EMP_hdrEvt.

Functions

void EMP_hdrClear (EMP_hdr *hdr)
 Clear the LSF_statsHdr structure.
unsigned int EMP_hdrEvtSet (EMP_hdrEvt *evt, unsigned int relative, unsigned long long seq, unsigned int gemClock, unsigned int gemStrobe)
 Sets specified event marker.

Detailed Description

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

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: EMP_hdr.h,v 1.1 2006/03/01 01:44:42 russell Exp $

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.

Function Documentation

void EMP_hdrClear (  EMP_hdr *  hdr  ) 
 

Clear the LSF_statsHdr structure.

Parameters:
hdr Pointer to LSF_statsHdr structure to fill in

unsigned int EMP_hdrEvtSet (  EMP_hdrEvt *  evt,
unsigned int  relative,
unsigned long long  seq,
unsigned int  gemClock,
unsigned int  gemStrobe
) 
 

Sets specified event marker.

Returns:
status
Parameters:
evt Pointer to the target EMP_hdrEvt
relative The relative (to the beginning of the buffer) event number (1 = first event)
seq Extended seqence number of the event
gemClock Event clock register read from GEM contributor of event
gemStrobe Event PPS cock register read from GEM contributor of event
This is convenient routine to fill in event info that is stored in a EMP_emp structure within an LSF packet for eventual output as science data on the SSR.

Generated on Mon Oct 16 23:51:38 2006 by  doxygen 1.4.4