QSE_ctx.h File Reference

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

#include <QSD/QSD_ctx.h>
#include <QSD/QSD_timetone.h>

Classes
struct	_QSE_ctxCounters
	Maps out the counters. 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_ctx
	Binds together all the meta-information about an event. More...
Typedefs
typedef struct _QSE_ctxCounters	QSE_ctxCounters
	Typedef for struct _QSE_ctxCounters.
typedef struct _QSE_ctxTime	QSE_ctxTime
	Typedef for struct _QSE_ctxTime.
typedef struct _QSE_ctx	QSE_ctx
Functions
void	QSE_ctxConstruct (QSE_ctx *ctx)
	Constructs/Initializes the public context structure.

---

Detailed Description

Public defines of the standard event context.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: QSE_ctx.h,v 1.13 2011/03/27 01:45:43 russell Exp $

---

Typedef Documentation

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_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.

---

Function Documentation

void QSE_ctxConstruct

(

QSE_ctx *

ctx

)

Constructs/Initializes the public context structure.

Parameters:

ctx

The public context structure

References _QSE_ctx::dgm.