\hypertarget{PBS_8c}{ \section{PBS.c File Reference} \label{PBS_8c}\index{PBS.c@{PBS.c}} } PBS library, contains the initialization routines for PBS. {\tt \#include $<$stdio.h$>$}\par {\tt \#include $<$stdlib.h$>$}\par {\tt \#include \char`\"{}IPBS/PBS.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/REG.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/MBA.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/TAU.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/TBD.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/PTS.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/WUT.h\char`\"{}}\par {\tt \#include \char`\"{}IPBS/WCT.h\char`\"{}}\par {\tt \#include \char`\"{}PBI/Unions.h\char`\"{}}\par {\tt \#include \char`\"{}CDM/CDM\_\-pubdefs.h\char`\"{}}\par {\tt \#include \char`\"{}impl/PBS.c.xx-xxx-xxx\char`\"{}}\par Include dependency graph for PBS.c:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=387pt]{PBS_8c__incl} \end{center} \end{figure} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{PBS_8c_a1}{TASK\_\-sys\_\-init} (void) \begin{CompactList}\small\item\em Performs one time only initialization of the TASK facility. \item\end{CompactList}\item int \hyperlink{PBS_8c_a2}{TASK\_\-sys\_\-shutdown} (void) \begin{CompactList}\small\item\em Performs the shutdown of the TASK facility. This essentially undoes what TASK\_\-sys\_\-init did. \item\end{CompactList}\item int \hyperlink{PBS_8c_a3}{PBS\_\-initialize} (int wut\_\-tmr\_\-cnt, int keepalive\_\-period) \begin{CompactList}\small\item\em One-time PBS library initialization routine. \item\end{CompactList}\item int \hyperlink{PBS_8c_a4}{PBS\_\-initialize2} (int wut\_\-tmr\_\-cnt, int keepalive\_\-period, \hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb} mba\_\-create, void $\ast$mba\_\-prm) \begin{CompactList}\small\item\em One-time PBS library initialization routine. \item\end{CompactList}\item int \hyperlink{PBS_8c_a5}{PBS\_\-shutdown} () \begin{CompactList}\small\item\em Shuts down the PBS facility. \item\end{CompactList}\item void \hyperlink{PBS_8c_a6}{PBS\_\-fast\_\-clear} (void $\ast$ptr, unsigned int nbytes) \begin{CompactList}\small\item\em Clears (Zeroes) the specified memory. \item\end{CompactList}\item int \hyperlink{PBS_8c_a7}{PBS\_\-crash\-Print} (\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type} type, const \hyperlink{struct__PBS__crashCtx}{PBS\_\-crash\-Ctx} $\ast$ctx, unsigned int options, const char $\ast$string) \begin{CompactList}\small\item\em Very simple default PBS crash handler. \item\end{CompactList}\item \hyperlink{PBS_8h_a3}{PBS\_\-crash\-Handler} \hyperlink{PBS_8c_a8}{PBS\_\-crash\-Handler\-Set} (\hyperlink{PBS_8h_a3}{PBS\_\-crash\-Handler} crash\-Handler) \begin{CompactList}\small\item\em Installs a new user crash handler. \item\end{CompactList}\item void \hyperlink{PBS_8c_a9}{PBS\_\-crash} (\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type} type, const \hyperlink{struct__PBS__crashCtx}{PBS\_\-crash\-Ctx} $\ast$ctx, unsigned int options, const char $\ast$string) \begin{CompactList}\small\item\em General purposes reboot routine. \item\end{CompactList}\item void \hyperlink{PBS_8c_a10}{PBS\_\-reboot} (unsigned int reason, unsigned int parameter, void $\ast$pc, unsigned int options, const char $\ast$string) \begin{CompactList}\small\item\em Routine to initiate a commanded reboot. \item\end{CompactList}\item void \hyperlink{PBS_8c_a11}{PBS\_\-panic} (unsigned int reason, unsigned int parameter, void $\ast$pc, unsigned int options, const char $\ast$string) \begin{CompactList}\small\item\em Routine to initiate a panic reboot. \item\end{CompactList}\end{CompactItemize} \subsection*{Variables} \begin{CompactItemize} \item \hypertarget{PBS_8c_a0}{ static int \hyperlink{PBS_8c_a0}{Pbs\-Initialized} = 0} \label{PBS_8c_a0} \begin{CompactList}\small\item\em Static flag indicating the PBS facility has been initialized. \item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} PBS library, contains the initialization routines for PBS. \begin{Desc} \item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \footnotesize\begin{verbatim} CVS $Id: PBS.c,v 1.1.1.1 2006/02/10 21:45:33 saxton Exp $ \end{verbatim} \normalsize \begin{Desc} \item[Warning:]This is currently a kludge.\end{Desc} \subsection{Function Documentation} \hypertarget{PBS_8c_a9}{ \index{PBS.c@{PBS.c}!PBS_crash@{PBS\_\-crash}} \index{PBS_crash@{PBS\_\-crash}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-crash]{\setlength{\rightskip}{0pt plus 5cm}void PBS\_\-crash (\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type} {\em type}, const \hyperlink{struct__PBS__crashCtx}{PBS\_\-crash\-Ctx} $\ast$ {\em ctx}, unsigned int {\em options}, const char $\ast$ {\em string})}} \label{PBS_8c_a9} General purposes reboot routine. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em type}]The type of reboot being requested, {\em i.e\/}. one of \end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type}. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em ctx}]A filled in\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a2}{PBS\_\-crash\-Ctx} block. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em options}]A set options. See\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a4}{PBS\_\-crash\-Options} for further details. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em string}]An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it.\end{description} \end{Desc} \hypertarget{PBS_8c_a8}{ \index{PBS.c@{PBS.c}!PBS_crashHandlerSet@{PBS\_\-crashHandlerSet}} \index{PBS_crashHandlerSet@{PBS\_\-crashHandlerSet}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-crashHandlerSet]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{PBS_8h_a3}{PBS\_\-crash\-Handler} PBS\_\-crash\-Handler\-Set (\hyperlink{PBS_8h_a3}{PBS\_\-crash\-Handler} {\em crash\-Handler})}} \label{PBS_8c_a8} Installs a new user crash handler. \begin{Desc} \item[Returns:]The old crash handler\end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em crash\-Handler}]The new crash handler routine. If this may be NULL or PBS\_\-CRASH\_\-HANDLER\_\-DEFAULT\end{description} \end{Desc} This routine may be specified as NULL, in which case no user crash handler callback routine is executed. \begin{Desc} \item[Note:]While one can currently get the same effect using either of the two example pieces of code below. If one uses the former, then the PBS crash handler is always\end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a18}{PBS\_\-crash\-Print()}, while if one uses the later, the crash handler tracks the current runtime default.\end{Desc} \footnotesize\begin{verbatim} PBS_crashHandlerSet (PBS_crashPrint); \end{verbatim} \normalsize \footnotesize\begin{verbatim} PBS_crashHandlerSet (PBS_CRASH_HANDLER_DEFAULT); \end{verbatim} \normalsize \hypertarget{PBS_8c_a7}{ \index{PBS.c@{PBS.c}!PBS_crashPrint@{PBS\_\-crashPrint}} \index{PBS_crashPrint@{PBS\_\-crashPrint}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-crashPrint]{\setlength{\rightskip}{0pt plus 5cm}int PBS\_\-crash\-Print (\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type} {\em type}, const \hyperlink{struct__PBS__crashCtx}{PBS\_\-crash\-Ctx} $\ast$ {\em ctx}, unsigned int {\em options}, const char $\ast$ {\em string})}} \label{PBS_8c_a7} Very simple default PBS crash handler. \begin{Desc} \item[Returns:]{\em options\/} \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em type}]The type of reboot being requested, {\em i.e\/}. one of\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_8vx-xxx-xxx_a2}{PBS\_\-crash\-Type}. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em ctx}]Pointer to a completed PBS\_\-crash\-Ctx block. \item[{\em options}]A set options. See\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a4}{PBS\_\-crash\-Options} for further details. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em string}]An arbitrary user string. It is just printed as the first line of the output.\end{description} \end{Desc} This is the current default user handler, {\em i\/}..e the one gets if PBS\_\-CRASH\_\-HANDLER\_\-DEFAULT is specified as the argument to \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a17}{PBS\_\-crash\-Handler\-Set()}.\end{Desc} \hypertarget{PBS_8c_a6}{ \index{PBS.c@{PBS.c}!PBS_fast_clear@{PBS\_\-fast\_\-clear}} \index{PBS_fast_clear@{PBS\_\-fast\_\-clear}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-fast\_\-clear]{\setlength{\rightskip}{0pt plus 5cm}void PBS\_\-fast\_\-clear (void $\ast$ {\em ptr}, unsigned int {\em nbytes})}} \label{PBS_8c_a6} Clears (Zeroes) the specified memory. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em ptr}]Pointer to the memory to zero \item[{\em nbytes}]The number of bytes to zero\end{description} \end{Desc} \begin{Desc} \item[]This provides a fast way of zeroing large chunks of memory on PPC platforms using the {\em dcbz\/} instruction. This instruction zeroes a cache line at a time. The savings in speed varies by processor, but factors of 5 or more are in the ballpark, saturating out at a factor of 2 once the data cache size is exceeded (32Kbytes).\end{Desc} \begin{Desc} \item[]On other platforms, the library supplied routine is used.\end{Desc} \begin{Desc} \item[Warning:]On PPC platforms, this will work if and only if the memory being cleared is cache enabled. For the most part this is not a problem since usually all memory but memory mapped to IO space and set aside for driver use is marked cacheable. This routine does check to make sure the data cache is globally enabled. If not, the generic clear routine is called. The routine is protected if the data cache is globally disabled, in this case, dropping make and using the generic routine.\end{Desc} \hypertarget{PBS_8c_a3}{ \index{PBS.c@{PBS.c}!PBS_initialize@{PBS\_\-initialize}} \index{PBS_initialize@{PBS\_\-initialize}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-initialize]{\setlength{\rightskip}{0pt plus 5cm}int PBS\_\-initialize (int {\em wut\_\-tmr\_\-cnt}, int {\em keepalive\_\-period})}} \label{PBS_8c_a3} One-time PBS library initialization routine. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em wut\_\-tmr\_\-cnt}]The number of WUT timers to keep in the system pool. If specified as 0, a default value of 256 will be used. \item[{\em keepalive\_\-period}]The period (in nanoseconds) of the periodic keepalive timer. If specified as 0, a default value of 20,000,000, corresponding to 50Hz will be used.\end{description} \end{Desc} \begin{Desc} \item[Returns:]Status, 1 indicates PBS was already initialized\end{Desc} This is a one-time initialization of the PBS library. This call not only initializes static resources, but also replaces the Vx\-Works decrement counter interrupt routine (the 'timer') with the high resolution WUT timers.\hypertarget{PBS_8c_a4}{ \index{PBS.c@{PBS.c}!PBS_initialize2@{PBS\_\-initialize2}} \index{PBS_initialize2@{PBS\_\-initialize2}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-initialize2]{\setlength{\rightskip}{0pt plus 5cm}int PBS\_\-initialize2 (int {\em wut\_\-tmr\_\-cnt}, int {\em keepalive\_\-period}, \hyperlink{MBA_8h_a1}{MBA\_\-create\_\-cb} {\em mba\_\-create}, void $\ast$ {\em mba\_\-prm})}} \label{PBS_8c_a4} One-time PBS library initialization routine. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em wut\_\-tmr\_\-cnt}]The number of WUT timers to keep in the system pool. If specified as 0, a default value of 256 will be used. \item[{\em keepalive\_\-period}]The period (in nanoseconds) of the periodic keepalive timer. If specified as 0, a default value of 20,000,000, corresponding to 50Hz will be used.\item[{\em mba\_\-create}]Alternate MBA partition creation routine. If specified as NULL, a default creation routine will be used and {\em prm\/} will be interpretted as a list of bad blocks, {\em i.e\/}. of type MBA\_\-bad\-Block\-List.\item[{\em mba\_\-prm}]Arbitrary parameter passed to the MBA partition creation routine.\end{description} \end{Desc} \begin{Desc} \item[Returns:]Status, 1 indicates PBS was already initialized\end{Desc} This is a one-time initialization of the PBS library.\hypertarget{PBS_8c_a11}{ \index{PBS.c@{PBS.c}!PBS_panic@{PBS\_\-panic}} \index{PBS_panic@{PBS\_\-panic}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-panic]{\setlength{\rightskip}{0pt plus 5cm}void PBS\_\-panic (unsigned int {\em reason}, unsigned int {\em parameter}, void $\ast$ {\em pc}, unsigned int {\em options}, const char $\ast$ {\em string})}} \label{PBS_8c_a11} Routine to initiate a panic reboot. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em reason}]An application specific reason for the reboot. For example, this may identify the reason why the software is in a panic. \item[{\em parameter}]An additional opaque user application parameter \item[{\em pc}]The PC of where the reboot panic originated. Typically one would use PBS\_\-PC() to get fill this value. \item[{\em options}]A set options. Set\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a4}{PBS\_\-crash\-Options} for further details. \end{Desc} \begin{Desc} \item[Parameters:] \begin{description} \item[{\em string}]An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it.\end{description} \end{Desc} This routine is typically called when a piece of application code finds itself confronted with a software or hardware error which it cannot handle. This routine will\begin{enumerate} \item fill out the remaining fields of the PCB\_\-crash\-Ctx block\item callback any user supplied PBS\_\-crash\-Handler, see\begin{Desc} \item[See also:]\hyperlink{PBS_8c_a8}{PBS\_\-crash\-Handler\-Set} ().\end{Desc} \item call the underlying OS dependent reboot or abort routine.\end{enumerate} \hypertarget{PBS_8c_a10}{ \index{PBS.c@{PBS.c}!PBS_reboot@{PBS\_\-reboot}} \index{PBS_reboot@{PBS\_\-reboot}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-reboot]{\setlength{\rightskip}{0pt plus 5cm}void PBS\_\-reboot (unsigned int {\em reason}, unsigned int {\em parameter}, void $\ast$ {\em pc}, unsigned int {\em options}, const char $\ast$ {\em string})}} \label{PBS_8c_a10} Routine to initiate a commanded reboot. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em string}]An arbitrary user string. This is used iff there is an active PBS crash handler, in which case it is merely passed through to it. \item[{\em reason}]An command specific reason for the reboot. For example this may identify the source of the reboot command \item[{\em parameter}]An additional opaque user parameter \item[{\em pc}]The PC of where the reboot command originated. Typically one would use PBS\_\-PC() to get fill this value. \item[{\em options}]A set options. See\end{description} \end{Desc} \begin{Desc} \item[See also:]\hyperlink{PBS_8h_a4}{PBS\_\-crash\-Options} for further details.\end{Desc} This routine is called when a command instructing the OS to reboot has been received. This routine will\begin{enumerate} \item fill out the remaining fields of the PCB\_\-crash\-Ctx block\item callback any user supplied PBS\_\-crash\-Handler, see\begin{Desc} \item[See also:]\hyperlink{PBS_8c_a8}{PBS\_\-crash\-Handler\-Set} ().\end{Desc} \item call the underlying OS dependent reboot or abort routine.\end{enumerate} \hypertarget{PBS_8c_a5}{ \index{PBS.c@{PBS.c}!PBS_shutdown@{PBS\_\-shutdown}} \index{PBS_shutdown@{PBS\_\-shutdown}!PBS.c@{PBS.c}} \subsubsection[PBS\_\-shutdown]{\setlength{\rightskip}{0pt plus 5cm}int PBS\_\-shutdown (void)}} \label{PBS_8c_a5} Shuts down the PBS facility. \begin{Desc} \item[Warning:]This function is only meant to be used during development. Its main use is to allow the semi-graceful reloading of PBS in the Vx\-Works environment.\end{Desc} \hypertarget{PBS_8c_a1}{ \index{PBS.c@{PBS.c}!TASK_sys_init@{TASK\_\-sys\_\-init}} \index{TASK_sys_init@{TASK\_\-sys\_\-init}!PBS.c@{PBS.c}} \subsubsection[TASK\_\-sys\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-sys\_\-init (void)}} \label{PBS_8c_a1} Performs one time only initialization of the TASK facility. \begin{Desc} \item[Returns:]Status\end{Desc} \hypertarget{PBS_8c_a2}{ \index{PBS.c@{PBS.c}!TASK_sys_shutdown@{TASK\_\-sys\_\-shutdown}} \index{TASK_sys_shutdown@{TASK\_\-sys\_\-shutdown}!PBS.c@{PBS.c}} \subsubsection[TASK\_\-sys\_\-shutdown]{\setlength{\rightskip}{0pt plus 5cm}int TASK\_\-sys\_\-shutdown (void)}} \label{PBS_8c_a2} Performs the shutdown of the TASK facility. This essentially undoes what TASK\_\-sys\_\-init did. \begin{Desc} \item[Returns:]Status\end{Desc}