EFC.h File Reference

Provides a wrapper in which to run a filter as an EDS callback routine. More...

#include <EFC/EFC_fate.h>
#include <EFC/EFA_def.h>
#include <EDS/EDS_fw.h>
#include <EDS/EBF_siv.h>
#include <EDS_DB/EDS_DB_schema.h>

Classes
struct	_EFC_services
	The defining services of a standard filter. More...
struct	_EFC_sizes
	The defining sizes the filters control block, configuration block and result vector. More...
struct	_EFC_classes
	Breaks the status word into classes of bits. More...
struct	_EFC_definition
	The defining values of a standard filter. More...
Typedefs
typedef void *(*	EFC_servicesConstruct )(void *ctl, const void *schema)
	Constructs the configuration parameters block.
typedef EFC_fate(*	EFC_servicesFilter )(void *ctl, int pktBytes, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, unsigned int vetoes, void *result)
	EFC filter routine function signature.
typedef void *(*	EFC_servicesCfgSet )(void *cfg_ctl, const void *parameters)
	Constructs the configuration parameters block.
typedef void(*	EFC_servicesDestruct )(void *ctl)
	Destroys this filter's context.
typedef unsigned int(*	EFC_servicesReport )(void *prm, const void *cfg, const EFC_sampler *sampler, int which)
	Configuration reporting callback routine.
typedef struct _EFC_services	EFC_services
	Typedef for struct _EFC_services.
typedef struct _EFC_sizes	EFC_sizes
	Typedef for struct _EFC_sizes.
typedef struct _EFC_classes	EFC_classes
	Typedef for struct _EFC_classes.
typedef struct _EFC_definition	EFC_definition
	Typedef for struct _EFC_defintion.
typedef enum _EFC_OBJECT_K	EFC_OBJECT_K
	Typedef for enum _EFC_OBJECT_K.
Enumerations
enum	_EFC_OBJECT_K {   EFC_OBJECT_K_MODE = 0,   EFC_OBJECT_K_FILTER_RTN = 1,   EFC_OBJECT_K_FILTER_PRM = 2,   EFC_OBJECT_K_CFGSET_RTN = 3,   EFC_OBJECT_K_REPORT_RTN = 4,   EFC_OBJECT_K_SAMPLER = 5,   EFC_OBJECT_K_EFA = 6,   EFC_OBJECT_K_ID = 7 }
	Enumeration of the objects. More...
Functions
int	EFC_sizeof (const EFC_DB_SchemaFilter *schema, void *prm, const EFC_sizes *sizes)
	Returns the size, in bytes, of the filter control structure and the associated configuration constants.
const EDS_fwHandlerServicesX1 *	EFC_construct (EFC *efc, unsigned int handler_id, const EFC_DB_SchemaFilter *schema, unsigned int schema_key, void *prm, EDS_fw *edsFw, const EFC_definition *definition, unsigned int objects, unsigned int needs)
	Resolves all the indirect references in the specified master configuration file and files in both the EFC control structure and the filter specific control structure. This is merely a call-through to the general purpose constructor.
unsigned int	EFC_objectsAdd (EDS_fw *fw, unsigned int objects)
unsigned int	EFC_objectsGet (const EFC *efc)
	Returns the list of EDS framework objects needed by this filter.
unsigned int	EFC_needsGet (const EFC *efc)
	Returns the list of EDS framework needs for this filter.
void *	EFC_get (const EFC *efc, EFC_OBJECT_K object)
	Returns a pointer to named object.
int	EFC_set (EFC *efc, EFC_OBJECT_K object, void *value)
	Sets the named object to the specified value. This is primarily used for backdoor debugging.
int	EFC_filter (EFC *efc, unsigned int pktBytes, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, int id)
	Calls the filter function for each of the specified events.
const EFC_DB_Schema *	EFC_lookup (unsigned short int schema_id, unsigned short int instance_id)
	Looks up the CDM database associated with the specified schema_id and instance_id.
int	EFC_modeAssociate (EFC *efc, int mode, int configuration)
	Establish a new configuration to be associated with the indicated mode.
int	EFC_modeSelect (EFC *efc, int mode, EDS_cfgInfo *info)
	Selects the operating environment according to the specified mode.
int	EFC_start (EFC *efc, unsigned int reason, unsigned int run_id, unsigned int start_time, unsigned int mode)
	EDS start run callback routine.
void	EFC_report (EFC *efc, unsigned int list)
	Calls back the user to report on the configuration.
int	EFC_teardown (EFC *efc)

---

Detailed Description

Provides a wrapper in which to run a filter as an EDS callback routine.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: EFC.h,v 1.9 2012/01/04 20:28:08 russell Exp $

---

Typedef Documentation

EFC_definition

Typedef for struct _EFC_defintion.

The original definition of an EFC_definition did not contain that information. In order to stay backwards compatible, an augmented version, EFC_definitionC, along with a matching constructor, EFC_constructC was added. With EFC_2.0.0, the qualifying C was dropped and all references to the original version were eliminated.

EFC_OBJECT_K

Typedef for enum _EFC_OBJECT_K.

This enumerates the objects that can be accessed and set via the EFC_objectGet and EFC_objectSet routines.

These routines allow access to the private EFC structure and is meant to be used mainly in a debugging environment. However, there may be uses for this outside of that arena, so it was decided to exposed this as a general interface. With that said, one should realize that this facility should be used with caution.

The one very legitimate use is to get a pointer to the filter specific parameter. This would be called immediately after EFC_construct completes. Fetching this value will all the user to complete initialization of the structure. This was omitted from the first implementation by oversight and by the fact that the early filters did not need it.

void *(* EFC_servicesCfgSet)(void *ctl, void *parameters)

Constructs the configuration parameters block.

Returns:

Status

Parameters:

	ctl	The target filter's control block
	parameters	The defining parameters

void *(* EFC_servicesConstruct)(void *ctl, const void *schema)

Constructs the configuration parameters block.

Returns:

Status

Parameters:

	ctl	The target filter's control block
	schema	The defining configuration schema

void(* EFC_servicesDestruct)(void *ctl)

Destroys this filter's context.

Parameters:

ctl

The target filter's control block

EFC_fate(* EFC_servicesFilter)(void *ctl, int pktBytes, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, unsigned int vetoes, void *result)

EFC filter routine function signature.

Returns:

The filtering fate

Parameters:

	ctl	The target filter's control block
	pktBytes	Number of bytes in the EBF packet
	pkt	The EBF packet
	siv	The EBF state information vector
	EDS_fwIxb	The framework's information exchange block
	vetoes	The list of active vetoes
	result	The result vector to fill

unsigned int(* EFC_servicesReport)(void *prm, const void *cfg, const EFC_sampler *sampler, int list)

Configuration reporting callback routine.

Returns:

The bit list of the remaining ones to print, 0 terminates it

Parameters:

	prm	User context parameter
	cfg	The configuration to report on
	sampler	The sampler structure that is paired with this configuration
	list	The bit list of what is remaining, by implication, this is 0 when done

---

Enumeration Type Documentation

enum _EFC_OBJECT_K

Enumeration of the objects.

Enumerator:

EFC_OBJECT_K_MODE	The configuration mode
EFC_OBJECT_K_FILTER_RTN	The filter routine
EFC_OBJECT_K_FILTER_PRM	The filter parameter
EFC_OBJECT_K_CFGSET_RTN	The configuration set routine
EFC_OBJECT_K_REPORT_RTN	The report routine
EFC_OBJECT_K_SAMPLER	The sampling parameters
EFC_OBJECT_K_EFA	The event analysis structure
EFC_OBJECT_K_ID	The id of this event filter/handler

---

Function Documentation

const EDS_fwHandlerServicesX1 EFC_construct	(	EFC *	efc,
		unsigned int	id,
		const EFC_DB_SchemaFilter *	schema,
		unsigned int	schema_key,
		void *	prm,
		EDS_fw *	edsFw,
		const EFC_definition *	definition,
		unsigned int	objects,
		unsigned int	needs
	)

Resolves all the indirect references in the specified master configuration file and files in both the EFC control structure and the filter specific control structure. This is merely a call-through to the general purpose constructor.

Returns:

A pointer to the service vector of routines

Parameters:

	efc	The Event Filter Control block to initialize
	id	A unique identifier to assign to this EFC handler
	schema	Pointer to the schema of the filter configuration file
	schema_key	The schema's file resolution key
	prm	An optional, modifying parameter
	edsFw	The controlling EDS framework handle
	definition	The defining information for this filter
	objects	The list of EDS framework objects used by this filter
	needs	The list of EDS needs for this filter.

References _EFC_definition::classes, construct_efc(), _EFC_definition::services, and _EFC_definition::sizes.

Referenced by EFC_stdConstruct().

int EFC_filter	(	EFC *	efc,
		unsigned int	pktBytes,
		EBF_pkt *	pkt,
		EBF_siv	siv,
		EDS_fwIxb *	ixb,
		int	id
	)

Calls the filter function for each of the specified events.

Returns:

Status

Parameters:

	efc	The event filter control structure
	pktBytes	The number bytes in this packet
	pkt	The event packet
	siv	The state information vector
	ixb	The Information Exchange Block
	id	The identification of this handler

The user will likely not call this routine directly, but use it as the EDS_fw callback routine. The parameter will be the EFC control structure.

References _EFC::active, _EFC_sampler::classes, copyResult(), _EFA::cur, _EFC::disabled_passes, _EFC::efa, EFA__preprocess(), EFA_postprocess(), EFA_STATE_K_STARTED, EFC__fateIsAccepted(), EFC__fateIsUndecided(), _EFC_samplerPrescaleCtx::enabled, _EFC_samplerClasses::enabled, _EFC::filterPrm, _EFC::filterRtn, getActive(), _EFC::ievt, if_would_have_been_vetoed(), _EFC_samplerPrescaleCtx::in, _EFC::needs_leaked, _EFC::needs_normal, _EFC_samplerPrescaleCtx::out, _EFA::postLeft, _EFC_sampler::prescale, _EFC_samplerPrescaleCtx::prescalers, _EFC::sampler, _EFA::size, _EFA::state, updateDisabledPasses(), updatePrescaler(), and _EFC_classes::vetoes.

Referenced by construct_efc().

void * EFC_get	(	const EFC *	efc,
		EFC_OBJECT_K	object
	)

Returns a pointer to named object.

Returns:

Pointer to the named object, or NULL if the object is non-existent

Parameters:

	efc	The Event Filter handle
	object	The object to get. This is one of the following set EFC_OBJECT_K_MODE EFC_OBJECT_K_FILTER_RTN EFC_OBJECT_K_FILTER_PRM EFC_OBJECT_K_CFGSET_RTN EFC_OBJECT_K_REPORT_RTN EFC_OBJECT_K_SAMPLER EFC_OBJECT_K_EFA EFC_OBJECT_K_ID

References _EFC::cfgSetRtn, _EFC::efa, EFC_OBJECT_K_CFGSET_RTN, EFC_OBJECT_K_EFA, EFC_OBJECT_K_FILTER_PRM, EFC_OBJECT_K_FILTER_RTN, EFC_OBJECT_K_ID, EFC_OBJECT_K_MODE, EFC_OBJECT_K_REPORT_RTN, EFC_OBJECT_K_SAMPLER, _EFC::filterPrm, _EFC::filterRtn, _EFC::id, _EFC::mode, _EFC::reportRtn, and _EFC::sampler.

Referenced by EFC_stdConstruct().

const EFC_DB_Schema EFC_lookup	(	unsigned short int	schema_id,
		unsigned short int	instance_id
	)

Looks up the CDM database associated with the specified schema_id and instance_id.

Returns:

A pointer to the filter schema. If not found NULL.

Parameters:

	schema_id	The schema id of the filter's configuration database
	instance_id	The instance id of the filter's configuratin database

int EFC_modeAssociate	(	EFC *	efc,
		int	mode,
		int	configuration
	)

Establish a new configuration to be associated with the indicated mode.

Return values:

The

old association

Parameters:

	efc	The EFC control context
	mode	The mode, must be 0-7
	configuration	One of the active configurations. This number is the index that the configurations where defined

Because this command is not given during data-taking, ff the mode being specified is the current mode, this routine does not change the current operating configuration.

References _EFC_cfg::byMode, _EFC::cfg, _EFC_cfg::db, _EFC_cfgDb::members, and _EFC_cfgDb::valid.

Referenced by construct_efc().

int EFC_modeSelect	(	EFC *	efc,
		int	mode,
		EDS_cfgInfo *	info
	)

Selects the operating environment according to the specified mode.

Return values:

	==0,success
	!=1,failure

Parameters:

	efc	The EFC control context
	mode	The new mode, must be 0-7
	info	Returned with information about the newly selected configuration

References _EFC_cfg::byMode, _EFC::cfg, _EFC::cfgSetRtn, _EFC_cfg::db, _EFC::efa, EFA_notify(), _EFC::filterPrm, _EFC::id, _EFC_cfgDbMember::idx, _EFC::key, _EFC_cfgDbMember::key, _EFC_cfgDb::members, _EFC::mode, _EFC_cfgDbMember::prms, _EFC_cfgDbMember::sampler, and _EFC::sampler.

Referenced by construct_efc().

unsigned int EFC_needsGet

(

const EFC *

efc

)

Returns the list of EDS framework needs for this filter.

Returns:

The list of EDS framework needs for this filter

Parameters:

efc

The EFC control context

References _EFC::needs.

Referenced by construct_efc().

unsigned int EFC_objectsGet

(

const EFC *

efc

)

Returns the list of EDS framework objects needed by this filter.

Returns:

The list of EDS framework objects needed by this filter

Parameters:

efc

The EFC control context

References _EFC::objects.

Referenced by construct_efc().

void EFC_report	(	EFC *	efc,
		unsigned int	list
	)

Calls back the user to report on the configuration.

Parameters:

	efc	The Event Filter Control Block
	list	The bit list of which ones to report on. If 0, then report only on the current one

References _EFC::cfg, _EFC_cfg::db, _EFC_cfgDb::members, _EFC::mode, _EFC_cfgDbMember::prms, _EFC::reportRtn, _EFC::sampler, _EFC_cfgDbMember::sampler, and _EFC_cfgDb::valid.

int EFC_set	(	EFC *	efc,
		EFC_OBJECT_K	object,
		void *	value
	)

Sets the named object to the specified value. This is primarily used for backdoor debugging.

Return values:

	0,Named	object is settable
	-1,Named	object is not setteable

Parameters:

	efc	The Event Filter handle
	object	The object to set. The following objects are supported EFC_OBJECT_K_MODE EFC_OBJECT_K_FILTER_RTN EFC_OBJECT_K_FILTER_PRM EFC_OBJECT_K_CFGSET_RTN EFC_OBJECT_K_REPORT_RTN
	value	The new value

References _EFC::cfgSetRtn, EFC_OBJECT_K_CFGSET_RTN, EFC_OBJECT_K_FILTER_PRM, EFC_OBJECT_K_FILTER_RTN, EFC_OBJECT_K_MODE, EFC_OBJECT_K_REPORT_RTN, _EFC::filterPrm, _EFC::filterRtn, _EFC::mode, and _EFC::reportRtn.

int EFC_sizeof	(	const EFC_DB_SchemaFilter *	schema,
		void *	prm,
		const EFC_sizes *	sizes
	)

Returns the size, in bytes, of the filter control structure and the associated configuration constants.

Returns:

The size, in bytes, of the filter control structure and the associated configuration constants.

Parameters:

	schema	Pointer to the schema of the filter configuration file
	prm	An optional, modifying parameter
	sizes	The sizes of the filter's various blocks

Warning:

This is a usually a good sized object so use an appropriate allocator.

References _EFC_sizes::cfg, and _EFC_sizes::ctl.

Referenced by EFC_stdConstruct(), and EFC_stdSizeof().

int EFC_start	(	EFC *	efc,
		unsigned int	reason,
		unsigned int	run_id,
		unsigned int	start_time,
		unsigned int	mode
	)

EDS start run callback routine.

Returns:

Status

Parameters:

	efc	The event filter control handle
	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
	start_time	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.

References _EFC::efa, and EFA_start().

Referenced by construct_efc().