\hypertarget{SPIN_8ih}{
\section{SPIN.ih File Reference}
\label{SPIN_8ih}\index{SPIN.ih@{SPIN.ih}}
}
Utilities to spin the CPU for a well-defined period of time. 


{\tt \#include \char`\"{}BBC/inline.h\char`\"{}}\par
{\tt \#include \char`\"{}BBC/SPIN\_\-time.h\char`\"{}}\par
\subsection*{Defines}
\begin{CompactItemize}
\item 
\hypertarget{SPIN_8ih_a0}{
\index{SPIN__EXT_PROTO@{SPIN\_\-\_\-EXT\_\-PROTO}!SPIN.ih@{SPIN.ih}}\index{SPIN.ih@{SPIN.ih}!SPIN__EXT_PROTO@{SPIN\_\-\_\-EXT\_\-PROTO}}
\#define \hyperlink{SPIN_8ih_a0}{SPIN\_\-\_\-EXT\_\-PROTO}\ INLINE\_\-USR\_\-EXT\_\-PROTO}
\label{SPIN_8ih_a0}

\begin{CompactList}\small\item\em External Prototype specification.\item\end{CompactList}\item 
\hypertarget{SPIN_8ih_a1}{
\index{SPIN__EXT_FNC@{SPIN\_\-\_\-EXT\_\-FNC}!SPIN.ih@{SPIN.ih}}\index{SPIN.ih@{SPIN.ih}!SPIN__EXT_FNC@{SPIN\_\-\_\-EXT\_\-FNC}}
\#define \hyperlink{SPIN_8ih_a1}{SPIN\_\-\_\-EXT\_\-FNC}\ INLINE\_\-USR\_\-EXT\_\-FNC}
\label{SPIN_8ih_a1}

\begin{CompactList}\small\item\em Internal Prototype specification.\item\end{CompactList}\item 
\hypertarget{SPIN_8ih_a2}{
\index{SPIN__LCL_PROTO@{SPIN\_\-\_\-LCL\_\-PROTO}!SPIN.ih@{SPIN.ih}}\index{SPIN.ih@{SPIN.ih}!SPIN__LCL_PROTO@{SPIN\_\-\_\-LCL\_\-PROTO}}
\#define \hyperlink{SPIN_8ih_a2}{SPIN\_\-\_\-LCL\_\-PROTO}\ INLINE\_\-USR\_\-LCL\_\-PROTO}
\label{SPIN_8ih_a2}

\begin{CompactList}\small\item\em External Function declaration.\item\end{CompactList}\item 
\hypertarget{SPIN_8ih_a3}{
\index{SPIN__LCL_FNC@{SPIN\_\-\_\-LCL\_\-FNC}!SPIN.ih@{SPIN.ih}}\index{SPIN.ih@{SPIN.ih}!SPIN__LCL_FNC@{SPIN\_\-\_\-LCL\_\-FNC}}
\#define \hyperlink{SPIN_8ih_a3}{SPIN\_\-\_\-LCL\_\-FNC}\ INLINE\_\-USR\_\-LCL\_\-FNC}
\label{SPIN_8ih_a3}

\begin{CompactList}\small\item\em Internal Function declaration.\item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
SPIN\_\-\_\-EXT\_\-PROTO unsigned int \hyperlink{SPIN_8ih_a4}{SPIN\_\-\_\-nsecs\_\-to\_\-ptus} (unsigned int nanoseconds)
\begin{CompactList}\small\item\em Converts a number of nanoseconds to PTUs.\item\end{CompactList}\item 
SPIN\_\-\_\-EXT\_\-PROTO unsigned int \hyperlink{SPIN_8ih_a5}{SPIN\_\-\_\-ptus\_\-to\_\-nsecs} (unsigned int ptus)
\item 
SPIN\_\-\_\-EXT\_\-PROTO \hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} \hyperlink{SPIN_8ih_a6}{SPIN\_\-\_\-curtime} (void)
\begin{CompactList}\small\item\em Returns the current time in units of PTUs.\item\end{CompactList}\item 
SPIN\_\-\_\-EXT\_\-PROTO int \hyperlink{SPIN_8ih_a7}{SPIN\_\-\_\-wait} (\hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} begin\_\-ptu, unsigned int ptus)
\begin{CompactList}\small\item\em Allows one to wait a specified time period after a start time.\item\end{CompactList}\item 
SPIN\_\-\_\-EXT\_\-PROTO int \hyperlink{SPIN_8ih_a8}{SPIN\_\-\_\-check} (\hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} begin\_\-ptu, unsigned int ptus)
\begin{CompactList}\small\item\em Checks whether the requested amount of time has elapsed.\item\end{CompactList}\item 
SPIN\_\-\_\-EXT\_\-PROTO int \hyperlink{SPIN_8ih_a9}{SPIN\_\-\_\-spin} (unsigned int ptus)
\begin{CompactList}\small\item\em Places the CPU into a spin loop until the specified number of PTUs has elapsed.\item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Utilities to spin the CPU for a well-defined period of time.



\begin{Desc}
\item[Author: ]\par
JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}
These are the inline versions of the SPIN routines. The inline and non-inline versions maybe used in any combination. For complete documentation refer to SPIN.h and SPIN.c.



\subsection{Function Documentation}
\hypertarget{SPIN_8ih_a8}{
\index{SPIN.ih@{SPIN.ih}!SPIN__check@{SPIN\_\-\_\-check}}
\index{SPIN__check@{SPIN\_\-\_\-check}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-check]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-\_\-check (\hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} {\em begin\_\-ptu}, unsigned int {\em ptus})}}
\label{SPIN_8ih_a8}


Checks whether the requested amount of time has elapsed.



 is that this routine is used in a polling mode. \begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
begin\_\-ptu}]The start time \item[{\em 
ptus\-To\-Wait}]The number of PTUs to wait \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
See \hyperlink{SPIN_8ih_a9}{SPIN\_\-\_\-spin}(). The difference here is that this routine can return a negative number, indicating the number of PTUs until expiration time.\end{Desc}
This is a polling version of \hyperlink{SPIN_8ih_a7}{SPIN\_\-\_\-wait}(). Whereas in \hyperlink{SPIN_8ih_a7}{SPIN\_\-\_\-wait}(), control does not return from until the requested amount of time has elapsed, this routine returns immediately with the amount of time till expiration. Using this routine, the caller can check, without blocking, if the specified amount of time has passed.

Note that in order to keep the interpretation of the return value uniform over the SPIN routines, the amount of time till expiration is returned as a negative number. A positive number indicates the amount of time past the expiration time. \hypertarget{SPIN_8ih_a6}{
\index{SPIN.ih@{SPIN.ih}!SPIN__curtime@{SPIN\_\-\_\-curtime}}
\index{SPIN__curtime@{SPIN\_\-\_\-curtime}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-curtime]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} SPIN\_\-\_\-curtime (void)}}
\label{SPIN_8ih_a6}


Returns the current time in units of PTUs.

\begin{Desc}
\item[Return values: ]\par
\begin{description}
\item[{\em 
The}]current time in units of PTUs.\end{description}
\end{Desc}
This gets the current time. For performance reasons, the units are in PTUs and the range is generally limited to 32 bits, although this is a platform dependent statement.

The customary use of this routine is to strobe the starting time, then use the return value along with \hyperlink{SPIN_8ih_a8}{SPIN\_\-\_\-check}() or \hyperlink{SPIN_8ih_a7}{SPIN\_\-\_\-wait}() to allow a specified amount of time to elapsed from the starting time. \hypertarget{SPIN_8ih_a4}{
\index{SPIN.ih@{SPIN.ih}!SPIN__nsecs_to_ptus@{SPIN\_\-\_\-nsecs\_\-to\_\-ptus}}
\index{SPIN__nsecs_to_ptus@{SPIN\_\-\_\-nsecs\_\-to\_\-ptus}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-nsecs\_\-to\_\-ptus]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-\_\-nsecs\_\-to\_\-ptus (unsigned int {\em nsecs})}}
\label{SPIN_8ih_a4}


Converts a number of nanoseconds to PTUs.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
nsecs}]The number of nanoseconds to convert to a PTUs \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
The equivalent time in PTUs.\end{Desc}
This routine converts nanoseconds into Processor Timer Units. This is usually a one time call which must be made to convert the natural time units of nanoseconds to the units the SPIN routines work in. \hypertarget{SPIN_8ih_a5}{
\index{SPIN.ih@{SPIN.ih}!SPIN__ptus_to_nsecs@{SPIN\_\-\_\-ptus\_\-to\_\-nsecs}}
\index{SPIN__ptus_to_nsecs@{SPIN\_\-\_\-ptus\_\-to\_\-nsecs}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-ptus\_\-to\_\-nsecs]{\setlength{\rightskip}{0pt plus 5cm}unsigned int SPIN\_\-\_\-ptus\_\-to\_\-nsecs (unsigned int {\em ptus})}}
\label{SPIN_8ih_a5}


\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
ptus}]The number of PTUs to convert to nanoseconds \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
The equivalent time in units of nanoseconds.\end{Desc}
This routine is the complement of the \hyperlink{SPIN_8ih_a4}{SPIN\_\-\_\-nsecs\_\-to\_\-ptus}(). It is useful only when converting the return value of the SPIN\_\-\_\-spin routines back to physically meaningful units, ie nanaseconds. It certainly will not be as heavily used as \hyperlink{SPIN_8ih_a4}{SPIN\_\-\_\-nsecs\_\-to\_\-ptus}(). \hypertarget{SPIN_8ih_a9}{
\index{SPIN.ih@{SPIN.ih}!SPIN__spin@{SPIN\_\-\_\-spin}}
\index{SPIN__spin@{SPIN\_\-\_\-spin}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-spin]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-\_\-spin (unsigned int {\em ptus\-To\-Spin})}}
\label{SPIN_8ih_a9}


Places the CPU into a spin loop until the specified number of PTUs has elapsed.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
ptus\-To\-Spin}]The number of PTUs to spin. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
The number of PTUs past the expiration time.\end{Desc}
The CPU is placed into a tight loop, sampling an internal clock until the specified time has elapsed. Because of task switching or interrupt activity, the SPIN routines can only guarantee that at least the specified time has elapsed. Generally spin loops are rather loose in nature, so that the actual elapsed time is not critical. Nevertheless, the return value of this routine indicates how far past the expiration time the SPIN routine ran. \hypertarget{SPIN_8ih_a7}{
\index{SPIN.ih@{SPIN.ih}!SPIN__wait@{SPIN\_\-\_\-wait}}
\index{SPIN__wait@{SPIN\_\-\_\-wait}!SPIN.ih@{SPIN.ih}}
\subsubsection[SPIN\_\-\_\-wait]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-\_\-wait (\hyperlink{SPIN__time_8h_8sx-xxx-scc_a0}{SPIN\_\-time} {\em begin\_\-ptu}, unsigned int {\em ptus\-To\-Wait})}}
\label{SPIN_8ih_a7}


Allows one to wait a specified time period after a start time.

\begin{Desc}
\item[Parameters: ]\par
\begin{description}
\item[{\em 
begin\_\-ptu}]The start time \item[{\em 
ptus\-To\-Wait}]The number of PTUs to wait \end{description}
\end{Desc}
\begin{Desc}
\item[Returns: ]\par
See \hyperlink{SPIN_8ih_a9}{SPIN\_\-\_\-spin}().\end{Desc}
This routine allows the user to spin for a specified amount of time after an arbitrary start time. It is similar to \hyperlink{SPIN_8ih_a9}{SPIN\_\-\_\-spin}(), but whereas SPIN\_\-spin starts from the current time, SPIN\_\-\_\-wait starts from an arbitrary time.

\begin{Desc}
\item[Warning: ]\par
Due to the split nature of the calls involved in SPIN\_\-wait's usage, ie one call to get the start time and another call to do the wait, it is somewhat easier to exceed the range limitation. Due to arthimetic reasons, the range is limited to less than 2$\ast$$\ast$31, or about 2 seconds. Do not split the call to get the start time, SPIN\_\-curtime() and the SPIN\_\-wait() with any code that code take significant amounts of time. \end{Desc}