EDS_fwServices.h File Reference

Defines the handler related services and parameters that are needed to register a handler. More...

#include <EDS/EDS_cfg.h>
#include <EDS/EBF_siv.h>

Classes
struct	_EDS_fwHandlerServicesX1
	Event handler servicesX1. More...
struct	_EDS_fwHandlerServices
	Event handler services. More...
struct	_EDS_fwPostServices
	The services as a structure. More...
Typedefs
typedef unsigned int(*	EDS_fwHandlerObjectsGetRtn )(void *prm)
	Returns the bit mask of EDS framework objects used by this handler.
typedef unsigned int(*	EDS_fwHandlerNeedsGetRtn )(void *prm)
	Returns the bit mask of EDS framework needs.
typedef int(*	EDS_fwHandlerFlushRtn )(void *prm, int reason)
typedef unsigned int(*	EDS_fwHandlerProcessRtn )(void *prm, unsigned int pktBytes, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, int id)
	The event handler.
typedef unsigned int(*	EDS_fwHandlerSelectRtn )(void *ctl, unsigned int mode, EDS_cfgInfo *cfg)
	Signature for a routine to select the handler mode.
typedef unsigned int(*	EDS_fwHandlerStartRtn )(void *ctl, unsigned int reason, unsigned int run_id, unsigned int start_time, unsigned int mode)
	Signature for a routine to select the handler mode.
typedef unsigned int(*	EDS_fwHandlerAssociateRtn )(void *ctl, unsigned int mode, unsigned int cfg)
	Signature for a routine to associate handler modes.
typedef int(*	EDS_fwHandlerResultSizeofRtn )(void *prm)
	Callback signature of a to be the size, in bytes, of a handler's result summary vector.
typedef int(*	EDS_fwHandlerDestructRtn )(void *prm)
	Callback signature of a registered handler's destruction routine.
typedef struct _EDS_fwHandlerServicesX1	EDS_fwHandlerServicesX1
	Typedef for struct _EDS_fwHandlerServicesX1.
typedef struct _EDS_fwHandlerServices	EDS_fwHandlerServices
	Typedef for struct _EDS_fwHandlerServices.
typedef int(*	EDS_fwPostStartRtn )(void *prm, int reason, unsigned int run_id, unsigned int startTime, unsigned int mode, unsigned int hw_key, unsigned int cfg_key)
	Callback signature to start or prepare a posting stream to receive events.
typedef void(*	EDS_fwPostWriteRtn )(void *prm, EDS_fwIxb *ixb)
	Callback signature to write an event to the post stream.
typedef int(*	EDS_fwPostNotifyRtn )(void *prm, unsigned int mode, unsigned int active, const EDS_cfgInfo cfgs[32], const EDS_rsdTbl *rsdTbl)
	Routine to notify clients of a change in the handlers' configuration.
typedef int(*	EDS_fwPostFlushRtn )(void *prm, int reason)
	Callback signature for the event post que flushing routine.
typedef struct _EDS_fwPostServices	EDS_fwPostServices
	Typedef for EDS_fwPostServices.

---

Detailed Description

Defines the handler related services and parameters that are needed to register a handler.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: EDS_fwServices.h,v 1.8 2011/03/25 22:16:55 russell Exp $

---

Typedef Documentation

unsigned int(* EDS_fwHandlerAssociateRtn)(void *ctl, unsigned int mode, unsigned int cfg)

Signature for a routine to associate handler modes.

Returns:

The index of the old configuration. Any value larger than 31 is considered an error and that the association for that handler was not changed.

Parameters:

	ctl	The control context for this handler
	mode	The target mode. It is this mode that the new configuration is associated with. Currently this number must be between 0 and 7 inclusive.
	cfg	The id of the new configuration. Currently this number must be between 0 and 31 inclusive.

Usage

Each handler may have a pallette of up to 32 configurations. It is the intent, but not a requirement, that when the 'set mode' method is invoked, that the handler consult an internal database that associates an operating mode with a configuration. This method provides a means to modify this association. Whereas the 'set mode' method is designed to work dynamically, i.e. when data is being accumulated, this method is meant to be invoked outside a active data taking. In particular, the method should not alter the current configuration, that is the duty of the set mode command. However, the design of the associate command should allow the following sequence

        associate (ctl, TOO, CONFIGURATION_2)
        set       (ctl, TOO);

int(* EDS_fwHandlerDestructRtn)(void *prm)

Callback signature of a registered handler's destruction routine.

Returns:

Status, although I have no idea what to do with it currently

Parameters:

prm

The arbitrary user parameter associated with the handler

unsigned int(* EDS_fwHandlerNeedsGetRtn)(void *prm)

Returns the bit mask of EDS framework needs.

Returns:

The bit mask of EDS framework needs

Parameters:

prm

The arbitrary user parameter associated with the handler

unsigned int(* EDS_fwHandlerObjectsGetRtn)(void *prm)

Returns the bit mask of EDS framework objects used by this handler.

Returns:

The bit mask of EDS framework needs

Parameters:

prm

The arbitrary user parameter associated with the handler

unsigned int(* EDS_fwHandlerProcessRtn)(void *prm, unsigned int pktBytes, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, int id)

The event handler.

Returns:

A bit mask of the fate and needs of this processor, see enum _EDS_FW_FN_M

Parameters:

	prm	Arbitrary user parameter
	pktBytes	The number of bytes in this packet
	pkt	The packet itself
	siv	The state information vector
	ixb	The Information Exchange Block
	id	The identity (0-31) of this handler. This can be used to index various arrays, In particular, the array of result descriptors in the Ixb Result Vector table

int(* EDS_fwHandlerResultSizeofRtn)(void *prm)

Callback signature of a to be the size, in bytes, of a handler's result summary vector.

Returns:

Size, in bytes, of a handler's result summary vector

Parameters:

prm

The arbitrary user parameter associated with the handler

unsigned int(* EDS_fwHandlerSelectRtn)(void *ctl, unsigned int mode, EDS_cfgInfo *cfg)

Signature for a routine to select the handler mode.

Return values:

	==0	Success
	!=0	Failure

Parameters:

	ctl	The control context for this handler
	mode	The new mode. Currently this number must be between 0 and 7 inclusive.
	cfg	Filled in by the called with information about the newly selected configuration.

EDS_fwHandlerServices

Typedef for struct _EDS_fwHandlerServices.

This is the vector of services that allow one to register a handler. It is intended that this vector carry little to no dynmatic context. That information should be carried in the context parameter passed as the first argument to each of the service routines. In particular, this includes the service routines to get the EDS framework objects and needs used during the handler registration.

Notably absent are services to

1. Get the size of a handler's control structure
2. Construct the handler's control structure.

These are deemed outside the scope to the EDS framework.

Warning:

This is an obsolete structure maintained only for backwardly compatiable reasons

EDS_fwHandlerServicesX1

Typedef for struct _EDS_fwHandlerServicesX1.

This is the vector of services that allow one to register a handler. It is intended that this vector carry little to no dynmatic context. That information should be carried in the context parameter passed as the first argument to each of the service routines. In particular, this includes the service routines to get the EDS framework objects and needs used during the handler registration.

Notably absent are services to

1. Get the size of a handler's control structure
2. Construct the handler's control structure.

These are deemed outside the scope to the EDS framework.

unsigned int(* EDS_fwHandlerStartRtn)(void *ctl, unsigned int reason, unsigned int run_id, unsigned int start_time, unsigned int mode)

Signature for a routine to select the handler mode.

Returns:

The index of the selected configuration. Any value larger than 31 is considered an error.

Parameters:

	ctl	The control context for this handler
	reason	Suggested use is to indicate why the post stream is being started
	run_id	Suggested use is to identify the block of events between when EDS_fwStart is called and EDS_fwFlush is called with a stop reason
	startTime	The run start time rounded to the nearest second
	mode	This must be the running mode. Note that a call to EDS_selectMode still must be done.

int(* EDS_fwPostFlushRtn)(void *prm, int reason)

Callback signature for the event post que flushing routine.

Status 0, success, anything else failure

Parameters:

	prm	Arbitrary user parameter
	list	The list of post ques to flush
	reason	The reason for flushing the ques

This service is generally called when the user wishes to manually force the posting queues to be flushed, such as at the end of a data taking run or, perhaps, based on a timer. In general queues flush themselves when their output buffering capacity is reached.

int(* EDS_fwPostNotifyRtn)(void *prm, unsigned int mode, unsigned int active, const EDS_cfgInfo cfgs[32], const EDS_rsdTbl *rsdTbl)

Routine to notify clients of a change in the handlers' configuration.

Returns:

0 on success, else non-zero

Parameters:

	prm	Arbitrary user parameter
	mode	The new mode
	active	List of the currently active handlers
	cfgs	The array of configurations, indexed by handler number
	rsdTbl	The table of result summary data table

This routine should be called back whenever the configuration or list of active handlers changes. It is used by the posting routines to track the active configuration. The most common time this would be used is to establish the initial context and after a mode change.

int(* EDS_fwPostStartRtn)(void *prm, int reason, unsigned int run_id, unsigned itn startTime, unsigned int mode, unsigned int hw_key, unsigned int cfg_key)

Callback signature to start or prepare a posting stream to receive events.

Returns:

0 is successful, non-zero otherwise

Parameters:

	prm	Arbitrary user parameter
	reason	Suggested use is to indicate why the post stream is being started
	run_id	Suggested use is to identify the block of events between when EDS_fwStart is called and EDS_fwFlush is called with a stop reason
	startTime	The run start time rounded to the nearest second
	mode	This must be the running mode.
	hw_key	The hardware configuration file key
	cfg_key	The software configuration file key. This likely a reference to how event handlers to EDS here configured (perhaps the LPA_DB key).

void(* EDS_fwPostWriteRtn)(void *prm, EDS_fwIxb *ixb)

Callback signature to write an event to the post stream.

Parameters:

	prm	Arbitrary user parameter
	ixb	The framework's Information Exchange Block

The user should assume that all memory associated with the event will vanish after this callback. Practically speaking, this means that the routine should not stash pointers to information in the ixb, but should copy the data.