GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> EDS / V2-12-1 > eds / rhel6-32

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » PHY » source » EDS » V2-12-1 » src

EDS_fw.c File Reference

Provides a framework so that multiple event processing routines can efficiently share global work. More...

#include <EDS/EDR_errUnpack.h>
#include <EDS/EDR_acdUnpack.h>
#include <EDS/EDR_calUnpack.h>
#include <EDS/EDR_tkrUnpack.h>
#include <EDS/EDR_err.h>
#include <EDS/EDR_acd.h>
#include <EDS/EDR_cal.h>
#include <EDS/EDR_tkr.h>
#include <EDS/ECR_acd.h>
#include <EDS/ECR_cal.h>
#include <EDS/EBF_evt.h>
#include <EDS/EBF_dir.h>
#include <EDS/EBF_edw.h>
#include <EDS/EBF_siv.h>
#include <EDS/LCBV.h>
#include <EDS/EDS_fw.h>
#include <EDS_fwPvt.h>
#include <PBI/FFS.ih>
#include <string.h>
#include <stdlib.h>

Classes

struct  _EDS_fwIxbObjAddDef
 Defines an object to add to the EDS_fwIxb table. More...

Defines

#define DEF(_id, _size, _constructor, _destructor, _reset)
 Macro to initialize an EDS_fwIxbObjAddDef structure.

Typedefs

typedef struct _EDS_fwIxbObjAddDef EDS_fwIxbObjAddDef
 Typedef for struct _EDS_fwIxbObjAddDef.

Functions

static int initIxbObjTbl (EDS_fwIxbObjTbl *tbl)
 Initializes the reserved portion of the Information Exchange Block's object table.
static int addIxbObj (EDS_fwIxbObjTbl *tbl, int object, int size, EDS_fwIxbObjConstructor construct, EDS_fwIxbObjDestructor destruct, EDS_fwIxbObjReset reset)
 Adds an object to the Information Exchange Block.
static unsigned int allocateIxb (EDS_fwIxb *ixb, EDS_fwIxbObjTbl *tbl, EDS_fwMem *mem, unsigned int objects)
 Allocates and initializes the unpacking buffers.
static unsigned int deallocateIxb (EDS_fwIxb *ixb, EDS_fwIxbObjTbl *tbl, EDS_fwMem *mem)
 DeAllocates the data structures in the Information Exchange Block.
static unsigned int destroyHandlers (unsigned int list, EDS_fwHandler *handlers)
 Destroys all the handlers in list.
static void * memDefaultNew (void *prm, unsigned int nbytes)
 Default memory allocator.
static void memDefaultDelete (void *prm, void *ptr, unsigned int nbytes)
 Default memory deallocator.
static __inline unsigned int needs_refresh (const unsigned int *needs, unsigned int active)
 Recalculates the list of needs based on the active list.
unsigned int EDS_fwHandlerChange (EDS_fw *fw, unsigned int targets, unsigned int newState)
 Changes the enabled/disabled state of the select targets.
unsigned int EDS_fwDestruct (EDS_fw *fw)
 Destroys the EDS framework by unregistering all the registered handlers and destroying all objects.
unsigned int EDS_fwHandlerFlush (EDS_fw *fw, unsigned int targets, int reason)
 This flushes the output of the specified list of handlers.
unsigned int EDS_fwHandlerAssociate (EDS_fw *fw, unsigned int targets, unsigned int mode, unsigned int configuration)
 Associates a configuration with a mode.
unsigned int EDS_fwHandlerStart (EDS_fw *fw, unsigned int targets, int reason, unsigned int run_id, unsigned int startTime, unsigned int mode)
 Informs the specified list of handlers of the start of a run.
unsigned int EDS_fwHandlerSelect (EDS_fw *fw, unsigned int targets, unsigned int mode)
 Selects a new mode.
void EDS_fwConstruct (EDS_fw *fw, EDS_fwMemNew memNew, EDS_fwMemDelete memDelete, void *memPrm)
 Initializes the specified EDS_fw structure.
void EDS_fwConstruct1 (EDS_fw *fw, EDS_fwMemNew memNew, EDS_fwMemDelete memDelete, void *memPrm, unsigned int origin, unsigned int cpu, unsigned int apidOffset)
 Initializes the specified EDS_fw structure. This is an expanded version of the construct that includes the data producer (origin) and the data processor (cpu).
void EDS_fwFreeSet (EDS_fw *fw, LCBV_pktsRngFreeCb pktsFreeRtn, void *pktsFreePrm)
 Sets the packet freeing routine.
int EDS_fwPostRegister (EDS_fw *fw, unsigned int idx, EDS_fwPostStartRtn start, EDS_fwPostWriteRtn write, EDS_fwPostNotifyRtn notify, EDS_fwPostFlushRtn flush, void *prm)
 Initializes the specified EDS_fw posting stream.
int EDS_fwPostServicesRegister (EDS_fw *fw, unsigned int idx, const EDS_fwPostServices *services, void *prm)
 Initializes the specified EDS_fw posting stream.
unsigned int EDS_fwPostChange (EDS_fw *fw, unsigned int list, unsigned int newState)
 Changes the state of the enable/disable post list.
unsigned int EDS_fwPostResume (EDS_fw *fw, unsigned int list, int reason)
 Resumes after a pause.
unsigned int EDS_fwPostStart (EDS_fw *fw, unsigned int list, int reason, unsigned int run_id, unsigned int startTime, unsigned int mode, unsigned int hw_key, unsigned int cfg_key)
 Sets the parameters associated with a new run.
unsigned int EDS_fwPostFlush (EDS_fw *fw, unsigned int list, int reason)
 Selects a new mode.
unsigned int EDS_fwPostNotify (EDS_fw *fw, unsigned int list, unsigned int mode)
 Notifies the list of post routines of a change in the configuraion.
int EDS_fwHandlerRegisterX1 (EDS_fw *fw, int priority, unsigned int objects, unsigned int needs, unsigned int result_size, EDS_fwHandlerProcessRtn process, EDS_fwHandlerAssociateRtn associate, EDS_fwHandlerStartRtn start, EDS_fwHandlerSelectRtn select, EDS_fwHandlerFlushRtn flush, EDS_fwHandlerDestructRtn destruct, void *prm)
 Routine to register a packet handler.
int EDS_fwHandlerServicesRegisterX1 (EDS_fw *fw, int priority, const EDS_fwHandlerServicesX1 *services, void *prm)
 Routine to register a packet handler using a service vector.
int EDS_fwHandlerRegister (EDS_fw *fw, int priority, unsigned int objects, unsigned int needs, unsigned int result_size, EDS_fwHandlerProcessRtn process, EDS_fwHandlerAssociateRtn associate, EDS_fwHandlerSelectRtn select, EDS_fwHandlerFlushRtn flush, EDS_fwHandlerDestructRtn destruct, void *prm)
 Routine to register a packet handler.
int EDS_fwHandlerServicesRegister (EDS_fw *fw, int priority, const EDS_fwHandlerServices *services, void *prm)
 Routine to register a packet handler using a service vector.
int EDS_fwHandlerProcess (EDS_fw *fw, unsigned int edw, EBF_pkt *pkt)
 This is the LCB event callback handler.
int EDS_fwHandlerUnregister (EDS_fw *fw, int priority)
 Routine to unregister a packet processor.
int EDS_fwEvtQueSet (EDS_fw *fw, unsigned int que_id, FORK_que *que)
 Sets the FORK queues that feed the event delivery task. This is used to send synchronized messages to the event delivery task.
FORK_que * EDS_fwEvtQueGet (EDS_fw *fw, unsigned int que_id)
 Returns a poitner to the FORK queues that feed the event delivery task. This is used to send synchronized messages to the event delivery task.
int EDS_fwSizeof ()
 Returns the size, in bytes, of and EDS_fw control structure.
int EDS_fwIxbObjAdd (EDS_fw *fw, int object, int size, EDS_fwIxbObjConstructor construct, EDS_fwIxbObjDestructor destruct, EDS_fwIxbObjReset reset)
 Adds an object to the Information Exchange Block.
unsigned int EDS_fwIxbObjAllocate (EDS_fw *fw, unsigned int objects)
 Allocates any previously added (known) objects.
EDS_fwIxb * EDS_fwIxbLocate (EDS_fw *fw)
 Locates the EDS_fwIxb structure.

Detailed Description

Provides a framework so that multiple event processing routines can efficiently share global work.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: EDS_fw.c,v 1.21 2011/03/25 22:16:56 russell Exp $

Define Documentation

#define DEF ( _id,
_size,
_constructor,
_destructor,
_reset   ) 

Value:

{    EDS_FW_OBJ_K_ ## _id,                                         \
           _size,                                                         \
           (EDS_fwIxbObjConstructor)_constructor,                         \
           (EDS_fwIxbObjDestructor )_destructor,                          \
           (EDS_fwIxbObjReset      )_reset                                \
       }
Macro to initialize an EDS_fwIxbObjAddDef structure.

This is purely for convenience, to save typing, avoiding all the necessary but nasty casts and it does make the code more readable.

Referenced by initIxbObjTbl().

Typedef Documentation

EDS_fwIxbObjAddDef

Typedef for struct _EDS_fwIxbObjAddDef.

This is a convenience structure so that the default objects to be installed in each EDS framework can be specified in table fashion

Function Documentation

static int addIxbObj ( EDS_fwIxbObjTbl *  tbl,
int  object,
int  size,
EDS_fwIxbObjConstructor  construct,
EDS_fwIxbObjDestructor  destruct,
EDS_fwIxbObjReset  reset 
) [static]

Adds an object to the Information Exchange Block.

Return values:
0,success 
If negative, failure
Parameters:
tbl The table to add to
object The index of the object to add
size The size, in bytes, of the object
construct The constructor routine (if any)
destruct The destructor routine (if any)
reset The reset routine (if any)

References _EDS_fwIxbObjDsc::construct, _EDS_fwIxbObjDsc::destruct, _EDS_fwIxbObjTbl::dscs, EDS_FW_MASK, _EDS_fwIxbObjTbl::objects, _EDS_fwIxbObjDsc::reset, and _EDS_fwIxbObjDsc::size.

Referenced by EDS_fwIxbObjAdd(), and initIxbObjTbl().

static unsigned int allocateIxb ( EDS_fwIxb *  ixb,
EDS_fwIxbObjTbl *  tbl,
EDS_fwMem *  mem,
unsigned int  objects 
) [static]

Allocates and initializes the unpacking buffers.

Returns:
Status
Parameters:
ixb The framework's Information Exchange Block
tbl The object table
mem The memory manager
objects Which objects to unpack

References _EDS_fwIxb::blk, _EDS_fwIxbObjDsc::construct, _EDS_fwMem::delete, _EDS_fwIxbObjTbl::dscs, _EDS_fwMem::new, _EDS_fwIxb::objects, _EDS_fwIxbObjTbl::objects, _EDS_fwMem::prm, _EDS_fwIxbBlk::ptrs, _EDS_fwIxbObjDsc::reset, _EDS_fwIxbObjTbl::resettable, and _EDS_fwIxbObjDsc::size.

Referenced by EDS_fwHandlerRegisterX1(), and EDS_fwIxbObjAllocate().

static unsigned int deallocateIxb ( EDS_fwIxb *  ixb,
EDS_fwIxbObjTbl *  tbl,
EDS_fwMem *  mem 
) [static]

DeAllocates the data structures in the Information Exchange Block.

Returns:
A bit mask of those objects that returned a non-zero status from their destructor
Parameters:
ixb The information exchange block
tbl The object management table
mem The memory manager

References _EDS_fwIxb::blk, _EDS_fwMem::delete, _EDS_fwIxbObjDsc::destruct, _EDS_fwIxbObjTbl::dscs, _EDS_fwIxbObjTbl::objects, _EDS_fwIxb::objects, _EDS_fwMem::prm, _EDS_fwIxbBlk::ptrs, and _EDS_fwIxbObjDsc::size.

Referenced by EDS_fwDestruct().

static unsigned int destroyHandlers ( unsigned int  list,
EDS_fwHandler *  handlers 
) [static]

Destroys all the handlers in list.

Returns:
A bit mask of those handlers which returned a non-zero status from their destructor
Parameters:
list The list of handlers to destroy
handlers The array of handlers

References _EDS_fwHandlerRegisteredServices::destruct, _EDS_fwHandler::prm, and _EDS_fwHandler::services.

Referenced by EDS_fwDestruct().

void EDS_fwConstruct ( EDS_fw *  fw,
EDS_fwMemNew  memNew,
EDS_fwMemDelete  memDelete,
void *  memPrm 
)

Initializes the specified EDS_fw structure.

Parameters:
fw The EDS_fw structure to initialize
memNew Memory allocator
memDelete Memory deallocator
memPrm Memory context handle

References EDS_fwConstruct1().

void EDS_fwConstruct1 ( EDS_fw *  fw,
EDS_fwMemNew  memNew,
EDS_fwMemDelete  memDelete,
void *  memPrm,
unsigned int  origin,
unsigned int  cpu,
unsigned int  apidOffset 
)

Initializes the specified EDS_fw structure. This is an expanded version of the construct that includes the data producer (origin) and the data processor (cpu).

Parameters:
fw The EDS_fw structure to initialize
memNew Memory allocator
memDelete Memory deallocator
memPrm Memory context handle
origin The data production origin. This is typically a small integer describing the entity (for example the LAT, the GLEAM Monte Carlo program) that produced the data. The value -1 is reserved for an unknown.producer.
cpu The cpu identifier. This is typically a small integer describing the CPU that processed the data. -1 is reserved for an unspecified CPU.
apidOffset An offset (0-4) that is added to an APID base value in order to create a CPU unique APID.

References _EDS_fwIxbDst::apid_offset, _EDS_fwIxbSrc::cpu, _EDS_fwMem::delete, _EDS_fwIxb::dst, EBF_sivInit(), _EDS_fwLists::free, initIxbObjTbl(), _EDS_fw::ixb, _EDS_fw::lists, _EDS_fw::mem, memDefaultDelete(), memDefaultNew(), _EDS_fwMem::new, _EDS_fwIxbSrc::origin, _EDS_fwMem::prm, _EDS_fw::siv, _EDS_fwIxb::src, and _EDS_fw::tbl.

Referenced by EDS_fwConstruct().

unsigned int EDS_fwDestruct ( EDS_fw *  fw  ) 

Destroys the EDS framework by unregistering all the registered handlers and destroying all objects.

Returns:
The OR of the bit mask of objects or handlers that failed being destroyed (this is not real useful in programming, but could be useful in helping debug.
Parameters:
fw The framework to destroy

References deallocateIxb(), destroyHandlers(), _EDS_fwLists::free, _EDS_fw::handlers, _EDS_fw::ixb, _EDS_fw::lists, _EDS_fw::mem, and _EDS_fw::tbl.

FORK_que * EDS_fwEvtQueGet ( EDS_fw *  fw,
unsigned int  que_id 
)

Returns a poitner to the FORK queues that feed the event delivery task. This is used to send synchronized messages to the event delivery task.

Return values:
!= NULL, The fork que
== NULL, Either the FORK_que requested FORK que has not been set or que_id is out-of-range (0-31)
Parameters:
fw The EDS framework structure
que_id The que id, 0-31, see the enum EDS_FW_EVTQUE_K for the symbolic names of these queues.

References _EDS_fwSynchCtx::ques, and _EDS_fw::synch.

int EDS_fwEvtQueSet ( EDS_fw *  fw,
unsigned int  que_id,
FORK_que *  que 
)

Sets the FORK queues that feed the event delivery task. This is used to send synchronized messages to the event delivery task.

Return values:
0,Success 
-1,Failure,\a que_id is out-of-range (0-31)
Parameters:
fw The EDS framework structure
que_id The que id, 0-31, see the enum EDS_FW_EVTQUE_K for the symbolic names of these queues.
que The FORK que

References _EDS_fwSynchCtx::ques, and _EDS_fw::synch.

void EDS_fwFreeSet ( EDS_fw *  fw,
LCBV_pktsRngFreeCb  pktsFreeRtn,
void *  pktsFreePrm 
)

Sets the packet freeing routine.

Parameters:
fw The EDS_fw structure to initialize
pktsFreeRtn Routine to free the packet
pktsFreePrm Parameter to the free routine.

References _EDS_fw::free, _EDS_fwPktFree::prm, and _EDS_fwPktFree::rtn.

unsigned int EDS_fwHandlerAssociate ( EDS_fw *  fw,
unsigned int  targets,
unsigned int  mode,
unsigned int  configuration 
)

Associates a configuration with a mode.

Returns:
A bit map of those handlers reporting failure
Parameters:
fw The EDS_fw structure
targets The target list, specified as a bit mask, of those handlers to set the new mode in
mode The mode, passed through to the user's associate routine.
configuration The index of the configuration to associate with the specified mode, passed through to the user's associate routine.

References _EDS_fwHandlerRegisteredServices::associate, _EDS_fwLists::associate, EDS_FW_MASK, _EDS_fw::handlers, _EDS_fw::lists, _EDS_fwHandler::prm, and _EDS_fwHandler::services.

unsigned int EDS_fwHandlerChange ( EDS_fw *  fw,
unsigned int  targets,
unsigned int  newState 
)

Changes the enabled/disabled state of the select targets.

Returns:
The set of previous enabled targets
Parameters:
fw The framework handle
targets A bit mask of the targets.
newState A bit mask of the new state (0 = disable, 1 = enabled))
This operation changes the state of only the handler targets selected by a 1 bit in the target mask, targets. The state is changed to either enabled or disabled depending on whether the corresponding bit in new is clear (DISABLED) or set (ENABLED). This operation is done under a lock so that it is indivisible.

References _EDS_fwLists::enabled, _EDS_fwLists::free, _EDS_fwFateNeeds::handlers, _EDS_cfgInfo::key, _EDS_fw::lists, _EDS_fw::needs, needs_refresh(), and _EDS_fwFateNeeds::permanent.

Referenced by EDS_fwHandlerUnregister().

unsigned int EDS_fwHandlerFlush ( EDS_fw *  fw,
unsigned int  targets,
int  reason 
)

This flushes the output of the specified list of handlers.

Returns:
A bit map of those handlers reporting failure
Parameters:
fw The EDS_fw structure
targets The target list, specified as a bit mask, of those handlers to flush
reason The reason flush is being called. This is just passed through to the user's flush routine

References EDS_FW_MASK, _EDS_fwHandlerRegisteredServices::flush, _EDS_fwLists::flush, _EDS_fw::handlers, _EDS_fw::lists, _EDS_fwHandler::prm, and _EDS_fwHandler::services.

int EDS_fwHandlerProcess ( EDS_fw *  fw,
unsigned int  edw,
EBF_pkt *  pkt 
)

This is the LCB event callback handler.

Returns:
The fate of the event
Parameters:
fw The control structure
edw The Event Descriptor Word
pkt The packet to process
What's going on here
While there is not much code here, the logic is involved. The complications are mainly due to packetization and the desire to avoid doing certain operations, such as forming a directory, for as long as possible.
Each register callback has determined whether, by default, it wishes to be called back on
  • The first packet in a list
  • The middle packets of a list
  • The last packets of a list

Static vs Dynamic Properties
This default can be altered by the callback routine returning the code EDS_FW_FN_M_NO_MORE, at anytime (well except on the last packet where it makes no logical sense). The control structure also contains a default setting for the global resources needed. While a callback routine can add to this set, currently it cannot subtract from this set. If the routine involves any dynamics, it is best to not declare the need for these resources during registration, but, rather to request them in the return code.
A good example is the standard filter. For a large fraction of the events, the filter can make its decision using only the GEM contribution. For the remainder it needs a directory to help decode the event. Therefore, it should not state that it needs a directory to do its work when registering. Rather, on the first packet it should state whether it needs a directory or not. If it does, one will be formed and on the last packet in the sequence it will be passed in. Thus, during registration, the filter would request
  • Call me on the first packet of the event
  • Call me on the last packet of the list
    If the event is rejected on the first callback, then it should return the EDS_FW_FN_NO_MORE code. If the event is accepted on the first callback, it should request EDS_FW_FN_M_DIR.

References _EDS_fwLists::active, _EDS_fwFateNeeds::active, _EDS_fwIxb::blk, _EDS_fwEvt::dir, _EDS_fwIxbObjTbl::dscs, EBF__edwPktSize(), EBF__evtSequence(), EBF__pktAdvance(), EBF__sivIsFirst(), EBF__sivIsLast(), EBF__sivIsLastSeq(), EBF__sivIsOnly(), EBF_dirCompose(), EBF_sivUpdate(), EDS_FW_FN_V_POST, EDS_FW_K_POST_CNT, EDS_FW_OBJ_M_DIR, _EDS_fwPostCtl::enabled, _EDS_fwLists::enabled, _EDS_fwIxbBlk::evt, _EDS_fwIxbInfo::evt, _EDS_fw::free, _EDS_fw::handlers, _EDS_fwIxb::info, _EDS_fw::ixb, LCBV_PKT_FATE_M_ABORT, LCBV_PKT_FATE_M_NO_FREE, _EDS_fw::lists, _EDS_fw::needs, _EDS_fwIxbInfo::npkts, _EDS_fwFateNeeds::permanent, _EDS_fwLists::phases, _EDS_fwPktFree::pkt, _EDS_fw::post, _EDS_fwPostCtl::posters, _EDS_fwPktFree::prm, _EDS_fwPoster::prm, _EDS_fwHandler::prm, _EDS_fwHandlerRegisteredServices::process, _EDS_fwIxbBlk::ptrs, _EDS_fwIxbObjDsc::reset, _EDS_fwIxbObjTbl::resettable, _EDS_fwPktFree::rtn, _EDS_fwPoster::service, _EDS_fwHandler::services, _EDS_fw::siv, _EDS_fwIxbInfo::size, _EDS_fw::tbl, _EDS_fwIxb::valid, _EDS_fwPostServices::write, _EDS_fwIxbInfo::xcount, and _EDS_fwIxbInfo::xsequence.

int EDS_fwHandlerRegister ( EDS_fw *  fw,
int  priority,
unsigned int  objects,
unsigned int  needs,
unsigned int  result_size,
EDS_fwHandlerProcessRtn  process,
EDS_fwHandlerAssociateRtn  associate,
EDS_fwHandlerSelectRtn  select,
EDS_fwHandlerFlushRtn  flush,
EDS_fwHandlerDestructRtn  destruct,
void *  prm 
)

Routine to register a packet handler.

Returns:
The priority of the handler registered or -1 on failure
Parameters:
fw The framework's control structure
priority The requested priority of the handler. If this is specified as
  • 0-31, then this absolute priority will be used, if it is available. While there is no restriction on this number, other than it is between 0-31, the priorities 0-7 are set aside as dedicated to absolute priorities
  • -1, then the priority will be allocated as the highest available priority.
objects A bit list of the event objects (ACD unpack structure DIR structure, see EDS_FW_OBJ_M) that this processor needs. If this resource has not yet been allocated by a previous processor, then this call will allocate them. Note that this routine treats this request exactly as is. That is, it does not decide that because one has requested the TKR to be unpacked, that this implies one needs a directory structure. If the caller wishes to have a resource allocated on his behalf, the user must specify it.
needs This is from the list EDS_FW_FN_M. It includes the these important pieces
  • EDS_FW_FN_M_FIRST, need to be called back on the first packet of an event. This call back will not have a directory structure filled, since this cannot be completed until the last packet has been seen
  • EDS_FW_FN_M_MID, need to be called back for the middle packets of a sequence. While this is rare, some testing programs use this feature. In the case of only one packet in the event, there is no middle packet.
  • EDS_FW_FN_M_LAST, need to be called back on the last packet of an event. This callback may have the directory information filled, but, unless this processor has explicitly requested it, it should not count on it.
  • EDS_FW_FN_M_POST_x, this processor needs to have the posting routine(s) called. This is also rare, since this value is usually dynamically specified.(x = [0, EDS_FW_K_POST_CNT)
  • EDS_FW_FN_M_DIR, this processor needs a directory to do its work. The directory is not completed until the last packet of a sequence has been seen. In the case that an event consists of one and only on packet, the processor may get called back twice, once if he has specified EDS_FW_FN_M_FIRST and the second if he has specified EDS_FW_FN_M_LAST. Typically if a user always needs a directory he would specify EDS_FW_FN_M_DIR and EDS_FW_FN_M_LAST.
result_size Size, in bytes, of the handler's result. An area of this size will be reserved in the Ixb.
prm Arbitrary user parameter passed to the processor and destructor
process The packet processing routine
associate Routine to associate a configuration with a mode
select Routine to selects the mode
flush The packet handler's flush routine
destruct The handler's destructor. This is called on during framework deletion and unregisteration
Warning:
This is an obsolete routine

References EDS_fwHandlerRegisterX1().

int EDS_fwHandlerRegisterX1 ( EDS_fw *  fw,
int  priority,
unsigned int  objects,
unsigned int  needs,
unsigned int  result_size,
EDS_fwHandlerProcessRtn  process,
EDS_fwHandlerAssociateRtn  associate,
EDS_fwHandlerStartRtn  start,
EDS_fwHandlerSelectRtn  select,
EDS_fwHandlerFlushRtn  flush,
EDS_fwHandlerDestructRtn  destruct,
void *  prm 
)

Routine to register a packet handler.

Returns:
The priority of the handler registered or -1 on failure
Parameters:
fw The framework's control structure
priority The requested priority of the handler. If this is specified as
  • 0-31, then this absolute priority will be used, if it is available. While there is no restriction on this number, other than it is between 0-31, the priorities 0-7 are set aside as dedicated to absolute priorities
  • -1, then the priority will be allocated as the highest available priority.
objects A bit list of the event objects (ACD unpack structure DIR structure, see EDS_FW_OBJ_M) that this processor needs. If this resource has not yet been allocated by a previous processor, then this call will allocate them. Note that this routine treats this request exactly as is. That is, it does not decide that because one has requested the TKR to be unpacked, that this implies one needs a directory structure. If the caller wishes to have a resource allocated on his behalf, the user must specify it.
needs This is from the list EDS_FW_FN_M. It includes the these important pieces
  • EDS_FW_FN_M_FIRST, need to be called back on the first packet of an event. This call back will not have a directory structure filled, since this cannot be completed until the last packet has been seen
  • EDS_FW_FN_M_MID, need to be called back for the middle packets of a sequence. While this is rare, some testing programs use this feature. In the case of only one packet in the event, there is no middle packet.
  • EDS_FW_FN_M_LAST, need to be called back on the last packet of an event. This callback may have the directory information filled, but, unless this processor has explicitly requested it, it should not count on it.
  • EDS_FW_FN_M_POST_x, this processor needs to have the posting routine(s) called. This is also rare, since this value is usually dynamically specified.(x = [0, EDS_FW_K_POST_CNT)
  • EDS_FW_FN_M_DIR, this processor needs a directory to do its work. The directory is not completed until the last packet of a sequence has been seen. In the case that an event consists of one and only on packet, the processor may get called back twice, once if he has specified EDS_FW_FN_M_FIRST and the second if he has specified EDS_FW_FN_M_LAST. Typically if a user always needs a directory he would specify EDS_FW_FN_M_DIR and EDS_FW_FN_M_LAST.
result_size Size, in bytes, of the handler's result. An area of this size will be reserved in the Ixb.
prm Arbitrary user parameter passed to the processor and destructor
process The packet processing routine
associate Routine to associate a configuration with a mode
start Routine to handle a start run
select Routine to selects the mode
flush The packet handler's flush routine
destruct The handler's destructor. This is called on during framework deletion and unregisteration

References allocateIxb(), _EDS_fwHandlerRegisteredServices::associate, _EDS_fwLists::associate, _EDS_fw::cfg, _EDS_fwHandlerRegisteredServices::destruct, _EDS_rsdTbl::dscs, EDS_CFG_TYPE_K_UNKNOWN, EDS_FW_MASK, _EDS_fwHandlerRegisteredServices::flush, _EDS_fwLists::flush, _EDS_fwLists::free, _EDS_fwFateNeeds::handlers, _EDS_fw::handlers, _EDS_rsdDsc::id, _EDS_fwHandlerCfgs::infos, _EDS_fw::ixb, _EDS_cfgInfo::key, _EDS_rsdDsc::len, _EDS_fw::lists, _EDS_fw::mem, _EDS_fw::needs, _EDS_fwHandler::needs, _EDS_fwMem::new, _EDS_fwHandler::objects, _EDS_fwLists::phases, _EDS_fwMem::prm, _EDS_fwHandler::prm, _EDS_fwHandlerRegisteredServices::process, _EDS_rsdDsc::ptr, _EDS_fwIxb::rsd, _EDS_rsdDsc::sb, _EDS_fwHandlerRegisteredServices::select, _EDS_fwLists::select, _EDS_fwHandler::services, _EDS_fwHandlerRegisteredServices::start, _EDS_fwLists::start, _EDS_fw::tbl, _EDS_cfgInfo::type, and _EDS_rsdTbl::valid.

Referenced by EDS_fwHandlerRegister(), EDS_fwHandlerServicesRegister(), and EDS_fwHandlerServicesRegisterX1().

unsigned int EDS_fwHandlerSelect ( EDS_fw *  fw,
unsigned int  targets,
unsigned int  mode 
)

Selects a new mode.

Returns:
A bit map of those handlers reporting failure
Parameters:
fw The EDS_fw structure
targets The target list, specified as a bit mask, of those handlers to set the new mode in
mode The new mode, passed through to the user's set routine

References _EDS_fw::cfg, _EDS_fw::handlers, _EDS_fwHandlerCfgs::infos, _EDS_fw::lists, _EDS_fwHandler::prm, _EDS_fwHandlerRegisteredServices::select, _EDS_fwLists::select, and _EDS_fwHandler::services.

int EDS_fwHandlerServicesRegister ( EDS_fw *  fw,
int  priority,
const EDS_fwHandlerServices *  services,
void *  prm 
)

Routine to register a packet handler using a service vector.

Returns:
The priority of the handler registered or -1 on failure
Parameters:
fw The framework's control structure
priority The requested priority of the handler. If this is specified as
  • 0-31, then this absolute priority will be used, if it is available. While there is no restriction on this number, other than it is between 0-31, the priorities 0-7 are set aside as dedicated to absolute priorities
  • -1, then the priority will be allocated as the highest available priority.
services The services structure
prm Arbitrary user parameter passed to the processor and destructor
Warning:
This is an obsolete routine

References _EDS_fwHandlerServices::associate, _EDS_fwHandlerServices::destruct, EDS_fwHandlerRegisterX1(), _EDS_fwHandlerServices::flush, _EDS_fwHandlerServices::needs, _EDS_fwHandlerServices::objects, _EDS_fwHandlerServices::process, _EDS_fwHandlerServices::rsizeof, and _EDS_fwHandlerServices::select.

int EDS_fwHandlerServicesRegisterX1 ( EDS_fw *  fw,
int  priority,
const EDS_fwHandlerServicesX1 *  services,
void *  prm 
)

Routine to register a packet handler using a service vector.

Returns:
The priority of the handler registered or -1 on failure
Parameters:
fw The framework's control structure
priority The requested priority of the handler. If this is specified as
  • 0-31, then this absolute priority will be used, if it is available. While there is no restriction on this number, other than it is between 0-31, the priorities 0-7 are set aside as dedicated to absolute priorities
  • -1, then the priority will be allocated as the highest available priority.
services The services structure
prm Arbitrary user parameter passed to the processor and destructor

References _EDS_fwHandlerServicesX1::associate, _EDS_fwHandlerServicesX1::destruct, EDS_fwHandlerRegisterX1(), _EDS_fwHandlerServicesX1::flush, _EDS_fwHandlerServicesX1::needs, _EDS_fwHandlerServicesX1::objects, _EDS_fwHandlerServicesX1::process, _EDS_fwHandlerServicesX1::rsizeof, _EDS_fwHandlerServicesX1::select, and _EDS_fwHandlerServicesX1::start.

unsigned int EDS_fwHandlerStart ( EDS_fw *  fw,
unsigned int  targets,
int  reason,
unsigned int  run_id,
unsigned int  startTime,
unsigned int  mode 
)

Informs the specified list of handlers of the start of a run.

Returns:
A bit map of those handlers reporting failure
Parameters:
fw The EDS_fw structure
targets The target list, specified as a bit mask, of those handlers to send the start run to
reason Suggested use is to indicate why the run is being started
run_id Suggested use is to identify the block of events between when EDS_fwHandlerStart is called and EDS_fwHandlerFlush is called with a stop reason
startTime The run start time rounded to the nearest second
mode This must be the previously selected, by EDS_fwHandlerSelect, running mode.

References EDS_FW_MASK, _EDS_fw::handlers, _EDS_fw::lists, _EDS_fwHandler::prm, _EDS_fwHandler::services, _EDS_fwHandlerRegisteredServices::start, and _EDS_fwLists::start.

int EDS_fwHandlerUnregister ( EDS_fw *  fw,
int  priority 
)

Routine to unregister a packet processor.

Returns:
Status
Parameters:
fw The EDS framework structure
priority The identifying priority of the handler to unregister

References _EDS_fwMem::delete, _EDS_fwHandlerRegisteredServices::destruct, _EDS_rsdTbl::dscs, EDS_FW_MASK, EDS_fwHandlerChange(), _EDS_fwLists::free, _EDS_fw::handlers, _EDS_fw::ixb, _EDS_cfgInfo::key, _EDS_rsdDsc::len, _EDS_fw::lists, _EDS_fw::mem, _EDS_fw::needs, _EDS_fwFateNeeds::permanent, _EDS_fwLists::phases, _EDS_fwHandler::prm, _EDS_fwMem::prm, _EDS_rsdDsc::ptr, _EDS_fwIxb::rsd, _EDS_fwHandler::services, and _EDS_rsdTbl::valid.

EDS_fwIxb * EDS_fwIxbLocate ( EDS_fw *  fw  ) 

Locates the EDS_fwIxb structure.

Returns:
Pointer to the EDS_fwIxb structure
Parameters:
fw The framework's control structure

References _EDS_fw::ixb.

int EDS_fwIxbObjAdd ( EDS_fw *  fw,
int  object,
int  size,
EDS_fwIxbObjConstructor  construct,
EDS_fwIxbObjDestructor  destruct,
EDS_fwIxbObjReset  reset 
)

Adds an object to the Information Exchange Block.

Return values:
If postive, the index of the added object
If negative, failure
Parameters:
fw The framework's control structure
object The index of the object to add
size The size, in bytes, of the object
construct The constructor routine (if any)
destruct The destructor routine (if any)
reset The reset routine (if any)

References addIxbObj(), and _EDS_fw::tbl.

unsigned int EDS_fwIxbObjAllocate ( EDS_fw *  fw,
unsigned int  objects 
)

Allocates any previously added (known) objects.

Returns:
Bit mask of objects that failed to be allocated
Parameters:
fw The framework's control structure
objects The list of objects to allocate

References allocateIxb(), _EDS_fw::ixb, _EDS_fw::mem, and _EDS_fw::tbl.

unsigned int EDS_fwPostChange ( EDS_fw *  fw,
unsigned int  list,
unsigned int  newState 
)

Changes the state of the enable/disable post list.

Returns:
A bit map of the previous state
Parameters:
fw The EDS_fw structure
list The target list of posting routine, specified as a right justified bit mask
newState The new enable/disable state of those post ques/streams specified by list

References _EDS_fwPostCtl::enabled, _EDS_fwPostCtl::installed, _EDS_cfgInfo::key, and _EDS_fw::post.

unsigned int EDS_fwPostFlush ( EDS_fw *  fw,
unsigned int  list,
int  reason 
)

Selects a new mode.

Returns:
A bit map of those posting reporting failure
Parameters:
fw The EDS_fw structure
list The target list of posting routine, specified as a bit mask
reason The reason for flushing

References EDS_FW_MASK, _EDS_fwPostCtl::enabled, _EDS_fwPostServices::flush, _EDS_fw::post, _EDS_fwPostCtl::posters, and _EDS_fwPoster::service.

unsigned int EDS_fwPostNotify ( EDS_fw *  fw,
unsigned int  list,
unsigned int  mode 
)

Notifies the list of post routines of a change in the configuraion.

Returns:
A bit map of those notification routines reporting failure
Parameters:
fw The EDS_fw structure
list The target list of posting routines, specified as a bit mask
mode The new mode

References _EDS_rsdTbl::active, _EDS_fw::cfg, _EDS_rsdTbl::dscs, EDS_FW_MASK, _EDS_fwLists::enabled, _EDS_fwPostCtl::enabled, _EDS_cfgInfo::idx, _EDS_fwHandlerCfgs::infos, _EDS_fw::ixb, _EDS_rsdDsc::len, _EDS_fw::lists, _EDS_rsdTbl::nbytes, _EDS_fwPostServices::notify, _EDS_fwPostCtl::notify, _EDS_fw::post, _EDS_fwPostCtl::posters, _EDS_fwIxb::rsd, _EDS_fwPoster::service, and _EDS_rsdTbl::valid.

int EDS_fwPostRegister ( EDS_fw *  fw,
unsigned int  idx,
EDS_fwPostStartRtn  start,
EDS_fwPostWriteRtn  write,
EDS_fwPostNotifyRtn  notify,
EDS_fwPostFlushRtn  flush,
void *  prm 
)

Initializes the specified EDS_fw posting stream.

Returns:
0, if successful, -1 if which is not between 0 and 3 inclusive
Parameters:
fw The EDS_fw structure to initialize
idx Which post routine (0-3 inclusive)
start Routine to start (or more accurately) prepare a post stream to receive events. This routine may be specified as NULL.
write Routine to write the event to the post stream. This routine may not be specfied as NULL.
notify Routine to notify the post stream when a change to the configuration has occured. This routine may be specified as NULL.
flush Routine to flush the post stream. This routine may not be specified as NULL.
prm Parameter to the post routine

References EDS_FW_MASK, _EDS_fwPostServices::flush, _EDS_fwPostCtl::installed, _EDS_fwPostServices::notify, _EDS_fwPostCtl::notify, _EDS_fw::post, _EDS_fwPostCtl::posters, _EDS_fwPoster::prm, _EDS_fwPoster::service, _EDS_fwPostServices::start, _EDS_fwPostCtl::start, and _EDS_fwPostServices::write.

Referenced by EDS_fwPostServicesRegister().

unsigned int EDS_fwPostResume ( EDS_fw *  fw,
unsigned int  list,
int  reason 
)

Resumes after a pause.

Returns:
A bit map of those posting streams reporting failure.
Parameters:
fw The EDS_fw structure
list The target list of posting routine, specified as a bit mask
reason Suggested use is to indicate why the post stream is being resumed
This is really just a convenience routine, calling EDS_fwPostStart with arguments appropriate for a resume.

References EDS_fwPostStart().

int EDS_fwPostServicesRegister ( EDS_fw *  fw,
unsigned int  idx,
const EDS_fwPostServices *  services,
void *  prm 
)

Initializes the specified EDS_fw posting stream.

Returns:
0, if successful, -1 if which is not between 0 and 3 inclusive
Parameters:
fw The EDS_fw structure to initialize
idx Which post routine (0-3 inclusive)
services Pointer to the list of services to set.
prm Parameter to the post routine

References EDS_fwPostRegister(), _EDS_fwPostServices::flush, _EDS_fwPostServices::notify, _EDS_fwPostServices::start, and _EDS_fwPostServices::write.

unsigned int EDS_fwPostStart ( EDS_fw *  fw,
unsigned int  list,
int  reason,
unsigned int  run_id,
unsigned int  startTime,
unsigned int  mode,
unsigned int  hw_key,
unsigned int  cfg_key 
)

Sets the parameters associated with a new run.

Returns:
A bit map of those posting streams reporting failure
Parameters:
fw The EDS_fw structure
list The target list of posting routine, specified as a bit mask
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).

References EDS_FW_MASK, _EDS_fwPostCtl::enabled, _EDS_fw::post, _EDS_fwPostCtl::posters, _EDS_fwPoster::service, _EDS_fwPostServices::start, and _EDS_fwPostCtl::start.

Referenced by EDS_fwPostResume().

int EDS_fwSizeof ( void   ) 

Returns the size, in bytes, of and EDS_fw control structure.

Returns:
The size, in bytes, of and EBF_fw control structure

static int initIxbObjTbl ( EDS_fwIxbObjTbl *  tbl  )  [static]

Initializes the reserved portion of the Information Exchange Block's object table.

Returns:
A bit mask (big-endian style) of those objects that failed to install

References addIxbObj(), _EDS_fwIxbObjAddDef::construct, DEF, _EDS_fwIxbObjAddDef::destruct, EBF_dirInit(), EBF_dirReset(), ECR_acdInit(), ECR_calInit(), EDR_acdUnpackInit(), EDR_acdUnpackReset(), EDR_calUnpackInit(), EDR_calUnpackReset(), EDR_errUnpackInit(), EDR_errUnpackReset(), EDR_tkrUnpackInit(), EDR_tkrUnpackReset(), _EDS_fwIxbObjAddDef::id, _EDS_fwIxbObjAddDef::reset, and _EDS_fwIxbObjAddDef::size.

Referenced by EDS_fwConstruct1().

static void memDefaultDelete ( void *  prm,
void *  ptr,
unsigned int  nbytes 
) [static]

Default memory deallocator.

Parameters:
prm Unused
ptr Pointer to the memory to deallocate
nbytes Number of bytes to deallocate, unused in this routine

Referenced by EDS_fwConstruct1().

static void * memDefaultNew ( void *  prm,
unsigned int  nbytes 
) [static]

Default memory allocator.

Returns:
Pointer to the allocated memory
Parameters:
prm Unused
nbytes Number of bytes to allocate

Referenced by EDS_fwConstruct1().

static __inline unsigned int needs_refresh ( const unsigned int *  needs,
unsigned int  active 
) [static]

Recalculates the list of needs based on the active list.

Returns:
The new list of needs
Parameters:
needs The array of needs by handler
active The bit list of active handlers
When ever the list of active handlers changes the list of permanent needs must be updated. This happens at two different times, when either EDS_fwHandlerChange or EDS_fwHandlerUnregister is called.

Referenced by EDS_fwHandlerChange().

Generated on Thu Sep 27 13:51:03 2012 by  doxygen 1.5.8