EFC.c File Reference

Implementation of a wrapper for a generic filter. More...

#include <EFC_DB/EFC_DB_schemaFilter.h>
#include <EFC_DB/EFC_DB_sampler.h>
#include <EFC/EFC.h>
#include <EFC/EFA.h>
#include <EFA_p.h>
#include <EFC/EFC_samplerDef.h>
#include <EFC/EFC_edsFw.h>
#include <EDS/EDS_fwServices.h>
#include <EDS/EDS_cfg.h>
#include <EDS/EBF_siv.h>
#include <EFC/EFR_key.h>
#include <CDM/CDM_pubdefs.h>
#include <CAB/CAB_lookupPub.h>
#include <PBI/FFS.ih>
#include <PBI/PTR.h>
#include <string.h>

Classes
struct	_EFC_DB_generic_schema
	A generic configuration block. More...
struct	_EFC_cfgDbMember
	One database member. More...
struct	_EFC_cfgDb
	The database of bound the filter's bound sampler and configuration blocks. More...
struct	_EFC_cfg
	The configuration control structure. More...
struct	_EFC
	The control structure for the filter framework. More...
Typedefs
typedef struct _EFC_DB_generic_schema	EFC_DB_generic_schema
	Typedef for struct _EFC_generic_cfg.
typedef struct _EFC_cfgDbMember	EFC_cfgDbMember
	Typedef for struct _EFCcfgDbMember.
typedef struct _EFC_cfgDb	EFC_cfgDb
	Typedef for struct _EFC_cfgDb.
typedef struct _EFC_cfg	EFC_cfg
	Typedef for struct _EFC_cfg.
typedef struct _EFC	EFC
Functions
const EDS_fwHandlerServicesX1 *	construct_efc (EFC *efc, unsigned int id, const EFC_DB_SchemaFilter *schema, unsigned int schema_key, void *prm, EDS_fw *edsFw, const EFC_services *services, const EFC_sizes *sizes, const EFC_classes *classes, 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.
static __inline void	copyResult (EDS_rsdDsc *dsc, unsigned int *results, unsigned int flip)
	Copies the result vector into the result summary data descriptor.
static __inline unsigned int	getActive (EFC_sampler *sampler)
	Gets the active set of vetoes and passes bits for this event.
static __inline unsigned int	updateDisabledPasses (EFC_sampler *sampler, unsigned int disabled_passes, unsigned int status)
	Updates the list of disabled pass bits.
int	updatePrescaler (EFC_samplerPrescaleCounter *prescaler)
	Updates the prescaler.
static __inline int	if_would_have_been_vetoed (int status, const EFC_classes *enabled)
static __inline int	construct_prescaler (EFC_samplerPrescaleCounter *prescaler, int refresh)
	Constructs a prescaler.
static void	construct_sampler (EFC_sampler *sampler, const EFC_DB_sampler *db_sampler, const EFC_classes *defined)
	Compiles/commits the set of user sampling parameters into the the configuration block.
static int	efc_flush (EFC *efc, int reason)
	Currently just a call-through to EFA_flush.
static int	efc_result_sizeof (EFC *efc)
	Just a call-through to EFA_resultSizeof.
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.
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.
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.
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.
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.
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.
void	EFC_report (EFC *efc, unsigned int list)
	Calls back the user to report on the configuration.
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.
int	EFC_destruct (EFC *efc)
	Returns any resources garnered by EFC_construct.

---

Detailed Description

Implementation of a wrapper for a generic filter.

Author:

JJRussell - russell@slac.stanford.edu

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

Overview

This is wrapper for the EDS_fw framework layer, allowing one to register individual and modular filters. A filter in consists of

1. A processing routine that takes as its arguments the set of arguments from of an EDS framework callback plus a veto mask and a result vector
2. A set of callback routines to allocate an array of result vectors and to post the array all entries have been filled. The custumary use of this mechanism to compute and output summary statistics

Result Vector

This collection of routines makes only the following assumptions about a filter's result vector

1. An array of them can be allocated via a user callback routine
2. It has a fixed size, so that it can allocate the next one from the array
3. When all elements of the result vector array are filled or when a flush routine is called, another user routine is called to post the array of now, presumably, filled result arrays.

---

Typedef Documentation

EFC_DB_generic_schema

Typedef for struct _EFC_generic_cfg.

This is used to locate the specific EFC filter parameters.

---

Function Documentation

const EDS_fwHandlerServicesX1 * construct_efc	(	EFC *	efc,
		unsigned int	id,
		const EFC_DB_SchemaFilter *	schema,
		unsigned int	schema_key,
		void *	prm,
		EDS_fw *	edsFw,
		const EFC_services *	services,
		const EFC_sizes *	sizes,
		const EFC_classes *	classes,
		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.

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
	sizes	The sizes of the various components of this filter
	services	The standard set of EFC services
	classes	The status word classes (sets of bits giving the vetoes, passes, etc.)
	objects	The list of EDS framework objects used by this filter
	needs	The list of EDS needs for this filter.

The schema pertains to an instantiation of a filter. Each filter is described by 3 relevant pieces of information

1. A set of global information. This includes
   • The primary schema ID of the filter itself. All filter configurations will be accessed using this ID and an instance number.
   • A count of the number of configurations defined for this filter.
   • A string, giving the name of the routine to get the filter service vector
2. An array (dimensioned by the count indicated above) giving the instance ID of each configuration
3. An array indicating which configuration (from the array configurations), will be used in each of 8 possible modes

After locating the service vector, each configuration is constructed and the mapping of mode to configuration is resolved.

References _EFC_cfg::byMode, _EFC_sizes::cfg, _EFC::cfg, _EFC_services::cfg_set, _EFC::cfgSetRtn, _EFC_services::construct, construct_sampler(), _EFC_sizes::ctl, _EFC_cfg::db, _EFC::disabled_passes, EFC_edsFwObjectsAdd(), EFC_filter(), efc_flush(), EFC_modeAssociate(), EFC_modeSelect(), EFC_needsGet(), EFC_objectsGet(), efc_result_sizeof(), EFC_start(), EFR_keyGet(), _EFC_services::filter, _EFC::filterPrm, _EFC::filterRtn, _EFC::id, _EFC_cfgDbMember::idx, _EFC_cfgDbMember::key, _EFC::key, _EFC_cfgDb::members, _EFC::needs, _EFC::needs_leaked, _EFC::needs_normal, _EFC::objects, _EFC_cfgDbMember::prms, _EFC_services::report, _EFC::reportRtn, _EFC::rsdSize, _EFC_DB_generic_schema::sampler, _EFC::sampler, and _EFC_cfgDb::valid.

Referenced by EFC_construct().

static __inline int construct_prescaler	(	EFC_samplerPrescaleCounter *	prescaler,
		int	refresh
	)			[static]

Constructs a prescaler.

Returns:

Non-zero if this is an active prescaler

Parameters:

	prescaler	The prescaler to configure
	refresh	The refresh value

References _EFC_samplerPrescaleCounter::countdown, and _EFC_samplerPrescaleCounter::refresh.

Referenced by construct_sampler().

static void construct_sampler	(	EFC_sampler *	sampler,
		const EFC_DB_sampler *	db_sampler,
		const EFC_classes *	classes
	)			[static]

Compiles/commits the set of user sampling parameters into the the configuration block.

Parameters:

	sampler	The destination parameter sampler block
	db_sampler	The set of user defined sampling parameters
	classes	The bit list defining the various sets (classes) e.g. vetoes, passes, etc

References _EFC_classes::all, _EFC_sampler::classes, construct_prescaler(), _EFC_samplerClasses::defined, _EFC_samplerPrescaleCtx::enabled, _EFC_samplerClasses::enabled, _EFC_samplerPrescaleCtx::in, _EFC_classes::info, _EFC_samplerPrescaleCtx::out, _EFC_classes::passes, _EFC_sampler::prescale, _EFC_samplerPrescaleCtx::prescalers, and _EFC_classes::vetoes.

Referenced by construct_efc().

static __inline void copyResult	(	EDS_rsdDsc *	dsc,
		unsigned int *	results,
		unsigned int	flip
	)			[static]

Copies the result vector into the result summary data descriptor.

Parameters:

	dsc	The destination descriptor
	results	The result descriptor
	flip	Bits to flip in the first (status) word

Referenced by EFC_filter().

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_destruct

(

EFC *

efc

)

Returns any resources garnered by EFC_construct.

Returns:

Status

Parameters:

efc

The event filter control structure to destroy

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().

static int efc_flush	(	EFC *	efc,
		int	reason
	)			[static]

Currently just a call-through to EFA_flush.

Returns:

Status

Parameters:

	efc	The Event Filter Control block
	reason	The flush reason

References _EFC::efa, and EFA_flush().

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.

static int efc_result_sizeof

(

EFC *

efc

)

[static]

Just a call-through to EFA_resultSizeof.

Returns:

The sizeof on result vector

Parameters:

efc

The Event Filter Control block

References _EFC::efa, EFA_resultSizeof(), and _EFC::rsdSize.

Referenced by construct_efc().

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().

static __inline unsigned int getActive

(

EFC_sampler *

sampler

)

[static]

Gets the active set of vetoes and passes bits for this event.

Returns:

The active set of vetoes and passes bits for this event

Parameters:

sampler

The prescale/sampling structure

References _EFC::active, _EFC_classes::all, _EFC_sampler::classes, _EFC_samplerPrescaleCounter::countdown, _EFC_samplerClasses::enabled, _EFC_sampler::prescale, _EFC_samplerPrescaleCtx::prescalers, and _EFC_samplerPrescaleCounter::refresh.

Referenced by EFC_filter().

static __inline int if_would_have_been_vetoed	(	int	status,
		const EFC_classes *	enabled
	)			[static]

Return values:

	==0,if	the status indicates the event normally would not have been vetoed
	!=0,if	the status indicates the event normally would have been vetoed

Parameters:

	status	The filter status word
	enabled	The enabled classes (vetoed, passes are all that is important.

This function is called in the case when the active veto mask was set to 0. In this case, a filter will always run to completion and the overall veto bit (the MSB) will be 0 in this case. However, in order to be consistent with other prescale leakage, the state of the overall veto bit must be determined as if the veto mask was its nominal value. This ensures that the status byte (state) of the event is properly recorded as LEAKED or PASSED.

References _EFC_classes::passes, and _EFC_classes::vetoes.

Referenced by EFC_filter().

static __inline unsigned int updateDisabledPasses	(	EFC_sampler *	sampler,
		unsigned int	disabled_passes,
		unsigned int	status
	)			[static]

Updates the list of disabled pass bits.

Returns:

The updated list

Parameters:

	sampler	The sampler
	disabled_passes	The list of currently disabled passes
	status	The status bits

References _EFC_samplerPrescaleCounter::countdown, _EFC_samplerPrescaleCtx::enabled, _EFC_classes::passes, _EFC_sampler::prescale, _EFC_samplerPrescaleCtx::prescalers, and _EFC_samplerPrescaleCounter::refresh.

Referenced by EFC_filter().

int updatePrescaler

(

EFC_samplerPrescaleCounter *

prescaler

)

Updates the prescaler.

Returns:

The current prescale count

Parameters:

prescaler

The prescaler to update

References _EFC_samplerPrescaleCounter::countdown, and _EFC_samplerPrescaleCounter::refresh.

Referenced by EFC_filter().