GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > QSE / V1-6-3

Constituent: qseprint     Tag: linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » QSD » source » QSE » V1-6-3 » QSE

QSE_ctx.h File Reference

Public defines of the standard event context. More...

#include "PBI/Endianness.h"

Include dependency graph for QSE_ctx.h:

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


Data Structures

struct  _QSE_ctxOpen
 The Event Context's Datagram Opening Information. More...
struct  _QSE_ctxDid
 Contains the datagram indentification information. More...
struct  _QSE_ctxCounters
 Maps out the counters. More...
struct  _QSE_ctxTimetone
 The time/clock information associated with a timetone message. More...
struct  _QSE_ctxTime
 The time/clock information for the 1-second of the first event and the previous 1-second period. More...
struct  _QSE_ctxClose
 The Event Context's Datagram Closing Information. More...
struct  _QSE_ctx
 Binds together all the meta-information about an event. More...

Typedefs

typedef _QSE_ctxOpen QSE_ctxOpen
 Typedef for struct _QSE_ctxOpen.
typedef enum _QSE_CTXDID_FLAG_V QSE_CTXDID_FLAG_V
 Typedef for enum _QSE_CTXDID_FLAG_V.
typedef enum _QSE_CTXDID_FLAG_M QSE_CTXDID_FLAG_M
 Typedef for enum _QSE_CTXDID_FLAG_M.
typedef _QSE_ctxDid QSE_ctxDid
 Typedef for struct _QSE_ctxDid.
typedef _QSE_ctxCounters QSE_ctxCounters
 Typedef for struct _QSE_ctxCounters.
typedef enum _QSE_CTXTIMETONEFLAGS_S QSE_CTXTIMETONEFLAGS_S
 Typedef for enum _QSE_CTXTIMETONEFLAGS_S.
typedef enum _QSE_CTXTIMETONEFLAGS_V QSE_CTXTIMETONEFLAGS_V
 Typedef for enum _QSE_CTXTIMETONEFLAGS_V.
typedef enum _QSE_CTXTIMETONEFLAGS_M QSE_CTXTIMETONEFLAGS_M
 Typedef for enum _QSE_CTXTIMETONEFLAGS_M.
typedef _QSE_ctxTimetone QSE_ctxTimetone
 Typedef for struct _QSE_ctxTimetone.
typedef _QSE_ctxTime QSE_ctxTime
 Typedef for struct _QSE_ctxTime.
typedef _QSE_ctxClose QSE_ctxClose
 Typedef for struct _QSE_ctxClose.
typedef _QSE_ctx QSE_ctx
 Typedef for QSE_ctx.

Enumerations

enum  _QSE_CTXDID_FLAG_V { QSE_CTXDID_FLAG_V_DGM_FIRST = 0 }
 Enumeration of the bits of the QSE_ctxDid flag field, right justified shift value. More...
enum  _QSE_CTXDID_FLAG_M { QSE_CTXDID_FLAG_M_DGM_FIRST = (1 << QSE_CTXDID_FLAG_V_DGM_FIRST) }
 Enumeration of the bits of the QSE_ctxDid flag field, in place mask. More...
enum  _QSE_CTXTIMETONEFLAGS_S {
  QSE_CTXTIMETONEFLAGS_S_SIMULATED_VALUE = 1,
  QSE_CTXTIMETONEFLAGS_S_SIMULATED_PPS_CPU = 1,
  QSE_CTXTIMETONEFLAGS_S_SIMULATED_PPS_GEM = 1,
  QSE_CTXTIMETONEFLAGS_S_NO_MESSAGE = 1,
  QSE_CTXTIMETONEFLAGS_S_CNT_GPS_NO_LOCK = 12,
  QSE_CTXTIMETONEFLAGS_S_IS_SOURCE_GPS = 1,
  QSE_CTXTIMETONEFLAGS_S_SA_RSVD = 15
}
 Enumerates the timetone flags word, right-shift values. More...
enum  _QSE_CTXTIMETONEFLAGS_V {
  QSE_CTXTIMETONEFLAGS_V_SIMULATED_VALUE = 0,
  QSE_CTXTIMETONEFLAGS_V_SIMULATED_PPS_CPU = 1,
  QSE_CTXTIMETONEFLAGS_V_SIMULATED_PPS_GEM = 2,
  QSE_CTXTIMETONEFLAGS_V_NO_MESSAGE = 3,
  QSE_CTXTIMETONEFLAGS_V_CNT_GPS_NO_LOCK = 4,
  QSE_CTXTIMETONEFLAGS_V_IS_SOURCE_GPS = 16,
  QSE_CTXTIMETONEFLAGS_V_SA_RSVD = 17
}
 Enumerates the timetone flags word, right-shift values. More...
enum  _QSE_CTXTIMETONEFLAGS_M {
  QSE_CTXTIMETONEFLAGS_M_SIMULATED_VALUE = 0x1,
  QSE_CTXTIMETONEFLAGS_M_SIMULATED_PPS_CPU = 0x2,
  QSE_CTXTIMETONEFLAGS_M_SIMULATED_PPS_GEM = 0x4,
  QSE_CTXTIMETONEFLAGS_M_NO_MESSAGE = 0x8,
  QSE_CTXTIMETONEFLAGS_M_CNT_GPS_NO_LOCK = 0x0000FFF0,
  QSE_CTXTIMETONEFLAGS_M_IS_SOURCE_GPS = 0x00010000,
  QSE_CTXTIMETONEFLAGS_M_SA_RSVD = 0xfffe0000
}
 Enumerates the timetone flags word, in place mask values. More...

Functions

void QSE_ctxConstruct (QSE_ctx *ctx)

Detailed Description

Public defines of the standard event context.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: QSE_ctx.h,v 1.10 2007/04/08 22:36:24 russell Exp $

Typedef Documentation

QSE_ctxClose
 

Typedef for struct _QSE_ctxClose.

Overview
The QSE_ctxClose structure contains the reason why the datagram was closed.

QSE_ctxCounters
 

Typedef for struct _QSE_ctxCounters.

These are the extended counters for the finite range found in the GEM record.
Units
These counters increment in one of two units
  1. In units of the nominal 20MHz system clock
  2. In units of events

Ranges
In general, counters the increment in units of the nominal 20MHz system clock are expressed as a 64-bit unsigned integers and counters that count in units of events are expressed 32-bit unsigned integers. This says nothing about the actual range which is dictated by the transport layer representation. However, in general, the the transport layer keeps 32-40 bits for the event based counters and 41-bits (16 extended bits and 25 bits from the hardware registers.
  1. Time counters range = 30 hours
  2. Event counters range = 120 hours @ 10KHz

If the time range proves to be inadequate, only the transport layer definition will be changed, as the presentation layer representation of 64-bits is exceeds the projected mission time (or, for that matter, the project life of the universe).

If event counter range is a bit dicier, since the presentation layer only devotes 32-bits to it. This should be adequate.

QSE_ctxDid
 

Typedef for struct _QSE_ctxDid.

The DID is a series of numbers that uniquely identifies every data packet. That is, no two packets should every have exactly the same set of numbers. Some of these numbers are fixed at begin run time, e.g. the run identifier, the data source (origin), while others get updated as the run progresses. These include the datagram identifier, the mode, etc.

QSE_ctxOpen
 

Typedef for struct _QSE_ctxOpen.

Overview
The QSE_open contains why this datagram was opened.

QSE_ctxTime
 

Typedef for struct _QSE_ctxTime.

Overview
This structure contains information to determine the exact time of the event to a reasonable degree of accuracy. The hedge word reasonable is inserted because to do the calculation with this informaton one must extrapolate the time using a GEM clock frequency determined from the two most recent timetone messages. It may be possible to obtain a more accurate time by interpolating, instead of extrapolating. Even more sophisicated methods are available if one fits the recent history of the GEM clock frequency. However, both these methods require looking forward in time, that is using information that, at the time the event was captured was not available. A design decision was made not to wait for additional information. At a 10KHz rate, buffering events even for a short amount of time is not practical. The user is free to do his own buffering of this information in the relative peace and quiet of his workstation.
What's in here
There are three pieces of information, the two most recent timetone messages available when the associated event was processsed and the value of the GEM clock at event capture. Noticed that these words are carefully chosen and, for example, do not say, the timetone messages associated with the event to be processed and the timetone message from the one second period before. Why? While this latter statement is true 99% of the time it can be violated for two reasons
  1. For some reason, the timetone message associated with the event is not have been available when the event was processed. A practical case where this might happen is if the event occurs right after the 1PPS time hack was issued and the event wins the race arriving at the processing routines before the timetone messge.
  2. The timetone message was missed.

How to use this information
If one is satisfied that the GEM clock frequency is not changing significantly over timescales on the order of 1-2 seconds, the information in this structure should suffice to calculate the time of the event.
The prescription is to determine the clock frequency using the current and previous timetone messages
         // Get the 25 bit difference
         deltaTicks   = (time->cur.ticks - time->prv.ticks) & 0x1fffff;

         // Get the elapsed time, in seconds
         deltaSecs    = (time->cur.seconds - time->prv.seconds);

         // Calculate the frequency
         frequency    = deltaTicks / deltaSecs;

         // Calculate the number of elapsed GEM clock ticks since
         // the current timetone message
         elapsedTicks = (time->trgticks - cur->ticks) & 0x1ffffff;

         // Converted the elapsed ticks to elapsed seconds
         elapsedSecs  = elapsedTicks / frequency;

         // Get the absolute time
         time         = time->cur.seconds + elapsedSecs;

Warning:
The above calculation is only to give one an idea of how the informtion is meant to be used It is only correct if the flag word (containing both the 16-bit Spectrum Astro flags and the 16-bit FSW flags are zero. If this are not zero, a more elaborate calculation must be performed. To that end, routines will be provided to do the calculation in its full glory (or full ugliness depending on your viewpoint.)
In fact, the above calculation is not right when deltaSecs is not 0 or 1. In these cases, elapsedTicks exceeds the 25-bit range, meaning that some number of roll-overs have been lost. However, one can guess what the number that have been lost by simply adding 2**25 until one gets close to the nominal frequency times deltaSecs. Given the stability of the clock (1 part in 10**6 or 7), the more practical limitation comes from the rollover of the deltaSecs (128) itself. Even after 100 rollovers and an error of 1 part in 10**6, the extrapolation will only be off by 2000 counts.

QSE_CTXTIMETONEFLAGS_M
 

Typedef for enum _QSE_CTXTIMETONEFLAGS_M.

The flags word is a 32-bit word composed of 2 16-bit words. The most significant 16 bits belong to Spectrum Astro and are copied verbatim from the timetone message. As of this writing, only the least significant bit was defined as being set when the GPS lock was lost.
Warning:
Bit 30 has been usurped to indicate an internal inconsistency when decoding the data on the ground.
The least significant 16 bits are used by flight software. The low 4 bits are flags indicating problems with the timetone receiving mechanism. Essentially there are 3 signals to consider, the 1 PPS to the GEM, the 1 PPS to the receiving event processing CPU and the timetone message itself. Three of these bits indicate that one or more of the signals was not present at the required time.
The remaining 12 bits of the flight software 16 bit value is reserved for a count of the number of consecutive pulses that do have the NO_LOCK bit set. This allows the user to determine how long the system has been flywheeling on Spectrum-Astro's internal oscillator.

QSE_CTXTIMETONEFLAGS_S
 

Typedef for enum _QSE_CTXTIMETONEFLAGS_S.

See QSE_CTXTIMETONEFLAGS_M

QSE_CTXTIMETONEFLAGS_V
 

Typedef for enum _QSE_CTXTIMETONEFLAGS_V.

See QSE_CTXTIMETONEFLAGS_M

Enumeration Type Documentation

enum _QSE_CTXDID_FLAG_M
 

Enumeration of the bits of the QSE_ctxDid flag field, in place mask.

Enumerator:
QSE_CTXDID_FLAG_M_DGM_FIRST  Indicates on the first event in the datagram

enum _QSE_CTXDID_FLAG_V
 

Enumeration of the bits of the QSE_ctxDid flag field, right justified shift value.

Enumerator:
QSE_CTXDID_FLAG_V_DGM_FIRST  Indicates on the first event in the datagram

enum _QSE_CTXTIMETONEFLAGS_M
 

Enumerates the timetone flags word, in place mask values.

Enumerator:
QSE_CTXTIMETONEFLAGS_M_SIMULATED_VALUE  The timetone value is simulated
QSE_CTXTIMETONEFLAGS_M_SIMULATED_PPS_CPU  The receiving CPU did not receive a 1 PPS interrupted, so the 1 PPS was simulated by a timeout. In this case, the timetone message should be okay. This bit is really here for hardware accounting purposes. If this happens, it may indicate a faulty interrupt line to the CPU
QSE_CTXTIMETONEFLAGS_M_SIMULATED_PPS_GEM  The GEM did not get the 1 PPS. This IS a serious problem. It means the CPU thought that at least 1 second has gone by, but the 7-bit index in the GEM's 1 PPS register did not advance. One should not trust the 1 PPS register.
QSE_CTXTIMETONEFLAGS_M_NO_MESSAGE  The receiving CPU did not have a timetone message corresponding to the 1 PPS GEM register at the time the event arrived. This is a semi-normal situation, occuring when the event from the EBM (normally an event that occurs very near the 1-PPS time) arrives at the processing CPU before the timetone message arrives. When events are being processed on an EPU, this is just a race between the event from the EBM to the CPU and the timetone message from the SIU. Under normal conditions, a timetone message with this bit set will be followed (within a couple of events) by the real timetone message. However, the processing software, not wishing to wait an indeterminate amount of time for the real message, fabricates a timetone message, marking it with this bit
QSE_CTXTIMETONEFLAGS_M_CNT_GPS_NO_LOCK  The count of consecutive timetone messages that have the GPS_NO_LOCK bit set.
QSE_CTXTIMETONEFLAGS_M_IS_SOURCE_GPS  This is bit indicates the source of the time is the GPS. If not, the spacecraft lost the GPS lock and is simulating the timetone message by flywheeling off its own internal oscillator. This oscillator is very accurate, but one should exercise caution if the flywheel period lasts for a while.
QSE_CTXTIMETONEFLAGS_M_SA_RSVD  Reserved for future use

enum _QSE_CTXTIMETONEFLAGS_S
 

Enumerates the timetone flags word, right-shift values.

Enumerator:
QSE_CTXTIMETONEFLAGS_S_SIMULATED_VALUE  The timetone value is simulated
QSE_CTXTIMETONEFLAGS_S_SIMULATED_PPS_CPU  The receiving CPU did not receive a 1 PPS interrupted, so the 1 PPS was simulated by a timeout. In this case, the timetone message should be okay. This bit is really here for hardware accounting purposes. If this happens, it may indicate a faulty interrupt line to the CPU
QSE_CTXTIMETONEFLAGS_S_SIMULATED_PPS_GEM  The GEM did not get the 1 PPS. This IS a serious problem. It means the CPU thought that at least 1 second has gone by, but the 7-bit index in the GEM's 1 PPS register did not advance. One should not trust the 1 PPS register.
QSE_CTXTIMETONEFLAGS_S_NO_MESSAGE  The receiving CPU did not have a timetone message corresponding to the 1 PPS GEM register at the time the event arrived. This is a semi-normal situation, occuring when the event from the EBM (normally an event that occurs very near the 1-PPS time) arrives at the processing CPU before the timetone message arrives. When events are being processed on an EPU, this is just a race between the event from the EBM to the CPU and the timetone message from the SIU. Under normal conditions, a timetone message with this bit set will be followed (within a couple of events) by the real timetone message. However, the processing software, not wishing to wait an indeterminate amount of time for the real message, fabricates a timetone message, marking it with this bit
QSE_CTXTIMETONEFLAGS_S_CNT_GPS_NO_LOCK  The count of consecutive timetone messages that have the GPS_NO_LOCK bit set.
QSE_CTXTIMETONEFLAGS_S_IS_SOURCE_GPS  This is bit indicates the source of the time is the GPS. If not, the spacecraft lost the GPS lock and is simulating the timetone message by flywheeling off its own internal oscillator. This oscillator is very accurate, but one should exercise caution if the flywheel period lasts for a while.
QSE_CTXTIMETONEFLAGS_S_SA_RSVD  Reserved for future use

enum _QSE_CTXTIMETONEFLAGS_V
 

Enumerates the timetone flags word, right-shift values.

Enumerator:
QSE_CTXTIMETONEFLAGS_V_SIMULATED_VALUE  The timetone value is simulated
QSE_CTXTIMETONEFLAGS_V_SIMULATED_PPS_CPU  The receiving CPU did not receive a 1 PPS interrupted, so the 1 PPS was simulated by a timeout. In this case, the timetone message should be okay. This bit is really here for hardware accounting purposes. If this happens, it may indicate a faulty interrupt line to the CPU
QSE_CTXTIMETONEFLAGS_V_SIMULATED_PPS_GEM  The GEM did not get the 1 PPS. This IS a serious problem. It means the CPU thought that at least 1 second has gone by, but the 7-bit index in the GEM's 1 PPS register did not advance. One should not trust the 1 PPS register.
QSE_CTXTIMETONEFLAGS_V_NO_MESSAGE  The receiving CPU did not have a timetone message corresponding to the 1 PPS GEM register at the time the event arrived. This is a semi-normal situation, occuring when the event from the EBM (normally an event that occurs very near the 1-PPS time) arrives at the processing CPU before the timetone message arrives. When events are being processed on an EPU, this is just a race between the event from the EBM to the CPU and the timetone message from the SIU. Under normal conditions, a timetone message with this bit set will be followed (within a couple of events) by the real timetone message. However, the processing software, not wishing to wait an indeterminate amount of time for the real message, fabricates a timetone message, marking it with this bit
QSE_CTXTIMETONEFLAGS_V_CNT_GPS_NO_LOCK  The count of consecutive timetone messages that have the GPS_NO_LOCK bit set.
QSE_CTXTIMETONEFLAGS_V_IS_SOURCE_GPS  This is bit indicates the source of the time is the GPS. If not, the spacecraft lost the GPS lock and is simulating the timetone message by flywheeling off its own internal oscillator. This oscillator is very accurate, but one should exercise caution if the flywheel period lasts for a while.
QSE_CTXTIMETONEFLAGS_V_SA_RSVD  Reserved for future use

Generated on Thu Jul 12 01:45:21 2007 by  doxygen 1.4.4