CMX Generated Documentation

#include "BFU/BFR_ids.h"

Defines
#define	BFR_C_SUCCESS 0
	Indicates the routine succeeded.
#define	BFR_C_TOOMANY -1
	Attempt to allocate too many ro descriptors.
#define	BFR_C_DUPLICATE -2
	Attempt to add an existing ro descriptor.
Typedefs
typedef int(*	BFR_rdRtn )(void rdPrm, int sequence, void dst, int len)
	The callback signature to add a user defined record to the input data.
typedef _BFR_rop	BFR_rop
	Typedef for struct _BFR_rop.
typedef _BFR_roi	BFR_roi
	Typedef for struct _BFR_roi.
Functions
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...
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...
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...
BFR_roi *	BFR_roi_construct (const BFR_rop *rop)
	Constructs a template readout image from an readout program. More...
void	BFR_roi_print (const BFR_roi *roi)
	Diagnostic print routine to display the contents of a readout image. 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...

Detailed Description

ROP
---
The readout program contains all the static information about the readout. It depends only on what is being readout and the form of the output record. Specifically one needs to specify which hardware and software components are being used to assemble an output event. The caller is allowed to control both the gathering of the data from the hardware and its assembly into an output event.

While all the low level routines needed to construct the readout program are made public, the general user should find it sufficient to call BFR_rop_configure.

ROI
---
The readout image contains all the modular aspects of the readout. In particular, in addition to carrying along all the information of a ROP, it also carries prototypes to perform the hardware acquisition and an array of the sizes of any variable length data.

These first three calls are initialization calls In principle, one could get more than one ROI. That way one could continue to build up multiple readouts, before performing them.

In practice, I do not know whether this is a good idea or not. But from a modularity viewpoint, it seems right. I suspect that the right way to do this is to construct one ROI and keep appending to it, ie. perform multiple BFR_roi_read0's.

     rop = BFR_rop_configure (ro_list, .... ); /- Specify input and output  -/
     roi = BFR_roi_construct (rop);            /- Construct an ROI instance -/
     mcb = BFA_get           (pool_size, max); /- Get a memory pool         -/

     BFR_roi_complete0 (roi, nread, nsequence, ...);
     BFR_roi_read0 (roi);      /- Performs the first phase of reading   ... -/
                               /- specifically reads the lengths of any ... -/
                               /- variable size data                    ... -/
     BFR_roi_pend0 (roi, ...); /- Wait till done                        ... -/
  
     BFR_roi_complete1 (roi);  /- Can now construct DMA list            ... -/
                               /- since all sizes are now known             -/
     BFR_roi_pend1 (roi, ...); /- Wait till done                            -/

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.

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.

BFR.h File Reference

Defines

Typedefs

Functions

Detailed Description

Function Documentation