GFC.h File Reference

Gamma FilterCode, Interface. More...

#include <EFC/EFC_fate.h>
#include <EDS/EBF_siv.h>

Functions
int	GFC_sizeof (int cnt)
	Sizes the gamma filtering control structure.
int	GFC_cfgSizeof (void)
	Sizes the gamma filtering configuration as it is used in the actual filtering progam.
int	GFC_cfgCompile (GFC_cfg *cfg, const GFC_DB_V3_prms *prms)
	Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.
int	GFC_cfgSchemaCompile (GFC_cfg *cfg, const GFC_DB_V3_schema *schema)
	Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.
int	GFC_resultSizeof (const GFC *gfc)
	Returns the size, in bytes, of one result vector.
GFC_cfg *	GFC_cfgSet (GFC *gfc, GFC_cfg *cfg)
	Makes the specified internal representation of the configuration parameters the current active one.
int	GFC_filter (GFC *gfc, unsigned int pktByte, EBF_pkt *pkt, EBF_siv siv, EDS_fwIxb *ixb, unsigned int vetoes, GFC_result *result)
	Determines the fate of 1 event.
unsigned int	GFC_fwObjects (void)
	Returns a bit mask of the EDS_fw objects used by the gamma filter.
unsigned int	GFC_fwNeeds (void)
	Returns a bit mask of the EDS_fw needs.
const EFC_services *	GFC_servicesGet (void)

---

Detailed Description

Gamma FilterCode, Interface.

Author:

JJRussell - russell@slac.stanford.edu

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

---

Function Documentation

int GFC_cfgCompile	(	GFC_cfg *	cfg,
		const GFC_DB_V3_prms *	prms
	)

Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.

Return values:

	0	Successful
	-1	Unrecognized or non-backwardly compatiable user configuration version number.

Parameters:

	cfg	Filled in with the internal form of the configuration parameters
	prms	The user form of the configuration parameters

References compileCfgPrms(), and _GFC_cfg::prms.

Referenced by GFC_cfgSchemaCompile().

int GFC_cfgSchemaCompile	(	GFC_cfg *	cfg,
		const GFC_DB_V3_schema *	schema
	)

Implements the transformation of the configuration parameters as specified by the user, cfg, into the internal form, ctlCfg.

Return values:

	0	Successful
	-1	Unrecognized or non-backwardly compatiable user configuration version number.

Parameters:

	cfg	Filled in with the internal form of the configuration parameters
	schema	The user form of the configuration schema

References GFC_cfgCompile(), and _GFC_cfg::prms.

const GFC_cfg * GFC_cfgSet	(	GFC *	gfc,
		GFC_cfg *	cfg
	)

Makes the specified internal representation of the configuration parameters the current active one.

Returns:

Pointer to the current control configuration parameters

Parameters:

	gfc	The gamma filter control structure
	cfg	The internal representation of the configuration constants

References _GFC::cfg.

int GFC_cfgSizeof

(

void

)

Sizes the gamma filtering configuration as it is used in the actual filtering progam.

Returns:

Returns the size of the gamma filtering configuration control structure

There are two different breeds of the filtering configuration structure. There are two reasons for this. The more familar is the configuration structure that the user fills in. This structure is meant to be convenient for the user, but not for the program. Some of the information in the user structure is transformed into data that the program will find more accessible.

The second reason is that by having a user configuration and an internal configuration, the two can evolve separately. If more parameters are added to the filter, they will find a home in the internal structure. At some time they may be exposed to the user. The correct course of action is to define a new version of the user configuration block. Since the version number is carried along with the configuration constants, the routine transforming the user configuration to its internal representation can evolve and can be made to handle older versions of the user configuration parameters with some degree of grace, at least giving some hope to backward compatibility.

The correct usage model is

       ctlCfg = malloc (GFC_cfgSizeof ());
       status = GFC_cfgCompile (cfg, usrPrms);
       GFC_cfgSet (gfc, cfg);

Note:

Because the 'set routine just seeds a pointer to the user configuration, in the control structure. the user is free to swap it out with any other pre-prepared configuration.

int GFC_filter	(	GFC *	gfc,
		unsigned int	pktBytes,
		EBF_pkt *	pkt,
		EBF_siv	siv,
		EDS_fwIxb *	ixb,
		unsigned int	vetoes,
		GFC_result *	result
	)

Determines the fate of 1 event.

Return values:

	<	0, rejected
	==0,undecided
	>	0, accepted

Parameters:

	gfc	The gamma filter control structure
	pktBytes	The number of bytes in pkt, includes the packet header
	pkt	The event data packet
	siv	The packet's state information vector
	ixb	The information exchange block
	vetoes	The active vetoes
	result	The filter result vector

Overview

This acts as a wrapper of the actual filter. This is were the sampling logic is implemented by the use prescalers. A prescaler is defined by a pair of integers; one giving the current countdown value and the other giving the refresh value. When the countdown value reaches 0, the prescaler is said to expire.

Types of prescaling

There are two kinds of samplings allow.

1. Pass-thru sampling
2. Individual veto sampling

Pass-Thru Sampling

Conceptually this is the easiest to understand. When the pass-thru prescaler expires, instead of using the normal veto mask, a 0 is used, effectively causing the filter to evaluate all its cuts but not allowing an cut to veto the event. While easy to understand, the event sample leaked through by this technique will be dominated by events that would normally have been rejected by the very early cuts.

Individual Veto Sampling

This prescaler type allows to ignore the reject decision of each veto bit. While a bit harder to understand than the Pass-Thru Sampling, this technique allows one to tap a predetermined percentage of events failing at each cut. The hope is that one will be a statisitically meaningful sample of events that would have normally failed some of the later cuts in the filter.

References gammaFilter().

unsigned int GFC_fwNeeds

(

void

)

Returns a bit mask of the EDS_fw needs.

Returns:

A bit mask of the EDS_fw needs

Use

This value should be passed to EDS_fwRegister when registering the filter.

Referenced by gfc_construct().

unsigned int GFC_fwObjects

(

void

)

Returns a bit mask of the EDS_fw objects used by the gamma filter.

Returns:

A bit mask of the EDS_fw needs

Use

This value should be passed to EDS_fwRegister when registering the filter.

References EFC_EDS_FW_OBJ_M_TFC_PRJS.

Referenced by gfc_construct().

int GFC_resultSizeof

(

const GFC *

gfc

)

Returns the size, in bytes, of one result vector.

Return values:

The

size, in bytes, of one result vector

Parameters:

gfc

The configuration control structure

int GFC_sizeof

(

int

cnt

)

Sizes the gamma filtering control structure.

Returns:

Returns the size of the gamma filtering control structure

Parameters:

cnt

Number of configurations to accommodate