\hypertarget{BFR_8h}{ \section{BFR.h File Reference} \label{BFR_8h}\index{BFR.h@{BFR.h}} } Balloon Flight Readout, Interface. {\tt \#include \char`\"{}BFU/BFR\_\-ids.h\char`\"{}}\par \subsection*{Defines} \begin{CompactItemize} \item \hypertarget{BFR_8h_a0}{ \index{BFR_C_SUCCESS@{BFR\_\-C\_\-SUCCESS}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_C_SUCCESS@{BFR\_\-C\_\-SUCCESS}} \#define \hyperlink{BFR_8h_a0}{BFR\_\-C\_\-SUCCESS}\ 0} \label{BFR_8h_a0} \begin{CompactList}\small\item\em Indicates the routine succeeded.\item\end{CompactList}\item \hypertarget{BFR_8h_a1}{ \index{BFR_C_TOOMANY@{BFR\_\-C\_\-TOOMANY}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_C_TOOMANY@{BFR\_\-C\_\-TOOMANY}} \#define \hyperlink{BFR_8h_a1}{BFR\_\-C\_\-TOOMANY}\ -1} \label{BFR_8h_a1} \begin{CompactList}\small\item\em Attempt to allocate too many ro descriptors.\item\end{CompactList}\item \hypertarget{BFR_8h_a2}{ \index{BFR_C_DUPLICATE@{BFR\_\-C\_\-DUPLICATE}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_C_DUPLICATE@{BFR\_\-C\_\-DUPLICATE}} \#define \hyperlink{BFR_8h_a2}{BFR\_\-C\_\-DUPLICATE}\ -2} \label{BFR_8h_a2} \begin{CompactList}\small\item\em Attempt to add an existing ro descriptor.\item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{BFR_8h_a3}{ \index{BFR_rdRtn@{BFR\_\-rdRtn}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_rdRtn@{BFR\_\-rd\-Rtn}} typedef int($\ast$ \hyperlink{BFR_8h_a3}{BFR\_\-rd\-Rtn} )(void $\ast$rd\-Prm, int sequence, void $\ast$dst, int len)} \label{BFR_8h_a3} \begin{CompactList}\small\item\em The callback signature to add a user defined record to the input data.\item\end{CompactList}\item \hypertarget{BFR_8h_a4}{ \index{BFR_rop@{BFR\_\-rop}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_rop@{BFR\_\-rop}} typedef \hyperlink{struct__BFR__rop}{\_\-BFR\_\-rop} \hyperlink{BFR_8h_a4}{BFR\_\-rop}} \label{BFR_8h_a4} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__BFR__rop}{\_\-BFR\_\-rop}.\item\end{CompactList}\item \hypertarget{BFR_8h_a5}{ \index{BFR_roi@{BFR\_\-roi}!BFR.h@{BFR.h}}\index{BFR.h@{BFR.h}!BFR_roi@{BFR\_\-roi}} typedef \hyperlink{struct__BFR__roi}{\_\-BFR\_\-roi} \hyperlink{BFR_8h_a5}{BFR\_\-roi}} \label{BFR_8h_a5} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__BFR__roi}{\_\-BFR\_\-roi}.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{BFR_8h_a6}{BFR\_\-rop\_\-sizeof} (int rod\_\-max) \begin{CompactList}\small\item\em Calculates the size of a BFR readout control structure which can hold {\em rod\_\-max} readout descriptors.\item\end{CompactList}\item \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ \hyperlink{BFR_8h_a7}{BFR\_\-rop\_\-get} (int rod\_\-max) \begin{CompactList}\small\item\em Allocates a BFR readout control structure which can hold {\em rod\_\-max} readout descriptors.\item\end{CompactList}\item \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ \hyperlink{BFR_8h_a8}{BFR\_\-rop\_\-init} (\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$rop, unsigned int hdr\_\-id, int rod\_\-max, unsigned int tlr\_\-id, int sum\_\-cnt, int sum\_\-size) \begin{CompactList}\small\item\em Initializes a previously allocated readout program.\item\end{CompactList}\item const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ \hyperlink{BFR_8h_a9}{BFR\_\-rop\_\-configure} (unsigned int hdr\_\-id, unsigned int ro\_\-list, unsigned int tlr\_\-id, int sum\_\-cnt, int sum\_\-size, const \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} $\ast$output\_\-order, const \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} $\ast$input\_\-order, const unsigned int $\ast$ivte\_\-ids, const int $\ast$data\_\-sizes, const unsigned int $\ast$tem\_\-vmes, const int $\ast$data\_\-fifos, const int $\ast$size\_\-fifos, const \hyperlink{BFR_8h_a3}{BFR\_\-rd\-Rtn} $\ast$rd\-Rtns, void $\ast$const $\ast$rd\-Prms) \begin{CompactList}\small\item\em High level routine to construct a readout program.\item\end{CompactList}\item void \hyperlink{BFR_8h_a10}{BFR\_\-rop\_\-print} (const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$rop) \begin{CompactList}\small\item\em Diagnostic routine to print the contents of an readout program. {\em rod\_\-max} readout descriptors.\item\end{CompactList}\item int \hyperlink{BFR_8h_a11}{BFR\_\-rod\_\-add} (\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$rop, int input, \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} rid, unsigned int id, int size, unsigned int data\_\-fifo, unsigned int size\_\-fifo, \hyperlink{BFR_8h_a3}{BFR\_\-rd\-Rtn} rd\-Rtn, void $\ast$rd\-Prm) \begin{CompactList}\small\item\em Adds a readout descriptor to the readout program.\item\end{CompactList}\item \hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ \hyperlink{BFR_8h_a12}{BFR\_\-roi\_\-construct} (const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$rop) \begin{CompactList}\small\item\em Constructs a template readout image from an readout program.\item\end{CompactList}\item void \hyperlink{BFR_8h_a13}{BFR\_\-roi\_\-print} (const \hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Diagnostic print routine to display the contents of a readout image.\item\end{CompactList}\item int \hyperlink{BFR_8h_a14}{BFR\_\-roi\_\-bind0} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi, int nread, unsigned int sequence) \begin{CompactList}\small\item\em Does the phase 0 of binding the readout image to a specific readout instance.\item\end{CompactList}\item int \hyperlink{BFR_8h_a15}{BFR\_\-roi\_\-read0} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Does phase 0 of reading out the event.\item\end{CompactList}\item int \hyperlink{BFR_8h_a16}{BFR\_\-roi\_\-pend0} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Waits for any asynchronous activity associated with the 0th phase of the readout to complete.\item\end{CompactList}\item int \hyperlink{BFR_8h_a17}{BFR\_\-roi\_\-bind1} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$acb) \begin{CompactList}\small\item\em Does the phase1 of binding the readout image to a specific readout instance.\item\end{CompactList}\item int \hyperlink{BFR_8h_a18}{BFR\_\-roi\_\-read1} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Does the first phase of reading out the event.\item\end{CompactList}\item int \hyperlink{BFR_8h_a19}{BFR\_\-roi\_\-pend1} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Waits for any asynchronous activity associated with the phase 1 of the readout to complete.\item\end{CompactList}\item int \hyperlink{BFR_8h_a20}{BFR\_\-roi\_\-copy1} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$acb) \begin{CompactList}\small\item\em Completes the output record by copying an indirectly read data into the output record.\item\end{CompactList}\item int \hyperlink{BFR_8h_a21}{BFR\_\-roi\_\-finish} (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$acb) \begin{CompactList}\small\item\em Performs any work needed after the event and all summary information has been read in.\item\end{CompactList}\item \hyperlink{struct__BFU__fileDsc}{\_\-BFU\_\-file\-Dsc} $\ast$ \hyperlink{BFR_8h_a22}{BFR\_\-roi\_\-evt\-Dsc\-Get} (const \hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$roi) \begin{CompactList}\small\item\em Returns a pointer to an event descriptor structure.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Balloon Flight Readout, Interface. \begin{Desc} \item[Author: ]\par JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} {\bf ABSTRACT} \par {\bf --------} \par Services to construct a BFR readout program. This data structure contains all the static information necessary to perform both the readin from the hardware and control where the data appears in the output record. {\bf DESCRIPTION} \par {\bf -----------} \par There are 2 data structures being managed. ROP - readout program ROI - readout image {\bf ROP} \par {\bf ---} \par 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. {\bf ROI} \par {\bf ---} \par 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. {\bf USAGE} \par {\bf -----} \par The general flow is 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. \footnotesize\begin{verbatim} 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 -/ \end{verbatim}\normalsize When it time to go read the events, do \footnotesize\begin{verbatim} 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 -/ \end{verbatim}\normalsize \subsection{Function Documentation} \hypertarget{BFR_8h_a11}{ \index{BFR.h@{BFR.h}!BFR_rod_add@{BFR\_\-rod\_\-add}} \index{BFR_rod_add@{BFR\_\-rod\_\-add}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rod\_\-add]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-rod\_\-add (\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ {\em rop}, int {\em input}, \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} {\em rid}, unsigned int {\em id}, int {\em size}, unsigned int {\em data\_\-fifo}, unsigned int {\em size\_\-fifo}, \hyperlink{BFR_8h_a3}{BFR\_\-rd\-Rtn} {\em rd\-Rtns}, void $\ast$ {\em rd\-Prms})}} \label{BFR_8h_a11} Adds a readout descriptor to the readout program. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rop}]A pointer to a previously initialized readout program. \item[{\em input}]The order this should be readin. For example, if this number is 0, then this is the first data read from the hardware. \item[{\em rid}]The internal BFR identifier for this readout descriptor. \item[{\em id}]The 4 byte IVTE identifier. \item[{\em 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. \item[{\em data\_\-fifo}]The VME address of the data fifo. Use the low bit to specify SUPERVISOR access. \item[{\em size\_\-fifo}]The VME address of the size fifo (use -1 if non). Use the low bit to specify SUPERVISOR access. \end{description} \end{Desc} \begin{Desc} \item[Return values: ]\par \begin{description} \item[{\em BFR\_\-C\_\-SUCCESS, if}]okay. \item[{\em BFR\_\-C\_\-TOOMANY, if}]too have exhausted the readout descriptors. \item[{\em BFR\_\-C\_\-DUPLICATE, if}]an attempt is made to add an existing descriptor.\end{description} \end{Desc} 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 \hyperlink{BFR_8h_a9}{BFR\_\-rop\_\-configure}(). \hypertarget{BFR_8h_a14}{ \index{BFR.h@{BFR.h}!BFR_roi_bind0@{BFR\_\-roi\_\-bind0}} \index{BFR_roi_bind0@{BFR\_\-roi\_\-bind0}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-bind0]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-bind0 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi}, int {\em nread}, unsigned int {\em sequence})}} \label{BFR_8h_a14} Does the phase 0 of binding the readout image to a specific readout instance. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be bound. \item[{\em nread}]The number of events to read out. \item[{\em sequence}]The beginning event sequence number. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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. \hypertarget{BFR_8h_a17}{ \index{BFR.h@{BFR.h}!BFR_roi_bind1@{BFR\_\-roi\_\-bind1}} \index{BFR_roi_bind1@{BFR\_\-roi\_\-bind1}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-bind1]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-bind1 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi}, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$ {\em acb})}} \label{BFR_8h_a17} Does the phase1 of binding the readout image to a specific readout instance. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be bound. \item[{\em acb}]Handle to the Balloon Flight memory Allocator \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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. \hypertarget{BFR_8h_a12}{ \index{BFR.h@{BFR.h}!BFR_roi_construct@{BFR\_\-roi\_\-construct}} \index{BFR_roi_construct@{BFR\_\-roi\_\-construct}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-construct]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ BFR\_\-roi\_\-construct (const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ {\em rop})}} \label{BFR_8h_a12} Constructs a template readout image from an readout program. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rop}]The readout program to base the readout image on. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Pointer to the newly constructed readout image.\end{Desc} 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. \hypertarget{BFR_8h_a20}{ \index{BFR.h@{BFR.h}!BFR_roi_copy1@{BFR\_\-roi\_\-copy1}} \index{BFR_roi_copy1@{BFR\_\-roi\_\-copy1}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-copy1]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-copy1 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi}, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$ {\em acb})}} \label{BFR_8h_a20} Completes the output record by copying an indirectly read data into the output record. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be copied. This must be bound through phase 1 using \hyperlink{BFR_8h_a17}{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 \item[{\em acb}]The allocation control block. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status. \end{Desc} \hypertarget{BFR_8h_a22}{ \index{BFR.h@{BFR.h}!BFR_roi_evtDscGet@{BFR\_\-roi\_\-evtDscGet}} \index{BFR_roi_evtDscGet@{BFR\_\-roi\_\-evtDscGet}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-evtDscGet]{\setlength{\rightskip}{0pt plus 5cm}const struct \_\-BFR\_\-evt\-Dsc $\ast$ BFR\_\-roi\_\-evt\-Dsc\-Get (const \hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a22} Returns a pointer to an event descriptor structure. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image containing the event descriptor. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the structure describing the last sequence of events taken.\end{Desc} 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. \hypertarget{BFR_8h_a21}{ \index{BFR.h@{BFR.h}!BFR_roi_finish@{BFR\_\-roi\_\-finish}} \index{BFR_roi_finish@{BFR\_\-roi\_\-finish}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-finish]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-finish (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi}, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$ {\em acb})}} \label{BFR_8h_a21} Performs any work needed after the event and all summary information has been read in. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be copied. This must be bound through phase 1 using \hyperlink{BFR_8h_a17}{BFR\_\-roi\_\-bind1}() and a \hyperlink{BFR_8h_a18}{BFR\_\-roi\_\-read1}() must have been called to initiate the read. \hyperlink{BFR_8h_a19}{BFR\_\-roi\_\-pend1}() must also have been called to ensure the read has completed and BFR\_\-roi\_\-copy1 to move the indirect data. \item[{\em acb}]The allocation control block. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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. \hypertarget{BFR_8h_a16}{ \index{BFR.h@{BFR.h}!BFR_roi_pend0@{BFR\_\-roi\_\-pend0}} \index{BFR_roi_pend0@{BFR\_\-roi\_\-pend0}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-pend0]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-pend0 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a16} Waits for any asynchronous activity associated with the 0th phase of the readout to complete. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em 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. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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 \hyperlink{BFR_8h_a16}{BFR\_\-roi\_\-pend0}() gives this the same look and feel as the next phase of readout. \hypertarget{BFR_8h_a19}{ \index{BFR.h@{BFR.h}!BFR_roi_pend1@{BFR\_\-roi\_\-pend1}} \index{BFR_roi_pend1@{BFR\_\-roi\_\-pend1}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-pend1]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-pend1 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a19} Waits for any asynchronous activity associated with the phase 1 of the readout to complete. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em 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. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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 \hyperlink{BFR_8h_a18}{BFR\_\-roi\_\-read1}(). \hypertarget{BFR_8h_a13}{ \index{BFR.h@{BFR.h}!BFR_roi_print@{BFR\_\-roi\_\-print}} \index{BFR_roi_print@{BFR\_\-roi\_\-print}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-print]{\setlength{\rightskip}{0pt plus 5cm}void BFR\_\-roi\_\-print (const \hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a13} Diagnostic print routine to display the contents of a readout image. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be displayed.\end{description} \end{Desc} This routine is primarily used for diagnostics and debugging. \hypertarget{BFR_8h_a15}{ \index{BFR.h@{BFR.h}!BFR_roi_read0@{BFR\_\-roi\_\-read0}} \index{BFR_roi_read0@{BFR\_\-roi\_\-read0}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-read0]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-read0 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a15} Does phase 0 of reading out the event. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be read. This must be bound through phase 0. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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 \hyperlink{BFR_8h_a16}{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 \hyperlink{BFR_8h_a16}{BFR\_\-roi\_\-pend0}() gives this the same look and feel as the next phase of readout. \hypertarget{BFR_8h_a18}{ \index{BFR.h@{BFR.h}!BFR_roi_read1@{BFR\_\-roi\_\-read1}} \index{BFR_roi_read1@{BFR\_\-roi\_\-read1}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-roi\_\-read1]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-roi\_\-read1 (\hyperlink{BFR_8h_a5}{BFR\_\-roi} $\ast$ {\em roi})}} \label{BFR_8h_a18} Does the first phase of reading out the event. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em roi}]Handle to the Readout image to be read. This must be bound through phase 1. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status.\end{Desc} 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. \hypertarget{BFR_8h_a9}{ \index{BFR.h@{BFR.h}!BFR_rop_configure@{BFR\_\-rop\_\-configure}} \index{BFR_rop_configure@{BFR\_\-rop\_\-configure}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rop\_\-configure]{\setlength{\rightskip}{0pt plus 5cm}const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ BFR\_\-rop\_\-configure (unsigned int {\em hdr\_\-id}, unsigned int {\em ro\_\-list}, unsigned int {\em tlr\_\-id}, int {\em sum\_\-cnt}, int {\em sum\_\-size}, const \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} $\ast$ {\em output\_\-order}, const \hyperlink{BFR__ids_8h_a0}{BFR\_\-id} $\ast$ {\em input\_\-order}, const unsigned int $\ast$ {\em ivte\_\-ids}, const int $\ast$ {\em data\_\-sizes}, const unsigned int $\ast$ {\em tem\_\-vmes}, const int $\ast$ {\em data\_\-fifos}, const int $\ast$ {\em size\_\-fifos}, const \hyperlink{BFR_8h_a3}{BFR\_\-rd\-Rtn} $\ast$ {\em rd\-Rtns}, void $\ast$const $\ast$ {\em rd\-Prms})}} \label{BFR_8h_a9} High level routine to construct a readout program. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em hdr\_\-id}]The id to use in the event header. \item[{\em ro\_\-list}]The list or readout ids to be used. \item[{\em tlr\_\-id}]The id to use in the event trailer. \item[{\em sum\_\-cnt}]Number of summary records (really record descriptors) to be reserved at the end for user summary data. \item[{\em sum\_\-size}]The size of all the summary records. This must be a fixed sized to be shared.\item[{\em output\_\-order}]This is an array, indexed by readout id, which specifies the relative position of this data in the output event. \item[{\em input\_\-order}]This is an array, indexed by readout id, which specifies the relative order that this data element will be acquired. \item[{\em ivte\_\-ids}]This is an array, indexed by readout id, which specifies the IVTE ID to be used for this data. \item[{\em 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. \item[{\em tem\_\-vmes}]This is an array, indexed by readout id, which specifies the base VME address of this data. \item[{\em data\_\-fifos}]This is an array, indexed by readout id, which specifies the offset of the data fifo. \item[{\em 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. \item[{\em rd\-Rtns}]Array of special read routines indexed by rid \item[{\em rd\-Prms}]Parameters passed to read routines \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par If successful, a pointer to the readout program. Else NULL.\end{Desc} The only practical reason that this may fail is bad input arguments or insufficient memory. \hypertarget{BFR_8h_a7}{ \index{BFR.h@{BFR.h}!BFR_rop_get@{BFR\_\-rop\_\-get}} \index{BFR_rop_get@{BFR\_\-rop\_\-get}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rop\_\-get]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ BFR\_\-rop\_\-get (int {\em rod\_\-max})}} \label{BFR_8h_a7} Allocates a BFR readout control structure which can hold {\em rod\_\-max} readout descriptors. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rod\_\-max}]The maximum number of readout descriptors that will every be used. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par 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.\end{Desc} 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. \hypertarget{BFR_8h_a8}{ \index{BFR.h@{BFR.h}!BFR_rop_init@{BFR\_\-rop\_\-init}} \index{BFR_rop_init@{BFR\_\-rop\_\-init}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rop\_\-init]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ BFR\_\-rop\_\-init (\hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ {\em rop}, unsigned int {\em hdr\_\-id}, int {\em rod\_\-max}, unsigned int {\em tlr\_\-id}, int {\em sum\_\-cnt}, int {\em sum\_\-size})}} \label{BFR_8h_a8} Initializes a previously allocated readout program. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rop}]Pointer to the BFR readout control structure to initialize. \item[{\em hdr\_\-id}]The id to use for the IVTE header. \item[{\em rod\_\-max}]Maximum number of readout descriptors. \item[{\em tlr\_\-id}]The id to use for the IVTE trailer. \item[{\em sum\_\-cnt}]Number of summary records (really record descriptors) to be reserved at the end for user summary data. \item[{\em sum\_\-size}]The size of all the summary records. This must be a fixed sized to be shared. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the initialized BFR readout control structure or NULL if the initialization failed.\end{Desc} 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 \hypertarget{BFR_8h_a10}{ \index{BFR.h@{BFR.h}!BFR_rop_print@{BFR\_\-rop\_\-print}} \index{BFR_rop_print@{BFR\_\-rop\_\-print}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rop\_\-print]{\setlength{\rightskip}{0pt plus 5cm}void BFR\_\-rop\_\-print (const \hyperlink{BFR_8h_a4}{BFR\_\-rop} $\ast$ {\em rop})}} \label{BFR_8h_a10} Diagnostic routine to print the contents of an readout program. {\em rod\_\-max} readout descriptors. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rop}]The readout program to print. \end{description} \end{Desc} \hypertarget{BFR_8h_a6}{ \index{BFR.h@{BFR.h}!BFR_rop_sizeof@{BFR\_\-rop\_\-sizeof}} \index{BFR_rop_sizeof@{BFR\_\-rop\_\-sizeof}!BFR.h@{BFR.h}} \subsubsection[BFR\_\-rop\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int BFR\_\-rop\_\-sizeof (int {\em rod\_\-max})}} \label{BFR_8h_a6} Calculates the size of a BFR readout control structure which can hold {\em rod\_\-max} readout descriptors. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em rod\_\-max}]The maximum number of readout descriptors that will every be used. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The size (in bytes) of a readout control structure large enough to hold a rod\_\-max readout descriptors.\end{Desc} 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.