\hypertarget{rim_8h}{
\section{rim.h File Reference}
\label{rim_8h}\index{rim.h@{rim.h}}
}
Register In-memory Model structure. 

{\tt \#include \char`\"{}RIM/map.h\char`\"{}}\par
{\tt \#include $<$stdio.h$>$}\par


Include dependency graph for rim.h:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=201pt]{rim_8h__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=172pt]{rim_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{rim_8h_a0}{
typedef RIM\_\- \hyperlink{rim_8h_a0}{RIM}}
\label{rim_8h_a0}

\begin{CompactList}\small\item\em Forward declaration of the RIM structure. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \{ {\bf RIM\_\-MEM\_\-ALIGN} =  sizeof(unsigned long long)
 \}
\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
size\_\-t \hyperlink{rim_8h_a2}{RIM\_\-sizeof} (void)
\begin{CompactList}\small\item\em Calculate the footprint of the RIM structure. \item\end{CompactList}\item 
\hyperlink{rim_8h_a0}{RIM} $\ast$ \hyperlink{rim_8h_a3}{RIM\_\-construct} (void $\ast$buffer)
\begin{CompactList}\small\item\em Initialised a block of memory as a RIM object. \item\end{CompactList}\item 
void \hyperlink{rim_8h_a4}{RIM\_\-clear} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim)
\begin{CompactList}\small\item\em Clear out the map and data portions of the RIM structure. \item\end{CompactList}\item 
int \hyperlink{rim_8h_a5}{RIM\_\-compare} (const \hyperlink{rim_8h_a0}{RIM} $\ast$this, const \hyperlink{rim_8h_a0}{RIM} $\ast$that, \hyperlink{structRIM__map__}{RIM\_\-map} $\ast$map)
\begin{CompactList}\small\item\em Compares all the nodes of {\em this\/} and {\em that\/}, marking differences in the {\em map\/}. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a6}{RIM\_\-contrast} (const \hyperlink{rim_8h_a0}{RIM} $\ast$this, const \hyperlink{rim_8h_a0}{RIM} $\ast$that, const \hyperlink{structRIM__map__}{RIM\_\-map} $\ast$map, \hyperlink{lrd_8h_a0}{RIM\_\-type} $\ast$r\_\-type, \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$r\_\-addr)
\begin{CompactList}\small\item\em Compares all the nodes of {\em this\/} and {\em that\/}, that are not marked to be ignored. \item\end{CompactList}\item 
void \hyperlink{rim_8h_a7}{RIM\_\-correct} (\hyperlink{rim_8h_a0}{RIM} $\ast$orig, \hyperlink{rim_8h_a0}{RIM} $\ast$capt)
\begin{CompactList}\small\item\em Copy select portions of an original RIM into a copy, to ensure that the subsequent comparison will succeed. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a8}{RIM\_\-get} (const \hyperlink{rim_8h_a0}{RIM} $\ast$rim, \hyperlink{lrd_8h_a0}{RIM\_\-type} type, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$addr, int reg\-Id, void $\ast$value)
\begin{CompactList}\small\item\em Puts the contents of the requested register and field into {\em value\/}. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a9}{RIM\_\-set} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim, \hyperlink{lrd_8h_a0}{RIM\_\-type} type, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$addr, int reg\-Id, const void $\ast$value)
\begin{CompactList}\small\item\em Set the value of a register field. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a10}{RIM\_\-delete\-Data} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim, \hyperlink{lrd_8h_a0}{RIM\_\-type} type, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$addr)
\begin{CompactList}\small\item\em Delete all the register field settings for the targetted compoent and clear the corresponding bit in the map. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a11}{RIM\_\-consume} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim, int fd)
\begin{CompactList}\small\item\em Reads the buffer of data into the RIM structure. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a12}{RIM\_\-create\-Mask} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim)
\begin{CompactList}\small\item\em Creates a bitmask indicating which types can successfully be used with RIM\_\-create. \item\end{CompactList}\item 
unsigned \hyperlink{rim_8h_a13}{RIM\_\-create} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim, \hyperlink{lrd_8h_a0}{RIM\_\-type} type, int fd)
\begin{CompactList}\small\item\em Create a single binary configuration file containing the data of one component (or the default data). \item\end{CompactList}\item 
void \hyperlink{rim_8h_a14}{RIM\_\-report} (\hyperlink{rim_8h_a0}{RIM} $\ast$rim, FILE $\ast$fp)
\begin{CompactList}\small\item\em Print a report of the contents of the IMM to the file. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Register In-memory Model structure. 

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


\subsection{Function Documentation}
\hypertarget{rim_8h_a4}{
\index{rim.h@{rim.h}!RIM_clear@{RIM\_\-clear}}
\index{RIM_clear@{RIM\_\-clear}!rim.h@{rim.h}}
\subsubsection[RIM\_\-clear]{\setlength{\rightskip}{0pt plus 5cm}void RIM\_\-clear (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim})}}
\label{rim_8h_a4}


Clear out the map and data portions of the RIM structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]Pointer to the RIM object to clear\end{description}
\end{Desc}
\hypertarget{rim_8h_a5}{
\index{rim.h@{rim.h}!RIM_compare@{RIM\_\-compare}}
\index{RIM_compare@{RIM\_\-compare}!rim.h@{rim.h}}
\subsubsection[RIM\_\-compare]{\setlength{\rightskip}{0pt plus 5cm}int RIM\_\-compare (const \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em this}, const \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em that}, \hyperlink{structRIM__map__}{RIM\_\-map} $\ast$ {\em map})}}
\label{rim_8h_a5}


Compares all the nodes of {\em this\/} and {\em that\/}, marking differences in the {\em map\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em this}]First in-memory configuration structure \item[{\em that}]Second in-memory configuration structure \item[{\em map}]Indicates which nodes are different \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Number of different nodes\end{Desc}
If a node is NULL, then the default node is used.\hypertarget{rim_8h_a3}{
\index{rim.h@{rim.h}!RIM_construct@{RIM\_\-construct}}
\index{RIM_construct@{RIM\_\-construct}!rim.h@{rim.h}}
\subsubsection[RIM\_\-construct]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{rim_8h_a0}{RIM}$\ast$ RIM\_\-construct (void $\ast$ {\em buffer})}}
\label{rim_8h_a3}


Initialised a block of memory as a RIM object. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to uninitialised memory to use for the RIM structure \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]NULL if the buffer is misaligned, or an initialised RIM structure\end{Desc}
\hypertarget{rim_8h_a11}{
\index{rim.h@{rim.h}!RIM_consume@{RIM\_\-consume}}
\index{RIM_consume@{RIM\_\-consume}!rim.h@{rim.h}}
\subsubsection[RIM\_\-consume]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-consume (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, int {\em fd})}}
\label{rim_8h_a11}


Reads the buffer of data into the RIM structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]Pointer to the RIM structure to populate \item[{\em fd}]Descriptor of a file opened for reading \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]The data was successfully transfered into the RIM structure \item[{\em RIM\_\-TYPE\_\-UK}]The type identifier at the start of the buffer did not correspond to a known type \item[{\em RIM\_\-CPT\_\-NONE}]The type ID does not appear to be associated to a LAT component \item[{\em RIM\_\-MAP\_\-NONE}]The data was of a singleton type, by an attempt to recover a map was made \item[{\em RIM\_\-FILE\_\-END}]If the end of the file is reached \item[{\em RIM\_\-FILE\_\-READ}]If there is an error reading from the file\end{description}
\end{Desc}
\hypertarget{rim_8h_a6}{
\index{rim.h@{rim.h}!RIM_contrast@{RIM\_\-contrast}}
\index{RIM_contrast@{RIM\_\-contrast}!rim.h@{rim.h}}
\subsubsection[RIM\_\-contrast]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-contrast (const \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em this}, const \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em that}, const \hyperlink{structRIM__map__}{RIM\_\-map} $\ast$ {\em ign}, \hyperlink{lrd_8h_a0}{RIM\_\-type} $\ast$ {\em r\_\-type}, \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$ {\em r\_\-addr})}}
\label{rim_8h_a6}


Compares all the nodes of {\em this\/} and {\em that\/}, that are not marked to be ignored. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em this}]First in memory configuration model \item[{\em that}]Second in memory configuration model \item[{\em ign}]Pointer to a bit-map of sections of the LAT to ignore \item[{\em r\_\-type}]Location to fill with the type of the first different node (can be NULL if not interested) \item[{\em r\_\-addr}]Pointer to an address structure to populate with the first different node (can be NULL if not interested) \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]If the two in-memory models are functionally identical \item[{\em RIM\_\-DIFFER}]If the two in-memory models are different\end{description}
\end{Desc}
If a node is NULL then the default node is used.\hypertarget{rim_8h_a7}{
\index{rim.h@{rim.h}!RIM_correct@{RIM\_\-correct}}
\index{RIM_correct@{RIM\_\-correct}!rim.h@{rim.h}}
\subsubsection[RIM\_\-correct]{\setlength{\rightskip}{0pt plus 5cm}void RIM\_\-correct (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em orig}, \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em capt})}}
\label{rim_8h_a7}


Copy select portions of an original RIM into a copy, to ensure that the subsequent comparison will succeed. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em orig}]Orignal RIM \item[{\em capt}]New copy of the RIM (probably captured from the LAT)\end{description}
\end{Desc}
\hypertarget{rim_8h_a13}{
\index{rim.h@{rim.h}!RIM_create@{RIM\_\-create}}
\index{RIM_create@{RIM\_\-create}!rim.h@{rim.h}}
\subsubsection[RIM\_\-create]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-create (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, \hyperlink{lrd_8h_a0}{RIM\_\-type} {\em type}, int {\em fd})}}
\label{rim_8h_a13}


Create a single binary configuration file containing the data of one component (or the default data). 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]RIM structure to use as a source \item[{\em type}]Component type to write out \item[{\em fd}]Descriptor of a file opened for writing \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]if all goes well \item[{\em RIM\_\-FILE\_\-WRITE}]if one of the file write operations failed \item[{\em RIM\_\-MAP\_\-NONE}]if the selected type is not written seperately \item[{\em RIM\_\-CPT\_\-NONE}]if the selected type has not data specified\end{description}
\end{Desc}
\hypertarget{rim_8h_a12}{
\index{rim.h@{rim.h}!RIM_createMask@{RIM\_\-createMask}}
\index{RIM_createMask@{RIM\_\-createMask}!rim.h@{rim.h}}
\subsubsection[RIM\_\-createMask]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-create\-Mask (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim})}}
\label{rim_8h_a12}


Creates a bitmask indicating which types can successfully be used with RIM\_\-create. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]Pointer to the in-memory model \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Bit mask indicating the types of files that can be created\end{Desc}
\hypertarget{rim_8h_a10}{
\index{rim.h@{rim.h}!RIM_deleteData@{RIM\_\-deleteData}}
\index{RIM_deleteData@{RIM\_\-deleteData}!rim.h@{rim.h}}
\subsubsection[RIM\_\-deleteData]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-delete\-Data (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, \hyperlink{lrd_8h_a0}{RIM\_\-type} {\em type}, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$ {\em addr})}}
\label{rim_8h_a10}


Delete all the register field settings for the targetted compoent and clear the corresponding bit in the map. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]In memory configuration structure to be manipulated \item[{\em type}]Type of data sought \item[{\em addr}]Address of the leaf to delete \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]if all the parameters are in bounds and the data is successfully retrieved. \item[{\em RIM\_\-TYPE\_\-UK}]if {\em type\/} is not a valid RIM\_\-type\end{description}
\end{Desc}
\hypertarget{rim_8h_a8}{
\index{rim.h@{rim.h}!RIM_get@{RIM\_\-get}}
\index{RIM_get@{RIM\_\-get}!rim.h@{rim.h}}
\subsubsection[RIM\_\-get]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-get (const \hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, \hyperlink{lrd_8h_a0}{RIM\_\-type} {\em type}, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$ {\em addr}, int {\em reg\-Id}, void $\ast$ {\em value})}}
\label{rim_8h_a8}


Puts the contents of the requested register and field into {\em value\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]In memory configuration structure to be interogated \item[{\em type}]Type of data sought \item[{\em addr}]Address of the leaf requested \item[{\em reg\-Id}]Register to get \item[{\em value}]Location to put the contents of the target field \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]if all the parameters are in bounds and the data is successfully retrieved. \item[{\em RIM\_\-TYPE\_\-UK}]if {\em type\/} is not a valid RIM\_\-type \item[{\em RIM\_\-CPT\_\-NONE}]if the requested type has no real data \item[{\em RIM\_\-ADDR\_\-BCAST}]if the address contains a mixture of broadcast and unicast components \item[{\em RIM\_\-ADDR\_\-RANGE}]if any component of the address is outside the allowable range for this type \item[{\em RIM\_\-REG\_\-ID}]if {\em reg\-Id\/} is outside the acceptable range of register IDs for this type \item[{\em RIM\_\-NOT\_\-SET}]if the requested node has not been previously set\end{description}
\end{Desc}
\hypertarget{rim_8h_a14}{
\index{rim.h@{rim.h}!RIM_report@{RIM\_\-report}}
\index{RIM_report@{RIM\_\-report}!rim.h@{rim.h}}
\subsubsection[RIM\_\-report]{\setlength{\rightskip}{0pt plus 5cm}void RIM\_\-report (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, FILE $\ast$ {\em fp})}}
\label{rim_8h_a14}


Print a report of the contents of the IMM to the file. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]RIM structure to use as a source \item[{\em fp}]Pointer to destination of the report\end{description}
\end{Desc}
\hypertarget{rim_8h_a9}{
\index{rim.h@{rim.h}!RIM_set@{RIM\_\-set}}
\index{RIM_set@{RIM\_\-set}!rim.h@{rim.h}}
\subsubsection[RIM\_\-set]{\setlength{\rightskip}{0pt plus 5cm}unsigned RIM\_\-set (\hyperlink{rim_8h_a0}{RIM} $\ast$ {\em rim}, \hyperlink{lrd_8h_a0}{RIM\_\-type} {\em type}, const \hyperlink{unionRIM__addr}{RIM\_\-addr} $\ast$ {\em addr}, int {\em reg\-Id}, const void $\ast$ {\em value})}}
\label{rim_8h_a9}


Set the value of a register field. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rim}]In memory configuration structure to manipulated \item[{\em type}]Type of data sought \item[{\em addr}]Address of the leaf requested \item[{\em reg\-Id}]Register to set \item[{\em value}]Ptr to value to set the register field to \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em RIM\_\-SUCCESS}]if all the parameters are in bounds and the data is successfully retrieved. \item[{\em RIM\_\-TYPE\_\-UK}]if {\em type\/} is not a valid RIM\_\-type \item[{\em RIM\_\-CPT\_\-NONE}]if the requested type has no real data \item[{\em RIM\_\-ADDR\_\-BCAST}]if the address contains a mixture of broadcast and unicast components \item[{\em RIM\_\-ADDR\_\-RANGE}]if any component of the address is outside the allowable range for this type \item[{\em RIM\_\-REG\_\-ID}]if {\em reg\-Id\/} is outside the acceptable range of register IDs for this type \item[{\em RIM\_\-FLD\_\-ID}]if {\em fld\-Id\/} is outside the acceptable range of field IDs\end{description}
\end{Desc}
\hypertarget{rim_8h_a2}{
\index{rim.h@{rim.h}!RIM_sizeof@{RIM\_\-sizeof}}
\index{RIM_sizeof@{RIM\_\-sizeof}!rim.h@{rim.h}}
\subsubsection[RIM\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t RIM\_\-sizeof (void)}}
\label{rim_8h_a2}


Calculate the footprint of the RIM structure. 

\begin{Desc}
\item[Returns:]Amount of memory required to hold the RIM structure\end{Desc}