Main Page   Interface   Data Structures   File List   Data Fields   Globals  

BFM.h File Reference

Balloon Flight (VME) Modules, Interface. More...

#include "BTU/TEM.h"

Typedefs

typedef _BFM_dsc BFM_dsc
 Typedef for struct _BFM_dsc.

typedef enum _BFM_opTarget BFM_opTarget
 Typedef for enum _BFM_opTarget.

typedef int(* BFM_opReporter )(void *parameter, int opId, BFM_opTarget opTarget, unsigned int successes, unsigned int failures, const struct _TEM_tem *tems, const struct _TEM_fpga *fpgas)
 Callback signature for BFM_opReport. More...


Enumerations

enum  _BFM_opTarget {
  BFM_C_OP_TARGET_NONE = 0,
  BFM_C_OP_TARGET_TEMS = 1,
  BFM_C_OP_TARGET_FPGAS = 2
}
 Enumerates to what target type an operation applies to. More...


Functions

BFM_dsc * BFM_get (void)
 Returns a piece of memory that either is the TEM data base or can be filled in to be the TEM data base. More...

unsigned int BFM_describe (BFM_dsc *bfm, unsigned int requestTems, const unsigned vmeAdrs[TEM_C_CNT], const struct _TEM_temDsc *const temDscs[TEM_C_CNT], const struct _FPGA_ttcHdr *const fpgaTtcs[TEM_C_FPGA_CNT], const struct _TEM_fpgaDsc *const fpgaDscs[TEM_C_FPGA_CNT])
 Workhorse routine to describe the properties of a collection TEMs/FPGAs. More...

unsigned int BFM_initialize (BFM_dsc *bfm)
 Initializes the TEMs making them ready for use. More...

void BFM_opReport (const BFM_dsc *bfm, unsigned int operations, BFM_opReporter reporter, void *parameter)
 Reports on the success or failure of various operations. More...

unsigned int BFM_fpgasBistWrite (const BFM_dsc *bfm, unsigned int fpgasList, unsigned int bistList)
 Writes the self test mode for the specified list of fpgas. More...

unsigned int BFM_fpgasHfullClrWrite (const BFM_dsc *bfm, unsigned int fgpasList, unsigned int hfullList)
 Writes the FIFO Half Full Auto Clear mode for the specified list of FPGAS. More...

unsigned int BFM_fpgasHfullEnbWrite (const BFM_dsc *bfm, unsigned int fgpasList, unsigned int hfullList)
 Writes the FIFO Half Full Enable mode for the specified list of fpgas. More...

unsigned int BFM_fpgasLoaded (const BFM_dsc *bfm)
 Returns a list of the FPGAs that were successfully loaded. More...

unsigned int BFM_fpgasLogicClear (BFM_dsc *bfm, unsigned int fpgaList)
 Toggles the FPGA Logic Clear bit for the specified list of FPGAs. More...

unsigned int BFM_fpgasTemsGet (const BFM_dsc *bfm, unsigned int fpgaList)
 Returns the list of the TEMSs associated with the specified list of FPGAs. More...

unsigned int BFM_fpgasL1tCounterClear (BFM_dsc *bfm, unsigned int fpgaList)
 Clears the L1t event counter. More...

unsigned int BFM_fpgasL1tTimerClear (BFM_dsc *bfm, unsigned int fpgaList)
 Clears the L1t timer. More...

unsigned int BFM_temsFifosReset (const BFM_dsc *bfm, unsigned int temList)
 Resets all the FIFOs on a TEM. More...

const struct _TEM_tem * BFM_tems (const BFM_dsc *bfm)
 Returns a pointer to the TEM database. More...

const struct _TEM_fpga * BFM_fpgas (const BFM_dsc *bfm)
 Returns a pointer to the FPGA database. More...

unsigned int BFM_fpgasRdoModeWrite (const BFM_dsc *bfm, unsigned int fpgaList, unsigned int modeList)
 Writes the readout mode for the specified list of fpgas. More...

unsigned int BFM_fpgasRdoBsyMinMaxWrite (const BFM_dsc *bfm, unsigned int fpgaList, unsigned int modeList)
 Writes the readout min/max mode for the specified list of fpgas. More...

unsigned int BFM_temsPresent (const BFM_dsc *bfm)
 Returns a list of the TEMs that are present in the system. More...

unsigned int BFM_temsReadied (const BFM_dsc *bfm)
 Returns a list of the TEMs that are in the ready state. More...

unsigned int BFM_temsScopeBitClear (BFM_dsc *bfm, unsigned int temList)
 Clears the scope bit on the specified TEMs. More...

unsigned int BFM_temsScopeBitSet (BFM_dsc *bfm, unsigned int temList)
 Sets the scope bit on the specified TEMs. More...

unsigned int BFM_temsScopeBitToggle (BFM_dsc *bfm, unsigned int temList)
 Toggles the scope bit on the specified TEMs. More...

unsigned int BFM_temsFpgasGet (const BFM_dsc *bfm, unsigned int temList)
 Returns the list of the FPGAs associated with the specified list of TEMs. More...

const unsigned int * BFM_vmeAdrsByTem (const BFM_dsc *bfm)
 Returns an array, indexed by TEM, of the TEMs VME addresses. More...

const unsigned int * BFM_vmeAdrsByFpga (const BFM_dsc *bfm)
 Returns an array, indexed by FPGA, of the TEMs VME addresses. More...

volatile unsigned int *const * BFM_lclAdrsByTem (const BFM_dsc *bfm)
 Returns an array, indexed by TEM, of the TEMs local addresses. More...

volatile unsigned int *const * BFM_lclAdrsByFpga (const BFM_dsc *bfm)
 Returns an array, indexed by FPGA, of the TEMs local addresses. More...

unsigned int BFM_opsAttempted (const BFM_dsc *bfm)
 Returns a bit mask of all operations attempted on any TEM/FPGA. More...

unsigned int BFM_opErrors (const BFM_dsc *bfm)
 Returns a bit mask of all failed operations attempted on any TEM/FPGA. More...

Detailed Description

Balloon Flight (VME) Modules, Interface.

Author:
JJRussell - russell@slac.stanford.edu
BFM acts as a data base for the TEMS and other VME modules. It encapsulates both static information, such as the values VME and local addresses, and dynamic information, such as the current state of any given TEM, ie, PRESENT, LOADED, READY, etc.

The general usage is to first pour information in information about the TEMS one is interested in via a BFM_describe and then get the TEMS ready by doing a BFM_initialize, which will load the FPGAs and put the registers in a known and consistent state. After these two steps one is free to change the state of the TEMs or just use the BFM query interfaces to learn about the current state of affairs.

Typedef Documentation

BFM_opReporter
 

Callback signature for BFM_opReport.

BFM_opReport reports on the status of requested operations. Instead of merely generating a printf to the terminal, all information about the operation is passed back to the user via this callback routine. The callback handler is called for each relevant operation.

The call signature is 


         status = (*reporter) (void              *parameter,
                               int                     opId,
                               BFM_opTarget        opTarget,
                               unsigned int       successes,
                               unsigned int        failures,
                               const struct _TEM_tem  *tems,
                               const struct _TEM_fpga *fpags)

         where
             parameter: A user provided parameter passed transparently
                        through from the BFM_opReport call.
                  opId: The id of the operation, i.e. just which
                        operation is being reported on. The \a opId
                        can be translated to an ASCII name using
                        \c BFM_opnames(opId).
              opTarget: Either BFM_C_OP_TARGET_TEM or BFM_C_OP_TARGET_FPGA,
                        indicating the target type of the operation.
                        This parameter indicates how to interpret the
                        \a successes and \a failures arguments, as being
                        relevant to an array of TEMs or and array of FPGAs.
             successes: A list, expressed as a bit mask, indicating which
                        targets the operation was successful on.
              failures: A list, expressed as a bit mask, indicating which
                        targets the operation was unsuccessful on.
                  tems: An array, indexed by TEM_C_xxx of structure
                        describing the TEMS.
                 fpgas: An array, indexed by TEM_C_FPGA_xxx, describing
                        the FPGAs.

        The return code indicates whether one should stop (non-zero) or
        continue through the remaining list of operations.

        See BFM_opPrint for an usage example.

Enumeration Type Documentation

enum _BFM_opTarget
 

Enumerates to what target type an operation applies to.

Operations are generally directed at one of two target types, either TEMs or FPGAs. This enumeration clearly states the target type of any operation. It mainly used in the reporting BFM routines.

Enumeration values:
BFM_C_OP_TARGET_NONE  Operation NA to either TEM or FPGA
BFM_C_OP_TARGET_TEMS  Operation targets a TEM
BFM_C_OP_TARGET_FPGAS  Operation targets a FPGA

Function Documentation

unsigned int BFM_describe (  BFM_dsc *    bfm,
unsigned int    requestTems,
const unsigned    vmeAdrs[TEM_C_CNT],
const struct _TEM_temDsc *const    temDscs[TEM_C_CNT],
const struct _FPGA_ttcHdr *const    fpgaTtcs[TEM_C_FPGA_CNT],
const struct _TEM_fpgaDsc *const    fpgaDscs[TEM_C_FPGA_CNT]
) 
 

Workhorse routine to describe the properties of a collection TEMs/FPGAs.

Parameters:
bfm:  Handle of the Balloon Flight Tems description.
requestTems:  The list of requested TEMs, specified as a bit mask.
vmeAdrs:  An array of the VME addresses associated with each TEM.
temDscs:  An array of pointers to the TEM descriptors.
fpgaTtcs:  An array of pointers to the FPGA download data. This data must be in the form of TTC data structures.
fpgaDscs:  An array of pointers to the FPGA descriptors.
Returns:
The list of TEMs which where improperly described. Currently this can only be due to an internal inconsistency, ie a programming bug.
Describes an instance the Balloon Flight Tems (BFM) This routine defines a BFM to be composed of the specified TEMs. The remaining parameters are necessary to fully define the database.

These parameters all are specified as arrays of either TEM_C_CNT or TEM_C_FPGA_CNT. In all cases, if the set requested TEMs does not include a particular TEM, then the information about that TEM or its associated FPGAs need not be specified. In short, if one only wants the CAL, then you only need specify the information relevant for the CAL TEM and its FPGA.

The operations are basically beign. The only operation to actually touch a TEM is a VME bus probe to check on its presence.

const struct _TEM_fpga * BFM_fpgas (  const BFM_dsc *    bfm ) 
 

Returns a pointer to the FPGA database.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
A pointer to the FPGA database.
The return value can be provides assess to the TEM_fpgasXXXX routines.

unsigned int BFM_fpgasBistWrite (  const BFM_dsc *    bfm,
unsigned int    fpgaList,
unsigned int    bistList
) 
 

Writes the self test mode for the specified list of fpgas.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to write the self test
bistList  The value of the self-test bit, expressed as a bit list by fpga.
Returns:
The list of FPGAs which were requested to write, but not supported.

unsigned int BFM_fpgasHfullClrWrite (  const BFM_dsc *    bfm,
unsigned int    fpgaList,
unsigned int    hfullList
) 
 

Writes the FIFO Half Full Auto Clear mode for the specified list of FPGAS.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to write FIFO Half Full Auto Clear mode.
bistList  The value of the FIFO Half Full Enable Auto Clear mode bit, expressed as a bit list by FPGA.
Returns:
The list of FPGAs which were requested to write, but not supported.

unsigned int BFM_fpgasHfullEnbWrite (  const BFM_dsc *    bfm,
unsigned int    fpgaList,
unsigned int    hfullList
) 
 

Writes the FIFO Half Full Enable mode for the specified list of fpgas.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to write FIFO Half Full Enable mode.
bistList  The value of the FIFO Half Full Enable mode bit, expressed as a bit list by FPGA.
Returns:
The list of FPGAs which were requested to write, but not supported.

unsigned int BFM_fpgasL1tCounterClear (  BFM_dsc *    bfm,
unsigned int    fpgaList
) 
 

Clears the L1t event counter.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to clear.

unsigned int BFM_fpgasL1tTimerClear (  BFM_dsc *    bfm,
unsigned int    fpgaList
) 
 

Clears the L1t timer.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to clear.

unsigned int BFM_fpgasLoaded (  const BFM_dsc *    bfm ) 
 

Returns a list of the FPGAs that were successfully loaded.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
A list, expressed as a bit mask, of that FPGAs were successfully loaded.

unsigned int BFM_fpgasLogicClear (  BFM_dsc *    bfm,
unsigned int    fpgaList
) 
 

Toggles the FPGA Logic Clear bit for the specified list of FPGAs.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of FPGAs.
Returns:
A list, expressed as a bit mask, of FPGAs which failed to clear.

unsigned int BFM_fpgasRdoBsyMinMaxWrite (  const BFM_dsc *    bfm,
unsigned int    fpgaList,
unsigned int    modeList
) 
 

Writes the readout min/max mode for the specified list of fpgas.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to write the readout min/max mode
modeList  The value of the readout, expressed as a bit list by FPGA.
Returns:
The list of FPGAs which where requested to set, but not supported.

unsigned int BFM_fpgasRdoModeWrite (  const BFM_dsc *    bfm,
unsigned int    fpgaList,
unsigned int    modeList
) 
 

Writes the readout mode for the specified list of fpgas.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of fpgas to write the readout mode
modeList  The value of the readout, expressed as a bit list by FPGA.
Returns:
The list of FPGAs which where requested to set, but not supported.

unsigned int BFM_fpgasTemsGet (  const BFM_dsc *    bfm,
unsigned int    fpgaList
) 
 

Returns the list of the TEMSs associated with the specified list of FPGAs.

Parameters:
bfm  The description of the Balloon Flight Tems.
fpgaList  The list of FPGAs.
Returns:
A list, expressed as a bit mask, of TEMs associated with the specified list of FPGAs.

BFM_dsc * BFM_get (  void    ) 
 

Returns a piece of memory that either is the TEM data base or can be filled in to be the TEM data base.

Returns:
A handle to the TEM data base.
Given that there is only one set of TEMs/FPGAs, there is only one copy of the database needs to be maintained. Typical usage would be to first do an BFM_get, then BFG_describe. After initialization, one can either hold on to the handle or fetch it back with another call to BFG_get(). Note, however, that all routines require this handle as the first argument.

unsigned int BFM_initialize (  BFM_dsc *    bfm ) 
 

Initializes the TEMs making them ready for use.

Parameters:
bfm  The description of the Balloon Flight TEMs. This was previously setup with a call to BFM_describe.
Returns:
0 if successful, a bit mask representing any phase of the setup that failed. See below for further details.
Initializes the BFM. All TEMs and FPGAs are prepared for data taking. This involves downloading the correct FPGA code and preparing the TEMs themselves for data taking. It does NOT include setting up any detector specific FPGA registers nor does it involve setting up the detector front-end hardware.

Each TEM is initialized as far as possible. If a failure occurs, the return value is marked with a bit noting a failure of some TEM at this phase. Said another way, the return value is really a summary error mask, indicating which operations had at least on failure associated with it. The user can then interrogate the BFM for specifics about exactly what failed at each phase. (See BFM_opReport for instance).

volatile unsigned int BFM_lclAdrsByFpga (  const BFM_dsc *    bfm ) 
 

Returns an array, indexed by FPGA, of the TEMs local addresses.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
An array, indexed by FPGA, of the TEMs local addresses

volatile unsigned int BFM_lclAdrsByTem (  const BFM_dsc *    bfm ) 
 

Returns an array, indexed by TEM, of the TEMs local addresses.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
An array, indexed by TEM, of the TEMs local addresses

unsigned int BFM_opErrors (  const BFM_dsc *    bfm ) 
 

Returns a bit mask of all failed operations attempted on any TEM/FPGA.

Parameters:
bfm  The description of the Balloon Flight TEMs.
Returns:
A bit mask of all failed operations attempted on any TEM/FPGA.
This is meant to provide a quick piece of summary error information. If An error has occurred, BFM_opReport() can be used to pin down the exact error.

void BFM_opReport (  const BFM_dsc *    bfm,
unsigned int    operations,
BFM_opReporter    reporter,
void *    parameter
) 
 

Reports on the success or failure of various operations.

Parameters:
bfm  The description of the Balloon Flight Tems.
operations  The list of operations, expressed as a bit mask, to report on.
reporter  A user supplied callback routine to handle the status reporting. This routine is called back once per operation. See the description of the BFM_opeReporter for details on the callback usage
parameter  A context parameter passed transparently through to the user provided callback routine.
This routine allows the user to report the status of all TEMs and FPGAs in a manner consistent with his application, ie, it does not just dump the output to the screen. See BFM_opPrint for an example of how to code a callback routine.

unsigned int BFM_opsAttempted (  const BFM_dsc *    bfm ) 
 

Returns a bit mask of all operations attempted on any TEM/FPGA.

Parameters:
bfm  The description of the Balloon Flight TEMs.
Returns:
A bit mask of all operations attempted on any TEM/FPGA.

const struct _TEM_fpga * BFM_tems (  const BFM_dsc *    bfm ) 
 

Returns a pointer to the TEM database.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
A pointer to the TEM database.
The return value can be provides assess to the TEM_temsXXXX routines.

unsigned int BFM_temsFifosReset (  const BFM_dsc *    bfm,
unsigned int    temList
) 
 

Resets all the FIFOs on a TEM.

Parameters:
bfm  The description of the Balloon Flight Tems.
temList  The list to TEMs to reset the FIFOs on.
Returns:
A list, expressed as a bit mask, of that TEMs that failed to have there FIFOs reset.

unsigned int BFM_temsFpgasGet (  const BFM_dsc *    bfm,
unsigned int    temList
) 
 

Returns the list of the FPGAs associated with the specified list of TEMs.

Parameters:
bfm  The description of the Balloon Flight Tems.
temList  The list of TEMs.
Returns:
A list, expressed as a bit mask, of FPGAs associated with the specified list of TEMs.

unsigned int BFM_temsPresent (  const BFM_dsc *    bfm ) 
 

Returns a list of the TEMs that are present in the system.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
A list, expressed as a bit mask, of that TEMs that are present in the system.
This routine can be used, after BFM_describe() has been called, to learn which TEMs are physically present on the VME bus.

unsigned int BFM_temsReadied (  const BFM_dsc *    bfm ) 
 

Returns a list of the TEMs that are in the ready state.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
A list, expressed as a bit mask, of that TEMs that are in the ready state. This routine can be used, after BFM_initialize() has been called, to learn which TEMs are in the ready state. TEMs in the ready state have had their FPGAs successfully loaded and are ready to be setup for data taking.

unsigned int BFM_temsScopeBitClear (  BFM_dsc *    bfm,
unsigned int    temList
) 
 

Clears the scope bit on the specified TEMs.

Parameters:
bfm  The description of the Balloon Flight Tems.
temList  The list to TEMs to clear the scope bit on.
Returns:
A list, expressed as a bit mask, of that TEMs that failed to have their scope bit cleared.

unsigned int BFM_temsScopeBitSet (  BFM_dsc *    bfm,
unsigned int    temList
) 
 

Sets the scope bit on the specified TEMs.

Parameters:
bfm  The description of the Balloon Flight Tems.
temList  The list to TEMs to clear the scope bit on.
Returns:
A list, expressed as a bit mask, of that TEMs that failed to have their scope bit set.

unsigned int BFM_temsScopeBitToggle (  BFM_dsc *    bfm,
unsigned int    temList
) 
 

Toggles the scope bit on the specified TEMs.

Parameters:
bfm  The description of the Balloon Flight Tems.
temList  The list to TEMs to toggle the scope bit on.
Returns:
A list, expressed as a bit mask, of that TEMs that failed to have their scope bit toggled.

unsigned int BFM_vmeAdrsByFpga (  const BFM_dsc *    bfm ) 
 

Returns an array, indexed by FPGA, of the TEMs VME addresses.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
An array, indexed by FPGA, of the TEMs VME addresses

unsigned int BFM_vmeAdrsByTem (  const BFM_dsc *    bfm ) 
 

Returns an array, indexed by TEM, of the TEMs VME addresses.

Parameters:
bfm  The description of the Balloon Flight Tems.
Returns:
An array, indexed by TEM, of the TEMs VME addresses

Generated on Tue Mar 5 17:55:35 2002 by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002