\hypertarget{EFA_8c}{
\section{EFA.c File Reference}
\label{EFA_8c}\index{EFA.c@{EFA.c}}
}
Implementation of the event analysis handling facility. 

{\tt \#include \char`\"{}EFA\_\-p.h\char`\"{}}\par
{\tt \#include \char`\"{}EFC\_\-time.ih\char`\"{}}\par
{\tt \#include \char`\"{}EDS/EDS\_\-cfg.h\char`\"{}}\par
{\tt \#include \char`\"{}LSF/LSF\_\-reason.h\char`\"{}}\par
{\tt \#include \char`\"{}dprintf.h\char`\"{}}\par
{\tt \#include \char`\"{}EFA\_\-synch.c\char`\"{}}\par


Include dependency graph for EFA.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=308pt]{EFA_8c__incl}
\end{center}
\end{figure}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define \hyperlink{EFA_8c_a0}{PAUSED}
\begin{CompactList}\small\item\em Defines a bit mask representing which close reasons will force the state to paused. \item\end{CompactList}\item 
\#define \hyperlink{EFA_8c_a1}{STOPPED}
\begin{CompactList}\small\item\em Defines a bit mask representing which close reasons will force the state to stopped. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
\hypertarget{EFA_8c_a2}{
static \_\-\_\-inline void \hyperlink{EFA_8c_a2}{efa\_\-get\_\-new\_\-packet} (\hyperlink{struct__EFA}{EFA} $\ast$efa)}
\label{EFA_8c_a2}

\begin{CompactList}\small\item\em Gets a new packet after the current packet has been postedefa The Event Filter Analysis control handle. \item\end{CompactList}\item 
\hypertarget{EFA_8c_a3}{
static \_\-\_\-inline void \hyperlink{EFA_8c_a3}{efa\_\-compose\_\-end\_\-hdr} (\hyperlink{struct__EFA}{EFA} $\ast$efa)}
\label{EFA_8c_a3}

\begin{CompactList}\small\item\em Composes the end of sample header from the information of the last event efa The Event Filter Analysis control handle. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a4}{EFA\_\-enable} (\hyperlink{struct__EFA}{EFA} $\ast$efa, int enable)
\begin{CompactList}\small\item\em Enables/disables EFA. This can only be done outside the context of a run, i.e. the state must be STOPPED. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a5}{EFA\_\-sizeof} (int result\_\-size, int result\_\-cnt)
\begin{CompactList}\small\item\em Computes the size, in bytes, of the EFA control structure. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a6}{EFA\_\-result\-Sizeof} (const \hyperlink{struct__EFA}{EFA} $\ast$efa)
\begin{CompactList}\small\item\em Returns the size, in bytes, of one result vector. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a7}{EFA\_\-construct} (\hyperlink{struct__EFA}{EFA} $\ast$efa, void $\ast$pool, int enable, const \hyperlink{struct__EFA__services}{EFA\_\-services} $\ast$services, void $\ast$ctx, unsigned int size, unsigned int post\-Cnt, unsigned int flush\-Cnt)
\begin{CompactList}\small\item\em Set up the internal data structures of the EFA control structure. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a8}{EFA\_\-notify} (\hyperlink{struct__EFA}{EFA} $\ast$efa, int mode, const EDS\_\-cfg\-Info $\ast$cfg)
\begin{CompactList}\small\item\em Callback signature to notify an analyis routine of a mode change. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a9}{EFA\_\-flush} (\hyperlink{struct__EFA}{EFA} $\ast$efa, int reason)
\begin{CompactList}\small\item\em Forces a posting of the current results. \item\end{CompactList}\item 
void \hyperlink{EFA_8c_a10}{EFA\_\-postprocess} (\hyperlink{struct__EFA}{EFA} $\ast$efa)
\begin{CompactList}\small\item\em Processes a packet when it has been filled. This is just the logic to drive EFA\_\-flush. \item\end{CompactList}\item 
int \hyperlink{EFA_8c_a11}{EFA\_\-start} (\hyperlink{struct__EFA}{EFA} $\ast$efa, int reason, int run\_\-id, int start\-Time, int mode)
\begin{CompactList}\small\item\em Callback signature to start or prepare a posting stream to receive events. \item\end{CompactList}\item 
unsigned int \hyperlink{EFA_8c_a12}{EFA\_\-hdr\-Compose} (\hyperlink{struct__EFA__hdr}{EFA\_\-hdr} $\ast$hdr, unsigned int relative, unsigned long long seq, unsigned int gem\-Clock, unsigned int gem\-Strobe)
\begin{CompactList}\small\item\em Composes specified event header. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Implementation of the event analysis handling facility. 

\begin{Desc}
\item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}


\footnotesize\begin{verbatim}   CVS $Id: EFA.c,v 1.2 2007/11/02 18:20:27 russell Exp $
\end{verbatim}
\normalsize


Each filter is allowed to produced a vector of N 32-bits words which act as a summary of its results. The first word of this vector must be a 32-bit mask of the conditions.

This facility provides a framework to analyze these result vectors. Typically, these results are bundled into a vector of results and passed to an analysis routine. For example, EFS the generic statistics package, is an example of such a routine.

\begin{Desc}
\item[A word on the strategy in the asynchonous version]There are effectively two threads of execution that are important\begin{itemize}
\item The thread producing the data\item The thread processing the data\end{itemize}
\end{Desc}
\begin{Desc}
\item[]All EFA action routines, EFA\_\-start, EFA\_\-enable, EFA\_\-flush and EFA\_\-notify must be called within the thread producing the data. This ensures that the actions are synchronized to the production of the data. This means that all state changes are affected in this thread.\end{Desc}
\begin{Desc}
\item[]The thread processing the data is entirely invisible to the user and is there only to decouple the processing and disposition of the data. The only trick here is that the commands stopping the filling of the datagrams must be indivisibly tied with a flush. This is accomplished, in almost the backhanded way, of making the stop one of the flush reasons. Therefore, when a flush is issued with one of the stop run reasons, the asynchronous flush is posted to the data processing thread, then the state change is issued.\end{Desc}
\begin{Desc}
\item[Synchnonization]This implemenation forces a synchronization with the processing task when a flush with a stop run reason is issued only on host machines, but not on the embedded systems. This could cause problems {\em if\/} the system is shutdown, but avoids the more likely problem of stalling the event task on the synchronization.\end{Desc}


\subsection{Define Documentation}
\hypertarget{EFA_8c_a0}{
\index{EFA.c@{EFA.c}!PAUSED@{PAUSED}}
\index{PAUSED@{PAUSED}!EFA.c@{EFA.c}}
\subsubsection[PAUSED]{\setlength{\rightskip}{0pt plus 5cm}\#define PAUSED}}
\label{EFA_8c_a0}


{\bf Value:}

\footnotesize\begin{verbatim}((1<<LSF_REASON_CLOSE_K_PAUSE      )   \
               | (1<<LSF_REASON_CLOSE_K_PAUSE_OP   )   \
               | (1<<LSF_REASON_CLOSE_K_PAUSE_AUTO ))
\end{verbatim}\normalsize 
Defines a bit mask representing which close reasons will force the state to paused. 

\hypertarget{EFA_8c_a1}{
\index{EFA.c@{EFA.c}!STOPPED@{STOPPED}}
\index{STOPPED@{STOPPED}!EFA.c@{EFA.c}}
\subsubsection[STOPPED]{\setlength{\rightskip}{0pt plus 5cm}\#define STOPPED}}
\label{EFA_8c_a1}


{\bf Value:}

\footnotesize\begin{verbatim}((1<<LSF_REASON_CLOSE_K_STOP       )   \
                | (1<<LSF_REASON_CLOSE_K_STOP_OP    )   \
                | (1<<LSF_REASON_CLOSE_K_STOP_TIME  )   \
                | (1<<LSF_REASON_CLOSE_K_STOP_COUNT )   \
                | (1<<LSF_REASON_CLOSE_K_ABORT      )   \
                | (1<<LSF_REASON_CLOSE_K_ABORT_OP   )   \
                | (1<<LSF_REASON_CLOSE_K_ABORT_AUTO ))
\end{verbatim}\normalsize 
Defines a bit mask representing which close reasons will force the state to stopped. 



\subsection{Function Documentation}
\hypertarget{EFA_8c_a7}{
\index{EFA.c@{EFA.c}!EFA_construct@{EFA\_\-construct}}
\index{EFA_construct@{EFA\_\-construct}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-construct]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-construct (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa}, void $\ast$ {\em pool}, int {\em enable}, const \hyperlink{struct__EFA__services}{EFA\_\-services} $\ast$ {\em services}, void $\ast$ {\em ctx}, unsigned int {\em size}, unsigned int {\em post\-Cnt}, unsigned int {\em flush\-Cnt})}}
\label{EFA_8c_a7}


Set up the internal data structures of the EFA control structure. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0,Success}]\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The Event Filter Analysis control structure \item[{\em pool}]The memory pool \item[{\em enable}]1 if start in the enabled state, else start in the disabled state \item[{\em services}]The set of service routines \item[{\em ctx}]Arbitrary user context parameter passed to the user callback routines \item[{\em size}]The size of a result vector. This value should have been obtained by a call to EFA\_\-result\-Sizeof This routine checks that this value matches that from EFA\_\-result\-Sizeof. \item[{\em post\-Cnt}]The number of result vectors in a packet. This results in a process flush reason \item[{\em flush\-Cnt}]The number of result vectors before a flush is issued. This results in a process LSF\_\-REASON\_\-CLOSE\_\-K\_\-STOP\_\-CNT flush reason.\end{description}
\end{Desc}
\hypertarget{EFA_8c_a4}{
\index{EFA.c@{EFA.c}!EFA_enable@{EFA\_\-enable}}
\index{EFA_enable@{EFA\_\-enable}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-enable]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-enable (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa}, int {\em enable})}}
\label{EFA_8c_a4}


Enables/disables EFA. This can only be done outside the context of a run, i.e. the state must be STOPPED. 

\begin{Desc}
\item[Returns:]0, if successful 

-1, on failure.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The Event Filter Analysis control handle \item[{\em enable}]If non-zero, enable, if zero, disable\end{description}
\end{Desc}
\hypertarget{EFA_8c_a9}{
\index{EFA.c@{EFA.c}!EFA_flush@{EFA\_\-flush}}
\index{EFA_flush@{EFA\_\-flush}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-flush]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-flush (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa}, int {\em reason})}}
\label{EFA_8c_a9}


Forces a posting of the current results. 

\begin{Desc}
\item[Returns:]Status\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The event filter analysis control structure \item[{\em reason}]The reason flush is being called.\end{description}
\end{Desc}
\begin{Desc}
\item[]This routine is meant to flush any remaining result vectors, such as at the end of a run. There is no interlocking. If result vectors are still being accumulated, the caller must arrange such an interlocking mechanism.\end{Desc}
\hypertarget{EFA_8c_a12}{
\index{EFA.c@{EFA.c}!EFA_hdrCompose@{EFA\_\-hdrCompose}}
\index{EFA_hdrCompose@{EFA\_\-hdrCompose}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-hdrCompose]{\setlength{\rightskip}{0pt plus 5cm}unsigned int EFA\_\-hdr\-Compose (\hyperlink{struct__EFA__hdr}{EFA\_\-hdr} $\ast$ {\em hdr}, unsigned int {\em relative}, unsigned long long {\em seq}, unsigned int {\em gem\-Clock}, unsigned int {\em gem\-Strobe})}}
\label{EFA_8c_a12}


Composes specified event header. 

\begin{Desc}
\item[Returns:]The timetone's status flag word\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hdr}]Pointer to the target EFA\_\-hdr \item[{\em relative}]The relative (to the beginning of the buffer) event number (1 = first event) \item[{\em seq}]Extended seqence number of the event \item[{\em gem\-Clock}]Event clock register read from GEM contributor of event \item[{\em gem\-Strobe}]Event PPS cock register read from GEM contributor of event\end{description}
\end{Desc}
This is convenience routine to fill in event info that is stored in a EFA\_\-hdr structure within an LSF packet for eventual output as science data on the SSR.\hypertarget{EFA_8c_a8}{
\index{EFA.c@{EFA.c}!EFA_notify@{EFA\_\-notify}}
\index{EFA_notify@{EFA\_\-notify}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-notify]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-notify (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa}, int {\em mode}, const EDS\_\-cfg\-Info $\ast$ {\em cfg})}}
\label{EFA_8c_a8}


Callback signature to notify an analyis routine of a mode change. 

\begin{Desc}
\item[Returns:]0 is successful, non-zero otherwise\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The Event Filter Analysis control handle \item[{\em mode}]The new running mode. \item[{\em cfg}]The new configuration information\end{description}
\end{Desc}
\hypertarget{EFA_8c_a10}{
\index{EFA.c@{EFA.c}!EFA_postprocess@{EFA\_\-postprocess}}
\index{EFA_postprocess@{EFA\_\-postprocess}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-postprocess]{\setlength{\rightskip}{0pt plus 5cm}void EFA\_\-postprocess (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa})}}
\label{EFA_8c_a10}


Processes a packet when it has been filled. This is just the logic to drive EFA\_\-flush. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The event filter analysis control structure\end{description}
\end{Desc}
\hypertarget{EFA_8c_a6}{
\index{EFA.c@{EFA.c}!EFA_resultSizeof@{EFA\_\-resultSizeof}}
\index{EFA_resultSizeof@{EFA\_\-resultSizeof}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-resultSizeof]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-result\-Sizeof (const \hyperlink{struct__EFA}{EFA} $\ast$ {\em efa})}}
\label{EFA_8c_a6}


Returns the size, in bytes, of one result vector. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em The}]size, in bytes, of one result vector\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The Event Filter Analysis Control Block\end{description}
\end{Desc}
\hypertarget{EFA_8c_a5}{
\index{EFA.c@{EFA.c}!EFA_sizeof@{EFA\_\-sizeof}}
\index{EFA_sizeof@{EFA\_\-sizeof}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-sizeof (int {\em result\_\-size}, int {\em result\_\-cnt})}}
\label{EFA_8c_a5}


Computes the size, in bytes, of the EFA control structure. 

\begin{Desc}
\item[Returns:]The size, in bytes,\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em result\_\-size}]The size, in bytes, of one result vector \item[{\em result\_\-cnt}]The number of result vectors in one packet\end{description}
\end{Desc}
\hypertarget{EFA_8c_a11}{
\index{EFA.c@{EFA.c}!EFA_start@{EFA\_\-start}}
\index{EFA_start@{EFA\_\-start}!EFA.c@{EFA.c}}
\subsubsection[EFA\_\-start]{\setlength{\rightskip}{0pt plus 5cm}int EFA\_\-start (\hyperlink{struct__EFA}{EFA} $\ast$ {\em efa}, int {\em reason}, int {\em run\_\-id}, int {\em start\-Time}, int {\em mode})}}
\label{EFA_8c_a11}


Callback signature to start or prepare a posting stream to receive events. 

\begin{Desc}
\item[Returns:]0 is successful, non-zero otherwise\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em efa}]The Event Filter Analysis control handle \item[{\em reason}]The LSF\_\-REASON\_\-OPEN to indicate why the stream is being started \item[{\em run\_\-id}]Suggested use is to identify the block of events between when EDS\_\-fw\-Handler\-Start is called and EDS\_\-fw\-Handler\-Flush is called with a stop reason \item[{\em start\-Time}]The run start time rounded to the nearest second \item[{\em mode}]This must be the running mode.\end{description}
\end{Desc}
