\hypertarget{control_8h}{
\section{control.h File Reference}
\label{control_8h}\index{control.h@{control.h}}
}
The control functions coordinate the activities of the calibration package. 

{\tt \#include \char`\"{}LCI/lci.h\char`\"{}}\par
{\tt \#include \char`\"{}ITC/ITC\_\-pubdefs.h\char`\"{}}\par
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{control_8h_40322e35bea571c2bacd12d2a52ce720}{
typedef struct \hyperlink{struct__LCI__controller}{\_\-LCI\_\-controller} \hyperlink{control_8h_40322e35bea571c2bacd12d2a52ce720}{LCI\_\-controller}}
\label{control_8h_40322e35bea571c2bacd12d2a52ce720}

\begin{CompactList}\small\item\em Declaration of the opaque controller structure. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void \hyperlink{control_8h_fcbf0f417b3621f3890f945515149aa7}{LCI\_\-abort} (void)
\begin{CompactList}\small\item\em Abort a calibration. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_c8845f2cdd3fa2018106b9e6bd54fbe9}{LCI\_\-calibrate} (unsigned latccfg, unsigned lcicfg, unsigned lcirunid, ITC\_\-NodeID iniNode, ITC\_\-TaskID iniTask, ITC\_\-QueueID iniQueue)
\begin{CompactList}\small\item\em Start a new calibration. \item\end{CompactList}\item 
\hypertarget{control_8h_616280fc0e3ad9f57cae38ae9ae58b41}{
void \textbf{LCI\_\-cb\_\-statusFree} (ITC\_\-QueueItem $\ast$qitem, unsigned status, void $\ast$prm0, void $\ast$prm1, void $\ast$prm2, unsigned tx)}
\label{control_8h_616280fc0e3ad9f57cae38ae9ae58b41}

\item 
unsigned \hyperlink{control_8h_defc818848c6f17bb096455177ad34ed}{LCI\_\-comp} (unsigned comp)
\begin{CompactList}\small\item\em Set the calibration compression level. \item\end{CompactList}\item 
\hypertarget{control_8h_14335a97a2017b5dc317cc6ecc112d00}{
unsigned \textbf{LCI\_\-cycle} (void $\ast$prm, const struct \hyperlink{struct__ITC__QueueItem}{\_\-ITC\_\-QueueItem} $\ast$qitem, void $\ast$pay, unsigned len)}
\label{control_8h_14335a97a2017b5dc317cc6ecc112d00}

\item 
unsigned \hyperlink{control_8h_909c3b4b041de8bfb062510e084fc793}{LCI\_\-cycles} (void)
\begin{CompactList}\small\item\em Get the calibration cycle count. \item\end{CompactList}\item 
void \hyperlink{control_8h_d710fdeaf0a0093fe3cea760c7a0ad67}{LCI\_\-deleteController} (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$cnt)
\begin{CompactList}\small\item\em Free the calibration controller structure. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_0a2dd589898b35c95b7f87855ed67ddb}{LCI\_\-init} (unsigned capacity, unsigned cpuid, unsigned srcid)
\begin{CompactList}\small\item\em Initialize the calibration system. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_b8c7c1df2b2bf96872e109c230d83937}{LCI\_\-monitor} (unsigned mon)
\begin{CompactList}\small\item\em Set the calibration monitoring level. \item\end{CompactList}\item 
\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ \hyperlink{control_8h_26ed3fab76f83fe71864791092b2db7f}{LCI\_\-newController} (unsigned cap, unsigned cpuid, unsigned srcid)
\begin{CompactList}\small\item\em Create calibration controller structure. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_90c1754fe33dbd8aa659d59b3734fcd1}{LCI\_\-start} (const TASK\_\-attr $\ast$attr)
\begin{CompactList}\small\item\em Start the LCI task. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_6de72ca775513507fbb19431949dc62b}{LCI\_\-startCycle} (void)
\begin{CompactList}\small\item\em Request the next calibration cycle. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_866532c88fb7c94bbea3082270718521}{LCI\_\-status} (void)
\begin{CompactList}\small\item\em Get the calibration state. \item\end{CompactList}\item 
unsigned \hyperlink{control_8h_850580a01eab761f5bc4ee718512c6cb}{LCI\_\-terminate} (unsigned status)
\begin{CompactList}\small\item\em Terminate a calibration. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
The control functions coordinate the activities of the calibration package. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\end{Desc}


\subsection{Function Documentation}
\hypertarget{control_8h_fcbf0f417b3621f3890f945515149aa7}{
\index{control.h@{control.h}!LCI_abort@{LCI\_\-abort}}
\index{LCI_abort@{LCI\_\-abort}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-abort (void)}}
\label{control_8h_fcbf0f417b3621f3890f945515149aa7}


Abort a calibration. 

This routine is called when an abort calibration telecommand is received. If the current state is calibrating, it changes the state to aborting \hypertarget{control_8h_c8845f2cdd3fa2018106b9e6bd54fbe9}{
\index{control.h@{control.h}!LCI_calibrate@{LCI\_\-calibrate}}
\index{LCI_calibrate@{LCI\_\-calibrate}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-calibrate (unsigned {\em latccfg}, unsigned {\em lcicfg}, unsigned {\em lcirunid}, ITC\_\-NodeID {\em iniNode}, ITC\_\-TaskID {\em iniTask}, ITC\_\-QueueID {\em iniQueue})}}
\label{control_8h_c8845f2cdd3fa2018106b9e6bd54fbe9}


Start a new calibration. 

This routine is called when a start calibration telecommand is received. It first uses LATC to perform an initial LAT configuration then peforms a configure, collect, compact, consign cycle for each LCI configuration in the LCI file.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em latccfg}]File ID for the LATC configuration master to use with this calibration\item[{\em lcicfg}]File ID for the LCI configuration file to use to drive this calibration\item[{\em lcirunid}]Run ID to use in the datagrams\item[{\em iniNode}]Node ID of the task that initiated the calibration (used to send a message back when the calibration completes)\item[{\em iniTask}]Task ID of the task that initiated the calibration (used to send a message back when the calibration completes)\item[{\em iniQueue}]ID of the queue that will receive the status message.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-STATE}]LCI is not in the correct state to start a calibration \item[{\em ITC\_\-ALOCFAIL}]Memory allocation failure \item[{\em ITC\_\-FPAGET}]Memory allocation from FPA failed \item[{\em ITC\_\-SENDNID}]Invalid/unreachable destination node \item[{\em ITC\_\-SENDQID}]Invalid/unreachable destination queue \item[{\em ITC\_\-SHRMEM}]Shared memory pool stopping/stopped \item[{\em ITC\_\-SUCCESS}]If an item is sent to the LCI bulk queue \end{description}
\end{Desc}
\hypertarget{control_8h_defc818848c6f17bb096455177ad34ed}{
\index{control.h@{control.h}!LCI_comp@{LCI\_\-comp}}
\index{LCI_comp@{LCI\_\-comp}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-comp (unsigned {\em comp})}}
\label{control_8h_defc818848c6f17bb096455177ad34ed}


Set the calibration compression level. 

This routine sets the LCI compression level and returns the old value. This feature is used only for testing.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em comp}]Compression level to set\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Previous compression level \end{Desc}
\hypertarget{control_8h_909c3b4b041de8bfb062510e084fc793}{
\index{control.h@{control.h}!LCI_cycles@{LCI\_\-cycles}}
\index{LCI_cycles@{LCI\_\-cycles}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-cycles (void)}}
\label{control_8h_909c3b4b041de8bfb062510e084fc793}


Get the calibration cycle count. 

This rouine returns the number of cycles performed since the last calibration command was issued.

\begin{Desc}
\item[Returns:]Number of cycles performed since the last command to calibrate was issued \end{Desc}
\hypertarget{control_8h_d710fdeaf0a0093fe3cea760c7a0ad67}{
\index{control.h@{control.h}!LCI_deleteController@{LCI\_\-deleteController}}
\index{LCI_deleteController@{LCI\_\-deleteController}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-deleteController ({\bf LCI\_\-controller} $\ast$ {\em cnt})}}
\label{control_8h_d710fdeaf0a0093fe3cea760c7a0ad67}


Free the calibration controller structure. 

This routine frees all the resources associated with the LCI task. \hypertarget{control_8h_0a2dd589898b35c95b7f87855ed67ddb}{
\index{control.h@{control.h}!LCI_init@{LCI\_\-init}}
\index{LCI_init@{LCI\_\-init}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-init (unsigned {\em capacity}, unsigned {\em cpuid}, unsigned {\em srcid})}}
\label{control_8h_0a2dd589898b35c95b7f87855ed67ddb}


Initialize the calibration system. 

This routine performs resource allocation, initializes the ITC message queues, and sets the state to INITIALISED.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em srcid}]ID of the source of data being processed through LCI\item[{\em cpuid}]ID of the CPU LCI is being run on\item[{\em capacity}]Maximum number of events per calibration cycle.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]LCI\_\-SUCCESS if all goes well, otherwise one of many errors from LCI (typically LCI\_\-MEMERROR if an allocation fails), PBS, IMM or ITC. \end{Desc}
\hypertarget{control_8h_b8c7c1df2b2bf96872e109c230d83937}{
\index{control.h@{control.h}!LCI_monitor@{LCI\_\-monitor}}
\index{LCI_monitor@{LCI\_\-monitor}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-monitor (unsigned {\em mon})}}
\label{control_8h_b8c7c1df2b2bf96872e109c230d83937}


Set the calibration monitoring level. 

This routine sets the LCI monitoring level and returns the old value.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em mon}]Monitoring level to set\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Previous monitoring level \end{Desc}
\hypertarget{control_8h_26ed3fab76f83fe71864791092b2db7f}{
\index{control.h@{control.h}!LCI_newController@{LCI\_\-newController}}
\index{LCI_newController@{LCI\_\-newController}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf LCI\_\-controller}$\ast$ LCI\_\-newController (unsigned {\em cap}, unsigned {\em cpuid}, unsigned {\em srcid})}}
\label{control_8h_26ed3fab76f83fe71864791092b2db7f}


Create calibration controller structure. 

This routine allocates memory for an LCI\_\-controller structure and all associated structures.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em srcid}]ID of the source of data being processed through LCI\item[{\em cpuid}]ID of the CPU LCI is being run on\item[{\em cap}]Capacity of the calibration task, the maximum number of events that can be collected each cycle\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to a new LCI\_\-controller \end{Desc}
\hypertarget{control_8h_90c1754fe33dbd8aa659d59b3734fcd1}{
\index{control.h@{control.h}!LCI_start@{LCI\_\-start}}
\index{LCI_start@{LCI\_\-start}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-start (const TASK\_\-attr $\ast$ {\em attr})}}
\label{control_8h_90c1754fe33dbd8aa659d59b3734fcd1}


Start the LCI task. 

This routine starts the LCI task and waits for it be up and running before setting the state to WAITING.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em attr}]Task attributes to use for the LCI task.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Error status code from ITC\_\-startTaskW, LCI\_\-STATE if the state is not INITIALISED, LCI\_\-ATTRIBS if the task attribute pointer is NULL or LCI\_\-SUCCESS if all goes well. \end{Desc}
\hypertarget{control_8h_6de72ca775513507fbb19431949dc62b}{
\index{control.h@{control.h}!LCI_startCycle@{LCI\_\-startCycle}}
\index{LCI_startCycle@{LCI\_\-startCycle}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-startCycle (void)}}
\label{control_8h_6de72ca775513507fbb19431949dc62b}


Request the next calibration cycle. 

This routine is called whenever the next (or first) calibration cycle is to be performed. It puts an empty item to the LCI bulk queue to initiate the cycle. This indirection is needed to allow any abort requests to be processed in a timely manner.

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-QITEM}]The attempt to allocate a QueueItem fails \item[{\em ITC\_\-ALOCFAIL}]Memory allocation failure \item[{\em ITC\_\-FPAGET}]Memory allocation from FPA failed \item[{\em ITC\_\-SENDNID}]Invalid/unreachable destination node \item[{\em ITC\_\-SENDQID}]Invalid/unreachable destination queue \item[{\em ITC\_\-SHRMEM}]Shared memory pool stopping/stopped \item[{\em ITC\_\-SUCCESS}]If an item is sent to the LCI bulk queue \end{description}
\end{Desc}


!!! KULDGE - ITC won't accept a NULL payload pointer. \hypertarget{control_8h_866532c88fb7c94bbea3082270718521}{
\index{control.h@{control.h}!LCI_status@{LCI\_\-status}}
\index{LCI_status@{LCI\_\-status}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-status (void)}}
\label{control_8h_866532c88fb7c94bbea3082270718521}


Get the calibration state. 

This routine returns the current state of LCI.

\begin{Desc}
\item[Returns:]Current state of LCI \end{Desc}
\hypertarget{control_8h_850580a01eab761f5bc4ee718512c6cb}{
\index{control.h@{control.h}!LCI_terminate@{LCI\_\-terminate}}
\index{LCI_terminate@{LCI\_\-terminate}!control.h@{control.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-terminate (unsigned {\em status})}}
\label{control_8h_850580a01eab761f5bc4ee718512c6cb}


Terminate a calibration. 

This routine finishes out the calibration by sending a status message back to the originating task and setting the state to WAITING.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em status}]Termination status of the last calibration cycle, and hence of the whole calibration\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-QITEM}]The attempt to allocate a QueueItem fails \item[{\em ITC\_\-ALOCFAIL}]Memory allocation failure \item[{\em ITC\_\-FPAGET}]Memory allocation from FPA failed \item[{\em ITC\_\-SENDNID}]Invalid/unreachable destination node \item[{\em ITC\_\-SENDQID}]Invalid/unreachable destination queue \item[{\em ITC\_\-SHRMEM}]Shared memory pool stopping/stopped \item[{\em ITC\_\-SUCCESS}]If the item is sent \end{description}
\end{Desc}