ESS.c File Reference

Implementation of the Event Simple Selection utility. More...

#include <EDS/ESS.h>
#include <EDS/EDS_fw.h>
#include <EDS/EBF_dir.h>
#include <EDS/EBF_gem.h>
#include <EDS/EBF_gemLocate.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>

Classes
struct	_ESS_ctl
Typedefs
typedef struct _ESS_ctl	ESS_ctl
Enumerations
enum	Options {   OPT_M_PKT = 1 << 0,   OPT_M_SIZE = 1 << 1,   OPT_M_READOUT = 1 << 2,   OPT_M_DGN = 1 << 3,   OPT_M_ERR = 1 << 4,   OPT_M_COND = 1 << 5,   OPT_M_FILTER = ( 1 << 6) - 1 }
	Enumeration of the bit masks indicating which selection criteria are valid. More...
enum	Readout {   RO_M_ZS_SINGLE = 1 << 0,   RO_M_NS_SINGLE = 1 << 1,   RO_M_ZS_FOUR = 1 << 2,   RO_M_NS_FOUR = 1 << 3,   RO_M_SINGLE,   RO_M_FOUR,   RO_M_ZS,   RO_M_NS,   RO_M_ALL }
	Enumeration of the bit masks of which readout modes are allowed. More...
enum	Allow {   ALLOW_M_1 = 1<<0,   ALLOW_M_4 = 1<<1,   ALLOW_M_N = 1<<2,   ALLOW_M_Z = 1<<3,   ALLOW_M_ZN = ALLOW_M_Z | ALLOW_M_N,   ALLOW_M_14 = ALLOW_M_1 | ALLOW_M_4 }
	This enumeration is used only the get_readout parsing routine to make the code more readable. It has no use outside of that routine. More...
Functions
static unsigned int	get_range (const char *s, unsigned int opt, unsigned int *min, unsigned int *max)
	Parses the input string, extracting a range.
int	ESS_sizeof (void)
	Returns the size, in bytes, of the ESS control structure.
void	ESS_construct (ESS_ctl *ess)
	Constructs (initializes) the ESS control structure.
int	ESS_set_logic (ESS_ctl *ess, ESS_logic logic)
	Currently just sets the evaluation condition to the 'AND'.
int	ESS_parse_dgn (ESS_ctl *ess, const char *s)
	Parses the specified input string s, for a diagnostic selection.
int	ESS_parse_err (ESS_ctl *ess, const char *s)
	Parses the specified input string s, for an error selection.
int	ESS_parse_cond (ESS_ctl *ess, const char *s)
	Parses the string for the trigger condition specification.
int	ESS_parse_pkt (ESS_ctl *ess, const char *s)
	Parses the specified input string s, for a packet range.
int	ESS_parse_readout (ESS_ctl *ess, const char *s)
	Parses the input string, extracting a readout mask.
int	ESS_parse_size (ESS_ctl *ess, const char *s)
	Parses the specified input string s, for a packet range.
int	ESS_select (ESS_ctl *ess, const EBF_dir *dir, unsigned int npkts, unsigned int nbytes)
	Evaluates to the filter status.
Variables
const char	ESS_usage_cond []
	String for defining a GEM Pattern Condition specifier. This is meant to be used when reporting the usage of this specifier.
const char	ESS_usage_range []
	String for defining a range specifier. This is meant to be used when reporting the usage of this specifier.

---

Detailed Description

Implementation of the Event Simple Selection utility.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: ESS.c,v 1.5 2011/03/25 22:16:56 russell Exp $

---

Enumeration Type Documentation

enum Allow

This enumeration is used only the get_readout parsing routine to make the code more readable. It has no use outside of that routine.

Enumerator:

ALLOW_M_1	Allow single range readout events
ALLOW_M_4	Allow four range readout events
ALLOW_M_N	Allow nonzero-suppressed events
ALLOW_M_Z	Allow zero-suppressed events
ALLOW_M_ZN	Allow both zero and non-zero suppressed events
ALLOW_M_14	Allow both single and four range readout events

enum Options

Enumeration of the bit masks indicating which selection criteria are valid.

Enumerator:

OPT_M_PKT	Filter on packet count range
OPT_M_SIZE	Filter on minimum event size
OPT_M_READOUT	Filter on readout mode
OPT_M_DGN	Filter on events with diagnostic block
OPT_M_ERR	Filter on events with error block
OPT_M_COND	Filter on trigger conditions
OPT_M_FILTER	All filter bits

enum Readout

Enumeration of the bit masks of which readout modes are allowed.

Consider the 4 possible readout modes (single/four range x zero/non-zero suppressed). The selector works by forming a bit mask of the combinations that are permitted. For example if events with four range readout for either zero or non-zero suppressed data were desired, this bit mask would consist of RO_M_NS_FOUR or'd with RO_M_ZS_FOUR. To make the selection, the readout mode of any given event can be represented by the integers 0-3. Simply shift 1 to the left by this value and AND it with the permitted mask. If non-zero the event is selected.

Enumerator:

RO_M_ZS_SINGLE	Zero-suppress, single range readout
RO_M_NS_SINGLE	Non-zero-suppress, single range readout
RO_M_ZS_FOUR	Zero-suppress, four range readout
RO_M_NS_FOUR	Non-zero-suppress, four range readout
RO_M_SINGLE	Convenience symbol for single, either zero or non-zero-suppress
RO_M_FOUR	Convenience symbol for four, either zero or non-zero-suppress
RO_M_ZS	Convenience symbol for zero-suppress, either single or four range
RO_M_NS	Convenience symbol for non-zero-suppress, either single or four range
RO_M_ALL	Convenience symbol four all possible combinations

---

Function Documentation

void ESS_construct

(

ESS_ctl *

ess

)

Constructs (initializes) the ESS control structure.

Parameters:

ess

The control structure to initialize

References ESS_LOGIC_K_OR.

int ESS_parse_cond	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the string for the trigger condition specification.

Returns:

The trigger condition filter word

Parameters:

	ess	The control structure to fill
	s	The string to parse.

Syntax of the string

A form of a string is <logic_specifier><list of trigger condition specifiers>

List of trigger condition specifiers

The trigger condition specifiers are

• r Region of interest (throttle tracker trigger)
• t 3-in-a-row
• l CAL lo
• h CAL hi
• c CNO
• p Periodic
• s Solicited
• e External

The specifiers may be specified in the positive (must be present) or negative (must be absent) sense. A string of positive specifiers is introduced by a + and a string of negative specifiers is introduced by a -. By default, the initial string starts as a string of positive identifiers.

Logic

If the string begins with

List of trigger condition specifiers

This string to parse comes in in three forms

• :, True if the AND of the condition specifiers and the actual trigger conditions matches the comparison set. This effectively treats the specifiers not mentioned as don't care.
• =, True if the list of the specified trigger conditions and the actual trigger conditions are an exact match. In this case the default comparison set is the complete set.
• otherwise, True if the OR of the specified conditions specifiers and the actual trigger conditions is non-zero. In this case the concept of a comparison set is unnecessary

Limitations

In order to keep the interface simply, arbitrary combinations cannot be specified with the syntax above.

Examples

1. Clh
   Allow any event with either CAL LO or CAL HI present

1. Cl-h
   Allow any event with either CAL LO present or CAL HI absent

1. C:lh
   Allow any event with both CAL LO and CAL HI present

1. C=lh
   Allow any event with only CAL LO and CAL HI present

References OPT_M_COND.

int ESS_parse_dgn	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the specified input string s, for a diagnostic selection.

Returns:

Parsing status, 0 if succesful

Parameters:

	ess	The control structure to fill
	s	The string to parse. If NULL, the diagnostic selection defaults to any contributor

References OPT_M_DGN.

int ESS_parse_err	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the specified input string s, for an error selection.

Returns:

Parsing status, 0 if succesful

Parameters:

	ess	The control structure to fill
	s	The string to parse. If NULL, the error selection defaults to any contributor

References OPT_M_ERR.

int ESS_parse_pkt	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the specified input string s, for a packet range.

Returns:

Parsing status, 0 if succesful

Parameters:

	ess	The control structure to fill, see the documentation for get_range on the allowed syntax of s.
	s	The string to parse

References get_range(), and OPT_M_PKT.

int ESS_parse_readout	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the input string, extracting a readout mask.

Returns:

The readout mask

Parameters:

	ess	The control structure to fill, see the documentation for get_range on the allowed syntax of s.
	s	The input string, consisting of up to 4 characters z permit events with zero-suppression enabled n permit events with zero-suppression disabled 4 permit events in four range readout mode 1 permit events in single range readout mode

If neither z or n are specified, it is as if both are specified If neither 4 or 1 are specified, it is as if both are specified

References ALLOW_M_1, ALLOW_M_4, ALLOW_M_N, ALLOW_M_Z, OPT_M_READOUT, RO_M_ALL, RO_M_FOUR, RO_M_NS, RO_M_NS_FOUR, RO_M_NS_SINGLE, RO_M_SINGLE, RO_M_ZS, RO_M_ZS_FOUR, and RO_M_ZS_SINGLE.

int ESS_parse_size	(	ESS_ctl *	ess,
		const char *	s
	)

Parses the specified input string s, for a packet range.

Returns:

Parsing status, 0 if succesful

Parameters:

	ess	The control structure to fill, see the documentation for get_range on the allowed syntax of s.
	s	The string to parse

References get_range(), and OPT_M_SIZE.

int ESS_select	(	ESS_ctl *	ess,
		const EBF_dir *	dir,
		unsigned int	npkts,
		unsigned int	nbytes
	)

Evaluates to the filter status.

Return values:

	0,does	not pass
	1,passes

Parameters:

	ess	The selection parameters
	dir	The EBF directory structure
	npkts	The number of packets in this event. This is relevant if and only if the OPT_M_PKT selection option is active.
	nbytes	The number of bytes in this event. This is relevant if and only if the OPT_M_SIZE selection option is active.

References _EBF_gem::condsumCno, _EBF_dirRedux::dgn_ids, EBF__gemLocate(), EBF_GEM_DEADCONDCNO_EXTRACT, _EBF_dirRedux::err_ids, ESS_LOGIC_K_OR, _EBF_dir::evt, _EBF_dirRedux::nosup_ids, OPT_M_COND, OPT_M_DGN, OPT_M_ERR, OPT_M_FILTER, OPT_M_PKT, OPT_M_READOUT, OPT_M_SIZE, _EBF_dir::redux, and _EBF_dirRedux::rng_ids.

int ESS_set_logic	(	ESS_ctl *	ess,
		ESS_logic	logic
	)

Currently just sets the evaluation condition to the 'AND'.

Returns:

Parsing status, 0 if succesful

Parameters:

	ess	The control structure to fill
	logic	The string to parse. Currently unused, should be specified as NULL

int ESS_sizeof

(

void

)

Returns the size, in bytes, of the ESS control structure.

Returns:

The size, in bytes, of the ESS control structure.

static unsigned int get_range	(	const char *	s,
		unsigned int	opt,
		unsigned int *	min,
		unsigned int *	max
	)			[static]

Parses the input string, extracting a range.

Returns:

The specified option

Parameters:

	s	The input string. This can be a single number or a pair of numbers A single positive number indicates the value is an inclusive lower limit A single negative number indicates the value is an inclusive upper limit An = followed by a single number indicates precisely that number only. A pair of numbers separated by a comma indicates an inclusive range
	opt	Option used to indicate a minimum was specified
	min	Returned as the minimum value
	max	Returned as the maximum value

Referenced by ESS_parse_pkt(), and ESS_parse_size().

---

Variable Documentation

const char ESS_usage_cond

Initial value:

   "  GEM Trigger Condition Selection Pattern Definition\n"
   "  --------------------------------------------------\n"
   "  A GEM condition selection condition pattern is specified in three ways\n"
   "    -T< specifier set> - Any matching condition passes\n"
   "    -T:<specifier set> - The AND with GEM conditions must match the set\n"
   "    -T=<specifier set> - The specifier set must match exactly\n"
   "\n"
   "  A specifier set consists of the following codes:\n"
   "     r: Region of Interest (throttled tracker trigger\n"
   "     t: 3-in-a-row    l: CAL lo        h: CAL hi       c: CNO\n"
   "     p: Periodic      s: Solicited     e: External\n"
   "\n"
   "  A list specifiers may be specified as required to be present or\n"
   "  required to be absent by prefixing the list with either a '+' or\n"
   "  a '-'. The first string defaults to being reguired to be present.\n"
   "\n"
   "  Examples, assuming T is the option selector:\n"
   "    -Tlt    Select any event with either CAL LO or CAL HI present\n"
   "    -Tl-h   Select any event with either CAL LO present or CAL HI absent\n"
   "    -T:lh   Select any event with both CAL LO and CAL HI present\n"
   "    -T=lh   Select any event with only CAL LO and CAL HI present\n"
   "    -T:r-t  Select any event with a tracker throttle and no 3-in-a-row\n"
   "            Given normal triggering modes, this should be an empty set.\n"
   "    -T:r-lh Select any event with a tracker throttle and no CAL HI and\n"
   "            no CAL LO\n"
   "\n"
   "  Note that the '=' notation is just short hand and that specifying an\n"
   "  absent condition is unnecessary. C=lh is equivalent to C:lh-rtcpse\n"
   "\n"

String for defining a GEM Pattern Condition specifier. This is meant to be used when reporting the usage of this specifier.

const char ESS_usage_range

Initial value:

   "  Range Selection Definition\n"
   "  --------------------------\n"
   "  A range can be specified as\n"
   "     1 A single positive number, indicating an inclusive lower limit\n"
   "     2 A single negative number, indicating an inclusive upper limit\n"
   "     3 An = followed by a single number, indicates precisely that number\n"
   "     4 A pair of numbers separated by a ',' or ':', indicating an \n"
   "       inclusive range\n"
   "\n"
   "  Examples, assuming P is the option selector:\n"
   "    -P2   Select events with >= 2 objects\n"
   "    -P-2  Select events with <= 2 objects\n"
   "    -P2:3 Select events with between 2 and 3 objects\n"
   "    -P=3  Select events with precisely 3 objects\n"
   "    -P3:3 Select events with precisely 3 objects\n"

String for defining a range specifier. This is meant to be used when reporting the usage of this specifier.