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

#include "LSF/LSF.h"
#include "LSEW_ctx.h"
#include "LSE/LSE_ids.h"
#include "LSE/LSEW_dgm.h"
#include "LSE_time.ih"
#include "CCSDS/CCSDS_pkt.h"
#include <string.h>


Classes
struct	_LSEW_dgm
	Control structure for outputing events. More...
Defines
#define	RND_UP(_x, _r) ( (((int)(_x)) + (_r) - 1) & ~((_r) - 1) )
	Rounds _x up to the nearest multiple of _r.
#define	MAXIMUM_EVENTS_PER_CONTRIBUTION 255
	Sets the maximum number of events that can be committed to one event contribution.
Typedefs
typedef struct _LSEW_dgm	LSEW_dgm
	Typedef for struct _LSEW_dgm.
Functions
static __inline unsigned int	evt_size (void)
	Returns the minimum size of a new event contribution.
static __inline unsigned int *	evt_open (unsigned int *beg)
	Opens a new event record contribution.
static __inline unsigned int *	evt_close (unsigned int beg, const unsigned int end, unsigned int id, unsigned short int bridge)
	Closes out (completes) the current event contribution by filling in the LSF event header.
static __inline void	datagram_close (unsigned int beg, const unsigned int end, unsigned int dgm_id)
	Closes out (completes) the current data packet by filling in the LSF packet header.
static __inline unsigned int *	ccsds_complete (unsigned int beg, unsigned char dat, unsigned int lsf, unsigned int evt, unsigned int *end, unsigned int nevts, unsigned int apid, unsigned int seq)
	Completes the CCSDS header.
unsigned int	LSEW_dgmSizeof (void)
	The size, in bytes, of the control structure.
unsigned int	LSEW_dgmInit (LSEW_dgm *dgm, unsigned short int apid, unsigned int dgm_id, LSF_CPU_K cpu, LSF_ORIGIN_K origin)
	Initializes the control structure.
int	LSEW_dgmBufSet (LSEW_dgm dgm, unsigned int buf, int buf_size)
	Sets the specified buffer as the new output buffer.
void	LSEW_dgmRunStart (LSEW_dgm *dgm, unsigned int runId, unsigned int startTime, LSF_MODE_K mode)
	Sets the context for a new run.
void	LSEW_dgmModeChange (LSEW_dgm *dgm, LSF_MODE_K mode)
	Changes the current data-taking mode.
unsigned int *	LSEW_dgmOpen (LSEW_dgm dgm, unsigned int reason, unsigned int evt_seq, const EBF_gem gem)
	Opens a new event datagram.
unsigned int *	LSEW_dgmEvtOpen (LSEW_dgm dgm, unsigned int cur)
	Opens a new event datagram.
void	LSEW_dgmRootClose (LSEW_dgm dgm, const unsigned int end)
unsigned int *	LSEW_dgmEvtCommit (LSEW_dgm dgm, unsigned int cur)
	Commits this event. This does two things, updates the current write pointer and increments the number of events in this contribution.
unsigned int *	LSEW_dgmEvtClose (LSEW_dgm *dgm)
	Completes the final processing of an event just before it is presented to the output stream.
unsigned int *	LSEW_dgmUpdate (LSEW_dgm dgm, unsigned int evt_seq, const EBF_gem gem)
	Updates the current datagram, adding a time record if necessary.
unsigned int *	LSEW_dgmCommit (LSEW_dgm dgm, unsigned int cur)
	Commits the current write by updating the write potnter.
unsigned int *	LSEW_dgmClose (LSEW_dgm dgm, unsigned int cur, unsigned int reason)
	Closes out the datagram; it is now ready to be written out.
const LSEW_ctxPub *	LSEW_dgmCtxPub (const LSEW_dgm *dgm)
	Returns a pointer to the public context structure.
unsigned int *	LSEW_dgmBeg (const LSEW_dgm *dgm)
	Returns the value of the beginning of the specified event datagram.
unsigned int *	LSEW_dgmCur (const LSEW_dgm *dgm)
	Returns the value of the beginning of the specified event datagram.
unsigned int *	LSEW_dgmEnd (const LSEW_dgm *dgm)
	Returns the value of the end of the specified event datagram.
unsigned int	LSEW_dgmLeft32 (const LSEW_dgm *dgm)
	Returns the number of 32 words left in the buffer.

Detailed Description

Define Documentation

#define MAXIMUM_EVENTS_PER_CONTRIBUTION 255

Sets the maximum number of events that can be committed to one event contribution.

This value is set by the width of the bridge word in the LSF contribution header (1 byte)

#define RND_UP	(	_x,
		_r		)	( (((int)(_x)) + (_r) - 1) & ~((_r) - 1) )

Rounds _x up to the nearest multiple of _r.

Returns:: The rounded up value

Parameters:

	_x	The value to round
	_r	The multiple to round up to, must be a power of 2.

Function Documentation

static __inline unsigned int ccsds_complete	(	unsigned int *	beg,
		unsigned char *	dat,
		unsigned int *	lsf,
		unsigned int *	evt,
		unsigned int *	end,
		unsigned int	nevts,
		unsigned int	apid,
		unsigned int	seq
	)			`[static]`

Completes the CCSDS header.

Returns:: The total length of the packet, including the CCSDS header, in bytes.

Parameters:

	beg	The beginning address of the packet
	dat	The beginning address of the data portion of the CCSDS packet.
	lsf	The beginning address of the LSF datagram
	evt	The beginning address of the current event packet
	end	The ending address of the packet
	nevts	The nubmer of events in the event packet
	apid	The base apid
	seq	The CCSDS sequence count

static __inline void datagram_close	(	unsigned int *	beg,
		const unsigned int *	end,
		unsigned int	dgm_id
	)			`[static]`

Closes out (completes) the current data packet by filling in the LSF packet header.

Parameters:

	beg	The beginning of the event contribution to closeout
	end	The end of the event contribution to closeout
	dgm_id	The LAT Science Format datagram identifier

static __inline unsigned int evt_close	(	unsigned int *	beg,
		const unsigned int *	end,
		unsigned int	id,
		unsigned short int	bridge
	)			`[static]`

Closes out (completes) the current event contribution by filling in the LSF event header.

Returns:: end, i.e. the current value of the write pointer

Parameters:

	beg	The beginning of the event contribution to closeout
	end	The end of the event contribution to closeout
	id	The LSF id of the event contribution
	bridge	Arbitrary bridge word filled into the header.

static __inline unsigned int * evt_open ( unsigned int * cur ) [static]

Opens a new event record contribution.

Returns:: Pointer to where the data bytes should be inserted

Parameters:

cur

The beginning of the event contribution

static __inline unsigned int * evt_size ( void ) [static]

Returns the minimum size of a new event contribution.

Returns:: The size, in 32-bit integers of a minimum event contribution

: The absolute minimum size needed is the size of the contribution header. One could argue that any real event contribution record must contain at least 1 event. The issue here is what is the minimum size of an event. Certainly it must consist of at least the record header. Since information can be carried in the bridge word, it is technically possible that an event can consist of only the these two objects.

: Note that the only thing one absolutely must do is to return the maximum number of bytes that evt_open will consume. Making this number larger has two opposing effects

If it is too large, an event that would fit may be rejected
Saves adding an context udpate record only to have it pitched when it is discovered the event does not fit.

unsigned int* LSEW_dgmBeg ( const LSEW_dgm * dgm )

Returns the value of the beginning of the specified event datagram.

Returns:: The value of the beginning of the specified event datagram

Parameters:

dgm

The event datagram to query

int LSEW_dgmBufSet	(	LSEW_dgm *	dgm,
		unsigned int *	buf,
		int	buf_size
	)

Sets the specified buffer as the new output buffer.

Parameters:

	dgm	The output control block
	buf	The new buffer
	buf_size	The size, in bytes, of the new buffer

unsigned int* LSEW_dgmClose	(	LSEW_dgm *	dgm,
		unsigned int *	cur,
		unsigned int	reason
	)

Closes out the datagram; it is now ready to be written out.

Returns:: Pointer to the next write location. Everything from the beginning pointer to this pointer should be written out.

Parameters:

	dgm	The event datagram to close
	cur	The next write pointer, unless NULL, then it is ignored
	reason	One of an enumeration describing why this event datagram is being closed.

unsigned int* LSEW_dgmCommit	(	LSEW_dgm *	dgm,
		unsigned int *	cur
	)

Commits the current write by updating the write potnter.

Returns:: Pointer to where to put the next data item, i.e. cur rounded to the nearest 4-byte boundary.

Parameters:

	dgm	The output control block
	cur	The current write pointer.

const LSEW_ctxPub* LSEW_dgmCtxPub ( const LSEW_dgm * dgm )

Returns a pointer to the public context structure.

Returns:: A pointer to the public context structure

Parameters:

dgm

The event datagram to query

unsigned int* LSEW_dgmCur ( const LSEW_dgm * dgm )

Returns the value of the beginning of the specified event datagram.

Returns:: The value of the current write pointer of the specified event datagram

Parameters:

dgm

The event datagram to query

unsigned int* LSEW_dgmEnd ( const LSEW_dgm * dgm )

Returns the value of the end of the specified event datagram.

Returns:: The value of the current write pointer of the specified event datagram

Parameters:

dgm

The event datagram to query

unsigned int* LSEW_dgmEvtClose ( LSEW_dgm * dgm )

Completes the final processing of an event just before it is presented to the output stream.

Returns:: The number of bytes to be written

Parameters:

dgm

The datagram to close the event contribution

unsigned int* LSEW_dgmEvtCommit	(	LSEW_dgm *	dgm,
		unsigned int *	cur
	)

Commits this event. This does two things, updates the current write pointer and increments the number of events in this contribution.

Returns:: Pointer to where to put the next data item

Parameters:

	dgm	The output control block
	cur	The current write pointer, if NULL, then the internal value of the write pointer is used.

unsigned int* LSEW_dgmEvtOpen	(	LSEW_dgm *	dgm,
		unsigned int *	cur
	)

Opens a new event datagram.

Returns:: Pointer to where to put the next data item

Parameters:

	dgm	The output control block
	cur	The current write pointer, if NULL, then the internal value of the write pointer is used.

unsigned int LSEW_dgmInit	(	LSEW_dgm *	dgm,
		unsigned short int	apid,
		unsigned int	dgm_id,
		LSF_CPU_K	cpu,
		LSF_ORIGIN_K	origin
	)

Initializes the control structure.

Returns:: Status, currently always successs (0)

Parameters:

	dgm	The output control structure to initialize
	apid	The application id to use in the CCSDS packets
	dgm_id	The LAT Science Format Data Id (LSF) to use
	cpu	The CPU identifier
	origin	The originating data source (ie LAT, GLEAM, etc)

unsigned int LSEW_dgmLeft32 ( const LSEW_dgm * dgm )

Returns the number of 32 words left in the buffer.

Returns:: The value of the current write pointer of the specified event datagram

Parameters:

dgm

The event datagram to query

void LSEW_dgmModeChange	(	LSEW_dgm *	dgm,
		LSF_MODE_K	mode
	)

Changes the current data-taking mode.

Parameters:

	dgm	The destination event datagram 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_dgmOpen	(	LSEW_dgm *	dgm,
		unsigned int	reason,
		unsigned int	evt_seq,
		const EBF_gem *	gem
	)

Opens a new event datagram.

Returns:: Pointer to where to put the next data item

Parameters:

	dgm	The output control block
	reason	One of an enumeration describing why this event datagram is being opened
	evt_seq	The event sequence number
	gem	The GEM contributor

void LSEW_dgmRootClose	(	LSEW_dgm *	dgm,
		const unsigned int *	end
	)

Parameters:

	dgm	The output control block
	end	Pointer to the end of the root contribution

void LSEW_dgmRunStart	(	LSEW_dgm *	dgm,
		unsigned int	runId,
		unsigned int	startTime,
		LSF_MODE_K	mode
	)

Sets the context for a new run.

Parameters:

	dgm	The event datagram control handle
	runId	The run identifier
	startTime	The run start time to the nearest second
	mode	The running mode

unsigned int* LSEW_dgmUpdate	(	LSEW_dgm *	dgm,
		unsigned int	evt_seq,
		const EBF_gem *	gem
	)

Updates the current datagram, adding a time record if necessary.

Returns:: Pointer to where to put the next data item or NULL if could not fit in the update records

Parameters:

	dgm	The output control block
	evt_seq	The event sequence number
	gem	The GEM contributor

: This routine has one quirky bit of behavior. If a update time record is deemed necessary, the update time record and the beginnings of a new event contribution are added to the output, but the current write pointer is not committed. The reason for this is because it is not yet known whether the event about to be added will fit.

: If it fits, the user will add it at the location returned by this routine and do a LSEW_dgmCommit on the location returned by his event add routine. This commit will then commit both the update time contribution and the new event.

: If the event does not fit, while the added information will effectively be forgotten and the user will close the datagram out.

: This strategy simplifies the user code at the expense of occassionally going through all the work to add the time update record and open a new event contribution only to have it thrown away. The only alternative to this method was to demand the user determine beforehand whether the event fit or not. This was deemed

In some cases, very hard for the user to determine the size without actually formatting the event
Just made for an awkward call interface.

LSEW_dgm.c File Reference

Classes

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Function Documentation