Doxygen Page for LSE / V2-0-1 / lsew / sun-gcc

#include "dprintf.h"
#include "LSEW_ctx.h"
#include "LSE_time.ih"
#include "LSE/LSE_etxCtb.h"
#include "LSE/LSE_timCtb.h"
#include "EDS/EBF_gem.h"
#include "EDS/EBF_evt.h"
#include <string.h>


Functions
static __inline unsigned int *	add_tim (unsigned int *cur, unsigned int len32, unsigned int full_id, unsigned int abrv_id, unsigned int prv_pps, unsigned int prv_secs, unsigned int cur_pps, unsigned int cur_secs, unsigned int cur_flags, unsigned int force)
	Add either a full or abbreviated Time Specification Contribution.
static __inline void	fill_and_update_did (LSE_did dst, LSE_did src)
	Completes the Datagram Identification portion of the contribution.
static __inline unsigned int *	complete_etxFull (LSE_etxCtbFull *etx, unsigned int id, unsigned int bridge, unsigned int prv_secs, unsigned int prv_flags, unsigned int prv_pps, unsigned int cur_secs, unsigned int cur_flags, unsigned int cur_pps)
	Completes a LSE_etxCtbFull contribution.
static __inline unsigned int *	complete_etxAbbreviated (LSE_etxCtbAbbreviated *etx, unsigned int id, unsigned int bridge, unsigned int cur_secs, unsigned int prv_pps, unsigned int cur_pps)
	Completes a LSE_etxCtbAbbreviated contribution.
static __inline void	update_counter (unsigned short int ext, unsigned int base, unsigned int evt_counter)
	Updates the extended and base values of one counter.
static __inline void	update_xcr (LSEW_ctxGem ctx, unsigned int sequence, const EBF_gem gem)
	Updates the extended range counter information.
static __inline void	copy_xcr (LSE_xcr dst, LSE_xcr src)
	Copies the extended range counters.
static __inline unsigned int *	complete_etx (LSEW_ctx ctx, LSE_etxCtb etx, unsigned int reason, unsigned int gem_pps)
	Completes the event context portion of the event datagram by filling in the bridge word and time information.
static __inline unsigned int *	ctx_update (LSEW_ctx ctx, unsigned int cur, unsigned int len32, unsigned int gem_pps)
	Updates the time contribution.
void	LSEW_ctxInit (LSEW_ctx *ctx, LSF_CPU_K cpu, LSF_ORIGIN_K origin)
	Initializes the initial context structure.
unsigned int *	LSEW_ctxOpenAdd (LSEW_ctx ctx, unsigned int cur, unsigned int len32, unsigned int reason, unsigned int sequence, const EBF_gem *gem)
	Updates the Time/Counter context structure and inserts the the start of the appropriate (full or abbreviated) LSE_etxCtb contribution into the event datagram.
void	LSEW_ctxRunStart (LSEW_ctx *ctx, unsigned int runId, unsigned int startTime, LSF_MODE_K mode)
	Sets the context for a new run.
void	LSEW_ctxModeChange (LSEW_ctx *ctx, LSF_MODE_K mode)
	Changes the current data-taking mode.
unsigned int *	LSEW_ctxUpdateAdd (LSEW_ctx ctx, unsigned int cur, unsigned int len32, unsigned int sequence, const EBF_gem *gem)
	Updates the Time/Counter context structure and inserts an Time contribution in the data stream if necessary.
unsigned int *	LSEW_ctxCloseAdd (LSEW_ctx ctx, unsigned int cur, unsigned int len32, unsigned int reason)
	Called when an event datagram is filled, it completes the opening LSE_etxCtb contribution by filling in the bridge field from the specified context.

Detailed Description

Function Documentation

static __inline unsigned int * add_tim	(	unsigned int *	cur,
		unsigned int	len32,
		unsigned int	full_id,
		unsigned int	abrv_id,
		unsigned int	prv_pps,
		unsigned int	prv_secs,
		unsigned int	cur_pps,
		unsigned int	cur_secs,
		unsigned int	cur_flags,
		unsigned int	force
	)			`[static]`

Add either a full or abbreviated Time Specification Contribution.

Returns:: Pointer to the next 32-bit word to be filled or NULL if there is insufficient space

Parameters:

	cur	Current output pointer
	len32	The number of 32-bit words that are available
	full_id	The LSF id to use for a FULL time contribution
	abrv_id	The LSF id to use for an ABBREVIATED time contribution
	prv_pps	The previous (old) value of the GEM 1PPS register
	prv_secs	The previous (old) elapsed seconds since the Spectrum-Astro epoch
	cur_pps	The value of the GEM 1PPS register
	cur_secs	The current elapsed seconds since the Spectrum-Astro epoch
	cur_flags	The Spectrum-Astro and FSW flag words
	force	Force the addition

Usage: This routine is called for each event being added. It checks whether a time update record (either full or abbreviated) needs to be added and, if so, adds it if there is sufficient space.

Addition of a Full Time Update Record: A full time update record is added is the timetone message had any errors, reflected by a non-zero value in the current flags, cur_flags, word.

Addition of an Abbreviated Time Update Record

An abbreviated time update record, consisting solely of the GPS time, carried in cur_secs, is added, if and only if

There are no errors
The time difference between the current and previous GPS elapsed time (cur_secs - prv_secs) matches the difference between the indices of the current and previous 1-PPS register (cur_pps.idx - prv_pps.idx)

No Time Update Record is Necessary: The usual state of affairs should be that there are no errors and the 1-PPS indices are tracking the GPS elapsed seconds. In this case no time update record is added since it adds no information that is not already carried in the events 1-PPS register.

Insufficient Room: If it is determined that a time update record of any ilk needs to be added and there is insufficient room in the datagram to store add the record, this routine returns NULL. The caller's response is generally to flush the current datagram, prepare a new one and recall the code to add the event.

static __inline unsigned int complete_etx	(	LSEW_ctx *	ctx,
		LSE_etxCtb *	etx,
		unsigned int	reason,
		unsigned int	gem_ppstime
	)			`[static]`

Completes the event context portion of the event datagram by filling in the bridge word and time information.

Returns:: Pointer to the next location to be filled in.

Parameters:

	ctx	The context structure
	etx	The extended context contribution to fill
	reason	One of an enumerated list indicating why the datagram is being opened
	gem_ppstime	The value of the GEM's 1PPS register

static __inline unsigned int * complete_etxAbbreviated	(	LSE_etxCtbAbbreviated *	etx,
		unsigned int	id,
		unsigned int	bridge,
		unsigned int	cur_secs,
		unsigned int	prv_pps,
		unsigned int	cur_pps
	)			`[static]`

Completes a LSE_etxCtbAbbreviated contribution.

Returns:: A pointer to the next location to be filled

Parameters:

	etx	A pointer to the beginning of the LSE_ctxCtbAbbreviated contribution to fill
	id	The identifier to use for an ABBREVIATED event context contribution
	bridge	The value of the bridge field
	cur_secs	The current elapsed seconds since the Spectrum-Astro epoch
	prv_pps	The value of the GEM 1PPS register at the previous 1 PPS time hack
	cur_pps	The value of the GEM 1PPS register at the current 1 PPS time hack

Usage, Internal: This routine adds the time information to an abbreviated event context record that is part of a freshly minted datagram. The abbreviated time information is usually used when there are no errors in either the current or previous timetone message as reflected by non-zero values in cur_flags and prv_flags, and the difference between the current and previous times, as reflected in cur_secs - prv_secs, is exactly one, i.e. the usual situation.

Usage, External: This information is used by ground analysis to establish the base time and frequency of the GEM's system clock. The frequency is calculated taking the difference the current and the previous 1-PPS register values and dividing it by the elapsed time, i.e. the difference between the current and previous elapsed seconds (cur_sec - prv_secs). Doing it this way allows the datagram to stand by itself, without depending on information from either previous or subsequenct datagrams. This is in keeping with the philosophy that the transmission of datagrams is unreliable.

static __inline unsigned int * complete_etxFull	(	LSE_etxCtbFull *	etx,
		unsigned int	id,
		unsigned int	bridge,
		unsigned int	prv_secs,
		unsigned int	prv_flags,
		unsigned int	prv_pps,
		unsigned int	cur_secs,
		unsigned int	cur_flags,
		unsigned int	cur_pps
	)			`[static]`

Completes a LSE_etxCtbFull contribution.

Returns:: A pointer to the next location to be filled

Parameters:

	etx	A pointer to the beginning of the LSE_etxCtbFull contribution to fill
	id	The LSF identifier for a full event context contribution
	bridge	The value of the bridge word
	prv_secs	The previous elapsed seconds since the Spectrum-Astro epoch
	prv_flags	The previous flags
	prv_pps	The value of the GEM 1PPS register at the previous 1 PPS time hack
	cur_secs	The current elapsed seconds since the Spectrum-Astro epoch
	cur_flags	The current flags
	cur_pps	The value of the GEM 1PPS register at the current 1 PPS time

Usage, Internal: This routine adds the time information to a full event context record that is part of a freshly minted datagram. The full time information is usually used when there are errors in either the current or previous timetone message as reflected by non-zero values in cur_flags and prv_flags.

Usage, External: This information is used by ground analysis to establish the base time and frequency of the GEM's system clock. The frequency is calculated taking the difference the current and the previous 1-PPS register values and dividing it by the elapsed time, i.e. the difference between the current and previous elapsed seconds (cur_sec - prv_secs). Doing it this way allows the datagram to stand by itself, without depending on information from either previous or subsequenct datagrams. This is in keeping with the philosophy that the transmission of datagrams is unreliable.

Errors: Given the fact that, almost by definition, if this style of record appears, there will be errors, one must be ready to handle these error conditions. A discussion of how to do this is outside the scope of this documentation. Hopefully, a manual on properly consuming the time information will be available.

static __inline void copy_xcr	(	LSE_xcr *	dst,
		LSE_xcr *	src
	)			`[static]`

Copies the extended range counters.

Parameters:

	dst	The destination extended range counter contribution
	src	The source extended ranged counter information

Usage: This routine is called new a new datagram is opened, adding the extended counters to the event datagram.

static __inline unsigned int * ctx_update	(	LSEW_ctx *	ctx,
		unsigned int *	cur,
		unsigned int	len32,
		unsigned int	gem_pps
	)			`[static]`

Updates the time contribution.

Returns:: Pointer to the next location to be filled in or NULL if there is insufficient space.

Parameters:

	ctx	The context structure
	cur	The current output location
	len32	The number of 32-bit words that are available
	gem_pps	The value of the GEM's 1PPS counter

static __inline void fill_and_update_did	(	LSE_did *	dst,
		LSE_did *	src
	)			`[static]`

Completes the Datagram Identification portion of the contribution.

Parameters:

	dst	The Datagram Identification to complete
	src	The Datagram Identification used to complete the dst

Usage: This routine is called to add the Datagram Identification information to a freshly minted datagram. There is almost no logic in this routine (it adds 1 to the datagram sequence number), merely copying a template version of the information, stored in src, into the destination, dst.

unsigned int * LSEW_ctxCloseAdd	(	LSEW_ctx *	ctx,
		unsigned int *	cur,
		unsigned int	len32,
		unsigned int	reason
	)

Called when an event datagram is filled, it completes the opening LSE_etxCtb contribution by filling in the bridge field from the specified context.

Returns:: Pointer to the end of the datagram. If insufficient space remains to put the closing information in, it will be omitted. Currently this is a philosophical point, because there is no such information.

Parameters:

	cur	The current fill point in the event datagram.
	len32	The number of 32-bit words available.
	ctx	The context structure.
	reason	One of an enumerated list of reasons why this datagram is being closed.

: This routine currently only completes the LSE_etxCtb contribution by filling in the closing reason. It adds no new data of its own, so it merely returns cur.

void LSEW_ctxInit	(	LSEW_ctx *	ctx,
		LSF_CPU_K	cpu,
		LSF_ORIGIN_K	origin
	)

Initializes the initial context structure.

!!! KLUDGE - None of the stuff following belongs here (except the INIT)

Parameters:

	ctx	The Timer/Counter context structure to initialize
	cpu	The CPU producing this data
	origin	The originating data source (the LAT, GLEAM, etc)

void LSEW_ctxModeChange	(	LSEW_ctx *	ctx,
		LSF_MODE_K	mode
	)

Changes the current data-taking mode.

Parameters:

	ctx	The destination context
	mode	The new data-taking mode

: This routine does two things

Sets the new data-taking mode
Bumps the mode sequence number to indicate an update

unsigned int * LSEW_ctxOpenAdd	(	LSEW_ctx *	ctx,
		unsigned int *	cur,
		unsigned int	len32,
		unsigned int	reason,
		unsigned int	sequence,
		const EBF_gem *	gem
	)

Updates the Time/Counter context structure and inserts the the start of the appropriate (full or abbreviated) LSE_etxCtb contribution into the event datagram.

Returns:: The next write pointer or NULL if there is insufficient space. This later condition is considered a specification error; the caller did not provide a big enough buffer to handle even the opening contribution.

Parameters:

	ctx	The context structure
	cur	The current write pointer
	len32	The number of 32-bit words that are available
	reason	One of an enumerated list describing why the datagram is being opened.
	sequence	The sequence number of the next event. If the MSB of this value is set, no updating of extended counters is done. The caller may wish to by-pass this updating because it was already done. For example, this happens in the case of event failing to fit into the previous datagram. Here the update has already occurred.
	gem	The GEM data record of the next event

void LSEW_ctxRunStart	(	LSEW_ctx *	ctx,
		unsigned int	runId,
		unsigned int	startTime,
		LSF_MODE_K	mode
	)

Sets the context for a new run.

Parameters:

	ctx	The destination context
	runId	The run identifier
	startTime	The run start time rounded to the nearest second
	mode	The running mode

unsigned int * LSEW_ctxUpdateAdd	(	LSEW_ctx *	ctx,
		unsigned int *	cur,
		unsigned int	len32,
		unsigned int	sequence,
		const EBF_gem *	gem
	)

Updates the Time/Counter context structure and inserts an Time contribution in the data stream if necessary.

Returns:: The next write pointer or NULL if there was insufficient space

Parameters:

	ctx	The context structure
	cur	The current write pointer
	len32	The number of 32-bit words available.
	sequence	The sequence number of the next event
	gem	The GEM data record of the next event

static __inline void update_counter	(	unsigned short int *	ext,
		unsigned int *	base,
		unsigned int	evt_counter
	)			`[static]`

Updates the extended and base values of one counter.

Parameters:

	ext	Pointer to the current extended counter value
	base	Pointer to the current base counter value
	evt_counter	The value of the counter from the current event

Usage: Updates the extended bits of the specified counter. It does this by checking if the current value of the counter is less than the current base value of the counter. If this is true, it is assumed the that the counter has rolled-over, so 1 is added to the extened bits of this counter, properly accounting for this roll-over.

static __inline void update_xcr	(	LSEW_ctxGem *	ctx,
		unsigned int	sequence,
		const EBF_gem *	gem
	)			`[static]`

Updates the extended range counter information.

Parameters:

	ctx	The GEM context to update, holds the extended counters and their base values.
	sequence	The event sequence number of the current event.
	gem	The GEM data of the current event

Usage: This routine is called for each event added to the event datagram. It checks all the limited range counters in the GEM data plus the event sequence number to see if roll-over has occurred. If so, the extended range counter extended counters are update. The base values are always updated with the value of the counter for this event, thus preparing it to detect roll-over on the next event.

LSEW_ctx.c File Reference

Functions

Detailed Description

Function Documentation