\hypertarget{control_8c}{
\section{control.c File Reference}
\label{control_8c}\index{control.c@{control.c}}
}
Principal routines of the charge injection calibration utility. 

{\tt \#include \char`\"{}LCI/LCI\_\-msgs.h\char`\"{}}\par
{\tt \#include \char`\"{}LCI/LCI\_\-cmddefs.h\char`\"{}}\par
{\tt \#include \char`\"{}LCI/LCI\_\-cmdxtrn.h\char`\"{}}\par
{\tt \#include \char`\"{}control\_\-p.h\char`\"{}}\par
{\tt \#include \char`\"{}collect.h\char`\"{}}\par
{\tt \#include \char`\"{}configure.h\char`\"{}}\par
{\tt \#include \char`\"{}consign.h\char`\"{}}\par
{\tt \#include \char`\"{}macros\_\-p.h\char`\"{}}\par
{\tt \#include \char`\"{}CDM/CDM\_\-pubdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}CPU\_\-DB/CPU\_\-DB\_\-pubdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}EDS/EBF\_\-match.h\char`\"{}}\par
{\tt \#include \char`\"{}EDS/EBF\_\-cid.h\char`\"{}}\par
{\tt \#include \char`\"{}FBS/FBS\_\-pubrtos.h\char`\"{}}\par
{\tt \#include \char`\"{}CCSDS/CCSDS\_\-pkt.h\char`\"{}}\par
{\tt \#include \char`\"{}LCI\_\-DB/schema.h\char`\"{}}\par
{\tt \#include \char`\"{}LSF/LSF\_\-cpu.h\char`\"{}}\par
{\tt \#include \char`\"{}LSF/LSF\_\-origin.h\char`\"{}}\par
{\tt \#include \char`\"{}LSF/LSF\_\-reason.h\char`\"{}}\par
{\tt \#include \char`\"{}LSEC/compact.h\char`\"{}}\par
{\tt \#include \char`\"{}LATC/latc.h\char`\"{}}\par
{\tt \#include \char`\"{}MSG/MSG\_\-pubdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}ITC/ITC\_\-pubdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/BSWP.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/FPA.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/MBA.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/WCT.h\char`\"{}}\par
{\tt \#include $<$string.h$>$}\par


Include dependency graph for control.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=288pt]{control_8c__incl}
\end{center}
\end{figure}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\hypertarget{control_8c_a0}{
\#define \hyperlink{control_8c_a0}{FALSE}~0}
\label{control_8c_a0}

\begin{CompactList}\small\item\em FALSE defined to be 0. \item\end{CompactList}\item 
\hypertarget{control_8c_a1}{
\#define \hyperlink{control_8c_a1}{TRUE}~1}
\label{control_8c_a1}

\begin{CompactList}\small\item\em TRUE defined to be 1. \item\end{CompactList}\item 
\#define \hyperlink{control_8c_a2}{CHECK\_\-CALL\_\-TERMINATE}(FUNC)
\begin{CompactList}\small\item\em Call a function and check the return value, calling LCI\_\-terminate on error. \item\end{CompactList}\item 
\hypertarget{control_8c_a3}{
\#define {\bf inline}~\_\-\_\-inline}
\label{control_8c_a3}

\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \{ \par
{\bf LCI\_\-DIAG\_\-APID} =  0x2d8, 
\par
{\bf LCI\_\-DFT\_\-CAPACITY} =  100, 
\par
{\bf LCI\_\-N\_\-TERM\_\-PKTS} =  2, 
\par
{\bf CSR\_\-STALL} =  200
 \}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
static unsigned \hyperlink{control_8c_a9}{new\-ITC} (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$cnt)
\begin{CompactList}\small\item\em Allocate a new ITC structure. \item\end{CompactList}\item 
static void \hyperlink{control_8c_a10}{delete\-ITC} (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$cnt)
\begin{CompactList}\small\item\em Free the ITC structures. \item\end{CompactList}\item 
static unsigned \hyperlink{control_8c_a11}{cycle} (void)
\begin{CompactList}\small\item\em Perform a calibration cycle. \item\end{CompactList}\item 
\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ \hyperlink{control_8c_a12}{LCI\_\-new\-Controller} (unsigned cap, unsigned cpuid, unsigned srcid)
\begin{CompactList}\small\item\em Create calibration controller structure. \item\end{CompactList}\item 
void \hyperlink{control_8c_a13}{LCI\_\-delete\-Controller} (\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_8c_a14}{LCI\_\-initialise} (void)
\begin{CompactList}\small\item\em Initialize the calibration system from its config database. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a15}{LCI\_\-init} (unsigned capacity, unsigned cpuid, unsigned srcid)
\begin{CompactList}\small\item\em Initialize the calibration system. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a16}{LCI\_\-start\-Task} (void)
\begin{CompactList}\small\item\em Start the LCI task using its config database. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a17}{LCI\_\-start} (const TASK\_\-attr $\ast$attr)
\begin{CompactList}\small\item\em Start the LCI task. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a18}{LCI\_\-stop\-Task} (void)
\begin{CompactList}\small\item\em Stop the LCI task. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a19}{LCI\_\-teardown} (void)
\begin{CompactList}\small\item\em Tear down the calibraion system. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a20}{LCI\_\-calibrate} (unsigned latccfg, unsigned lcicfg, unsigned lcirunid, ITC\_\-Node\-ID ini\-Node, ITC\_\-Task\-ID ini\-Task, ITC\_\-Queue\-ID ini\-Queue)
\begin{CompactList}\small\item\em Start a new calibration. \item\end{CompactList}\item 
void \hyperlink{control_8c_a21}{LCI\_\-abort} (void)
\begin{CompactList}\small\item\em Abort a calibration. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a22}{LCI\_\-start\-Cycle} (void)
\begin{CompactList}\small\item\em Request the next calibration cycle. \item\end{CompactList}\item 
unsigned int \hyperlink{control_8c_a23}{LCI\_\-cycle} (void $\ast$prm, const struct \hyperlink{struct__ITC__QueueItem}{\_\-ITC\_\-Queue\-Item} $\ast$qitem, void $\ast$pay, unsigned int len)
\begin{CompactList}\small\item\em Perform a single calibration cycle. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a24}{LCI\_\-terminate} (unsigned status)
\begin{CompactList}\small\item\em Terminate a calibration. \item\end{CompactList}\item 
void \hyperlink{control_8c_a25}{LCI\_\-cb\_\-status\-Free} (ITC\_\-Queue\-Item $\ast$qitem, unsigned int status, void $\ast$prm0, void $\ast$prm1, void $\ast$prm2, unsigned int tx)
\begin{CompactList}\small\item\em ITC send completion callback. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a26}{LCI\_\-status} (void)
\begin{CompactList}\small\item\em Get the calibration state. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a27}{LCI\_\-cycles} (void)
\begin{CompactList}\small\item\em Get the calibration cycle count. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a28}{LCI\_\-get\-Run\-Info} (\hyperlink{struct__LCI__runInfo}{LCI\_\-run\-Info} $\ast$info)
\begin{CompactList}\small\item\em Get extended information about the calibration run. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a29}{LCI\_\-sizeof\-Run\-Info} (void)
\begin{CompactList}\small\item\em Get the size of the extended calibration run information. \item\end{CompactList}\item 
unsigned \hyperlink{control_8c_a30}{LCI\_\-monitor} (unsigned mon)
\begin{CompactList}\small\item\em Set the calibration monitoring level. \item\end{CompactList}\end{CompactItemize}
\subsection*{Variables}
\begin{CompactItemize}
\item 
\hypertarget{control_8c_a4}{
static \hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ \hyperlink{control_8c_a4}{lci}}
\label{control_8c_a4}

\begin{CompactList}\small\item\em Static pointer to the single LCI control block. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Principal routines of the charge injection calibration utility. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{control_8c}{control.c},v 1.25 2007/08/26 21:47:27 saxton Exp \end{Desc}


\subsection{Define Documentation}
\hypertarget{control_8c_a2}{
\index{control.c@{control.c}!CHECK_CALL_TERMINATE@{CHECK\_\-CALL\_\-TERMINATE}}
\index{CHECK_CALL_TERMINATE@{CHECK\_\-CALL\_\-TERMINATE}!control.c@{control.c}}
\subsubsection[CHECK\_\-CALL\_\-TERMINATE]{\setlength{\rightskip}{0pt plus 5cm}\#define CHECK\_\-CALL\_\-TERMINATE(FUNC)}}
\label{control_8c_a2}


{\bf Value:}

\footnotesize\begin{verbatim}{ \
  unsigned status = FUNC;\
  if (_msg_failure(status)) return LCI_terminate(status);\
}
\end{verbatim}\normalsize 
Call a function and check the return value, calling LCI\_\-terminate on error. 



\subsection{Function Documentation}
\hypertarget{control_8c_a11}{
\index{control.c@{control.c}!cycle@{cycle}}
\index{cycle@{cycle}!control.c@{control.c}}
\subsubsection[cycle]{\setlength{\rightskip}{0pt plus 5cm}unsigned cycle (void)\hspace{0.3cm}{\tt  \mbox{[}inline, static\mbox{]}}}}
\label{control_8c_a11}


Perform a calibration cycle. 

This routine performs a configure-collect-compact-consign calibration cycle.

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-ENDOFILE}]if there are no more configurations to read \item[{\em LCI\_\-FOPER}]if there is an error during the read or the configuration is incomplete \item[{\em LCI\_\-QITEM}]The attempt to allocate a Queue\-Item 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 calibration cycle is successful\end{description}
\end{Desc}
\hypertarget{control_8c_a10}{
\index{control.c@{control.c}!deleteITC@{deleteITC}}
\index{deleteITC@{deleteITC}!control.c@{control.c}}
\subsubsection[deleteITC]{\setlength{\rightskip}{0pt plus 5cm}void delete\-ITC (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ {\em cnt})\hspace{0.3cm}{\tt  \mbox{[}inline, static\mbox{]}}}}
\label{control_8c_a10}


Free the ITC structures. 

This routine frees the ITC resource associated with an LCI structure.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cnt}]Pointer to the LCI structure containing pointers to the ITC structures to destroy\end{description}
\end{Desc}
\hypertarget{control_8c_a21}{
\index{control.c@{control.c}!LCI_abort@{LCI\_\-abort}}
\index{LCI_abort@{LCI\_\-abort}!control.c@{control.c}}
\subsubsection[LCI\_\-abort]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-abort (void)}}
\label{control_8c_a21}


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_8c_a20}{
\index{control.c@{control.c}!LCI_calibrate@{LCI\_\-calibrate}}
\index{LCI_calibrate@{LCI\_\-calibrate}!control.c@{control.c}}
\subsubsection[LCI\_\-calibrate]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-calibrate (unsigned {\em latccfg}, unsigned {\em lcicfg}, unsigned {\em lcirunid}, ITC\_\-Node\-ID {\em ini\-Node}, ITC\_\-Task\-ID {\em ini\-Task}, ITC\_\-Queue\-ID {\em ini\-Queue})}}
\label{control_8c_a20}


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 ini\-Node}]Node ID of the task that initiated the calibration (used to send a message back when the calibration completes)\item[{\em ini\-Task}]Task ID of the task that initiated the calibration (used to send a message back when the calibration completes)\item[{\em ini\-Queue}]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_8c_a25}{
\index{control.c@{control.c}!LCI_cb_statusFree@{LCI\_\-cb\_\-statusFree}}
\index{LCI_cb_statusFree@{LCI\_\-cb\_\-statusFree}!control.c@{control.c}}
\subsubsection[LCI\_\-cb\_\-statusFree]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-cb\_\-status\-Free (ITC\_\-Queue\-Item $\ast$ {\em qitem}, unsigned int {\em status}, void $\ast$ {\em prm0}, void $\ast$ {\em prm1}, void $\ast$ {\em prm2}, unsigned int {\em tx})}}
\label{control_8c_a25}


ITC send completion callback. 

Completion call-back for use with ITC when sending the status back to the task that initiated calibration - just returns the qitem to the pool.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qitem}]Queue item to be returned to the pool\item[{\em status}]Success or failure of the ITC delivery\item[{\em prm0}]User defined parameter 0 (pointer to the FPM pool)\item[{\em prm1}]User defined (NULL)\item[{\em prm2}]User defined (NULL)\item[{\em tx}]Transmission status\end{description}
\end{Desc}
\hypertarget{control_8c_a23}{
\index{control.c@{control.c}!LCI_cycle@{LCI\_\-cycle}}
\index{LCI_cycle@{LCI\_\-cycle}!control.c@{control.c}}
\subsubsection[LCI\_\-cycle]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LCI\_\-cycle (void $\ast$ {\em prm}, const struct \hyperlink{struct__ITC__QueueItem}{\_\-ITC\_\-Queue\-Item} $\ast$ {\em qitem}, void $\ast$ {\em pay}, unsigned int {\em len})}}
\label{control_8c_a23}


Perform a single calibration cycle. 

This routine is called when a calibration cycle request is received. Provided there is configuration data to read and the abort flag has not been set, it performs a single calibration cycle and queues the next one if this one is successful.

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-ABORTED}]if the abort flag was found to be set at the start of the cycle \item[{\em LCI\_\-FOPER}]if there is an error during the read or the configuration is incomplete \item[{\em LCI\_\-QITEM}]The attempt to allocate a Queue\-Item 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 LCI\_\-SUCCESS}]if the calibration cycle is successfully completed\end{description}
\end{Desc}
\hypertarget{control_8c_a27}{
\index{control.c@{control.c}!LCI_cycles@{LCI\_\-cycles}}
\index{LCI_cycles@{LCI\_\-cycles}!control.c@{control.c}}
\subsubsection[LCI\_\-cycles]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-cycles (void)}}
\label{control_8c_a27}


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_8c_a13}{
\index{control.c@{control.c}!LCI_deleteController@{LCI\_\-deleteController}}
\index{LCI_deleteController@{LCI\_\-deleteController}!control.c@{control.c}}
\subsubsection[LCI\_\-deleteController]{\setlength{\rightskip}{0pt plus 5cm}void LCI\_\-delete\-Controller (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ {\em cnt})}}
\label{control_8c_a13}


Free the calibration controller structure. 

This routine frees all the resources associated with the LCI task.\hypertarget{control_8c_a28}{
\index{control.c@{control.c}!LCI_getRunInfo@{LCI\_\-getRunInfo}}
\index{LCI_getRunInfo@{LCI\_\-getRunInfo}!control.c@{control.c}}
\subsubsection[LCI\_\-getRunInfo]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-get\-Run\-Info (\hyperlink{struct__LCI__runInfo}{LCI\_\-run\-Info} $\ast$ {\em info})}}
\label{control_8c_a28}


Get extended information about the calibration run. 

This routine fills a block of information detailing the current state of calibration runs.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em info}]The address of a block to be filled with the current run information.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-SUCCESS}]success always\end{description}
\end{Desc}
\hypertarget{control_8c_a15}{
\index{control.c@{control.c}!LCI_init@{LCI\_\-init}}
\index{LCI_init@{LCI\_\-init}!control.c@{control.c}}
\subsubsection[LCI\_\-init]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-init (unsigned {\em capacity}, unsigned {\em cpuid}, unsigned {\em srcid})}}
\label{control_8c_a15}


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_8c_a14}{
\index{control.c@{control.c}!LCI_initialise@{LCI\_\-initialise}}
\index{LCI_initialise@{LCI\_\-initialise}!control.c@{control.c}}
\subsubsection[LCI\_\-initialise]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-initialise (void)}}
\label{control_8c_a14}


Initialize the calibration system from its config database. 

This routine is normally called at system initialization time to initialize the calibration system . It uses a configuration database to supply the {\em capacity\/}, {\em cpuid\/} and {\em srcid\/} parameters.

\begin{Desc}
\item[Returns:]Any of the return codes from LCI\_\-init\end{Desc}
\hypertarget{control_8c_a30}{
\index{control.c@{control.c}!LCI_monitor@{LCI\_\-monitor}}
\index{LCI_monitor@{LCI\_\-monitor}!control.c@{control.c}}
\subsubsection[LCI\_\-monitor]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-monitor (unsigned {\em mon})}}
\label{control_8c_a30}


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_8c_a12}{
\index{control.c@{control.c}!LCI_newController@{LCI\_\-newController}}
\index{LCI_newController@{LCI\_\-newController}!control.c@{control.c}}
\subsubsection[LCI\_\-newController]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__LCI__controller}{LCI\_\-controller}$\ast$ LCI\_\-new\-Controller (unsigned {\em cap}, unsigned {\em cpuid}, unsigned {\em srcid})}}
\label{control_8c_a12}


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_8c_a29}{
\index{control.c@{control.c}!LCI_sizeofRunInfo@{LCI\_\-sizeofRunInfo}}
\index{LCI_sizeofRunInfo@{LCI\_\-sizeofRunInfo}!control.c@{control.c}}
\subsubsection[LCI\_\-sizeofRunInfo]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-sizeof\-Run\-Info (void)}}
\label{control_8c_a29}


Get the size of the extended calibration run information. 

This routine returns the size of the area needed to hold the extended run information for the last calibration.

\begin{Desc}
\item[Returns:]The size, in bytes, of the extended run information.\end{Desc}
\hypertarget{control_8c_a17}{
\index{control.c@{control.c}!LCI_start@{LCI\_\-start}}
\index{LCI_start@{LCI\_\-start}!control.c@{control.c}}
\subsubsection[LCI\_\-start]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-start (const TASK\_\-attr $\ast$ {\em attr})}}
\label{control_8c_a17}


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\_\-start\-Task\-W, 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_8c_a22}{
\index{control.c@{control.c}!LCI_startCycle@{LCI\_\-startCycle}}
\index{LCI_startCycle@{LCI\_\-startCycle}!control.c@{control.c}}
\subsubsection[LCI\_\-startCycle]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-start\-Cycle (void)}}
\label{control_8c_a22}


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 Queue\-Item 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_8c_a16}{
\index{control.c@{control.c}!LCI_startTask@{LCI\_\-startTask}}
\index{LCI_startTask@{LCI\_\-startTask}!control.c@{control.c}}
\subsubsection[LCI\_\-startTask]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-start\-Task (void)}}
\label{control_8c_a16}


Start the LCI task using its config database. 

This routine is normally called during system initialization. It starts the LCI task using the CPU configuration database to supply its attributes.

\begin{Desc}
\item[Returns:]Any of the return codes from LCI\_\-start\-Task\end{Desc}
\hypertarget{control_8c_a26}{
\index{control.c@{control.c}!LCI_status@{LCI\_\-status}}
\index{LCI_status@{LCI\_\-status}!control.c@{control.c}}
\subsubsection[LCI\_\-status]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-status (void)}}
\label{control_8c_a26}


Get the calibration state. 

This routine returns the current state of LCI.

\begin{Desc}
\item[Returns:]Current state of LCI\end{Desc}
\hypertarget{control_8c_a18}{
\index{control.c@{control.c}!LCI_stopTask@{LCI\_\-stopTask}}
\index{LCI_stopTask@{LCI\_\-stopTask}!control.c@{control.c}}
\subsubsection[LCI\_\-stopTask]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-stop\-Task (void)}}
\label{control_8c_a18}


Stop the LCI task. 

This routine stops the LCI task and sets the state to INITIALISED.

\begin{Desc}
\item[Returns:]LCI\_\-STATE if the state is not WAITING, an error status code from ITC\_\-stop\-Task or LCI\_\-SUCCESS if all goes well\end{Desc}
\hypertarget{control_8c_a19}{
\index{control.c@{control.c}!LCI_teardown@{LCI\_\-teardown}}
\index{LCI_teardown@{LCI\_\-teardown}!control.c@{control.c}}
\subsubsection[LCI\_\-teardown]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-teardown (void)}}
\label{control_8c_a19}


Tear down the calibraion system. 

This routine frees all the resources associated with the LCI task.

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LCI\_\-STATE}]If the LCI task is not in the INITIALISED state\item[{\em LCI\_\-SUCCESS}]If all goes well\end{description}
\end{Desc}
\hypertarget{control_8c_a24}{
\index{control.c@{control.c}!LCI_terminate@{LCI\_\-terminate}}
\index{LCI_terminate@{LCI\_\-terminate}!control.c@{control.c}}
\subsubsection[LCI\_\-terminate]{\setlength{\rightskip}{0pt plus 5cm}unsigned LCI\_\-terminate (unsigned {\em status})}}
\label{control_8c_a24}


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 Queue\-Item 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}
\hypertarget{control_8c_a9}{
\index{control.c@{control.c}!newITC@{newITC}}
\index{newITC@{newITC}!control.c@{control.c}}
\subsubsection[newITC]{\setlength{\rightskip}{0pt plus 5cm}unsigned new\-ITC (\hyperlink{struct__LCI__controller}{LCI\_\-controller} $\ast$ {\em cnt})\hspace{0.3cm}{\tt  \mbox{[}inline, static\mbox{]}}}}
\label{control_8c_a9}


Allocate a new ITC structure. 

This routine obtains the ITC resources needed by the calibration task.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cnt}]Pointer to LCI\_\-controller structure to attach ITC structure to.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Status code from RBM\_\-create\-Ring or LCI\_\-MEMERROR\end{Desc}
