---

BFR.c File Reference

Balloon Flight Readout, Implementation. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <semLib.h>
#include "BBC/BUG.h"
#include "BBC/BSWP.ih"
#include "BBC/IVTE.ih"
#include "BBC/RNG.h"
#include "BBC/SPIN.ih"
#include "BVME/VME.h"
#include "BVME/UNIV.h"
#include "BVME/UNIV_print.h"
#include "BFU/BFA.h"
#include "BFU/BFR.h"
#include "BFU/BFU_fileDsc.h"

Data Structures
struct	_BFR_lst
	List head for the various readout types. More...
struct	_BFR_rod
	Describes and controls an object to be readout. More...
struct	_BFR_roi
	Defines a readout image. More...
struct	_BFR_rop
	Defines a readout program. More...
struct	_BFR_ros
	Describes the synchronization structure. More...
Defines
#define	BFR_K_RO_MAX   32
	The maximum number of types of readout.
#define	BFR_K_MAX_FIFO_CNT   4096
	Maximum number events in the FIFO.
#define	DCTL_SUP
	DMA control word for SUPERVISOR mode BLT. More...
#define	DCTL_USR
	DMA control word for USER mode BLT. More...
Typedefs
typedef _BFR_rod	BFR_rod
	Typedef for struct _BFR_rod. More...
typedef _BFR_ros	BFR_ros
	Typedef for struct _BFR_ros.
typedef _BFR_lst	BFR_lst
	Typedef for struct _BFR_lst.
Functions
void	dma_service (BFR_ros *dma_synch)
	Services a DMA completion interrupt. More...
int	cnt_bits (unsigned int word)
	Simple internal routine to count the bits in a 32 bit word. More...
int	get_input_position (const BFR_id *input_order, unsigned int ro_list, BFR_id which)
	Returns a number representing which input record this corresponds to. More...
UNIV_dcp *	bind1_indirect (UNIV_dcp *dcpp, const BFR_rod *rod, int nread)
	Completes the binding of indirect readout descriptors. More...
UNIV_dcp *	bind1_direct (UNIV_dcp *dcpp, BFU_fileDsc *dsc, BFR_roi *roi, const BFR_rop *rop, int nread)
	Binds all the readouts. More...
int	BFR_rop_sizeof (int rod_max)
	Calculates the size of a BFR readout control structure which can hold rod_max readout descriptors. More...
BFR_rop *	BFR_rop_get (int rod_max)
	Allocates a BFR readout control structure which can hold rod_max readout descriptors. More...
BFR_rop *	BFR_rop_init (BFR_rop *rop, unsigned int hdr_id, int rod_max, unsigned int tlr_id, int sum_cnt, int sum_size)
	Initializes a previously allocated readout program. More...
int	BFR_rod_add (BFR_rop *rop, int input, BFR_id rid, unsigned int id, int size, unsigned int data_fifo, unsigned int size_fifo, BFR_rdRtn rdRtn, void *rdPrm)
	Adds a readout descriptor to the readout program. More...
const BFR_rop *	BFR_rop_configure (unsigned int hdr_id, unsigned int ro_list, unsigned int tlr_id, int sum_cnt, int sum_size, const BFR_id *output_order, const BFR_id *input_order, const unsigned int *ivte_ids, const int *data_sizes, const unsigned int *tem_vmes, const int *data_fifos, const int *size_fifos, const BFR_rdRtn *rdRtns, void *const *rdPrms)
	High level routine to construct a readout program. More...
void	BFR_rop_print (const BFR_rop *rop)
	Diagnostic routine to print the contents of an readout program. rod_max readout descriptors. More...
BFR_roi *	BFR_roi_construct (const BFR_rop *rop)
	Constructs a template readout image from an readout program. More...
int	BFR_roi_bind0 (BFR_roi *roi, int nread, unsigned int sequence)
	Does the phase 0 of binding the readout image to a specific readout instance. More...
int	BFR_roi_read0 (BFR_roi *roi)
	Does phase 0 of reading out the event. More...
int	BFR_roi_pend0 (BFR_roi *roi)
	Waits for any asynchronous activity associated with the 0th phase of the readout to complete. More...
int	BFR_roi_bind1 (BFR_roi *roi, struct _BFA_acb *acb)
	Does the phase1 of binding the readout image to a specific readout instance. More...
int	BFR_roi_read1 (BFR_roi *roi)
	Does the first phase of reading out the event. More...
int	BFR_roi_pend1 (BFR_roi *roi)
	Waits for any asynchronous activity associated with the phase 1 of the readout to complete. More...
int	BFR_roi_copy1 (BFR_roi *roi, struct _BFA_acb *acb)
	Completes the output record by copying an indirectly read data into the output record. More...
int	BFR_roi_finish (BFR_roi *roi, struct _BFA_acb *acb)
	Performs any work needed after the event and all summary information has been read in. More...
_BFU_fileDsc *	BFR_roi_evtDscGet (const BFR_roi *roi)
	Returns a pointer to an event descriptor structure. More...
void	BFR_roi_print (const BFR_roi *roi)
	Diagnostic print routine to display the contents of a readout image. More...

---

Detailed Description

Balloon Flight Readout, Implementation.

Author:

JJRussell - russell@slac.stanford.edu

---

Define Documentation

#define DCTL_SUP

Value: (UNIV_K_DCTL_VDW_32 | \ UNIV_K_DCTL_VAS_A32 | \ UNIV_K_DCTL_PGM_DATA | \ UNIV_K_DCTL_SUPER_SUPER | \ UNIV_K_DCTL_VCT_BLT | \ UNIV_K_DCTL_LD64EN ) DMA control word for SUPERVISOR mode BLT.

#define DCTL_USR

Value: (UNIV_K_DCTL_VDW_32 | \ UNIV_K_DCTL_VAS_A32 | \ UNIV_K_DCTL_PGM_DATA | \ UNIV_K_DCTL_SUPER_USER | \ UNIV_K_DCTL_VCT_BLT | \ UNIV_K_DCTL_LD64EN ) DMA control word for USER mode BLT.

---

Typedef Documentation

BFR_rod

Typedef for struct _BFR_rod. Readouts come in a various types. The are classified by whether they are direct or indirect, fixed or variable and USER or SUPERVISOR VME assess mode. The direct or indirect refers to whether the data from a FIFO can be read direcly into the readout memory or whether it first needs to be read into a holding array and then copied into the readout memory. This occurs, for example, if the data from the FIFO needs to be processed. The L1T FIFO is an example of this. Because its FIFO is only byte-wide, 4 bytes must be packed into a 32-bit quantity before it is placed into the readout memory. The fixed or variable refers to whether the data from a FIFO is fixed length or variable length. All variable length data must have a supporting FIFO which holds the actual length of each event. Currently only the TKR data is variable length. Finally a FIFO may be assessed either in VME USER mode or VME SUPERVISOR mode. Currently only the L1T FIFO is assessed in VME SUPERVISOR mode.

---

Function Documentation

int BFR_rod_add (  BFR_rop *    rop, int    input, BFR_id    rid, unsigned int    id, int    size, unsigned int    data_fifo, unsigned int    size_fifo, BFR_rdRtn    rdRtns, void *    rdPrms )

Adds a readout descriptor to the readout program. Parameters: rop  A pointer to a previously initialized readout program. input  The order this should be readin. For example, if this number is 0, then this is the first data read from the hardware. rid  The internal BFR identifier for this readout descriptor. id  The 4 byte IVTE identifier. size  If the data is a fixed size, than that size in bytes. If the data size is dynamic (ie from a size_fifo) then 0. If the data must be read into a indirect array, then -size. data_fifo  The VME address of the data fifo. Use the low bit to specify SUPERVISOR access. size_fifo  The VME address of the size fifo (use -1 if non). Use the low bit to specify SUPERVISOR access. Return values: BFR_C_SUCCESS, if  okay. BFR_C_TOOMANY, if  too have exhausted the readout descriptors. BFR_C_DUPLICATE, if  an attempt is made to add an existing descriptor. Adds a readout descriptor to a BFR readout program. The order of addition specifies the order of readout. Although this routine may be called by the user, more likely it will be called by BFR_rop_configure().

int BFR_roi_bind0 (  BFR_roi *    roi, int    nread, unsigned int    sequence )

Does the phase 0 of binding the readout image to a specific readout instance. Parameters: roi  Handle to the Readout image to be bound. nread  The number of events to read out. sequence  The beginning event sequence number. Returns: Status. Does the phase 0 of binding the readout image to a specific instance. The number of events to be read along with the beginning sequence number are assigned to the image.

int BFR_roi_bind1 (  BFR_roi *    roi, struct _BFA_acb *    acb )

Does the phase1 of binding the readout image to a specific readout instance. Parameters: roi  Handle to the Readout image to be bound. acb  Handle to the Balloon Flight memory Allocator Returns: Status. Does the phase 1 of binding the readout image to a specific instance. Builds both the DMA list and the IVTE output event structure for the specified number of events.

BFR_roi * BFR_roi_construct (  const BFR_rop *    rop )

Constructs a template readout image from an readout program. Parameters: rop  The readout program to base the readout image on. Returns: Pointer to the newly constructed readout image. Constructs an instance of a Readout Image. This image is still incomplete, since it has not been given the number of events it is to read nor the destination address of these events.

int BFR_roi_copy1 (  BFR_roi *    roi, struct _BFA_acb *    acb )

Completes the output record by copying an indirectly read data into the output record. Parameters: roi  Handle to the Readout image to be copied. This must be bound through phase 1 using BFR_roi_bind1() and a BFR_read1() must have been called to initiate the read. BFR_pend1() must also have been called to ensure the read has completed acb  The allocation control block. Returns: Status.

const struct _BFR_evtDsc * BFR_roi_evtDscGet (  const BFR_roi *    roi )

Returns a pointer to an event descriptor structure. Parameters: roi  Handle to the Readout image containing the event descriptor. Returns: A pointer to the structure describing the last sequence of events taken. Since a pointer to the event description is returned, care should be taken not to initiate another set operations on this readout image until the information contained in the event descriptor has either been consumed or copied into a safe area. The memory behind the actual events is the user's responsibility, so as long as he does not free it, the pointers contained in the event descriptor are valid.

int BFR_roi_finish (  BFR_roi *    roi, struct _BFA_acb *    acb )

Performs any work needed after the event and all summary information has been read in. Parameters: roi  Handle to the Readout image to be copied. This must be bound through phase 1 using BFR_roi_bind1() and a BFR_roi_read1() must have been called to initiate the read. BFR_roi_pend1() must also have been called to ensure the read has completed and BFR_roi_copy1 to move the indirect data. acb  The allocation control block. Returns: Status. Currently this routine moves any possible shard in the ring buffer overflow block to the top of the memory. This routine performs a consistency check, but BUG checks upon failure.

int BFR_roi_pend0 (  BFR_roi *    roi )

Waits for any asynchronous activity associated with the 0th phase of the readout to complete. Parameters: roi  Handle to the Readout image to be read. This must be bound through phase 0 using BFR_bind0() and a BFR_read0() must have been called to initiate the read. Returns: Status. This routine is used to ensure that any IO activity associated with the phase 0 is complete. Now, under the truth in advertising, the only IO activity associated with this phase must be performed synchronously, but calling BFR_roi_pend0() gives this the same look and feel as the next phase of readout.

int BFR_roi_pend1 (  BFR_roi *    roi )

Waits for any asynchronous activity associated with the phase 1 of the readout to complete. Parameters: roi  Handle to the Readout image to be read. This must be bound through phase 1 using BFR_bind1() and a BFR_read1() must have been called to initiate the read. Returns: Status. Waits for any asynchronous activity associated with the 1rst phase of the readout to complete. This routine must be called after initiating the IO by a call to BFR_roi_read1().

void BFR_roi_print (  const BFR_roi *    roi )

Diagnostic print routine to display the contents of a readout image. Parameters: roi  Handle to the Readout image to be displayed. This routine is primarily used for diagnostics and debugging.

int BFR_roi_read0 (  BFR_roi *    roi )

Does phase 0 of reading out the event. Parameters: roi  Handle to the Readout image to be read. This must be bound through phase 0. Returns: Status. Phase 0 of reading out the event is performed. Currently this consists of reading any variable sized segments. This routine performs VME operations, so one should consider the activity on the bus before executing this routine. This read also is done asynchronously, so BFR_roi_pend0() should be used to ensure the IO is complete. Now, under the truth in advertising, the only IO activity associated with this phase must be performed synchronously, but calling BFR_roi_pend0() gives this the same look and feel as the next phase of readout.

int BFR_roi_read1 (  BFR_roi *    roi )

Does the first phase of reading out the event. Parameters: roi  Handle to the Readout image to be read. This must be bound through phase 1. Returns: Status. Begins any constructed DMA list in the readout image. The state of the VME bus should be considered before calling this routine. This routine only begins the read. BFR_pend1() should be called to ensure completion of the IO initiated by this routine.

const BFR_rop * BFR_rop_configure (  unsigned int    hdr_id, unsigned int    ro_list, unsigned int    tlr_id, int    sum_cnt, int    sum_size, const BFR_id *    output_order, const BFR_id *    input_order, const unsigned int *    ivte_ids, const int *    data_sizes, const unsigned int *    tem_vmes, const int *    data_fifos, const int *    size_fifos, const BFR_rdRtn *    rdRtns, void *const *    rdPrms )

High level routine to construct a readout program. Parameters: hdr_id  The id to use in the event header. ro_list  The list or readout ids to be used. tlr_id  The id to use in the event trailer. sum_cnt  Number of summary records (really record descriptors) to be reserved at the end for user summary data. sum_size  The size of all the summary records. This must be a fixed sized to be shared. output_order  This is an array, indexed by readout id, which specifies the relative position of this data in the output event. input_order  This is an array, indexed by readout id, which specifies the relative order that this data element will be acquired. ivte_ids  This is an array, indexed by readout id, which specifies the IVTE ID to be used for this data. data_sizes  This is an array, indexed by readout id, which specifies the size (in bytes) of the output data. If the size of the output data record is not fixed, then this number should be specified as <=0. tem_vmes  This is an array, indexed by readout id, which specifies the base VME address of this data. data_fifos  This is an array, indexed by readout id, which specifies the offset of the data fifo. size_fifos  This is an array, indexed by readout id, which specifies the offset of the size fifo. This is relevant only for those readouts which have variable sized data, ie the TKR. rdRtns  Array of special read routines indexed by rid rdPrms  Parameters passed to read routines Returns: If successful, a pointer to the readout program. Else NULL. The only practical reason that this may fail is bad input arguments or insufficient memory.

BFR_rop * BFR_rop_get (  int    rod_max )

Allocates a BFR readout control structure which can hold rod_max readout descriptors. Parameters: rod_max  The maximum number of readout descriptors that will every be used. Returns: A pointer to the allocate readout control structure. If the number of readout descriptors is not between 0 and 32 or there is insufficient memory, NULL is returned. Allocates a BFR readout program control structure with the specified number of BFR readout descriptors are allocated. The user should then initialize this structure with BFR_rop_init, then add readout descriptors with BFR_rod_add. This is merely a convenience routine. The user can control his own memory allocation by calling BFR_sizeof_rop() to get the size of the readout program, then using his favorite allocator to obtain the memory.

BFR_rop * BFR_rop_init (  BFR_rop *    rop, unsigned int    hdr_id, int    rod_max, unsigned int    tlr_id, int    sum_cnt, int    sum_size )

Initializes a previously allocated readout program. Parameters: rop  Pointer to the BFR readout control structure to initialize. hdr_id  The id to use for the IVTE header. rod_max  Maximum number of readout descriptors. tlr_id  The id to use for the IVTE trailer. sum_cnt  Number of summary records (really record descriptors) to be reserved at the end for user summary data. sum_size  The size of all the summary records. This must be a fixed sized to be shared. Returns: A pointer to the initialized BFR readout control structure or NULL if the initialization failed. Initializes a previously allocated BFR_rop control structure. The only gotcha, is that this routine assumes that enough memory to contain 'rod_max' readout descriptors actually exists. The approved method is to always use BFR_sizeof_rop (rod_max) to calculate the necessary size

void BFR_rop_print (  const BFR_rop *    rop )

Diagnostic routine to print the contents of an readout program. rod_max readout descriptors. Parameters: rop  The readout program to print.

int BFR_rop_sizeof (  int    rod_max )

Calculates the size of a BFR readout control structure which can hold rod_max readout descriptors. Parameters: rod_max  The maximum number of readout descriptors that will every be used. Returns: The size (in bytes) of a readout control structure large enough to hold a rod_max readout descriptors. Calculates the number of sizeof a BFR readout control structure necessary to hold the specified number of readout descriptors. There is norequirement that the caller use all that has been allocated, only that he does not try to use more. This number must be between 0 and 32. Although 0 is no very useful, it is a way to learn the size of just the control structure.

UNIV_dcp * bind1_direct (  UNIV_dcp *    dcpp, BFU_fileDsc *    dsc, BFR_roi *    roi, const BFR_rop *    rop, int    nread )  [inline, static]

Binds all the readouts. Parameters: dcpp  Pointer to the next DMA command packet to be filled in. dsc  Pointer to the event descriptor which describes these events. The memory must have already been allocated. roi  Pointer to the readout image. This contains various parameters which are relevant to this particular readout sequence. rop  Pointer to the readout program. This contains various parameters which only depend only on the source of the readouts (ie which things are being readout), not one the destination, (ie where they are being readout to). nread  The number of events to read out Returns: Pointer to the next DMA packet to be filled in. Binds all the readouts. Two operations occur in this routine. 1. The header/directories for all data read are constructed. 2. The DMA packets for all directly read records (both the fixed direct and the variable direct) are completed. NOTE: Direct readouts are those which have their data read directly into the output data structure records.

UNIV_dcp * bind1_indirect (  UNIV_dcp *    dcpp, const BFR_rod *    rod, int    nread )  [inline, static]

Completes the binding of indirect readout descriptors. Parameters: dcpp  Pointer to the array of DMA command packets rod  Pointer to the first element in the linked list of indirect readout descriptors. nread  The number of events to be read out. Returns: Pointer to the next DMA command packet to be filled. Completes the binding of indirect readout descriptors. These readout descriptors cannot be read directly into the output data record, but must be first read into a piece of memory, then copied to their final resting place. This is generally because the data fifo is not 32 bits wide and the data needs to be compacted from the readin width into 32 bit wide quantities. Two fields of the dma command packets must be modified 1. The transfer count, since this depends on the number of events to be read. 2. The DONE and TERMINATION bits must be cleared. The data itself is read into a fixed location, stored with the readout image.

int cnt_bits (  unsigned int    word )  [inline, static]

Simple internal routine to count the bits in a 32 bit word. Parameters: word  The word to count the bits in. Returns: The number of set bits in this word Simple internal routine to count the bits in a 32 bit word. This is only a convenience routine and is not meant for high-performance usage.

void dma_service (  BFR_ros *    dma_synch )  [static]

Services a DMA completion interrupt. Parameters: dma_synch  The DMA synchronization structure This routine handles the interrupts from the UNIVERSE II Tundra. This routine does very little, counting the number of interrupts received, purely for diagnostic reasons, and recording the reason for the interrupt.

int get_input_position (  const BFR_id *    input_order, unsigned int    ro_list, BFR_id    target_id )  [inline, static]

Returns a number representing which input record this corresponds to. Parameters: input_order  An array of BFR readout ids, giving the desired readout order. ro_list  The list of all active BFR readout ids. target_id  The target BFR readout id. This is the one we wish to know its relative order in the readout list. Returns: An integer representing the relative order of the target BFR readout id in the readout list. Returns a number representing which input record this corresponds to. A list, in the desired input order is scanned. This list would be fine to use as is, if all records types where to be included. However, since not all records types are always readout, the numbers must be compressed to form a dense list. See the example in the code.

---