\hypertarget{SPIN_8h}{
\section{SPIN.h File Reference}
\label{SPIN_8h}\index{SPIN.h@{SPIN.h}}
}
Spin the CPU for a well-defined period of time, callable version. 

{\tt \#include \char`\"{}IPBS/SPIN\_\-time.h\char`\"{}}\par


Include dependency graph for SPIN.h:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=117pt]{SPIN_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=87pt]{SPIN_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{CompactItemize}
\item 
unsigned int \hyperlink{SPIN_8h_a0}{SPIN\_\-nsecs\_\-to\_\-ptus} (unsigned int nsecs)
\begin{CompactList}\small\item\em Converts a number of nanoseconds to PTUs. \item\end{CompactList}\item 
unsigned int \hyperlink{SPIN_8h_a1}{SPIN\_\-ptus\_\-to\_\-nsecs} (unsigned int ptus)
\item 
\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} \hyperlink{SPIN_8h_a2}{SPIN\_\-curtime} (void)
\begin{CompactList}\small\item\em Returns the current time in units of PTUs. \item\end{CompactList}\item 
int \hyperlink{SPIN_8h_a3}{SPIN\_\-check} (\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} begin\_\-ptu, unsigned int ptus\-To\-Wait)
\begin{CompactList}\small\item\em Checks whether the requested amount of time has elapsed. is that this routine is used in a polling mode. \item\end{CompactList}\item 
int \hyperlink{SPIN_8h_a4}{SPIN\_\-wait} (\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} begin\_\-ptu, unsigned int ptus\-To\-Wait)
\begin{CompactList}\small\item\em Allows one to wait a specified time period after a start time. \item\end{CompactList}\item 
int \hyperlink{SPIN_8h_a5}{SPIN\_\-spin} (unsigned int ptu\-To\-Spin)
\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}
Spin the CPU for a well-defined period of time, callable version. 

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


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


\begin{Desc}
\item[SYNOPSIS]Provides the generic interface definitions of the SPIN utility. This utility implements timed spin loops with a specified resolution of nanoseconds. Note that this is the resolution but NOT the accuracy. The accuracy and precision will vary depending on the platform. The implementation method of choice is to use a local high resolution timer when available.\end{Desc}
These routines are useful when one needs to wait a very short amount of time for some operation to complete. Here short means short compared to the overhead of using an TIMER interrupt routine to do the same job.

The units of time are always in the processors native time units (PTUs). This varies platform to platform. For example, PPC implementations have resolutions in the range 50-100nsecs, Sun's are around 60nsecs and Linux around 10msecs.

This implementation is the standard function call interface. See \hyperlink{SPIN_8ih}{SPIN.ih} for an inline version of these same routines. Given that one is generally spinning for a very short period of time, the increased efficiency and, perhaps, more importantly, the better the minimum time that one can wait, the inlines may be more appropriate.

\begin{Desc}
\item[USAGE]General usage would be to use \hyperlink{SPIN_8h_a0}{SPIN\_\-nsecs\_\-to\_\-ptus()} to convert the number of nanoseconds to the number of processor timer unit (that's what the ptu stands for, Processor Timer Units) counts. This number would then be used as the argument to \hyperlink{SPIN_8h_a5}{SPIN\_\-spin()} which would spin wait for the specified time. Because tasks may be preemptied by higher priority goings-on, one can only guarantee that the elapsed time is greater than or equal to the requested time. T herefore, \hyperlink{SPIN_8h_a5}{SPIN\_\-spin()} returns the overrun, ie how long past the requested expiration time the SPIN lasted.\end{Desc}
\begin{Desc}
\item[EXAMPLE]

\footnotesize\begin{verbatim}    / * Convert 2 usec to local units * /
    ptus = SPIN_nsecs_to_ptus (2000);

    / * Load a register every 2 usecs * /
    while (--nbytes >= 0)
    {
        load_register (REG, value);
        SPIN_spin (ptus);
    }
\end{verbatim}
\normalsize
\end{Desc}
\begin{Desc}
\item[LIMITATIONS]Due to arthimetic reasons, the amount of time one can spin is limited to about 2$\ast$$\ast$31 nanoseconds or about 2 seconds. In practice this should not be a problem. The Wake\-Up Timer facility, WUT, is a much better choice if one wishes to mark off times greater than around $\sim$25 microseconds.\end{Desc}


\subsection{Function Documentation}
\hypertarget{SPIN_8h_a3}{
\index{SPIN.h@{SPIN.h}!SPIN_check@{SPIN\_\-check}}
\index{SPIN_check@{SPIN\_\-check}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-check]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-check (\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} {\em begin\_\-ptu}, unsigned int {\em ptus})}}
\label{SPIN_8h_a3}


Checks whether the requested amount of time has elapsed. is that this routine is used in a polling mode. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em begin\_\-ptu}]The start time \item[{\em ptus}]The number of PTUs to wait \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]See \hyperlink{SPIN_8h_a5}{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_8h_a4}{SPIN\_\-wait()}. Whereas in \hyperlink{SPIN_8h_a4}{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_8h_a2}{
\index{SPIN.h@{SPIN.h}!SPIN_curtime@{SPIN\_\-curtime}}
\index{SPIN_curtime@{SPIN\_\-curtime}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-curtime]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} SPIN\_\-curtime (void)}}
\label{SPIN_8h_a2}


Returns the current time in units of PTUs. 

\begin{Desc}
\item[Return values:]
\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_8h_a3}{SPIN\_\-check()} or \hyperlink{SPIN_8h_a4}{SPIN\_\-wait()} to allow a specified amount of time to elapsed from the starting time.\hypertarget{SPIN_8h_a0}{
\index{SPIN.h@{SPIN.h}!SPIN_nsecs_to_ptus@{SPIN\_\-nsecs\_\-to\_\-ptus}}
\index{SPIN_nsecs_to_ptus@{SPIN\_\-nsecs\_\-to\_\-ptus}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-nsecs\_\-to\_\-ptus]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-nsecs\_\-to\_\-ptus (unsigned int {\em nsecs})}}
\label{SPIN_8h_a0}


Converts a number of nanoseconds to PTUs. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em nsecs}]The number of nanoseconds to convert to a PTUs \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]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_8h_a1}{
\index{SPIN.h@{SPIN.h}!SPIN_ptus_to_nsecs@{SPIN\_\-ptus\_\-to\_\-nsecs}}
\index{SPIN_ptus_to_nsecs@{SPIN\_\-ptus\_\-to\_\-nsecs}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-ptus\_\-to\_\-nsecs]{\setlength{\rightskip}{0pt plus 5cm}unsigned int SPIN\_\-ptus\_\-to\_\-nsecs (unsigned int {\em ptus})}}
\label{SPIN_8h_a1}


\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ptus}]The number of PTUs to convert to nanoseconds \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The equivalent time in units of nanoseconds.\end{Desc}
This routine is the complement of the \hyperlink{SPIN_8h_a0}{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_8h_a0}{SPIN\_\-nsecs\_\-to\_\-ptus()}.\hypertarget{SPIN_8h_a5}{
\index{SPIN.h@{SPIN.h}!SPIN_spin@{SPIN\_\-spin}}
\index{SPIN_spin@{SPIN\_\-spin}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-spin]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-spin (unsigned int {\em ptus\-To\-Spin})}}
\label{SPIN_8h_a5}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ptus\-To\-Spin}]The number of PTUs to spin. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]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_8h_a4}{
\index{SPIN.h@{SPIN.h}!SPIN_wait@{SPIN\_\-wait}}
\index{SPIN_wait@{SPIN\_\-wait}!SPIN.h@{SPIN.h}}
\subsubsection[SPIN\_\-wait]{\setlength{\rightskip}{0pt plus 5cm}int SPIN\_\-wait (\hyperlink{SPIN__time_8h_8vx-xxx-xxx_a0}{SPIN\_\-time} {\em begin\_\-ptu}, unsigned int {\em ptus\-To\-Wait})}}
\label{SPIN_8h_a4}


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

\begin{Desc}
\item[Parameters:]
\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:]See \hyperlink{SPIN_8h_a5}{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_8h_a5}{SPIN\_\-spin()}, but whereas SPIN\_\-spin starts from the current time, SPIN\_\-wait starts from an arbitrary time.

\begin{Desc}
\item[Warning:]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, \hyperlink{SPIN_8h_a2}{SPIN\_\-curtime()} and the \hyperlink{SPIN_8h_a4}{SPIN\_\-wait()} with any code that code take significant amounts of time.\end{Desc}