\hypertarget{MBA_8h}{
\section{MBA.h File Reference}
\label{MBA_8h}\index{MBA.h@{MBA.h}}
}
Random memory allocation, function prototypes. 

{\tt \#include \char`\"{}IPBS/impl/MBA.h.xx-xxx-xxx\char`\"{}}\par


Include dependency graph for MBA.h:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=147pt]{MBA_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=158pt]{MBA_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__MBA__badBlock}{\_\-MBA\_\-bad\-Block}
\begin{CompactList}\small\item\em Definition of a bad block of memory. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef \hyperlink{struct__MBA__badBlock}{\_\-MBA\_\-bad\-Block} \hyperlink{MBA_8h_a0}{MBA\_\-bad\-Block}
\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__MBA__badBlock}{\_\-MBA\_\-bad\-Block}. \item\end{CompactList}\item 
typedef PART\_\-ID($\ast$ \hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb} )(void $\ast$prm)
\begin{CompactList}\small\item\em Function signature for a user definition initialization routine. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void $\ast$ \hyperlink{MBA_8h_a2}{MBA\_\-align} (unsigned int alignment, unsigned int n\-Bytes)
\begin{CompactList}\small\item\em Allocates {\em n\-Bytes\/} of aligned memory. \item\end{CompactList}\item 
void $\ast$ \hyperlink{MBA_8h_a3}{MBA\_\-alloc} (unsigned int n\-Bytes)
\begin{CompactList}\small\item\em Allocates {\em n\-Bytes\/} of at least word aligned memory. \item\end{CompactList}\item 
int \hyperlink{MBA_8h_a4}{MBA\_\-free} (void $\ast$p\-Block)
\begin{CompactList}\small\item\em Frees a piece of memory allocated with either {\em \hyperlink{MBA_8h_a2}{MBA\_\-align()}\/} or {\em \hyperlink{MBA_8h_a3}{MBA\_\-alloc()}\/}. \item\end{CompactList}\item 
int \hyperlink{MBA_8h_a5}{MBA\_\-stats\-Get} (\hyperlink{MBA_8h_8vx-xxx-xxx_a0}{MBA\_\-stats} $\ast$stats)
\begin{CompactList}\small\item\em Gets the memory stats for the MBA partition. \item\end{CompactList}\item 
int \hyperlink{MBA_8h_a6}{MBA\_\-initialize} (\hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb} create, void $\ast$prm)
\begin{CompactList}\small\item\em One time initialization of the MBA facility. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Random memory allocation, function prototypes. 

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


\footnotesize\begin{verbatim}    CVS $Id: MBA.h,v 1.1.1.1 2006/02/10 21:45:35 saxton Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]This file acts as a front for {\em malloc()\/} and {\em memalign()\/} on host platforms and for mem\-Part\-Alloc and mem\-Part\-Aligned\-Alloc on Vx\-Works. Application level code should always use the equivalent M routines. On Vx\-Work's platforms, {\em malloc()\/} and {\em memalign()\/}, by default, allocate out of the system partition. Because the Vx\-Work's dynamic loader uses {\em malloc()\/} and because restrictions on the range of branch statements, the system partition must be limited to less than 24Mbytes.\end{Desc}
With this in mind, FSW decided on a policy that discourages use of {\em malloc()\/} and {\em memalign()\/} in application code, effectively reserving the system partition for exclusive use by Vx\-Works itself.

\subsection{Typedef Documentation}
\hypertarget{MBA_8h_a0}{
\index{MBA.h@{MBA.h}!MBA_badBlock@{MBA\_\-badBlock}}
\index{MBA_badBlock@{MBA\_\-badBlock}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-badBlock]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__MBA__badBlock}{MBA\_\-bad\-Block}}}
\label{MBA_8h_a0}


Typedef for struct \hyperlink{struct__MBA__badBlock}{\_\-MBA\_\-bad\-Block}. 

\begin{Desc}
\item[]A bad block is defined as a starting address and a length, in bytes. Typically one will specify a list of bad blocks. By convention, the list is terminated with a block specified with a beginning address of 0 and a length of 0.\end{Desc}
\begin{Desc}
\item[]On embedded systems, MBA will remove bad blocks that fall within the range of its pool. This will be done at system initialization time. Unforturnately, there is no easy way to do this if the bad blocks fall within the system partition. It appears the only method here is to rebuild the kernel.\end{Desc}
\begin{Desc}
\item[Note:]This should have been an easy job. One would have used the memory mapping registers to remap around the bad blocks. But, alas, the page registers do not work on the RAD750, hence this method.\end{Desc}
\hypertarget{MBA_8h_a1}{
\index{MBA.h@{MBA.h}!MBA_create_cb@{MBA\_\-create\_\-cb}}
\index{MBA_create_cb@{MBA\_\-create\_\-cb}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-create\_\-cb]{\setlength{\rightskip}{0pt plus 5cm}PART\_\-ID($\ast$ \hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb})(void $\ast$prm)}}
\label{MBA_8h_a1}


Function signature for a user definition initialization routine. 

\begin{Desc}
\item[Returns:]The partition id\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em prm}]Arbitrary user parameter\end{description}
\end{Desc}
\begin{Desc}
\item[]While this function will get called back on non-Vx\-Works targets, it has no effect and is there simply for portability.\end{Desc}


\subsection{Function Documentation}
\hypertarget{MBA_8h_a2}{
\index{MBA.h@{MBA.h}!MBA_align@{MBA\_\-align}}
\index{MBA_align@{MBA\_\-align}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-align]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ MBA\_\-align (unsigned int {\em alignment}, unsigned int {\em n\-Bytes})}}
\label{MBA_8h_a2}


Allocates {\em n\-Bytes\/} of aligned memory. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em alignment}]The alignment factor. This must be a power of 2 \item[{\em n\-Bytes}]The number of bytes to allocate \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]If successful, a pointer to the allocated memory, Else NULL\end{Desc}
\begin{Desc}
\item[Warning:]Note that the calling sequence to this routine follows the convention of {\bf memalign()}, not that of the Vx\-Works routine {\bf mem\-Part\-Align()}.\end{Desc}
\hypertarget{MBA_8h_a3}{
\index{MBA.h@{MBA.h}!MBA_alloc@{MBA\_\-alloc}}
\index{MBA_alloc@{MBA\_\-alloc}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-alloc]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ MBA\_\-alloc (unsigned int {\em n\-Bytes})}}
\label{MBA_8h_a3}


Allocates {\em n\-Bytes\/} of at least word aligned memory. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em n\-Bytes}]The number of bytes to allocate \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]If successful, a pointer to the allocated memory, Else NULL\end{Desc}
\hypertarget{MBA_8h_a4}{
\index{MBA.h@{MBA.h}!MBA_free@{MBA\_\-free}}
\index{MBA_free@{MBA\_\-free}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-free]{\setlength{\rightskip}{0pt plus 5cm}int MBA\_\-free (void $\ast$ {\em p\-Block})}}
\label{MBA_8h_a4}


Frees a piece of memory allocated with either {\em \hyperlink{MBA_8h_a2}{MBA\_\-align()}\/} or {\em \hyperlink{MBA_8h_a3}{MBA\_\-alloc()}\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em p\-Block}]Pointer to the block of memory to be freed. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0,if}]successful \item[{\em -1,if}]error\end{description}
\end{Desc}
The return error codes are only supported on Vx\-Works platforms. On generic platforms, success is always returned. This is because {\em free()\/} does not give any indication of success or failure, whereas the Vx\-Works mem\-Part routines do.\hypertarget{MBA_8h_a6}{
\index{MBA.h@{MBA.h}!MBA_initialize@{MBA\_\-initialize}}
\index{MBA_initialize@{MBA\_\-initialize}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-initialize]{\setlength{\rightskip}{0pt plus 5cm}int MBA\_\-initialize (\hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb} {\em create}, void $\ast$ {\em prm})}}
\label{MBA_8h_a6}


One time initialization of the MBA facility. 

\begin{Desc}
\item[Returns:]Status\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em create}]User callback partition creation meant to usurp the default creation routine in an extreme emergency \item[{\em prm}]Arbitrary user parameter passed to partition creation routine. If the partition creation routine is specified as NULL, then, if this parameter is treated as a pointer to a list of bad blocks, MBA\_\-bad\-Block.\end{description}
\end{Desc}
This is not meant to be a user callable routine.\hypertarget{MBA_8h_a5}{
\index{MBA.h@{MBA.h}!MBA_statsGet@{MBA\_\-statsGet}}
\index{MBA_statsGet@{MBA\_\-statsGet}!MBA.h@{MBA.h}}
\subsubsection[MBA\_\-statsGet]{\setlength{\rightskip}{0pt plus 5cm}int MBA\_\-stats\-Get (\hyperlink{MBA_8h_8vx-xxx-xxx_a0}{MBA\_\-stats} $\ast$ {\em stats})}}
\label{MBA_8h_a5}


Gets the memory stats for the MBA partition. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em stats}]Pointer to the statistics block to fill \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0,if}]successful \item[{\em -1,if}]error\end{description}
\end{Desc}
On generic host platforms, this call is provided only for portability reasons. Such statistics either do not exist or exist, but there is no user level access to them.

\begin{Desc}
\item[Warning:]Because these statistics do not exist, the caller should not depend on the contents of the filled in statistics block. Anything beyond just displaying or reporting the contents is sure to get the caller in trouble. If one is depending on these results, then it is up to the caller to make his code portable across both a VXWORS and a generic platform.\end{Desc}