EFA_def.h File Reference

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

Classes
struct	_EFA_hdrTimetone
	Defines the most general version of the timetone information. More...
struct	_EFA_hdrTimetones
	Captures the information needed to convert a GEM event clock register value into an absolute time. More...
struct	_EFA_hdrSeq
	Hide the access to the long long to avoid alignment issues. More...
struct	_EFA_hdr
	Captures the information needed to uniquely identify this event by sequence and time. More...
struct	_EFA_span
	Defines the sample span. More...
struct	_EFA_services
	The services to handle the result vectors. More...
Typedefs
typedef struct _EFA_hdrTimetone	EFA_hdrTimetone
	Typedef for struct _EFA_hdrTimetone.
typedef struct _EFA_hdrTimetones	EFA_hdrTimetones
	Typedef for struct _EFA_hdrTimetones.
typedef struct _EFA_hdrSeq	EFA_hdrSeq
	Typedef for struct _EFA_hdrSeq.
typedef struct _EFA_hdr	EFA_hdr
	Typedef for _EFA_hdr.
typedef struct _EFA_span	EFA_span
	Typedef for struct _EFA_span.
typedef void(*	EFA_servicesPost )(void *ctx, int reason, const void *beg, const void *end, const EFA_span *span)
	Callback routine to post an array of results.
typedef int(*	EFA_servicesStart )(void *ctx, int reason, int run_id, int startTime, int mode)
	Callback routine to start a run.
typedef struct _EFA_services	EFA_services
	Typedef for struct _EFA_services.
Functions
static __inline unsigned long long int	EFA__hdrSeqGet (const EFA_hdrSeq *seq)
	Hide access to the long long sequence number to avoid big/little endian and alignment issues.

---

Detailed Description

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

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: EFA_def.h,v 1.2 2007/11/02 18:20:26 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.

Warning:

This is a kludge. This has been copied from EMP to avoid touching that package. From a programming standpoint, this is not right, but it is easier than trying to get CCB approval to touch a working package.

---

Typedef Documentation

EFA_hdr

Typedef for _EFA_hdr.

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.

EFA_hdrTimetone

Typedef for struct _EFA_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.

void(* EFA_servicesPost)(void *ctx, int reason, const void *beg, const void *end, const EFA_span *span)

Callback routine to post an array of results.

Parameters:

	ctx	The callback's context paramter
	reason	The reason post is being called. EFC reserves only the value 0. This is used when the packet of result vectors is exhausted. The user is free to use other values. For example, specific values could be used to indicate a TIMEOUT or a flush operation.
	beg	The beginning of result vectors
	end	The end (in the usual C sense of 1 past the end)
	span	Structure defining the begin and ending of the sample

int(* EFA_servicesStart)(void *ctx, int reason, int run_id, int startTime, int mode)

Callback routine to start a run.

Returns:

0 is successful, non-zero otherwise

Parameters:

	ctx	The callback context parameter
	reason	The LSF_REASON_OPEN to indicate why the stream is being started
	run_id	Suggested use is to identify the block of events between when EDS_fwHandlerStart is called and EDS_fwHandlerFlush is called with a stop reason
	startTime	The run start time rounded to the nearest second
	mode	This must be the running mode.

EFA_span

Typedef for struct _EFA_span.

A span defines the beginning and and ending periods, both in event numbers and wall clock time, of the sample of events and the conditions under which those events were taken. Currently the conditions are only the mode (like NORMAL, ARR, TOO, etc) and the configuration of the handler which produced the sample of result data being analyzed.

---

Function Documentation

static __inline unsigned long long int EFA__hdrSeqGet

(

const EFA_hdrSeq *

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 _EFA_hdrSeq::hi, and _EFA_hdrSeq::lo.