LSEW_dgmFw.h File Reference

Output events using a framework built around the LSEW_dgm utilities. More...

#include "LSF/LSF_cpu.h"
#include "LSF/LSF_mode.h"
#include "LSF/LSF_origin.h"
#include "LSF/LSF_reason.h"

Include dependency graph for LSEW_dgmFw.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_LSEW_dgmFwBegAddCbp
	Binds the routine to add a Begin Context Contribution routine (the callback) with its context parameter. More...
struct	_LSEW_dgmFwEvtAddCbp
	Binds the routine to add an event (the callback) with its parameter. More...
struct	_LSEW_dgmFwUsrAddCbp
	Binds the routine to add an User Context Contribution routine (the callback) with its context parameter. More...
struct	_LSEW_dgmFwEndAddCbp
	Binds the routine to add an End Context Contribution routine (the callback) with its context parameter. More...
struct	_LSEW_dgmFwPostCbp
	Binds the routine to add an datagram posting routine (the callback) with its context parameter. More...
struct	_LSEW_dgmFwNotifyCbp
	Binds the routine to notify a datagram of a change in configuration with with its context parameter. More...
Typedefs
typedef unsigned int (	LSEW_dgmFwBegAdder )(void prm, unsigned int buf, unsigned int len32)
	Callback signature for the routine to add a Begin Context Contribtution the event datagram.
typedef _LSEW_dgmFwBegAddCbp	LSEW_dgmFwBegAddCbp
	Typedef for struct _LSEW_dgmFwBegAddCbp.
typedef unsigned int (	LSEW_dgmFwEvtAdder )(void prm, void evt, unsigned int *buf, unsigned int len32)
	Callback signature for an adding an event to the event datagram or, more specifically to the current Event Contribution record.
typedef _LSEW_dgmFwEvtAddCbp	LSEW_dgmFwEvtAddCbp
	Typedef for struct _LSEW_dgmFwAddCbp.
typedef unsigned int (	LSEW_dgmFwUsrAdder )(void prm, void usrInfo, int usrLen, unsigned int *buf, unsigned int len32)
	Callback signature for the routine to add an User Context Contribution at an arbitrary point in the event datagram.
typedef _LSEW_dgmFwUsrAddCbp	LSEW_dgmFwUsrAddCbp
	Typedef for struct _LSEW_dgmFwUsrAddCbp.
typedef unsigned int (	LSEW_dgmFwEndAdder )(void prm, unsigned int buf, unsigned int len32)
	Callback signature for the routine to add an End Context Contribution the event datagram.
typedef _LSEW_dgmFwEndAddCbp	LSEW_dgmFwEndAddCbp
	Typedef for struct _LSEW_dgmFwEndAddCbp.
typedef unsigned int (	LSEW_dgmFwPoster )(void prm, void buf, int bytes)
	Callback signature to post a buffer.
typedef _LSEW_dgmFwPostCbp	LSEW_dgmFwPostCbp
	Typedef for struct _LSEW_dgmFwPostCbp.
typedef unsigned int (	LSEW_dgmFwNotifier )(void *prm, unsigned int active, const unsigned char cfgs[32])
	Callback signature to notify the datagram of the current configuration.
typedef _LSEW_dgmFwNotifyCbp	LSEW_dgmFwNotifyCbp
	Typedef for struct _LSEW_dgmFwNotifyCbp.
Functions
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.
void	LSEW_dgmFwBufSet (LSEW_dgmFw dgmFw, unsigned int buf, int buf_size)
	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.
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.
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.
unsigned int	LSEW_dgmFwNotify (LSEW_dgmFw *dgmFw, unsigned int active, const unsigned char cfgs[32])
unsigned int	LSEW_dgmFwLeft32 (LSEW_dgmFw *dgmFw)
	Returns the number of 32 words left in the datagram.
const LSEW_ctxPub *	LSEW_dgmFwCtxPub (const LSEW_dgmFw *dgmFw)
	Returns a pointer to the public portion of the standard context.

Detailed Description

Output events using a framework built around the LSEW_dgm utilities.

Author:: JJRussell - russell@slac.stanford.edu

   CVS $Id: LSEW_dgmFw.h,v 1.11 2006/09/13 19:46:14 russell Exp $

Typedef Documentation

unsigned int *(* LSEW_dgmFwBegAdder)(void *prm, unsigned int *buf, unsigned int len32)

Callback signature for the routine to add a Begin Context Contribtution the event datagram.

Returns:
If the information fits in the alloted space, a pointer to the next output location to be filled or NULL if the information does not fit.

Parameters:

prm Static user provided parameter

buf The buffer to accept the Begin Contribution data

len32 The number of 32-bit words available in buf. If the information does not fit in this space, return NULL.

The user should return NULL if this Begin Contribution plus any space needed for his END contribution will not fit in the allocated space.

This is really an error in specifying the size of the datagram. All one can do in this case toss the current datagram and establish a new and bigger buffer using LSEW_dgmFwBufSet.

unsigned int *(* LSEW_dgmFwEndAdder)(void *prm, unsigned int *buf, unsigned int len32)

Callback signature for the routine to add an End Context Contribution the event datagram.

Returns:
If the information fits in the alloted space, a pointer to the next output location to be filled or NULL if the information does not fit.

Parameters:

prm Static user provided parameter

buf The buffer to accept the End Contribution data.

len32 The number of 32-bit words available in buf. If the information does not fit in this space, return NULL.

unsigned int *(* LSEW_dgmFwEvtAdder)(void *prm, void *evt, unsigned int *buf, unsigned int len32)

Callback signature for an adding an event to the event datagram or, more specifically to the current Event Contribution record.

Returns:
If the event fits in the alloted space, a pointer to the next output location to be filled or NULL if the information does not fit.

Parameters:

prm Static user provided parameter

evt Dynamic user provided parameter, usually a pointer some representation of the event data.

buf The buffer to accept the Event Record data

len32 The number of 32-bit words available in buf. If the information does not fit in this space, return NULL.

The user should return NULL if this event plus any space needed for his END contribution will not fit in the allocated space.

int(* LSEW_dgmFwNotifier)(void *prm, unsigned int active, const unsigned char cfgs[32])

Callback signature to notify the datagram of the current configuration.

Returns:
0, if successful, non-zero if unsuccessful

Parameters:

prm Arbitrary user context parameter

active The bit list of active handlers

cfgs The array of configuration ids;

unsigned int *(* LSEW_dgmFwPoster)(void *prm, void *buf, int nbytes)

Callback signature to post a buffer.

Returns:
Pointer to the next buffer to be filled.

Parameters:

prm Arbitrary user context parameter

buf The buffer to post

nbytes The number of bytes in the buffer

unsigned int *(* LSEW_dgmFwUsrAdder)(void *prm, void *usrInfo, int usrLen, unsigned int *buf, unsigned int len32)

Callback signature for the routine to add an User Context Contribution at an arbitrary point in the event datagram.

Returns:
If the information fits in the alloted space, a pointer to the next output location to be filled or NULL if the information does not fit.

Parameters:

prm Static user provided parameter

usrInfo Pointer to the information (or some representation of the information) to be written

usrLen Can be interpretted as the length of the information or can be used as an arbitrary 32-bit piece of information, i.e. it is just passed as is through to the user routine.

buf The buffer to accept the User Contribution data

len32 The number of 32-bit words available in buf. If the information does not fit in this space, return NULL.

The user should return NULL if this event plus any space needed for his END contribution will not fit in the allocated space.

Function Documentation

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

const LSEW_ctxPub* 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

Update the extended counter/time context
Attempt to add the event to the event datagram, using the event formatting routine being managed by the framework
If the user's event formatting routine determines that the event does not fit in the current event datagram, then

Close out and post the current datagram
Establish a new event datagram, filling in the standard context record and calling a user provdied begin event datagram routine
Attempt to add the event once to the new event datagram
If this fails, then there is no hope in adding this event, the datagram is too small..

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

Any event may need to inject the Context Update Record.
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

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

LSEW_dgmFwPostCbp 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_dgmFwUsrAddCbp 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

Generated on Wed Aug 27 01:33:52 2008 by

1.4.4

LSEW_dgmFw.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation