---

GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> LSE / V2-0-4 > lsew / mv2304

---

         

---

LSEW_dgmFw.c File Reference

Code to write events using a framework built around the LSDW_dgm utilities. More...

#include "LSF/LSF_reason.h"
#include "LSE/LSEW_dgmFw.h"
#include "LSE/LSEW_dgm.h"
#include <string.h>

Classes
struct	_LSEW_dgmFw
	Control structure for outputing events. More...
Typedefs
typedef struct _LSEW_dgmFw	LSEW_dgmFw
Functions
static __inline LSEW_dgm *	locate (const LSEW_dgmFw *dgmFw)
	Give the LSEW_dgmFw, locates the LSEW_dgm.
static unsigned int *	datagram_open (LSEW_dgmFw *dgmFw, unsigned int reason, unsigned int evt_seq, const EBF_gem *gem)
	Opens a new event datagram.
static unsigned int	datagram_close (LSEW_dgmFw *dgmFw, unsigned int reason)
	Unconditionally writes out whatever is in the current buffer.
static unsigned int *	datagram_retry (LSEW_dgmFw *dgmFw, void *evt, unsigned int evt_seq, const EBF_gem *gem)
	Attempts to retry the adding of an event by closing the current datagram and opening a new one. If this attempt fails, it is because the datagram is not large enough to accomodate the overhead (beginning contributions) and the event.
unsigned int	LSEW_dgmFwSizeof (void)
	The size, in bytes, of the control structure.
unsigned int	LSEW_dgmFwInit (LSEW_dgmFw *dgmFw, unsigned short int apid, unsigned int dgm_id, LSF_CPU_K cpu, LSF_ORIGIN_K origin)
	Initializes the control structure.
LSEW_dgmFwBegAddCbp	LSEW_dgmFwBegAddSet (LSEW_dgmFw *dgmFw, LSEW_dgmFwBegAdder begRtn, void *begPrm)
	Sets the callback to add a user specified Begin Context Contribution record.
LSEW_dgmFwEvtAddCbp	LSEW_dgmFwEvtAddSet (LSEW_dgmFw *dgmFw, LSEW_dgmFwEvtAdder evtRtn, void *evtPrm)
	Sets the callback to add an event to the event datagram.
LSEW_dgmFwUsrAddCbp	LSEW_dgmFwUsrAddSet (LSEW_dgmFw *dgmFw, LSEW_dgmFwUsrAdder usrRtn, void *usrPrm)
	Sets the callback to add an event to the event datagram.
LSEW_dgmFwEndAddCbp	LSEW_dgmFwEndAddSet (LSEW_dgmFw *dgmFw, LSEW_dgmFwEndAdder endRtn, void *endPrm)
	Sets the callback to add a user specified End Context Contribution record.
LSEW_dgmFwPostCbp	LSEW_dgmFwPostSet (LSEW_dgmFw *dgmFw, LSEW_dgmFwPoster postRtn, void *postPrm)
	Sets the callback to add a user specified End Context Contribution record.
void	LSEW_dgmFwBufSet (LSEW_dgmFw *dgmFw, unsigned int *buf, int bufSize)
	Sets the buffer to be used for the event datagram and its size.
void	LSEW_dgmFwRunStart (LSEW_dgmFw *dgmFw, unsigned int runId, unsigned int startTime, LSF_MODE_K mode, LSF_REASON_OPEN_K reason)
	Sets the context for a new run.
void	LSEW_dgmFwModeChange (LSEW_dgmFw *dgmFw, LSF_MODE_K mode)
	Changes the current data-taking mode.
unsigned int	LSEW_dgmFwEvtAdd (LSEW_dgmFw *dgmFw, void *evt, unsigned int evt_seq, const EBF_gem *gem)
	Formats the specified event, flushing the current event datagram if the event datagram is full.
unsigned int	LSEW_dgmFwUsrAdd (LSEW_dgmFw *dgmFw, void *usrInfo, int usrLen)
	Formats the specified event, flushing the current event datagram if the event datagram is full.
unsigned int	LSEW_dgmFwFlush (LSEW_dgmFw *dgmFw, int reason)
	Flushes the last events out.
const LSEW_ctxPub *	LSEW_dgmFwCtxPub (const LSEW_dgmFw *dgmFw)
	Returns a pointer to the public portion of the standard context.
unsigned int	LSEW_dgmFwLeft32 (LSEW_dgmFw *dgmFw)
	Returns the number of 32 words left in the datagram.
Variables
static const unsigned char	OpenReasons [16]
	Maps a closing reason into its complimentary open reason.

---

Detailed Description

Code to write events using a framework built around the LSDW_dgm utilities.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: LSEW_dgmFw.c,v 1.13 2008/01/31 23:31:41 russell Exp $

---

Function Documentation

static unsigned int datagram_close	(	LSEW_dgmFw *	dgmFw,
		unsigned int	reason
	)			[static]

Unconditionally writes out whatever is in the current buffer.

Return values:

	0,If	successful
	-1,If	the user close contribution did not fit. In this case the datagram is left open. A reasonable course of action on the user's part would be to manually flush the datagram, specifying it is being closed due to error.

Parameters:

	dgmFw	The framework's control block
	reason	One of an enumerated list describing why this event datagram is being closed

static unsigned int * datagram_open	(	LSEW_dgmFw *	dgmFw,
		unsigned int	reason,
		unsigned int	evt_seq,
		const EBF_gem *	gem
	)			[static]

Opens a new event datagram.

Returns:

Pointer to the new datagram or NULL if unsuccessful in opening the datagram and adding the standard contribution plus any potential user contribution.

Parameters:

	dgmFw	The framework's control block
	reason	One of enumerated list describing why this datagram is being opened
	evt_seq	The event sequence number
	gem	The GEM contribution

static unsigned int * datagram_retry	(	LSEW_dgmFw *	dgmFw,
		void *	evt,
		unsigned int	evt_seq,
		const EBF_gem *	gem
	)			[static]

Attempts to retry the adding of an event by closing the current datagram and opening a new one. If this attempt fails, it is because the datagram is not large enough to accomodate the overhead (beginning contributions) and the event.

Returns:

The next write pointer or NULL if insufficient space

Parameters:

	dgmFw	The framework's control block
	evt	The event to add
	evt_seq	The event sequence number
	gem	The GEM data

static __inline LSEW_dgm * locate

(

const LSEW_dgmFw *

dgmFw

)

[static]

Give the LSEW_dgmFw, locates the LSEW_dgm.

Returns:

Pointer to the LDSW_dgm

Parameters:

dgmFw

The framework's control block

The LDSW_dgm is located immediately following the LDSW_dgmFw handle. This routine merely encapsulates this information so that it only appears in one place.

LSEW_dgmFwBegAddCbp LSEW_dgmFwBegAddSet	(	LSEW_dgmFw *	dgmFw,
		LSEW_dgmFwBegAdder	begRtn,
		void *	begPrm
	)

Sets the callback to add a user specified Begin Context Contribution record.

Returns:

The previous routine plus its context parameter

Parameters:

	dgmFw	The framework control block to initialize
	begRtn	The begin context contribution add routine
	begPrm	The begin context contribution add routine's user parameter

void LSEW_dgmFwBufSet	(	LSEW_dgmFw *	dgmFw,
		unsigned int *	buf,
		int	bufSize
	)

Sets the buffer to be used for the event datagram and its size.

Parameters:

	dgmFw	The target framework control block
	buf	The first, preallocated buffer to fill
	bufSize	The size, in bytes, of the ouptut buffer. Events will be packed into this buffer until full

unsigned int LSEW_dgmFwCtxPub

(

const LSEW_dgmFw *

dgmFw

)

Returns a pointer to the public portion of the standard context.

Returns:

A pointer to the public portion of the standard context

Parameters:

dgmFw

The framework's control block

LSEW_dgmFwEndAddCbp LSEW_dgmFwEndAddSet	(	LSEW_dgmFw *	dgmFw,
		LSEW_dgmFwEndAdder	endRtn,
		void *	endPrm
	)

Sets the callback to add a user specified End Context Contribution record.

Returns:

The previous routine plus its context parameter

Parameters:

	dgmFw	The target framework control block
	endRtn	The end context contribution add routine
	endPrm	The end context contribution add routine's context parameter

unsigned int LSEW_dgmFwEvtAdd	(	LSEW_dgmFw *	dgmFw,
		void *	evt,
		unsigned int	evt_seq,
		const EBF_gem *	gem
	)

Formats the specified event, flushing the current event datagram if the event datagram is full.

Return values:

	0,Record	use succesfully added
	-1,User	callback routine refused to add the event because not only did it not fit in the current datagram, it would not fit in a new datagram. Either the user accepts that the event is too big or he must change recompile with a larger datagram size.

Parameters:

	dgmFw	The framework's control block
	evt	Dynamic (i.e. associated with this event) context parameter
	evt_seq	The event sequence number
	gem	The GEM contributor

This is the workhorse routine of LSEW_dgmFw. Its primary job to take an input event, nominally specified as a pointer to the beginning of the event and its size and bytes and call the user specified formatting routine to commit it to the buffer. To do this correctly it must

1. Update the extended counter/time context
2. Attempt to add the event to the event datagram, using the event formatting routine being managed by the framework
3. If the user's event formatting routine determines that the event does not fit in the current event datagram, then
   1. Close out and post the current datagram
   2. Establish a new event datagram, filling in the standard context record and calling a user provdied begin event datagram routine
   3. Attempt to add the event once to the new event datagram
   4. If this fails, then there is no hope in adding this event, the datagram is too small..
4. If the event fits, commit it to the datagram

Caveat

When considering the user's event formatting routine is determining whether and event fits in the current buffer, the bear in mind the following two considerations

1. Any event may need to inject the Context Update Record.
2. When an event datagram is posted, the user must leave enough room for any data added by the user's end event datagram contribution.

Because of this, the recommendation is that when declaring the size of the buffer to be used for the event datagram, one does not include the size of these two contributions. That way one can be assured that this routine will declare buffer full when there is enough space left to fit these contributions in. This tactic works only if the size of these two buffers is known at the time the event datagram framework is constructed (initialization time).

If the size of the end contribution is unknown at event datagram framework construction time, then the only tactic is to include the of end contribution size with the estimated size of the event.

LSEW_dgmFwEvtAddCbp LSEW_dgmFwEvtAddSet	(	LSEW_dgmFw *	dgmFw,
		LSEW_dgmFwEvtAdder	evtRtn,
		void *	evtPrm
	)

Sets the callback to add an event to the event datagram.

Returns:

The previous routine plus its context parameter

Parameters:

	dgmFw	The target framework control block
	evtRtn	The event add routine
	evtPrm	The event add routine's context parameter

unsigned int LSEW_dgmFwFlush	(	LSEW_dgmFw *	dgmFw,
		int	reason
	)

Flushes the last events out.

Returns:

Success

Parameters:

	dgmFw	The framework's control block
	reason	The reason the flush is being called

unsigned int LSEW_dgmFwInit	(	LSEW_dgmFw *	dgmFw,
		unsigned short int	apid,
		unsigned int	dgm_id,
		LSF_CPU_K	cpu,
		LSF_ORIGIN_K	origin
	)

Initializes the control structure.

Returns:

Status

Parameters:

	dgmFw	The framework control block 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 originating CPU
	origin	The data source type

unsigned int LSEW_dgmFwLeft32

(

LSEW_dgmFw *

dgmFw

)

Returns the number of 32 words left in the datagram.

Returns:

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

Parameters:

dgmFw

The framework's control block

This routine may be called at anytime to learn how many 32-bit words remain in the buffer. This information can be used to decide whether there is sufficient room to make it worthwhile to add another contribution or record. For example, the caller may find himself in the position where he needs to add user context record, but realizes that the user context record only is useful if there is sufficient room for both the user context record and the next event. By querying the amount left, the caller can decide on a sensible course of action.

void LSEW_dgmFwModeChange	(	LSEW_dgmFw *	dgmFw,
		LSF_MODE_K	mode
	)

Changes the current data-taking mode.

Parameters:

	dgmFw	The destination event datagram framework handle
	mode	The new data-taking mode

This routine does two things

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

LSEW_dgmFwBegAddCbp LSEW_dgmFwPostSet	(	LSEW_dgmFw *	dgmFw,
		LSEW_dgmFwPoster	postRtn,
		void *	postPrm
	)

Sets the callback to add a user specified End Context Contribution record.

Returns:

The previous routine plus its context parameter

Parameters:

	dgmFw	The target framework control block
	postRtn	The post event datagram routine
	postPrm	The post event datagram routine's context parameter

void LSEW_dgmFwRunStart	(	LSEW_dgmFw *	dgmFw,
		unsigned int	runId,
		unsigned int	startTime,
		LSF_MODE_K	mode,
		LSF_REASON_OPEN_K	reason
	)

Sets the context for a new run.

Parameters:

	dgmFw	The framework's control block
	runId	The run identifier
	startTime	The start time to the nearest second
	mode	The running mode
	reason	The start reason

unsigned int LSEW_dgmFwUsrAdd	(	LSEW_dgmFw *	dgmFw,
		void *	usrInfo,
		int	usrLen
	)

Formats the specified event, flushing the current event datagram if the event datagram is full.

Return values:

	0,if	the user information was added
	-1,if	the user information was not added because the datagram did not have enough room. In this case the likely strategy is to for the user to have an ADD BEGIN contribution add this information This will happen automatically when the new datagram is opened, ie when the next event is inserted.

Parameters:

	dgmFw	The framework's control block
	usrInfo	A pointer to the user information
	usrLen	Meant to be the length of the user information, but since it is passed transparently the callback routine that does the adding, it can be any 32-bit parameter you wish.

LSEW_dgmFwEvtAddCbp LSEW_dgmFwUsrAddSet	(	LSEW_dgmFw *	dgmFw,
		LSEW_dgmFwUsrAdder	usrRtn,
		void *	usrPrm
	)

Sets the callback to add an event to the event datagram.

Returns:

The previous routine plus its context parameter

Parameters:

	dgmFw	The target framework control block
	usrRtn	The user contribution add routine
	usrPrm	The user contribution add rotuines's context parameter

---

Variable Documentation

unsigned char OpenReasons[16] [static]

Initial value:

{
  LSF_REASON_OPEN_K_START,      
  LSF_REASON_OPEN_K_START_OP,   
  LSF_REASON_OPEN_K_AUTO_TIME,  
  LSF_REASON_OPEN_K_AUTO_COUNT, 


                                
  LSF_REASON_OPEN_K_START,      
  LSF_REASON_OPEN_K_START_OP,   
  LSF_REASON_OPEN_K_START_AUTO, 
  LSF_REASON_OPEN_K_START,      

                                
  LSF_REASON_OPEN_K_RESUME,     
  LSF_REASON_OPEN_K_RESUME_OP,  
  LSF_REASON_OPEN_K_RESUME_AUTO,

                                
  LSF_REASON_OPEN_K_AUTO,       
  LSF_REASON_OPEN_K_AUTO_MODE,  
  LSF_REASON_CLOSE_K_AUTO_TIME, 
  LSF_REASON_CLOSE_K_AUTO_COUNT,
  LSF_REASON_CLOSE_K_AUTO_FULL  
}

Maps a closing reason into its complimentary open reason.

When a datagram is closed, it is highly likely that a new one will be opened. This new datagram needs a reason for being opened. In many cases this reopening is automatic, so the opening reason must be internally generated. This array fills that need, mapping an closing reason into its complimentary open reason.

Even though this maps all close reasons, some the close reasons are not automatically and likely will not be used. For completeness, a reasonable value is filled in. These entries are marked in the comments with an XX

---