\hypertarget{WUT_8h}{
\section{WUT.h File Reference}
\label{WUT_8h}\index{WUT.h@{WUT.h}}
}
Wake\-Up Timer facility. 


\subsection*{Defines}
\begin{CompactItemize}
\item 
\hypertarget{WUT_8h_a0}{
\index{WUT_CLK_WUT@{WUT\_\-CLK\_\-WUT}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_CLK_WUT@{WUT\_\-CLK\_\-WUT}}
\#define \hyperlink{WUT_8h_a0}{WUT\_\-CLK\_\-WUT}\ ((struct \hyperlink{struct__WUT}{\_\-WUT} $\ast$)(0))}
\label{WUT_8h_a0}

\begin{CompactList}\small\item\em Internal WUT clock.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a1}{
\index{WUT_CLK_CPU@{WUT\_\-CLK\_\-CPU}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_CLK_CPU@{WUT\_\-CLK\_\-CPU}}
\#define \hyperlink{WUT_8h_a1}{WUT\_\-CLK\_\-CPU}\ ((struct \hyperlink{struct__WUT}{\_\-WUT} $\ast$)(1))}
\label{WUT_8h_a1}

\begin{CompactList}\small\item\em CPU clock.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a2}{
\index{WUT_CLK_WALL@{WUT\_\-CLK\_\-WALL}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_CLK_WALL@{WUT\_\-CLK\_\-WALL}}
\#define \hyperlink{WUT_8h_a2}{WUT\_\-CLK\_\-WALL}\ ((struct \hyperlink{struct__WUT}{\_\-WUT} $\ast$)(2))}
\label{WUT_8h_a2}

\begin{CompactList}\small\item\em Wall clock.\item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{WUT_8h_a3}{
\index{WUT@{WUT}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT@{WUT}}
typedef \hyperlink{struct__WUT}{\_\-WUT} \hyperlink{WUT_8h_a3}{WUT}}
\label{WUT_8h_a3}

\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__WUT}{\_\-WUT}.\item\end{CompactList}\item 
typedef long long \hyperlink{WUT_8h_a4}{WUT\_\-time}
\begin{CompactList}\small\item\em Defines the internal time representation.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a5}{
\index{WUT_state@{WUT\_\-state}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_state@{WUT\_\-state}}
typedef enum \hyperlink{WUT_8h_a28}{\_\-WUT\_\-state} \hyperlink{WUT_8h_a5}{WUT\_\-state}}
\label{WUT_8h_a5}

\begin{CompactList}\small\item\em Typedef for enum \_\-WUT\_\-state.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a6}{
\index{WUT_cb_status@{WUT\_\-cb\_\-status}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_cb_status@{WUT\_\-cb\_\-status}}
typedef enum \hyperlink{WUT_8h_a29}{\_\-WUT\_\-cb\_\-status} \hyperlink{WUT_8h_a6}{WUT\_\-cb\_\-status}}
\label{WUT_8h_a6}

\begin{CompactList}\small\item\em Typedef for enum \_\-WUT\_\-cb\_\-status.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a7}{
\index{WUT_cb_parameter@{WUT\_\-cb\_\-parameter}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_cb_parameter@{WUT\_\-cb\_\-parameter}}
typedef void $\ast$ \hyperlink{WUT_8h_a7}{WUT\_\-cb\_\-parameter}}
\label{WUT_8h_a7}

\begin{CompactList}\small\item\em The callback parameter type.\item\end{CompactList}\item 
typedef \hyperlink{WUT_8h_a6}{WUT\_\-cb\_\-status}($\ast$ \hyperlink{WUT_8h_a8}{WUT\_\-cb\_\-routine} )(\hyperlink{WUT_8h_a7}{WUT\_\-cb\_\-parameter} $\ast$prm, \hyperlink{WUT_8h_a3}{WUT} $\ast$wut)
\begin{CompactList}\small\item\em Define the callback routine signature.\item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \hyperlink{WUT_8h_a28}{\_\-WUT\_\-state} \{ \hyperlink{WUT_8h_a28a9}{WUT\_\-K\_\-FREE} =  -2, 
\hyperlink{WUT_8h_a28a10}{WUT\_\-K\_\-ACTIVE} =  -1, 
\hyperlink{WUT_8h_a28a11}{WUT\_\-K\_\-QUEUED} =   0, 
\hyperlink{WUT_8h_a28a12}{WUT\_\-K\_\-ALLOCATED} =   1, 
\hyperlink{WUT_8h_a28a13}{WUT\_\-K\_\-CANCELLED} =   2, 
\hyperlink{WUT_8h_a28a14}{WUT\_\-K\_\-EXPIRED} =   3
 \}
\begin{CompactList}\small\item\em Enumerate the possible states of a Wake\-Up Timer entry.\item\end{CompactList}\item 
enum \hyperlink{WUT_8h_a29}{\_\-WUT\_\-cb\_\-status} \{ \hyperlink{WUT_8h_a29a15}{WUT\_\-K\_\-STATE\_\-CHANGE\_\-NO} =  0, 
\hyperlink{WUT_8h_a29a16}{WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES} =  1
 \}
\begin{CompactList}\small\item\em Enumerates the various values of a WUT callable service routine.\item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
\hypertarget{WUT_8h_a17}{
\index{WUT_init@{WUT\_\-init}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_init@{WUT\_\-init}}
int \hyperlink{WUT_8h_a17}{WUT\_\-init} (int count)}
\label{WUT_8h_a17}

\begin{CompactList}\small\item\em One time WUT services initialization routine.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a18}{
\index{WUT_connect@{WUT\_\-connect}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_connect@{WUT\_\-connect}}
int \hyperlink{WUT_8h_a18}{WUT\_\-connect} (int hertz)}
\label{WUT_8h_a18}

\begin{CompactList}\small\item\em One time WUT service connection routine.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a19}{
\index{WUT_cancel@{WUT\_\-cancel}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_cancel@{WUT\_\-cancel}}
\hyperlink{WUT_8h_a5}{WUT\_\-state} \hyperlink{WUT_8h_a19}{WUT\_\-cancel} (\hyperlink{WUT_8h_a3}{WUT} $\ast$wut)}
\label{WUT_8h_a19}

\begin{CompactList}\small\item\em Cancels a WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a20}{
\index{WUT_create@{WUT\_\-create}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_create@{WUT\_\-create}}
\hyperlink{WUT_8h_a3}{WUT} $\ast$ \hyperlink{WUT_8h_a20}{WUT\_\-create} (void)}
\label{WUT_8h_a20}

\begin{CompactList}\small\item\em Allocate a WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a21}{
\index{WUT_destroy@{WUT\_\-destroy}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_destroy@{WUT\_\-destroy}}
\hyperlink{WUT_8h_a5}{WUT\_\-state} \hyperlink{WUT_8h_a21}{WUT\_\-destroy} (\hyperlink{WUT_8h_a3}{WUT} $\ast$wut)}
\label{WUT_8h_a21}

\begin{CompactList}\small\item\em Destroys, ie frees, an unused WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a22}{
\index{WUT_restart@{WUT\_\-restart}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_restart@{WUT\_\-restart}}
\hyperlink{WUT_8h_a5}{WUT\_\-state} \hyperlink{WUT_8h_a22}{WUT\_\-restart} (\hyperlink{WUT_8h_a3}{WUT} $\ast$wut, int delay, const \hyperlink{WUT_8h_a3}{WUT} $\ast$rel)}
\label{WUT_8h_a22}

\begin{CompactList}\small\item\em Restarts a WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a23}{
\index{WUT_start@{WUT\_\-start}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_start@{WUT\_\-start}}
\hyperlink{WUT_8h_a5}{WUT\_\-state} \hyperlink{WUT_8h_a23}{WUT\_\-start} (\hyperlink{WUT_8h_a3}{WUT} $\ast$wut, int delay, const \hyperlink{WUT_8h_a3}{WUT} $\ast$rel, \hyperlink{WUT_8h_a8}{WUT\_\-cb\_\-routine} cb, \hyperlink{WUT_8h_a7}{WUT\_\-cb\_\-parameter} prm)}
\label{WUT_8h_a23}

\begin{CompactList}\small\item\em Convenience routine to start a WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a24}{
\index{WUT_state_get@{WUT\_\-state\_\-get}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_state_get@{WUT\_\-state\_\-get}}
\hyperlink{WUT_8h_a5}{WUT\_\-state} \hyperlink{WUT_8h_a24}{WUT\_\-state\_\-get} (const \hyperlink{WUT_8h_a3}{WUT} $\ast$wut)}
\label{WUT_8h_a24}

\begin{CompactList}\small\item\em Gets the current state of the WUT timer entry.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a25}{
\index{WUT_time_get@{WUT\_\-time\_\-get}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_time_get@{WUT\_\-time\_\-get}}
\hyperlink{WUT_8h_a4}{WUT\_\-time} \hyperlink{WUT_8h_a25}{WUT\_\-time\_\-get} (void)}
\label{WUT_8h_a25}

\begin{CompactList}\small\item\em Gets the current internal value the WUT time.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a26}{
\index{WUT_dec_get@{WUT\_\-dec\_\-get}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_dec_get@{WUT\_\-dec\_\-get}}
int \hyperlink{WUT_8h_a26}{WUT\_\-dec\_\-get} (void)}
\label{WUT_8h_a26}

\begin{CompactList}\small\item\em Gets the current time left till the next timer expiration.\item\end{CompactList}\item 
\hypertarget{WUT_8h_a27}{
\index{WUT_dec_rate_get@{WUT\_\-dec\_\-rate\_\-get}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_dec_rate_get@{WUT\_\-dec\_\-rate\_\-get}}
int \hyperlink{WUT_8h_a27}{WUT\_\-dec\_\-rate\_\-get} (void)}
\label{WUT_8h_a27}

\begin{CompactList}\small\item\em Gets frequency, in Hertz of the WUT clock.\item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Wake\-Up Timer facility.



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


\subsection{Typedef Documentation}
\hypertarget{WUT_8h_a8}{
\index{WUT.h@{WUT.h}!WUT_cb_routine@{WUT\_\-cb\_\-routine}}
\index{WUT_cb_routine@{WUT\_\-cb\_\-routine}!WUT.h@{WUT.h}}
\subsubsection[WUT\_\-cb\_\-routine]{\setlength{\rightskip}{0pt plus 5cm}WUT\_\-cb\_\-routine}}
\label{WUT_8h_a8}


Define the callback routine signature.



The callback signature of a WUT interupt servicing routine is 

\footnotesize\begin{verbatim}

        WUT_cb_status = (*WUT_cb_routine) (WUT_cb_parameter *prm,
                                           WUT              *wut);

    where:
        prm: Is a parameter established when creating the timer entry and
             passed transparently back.
        wut: The WUT control block for this timer entry.
        
    The return value should be
 
     WUT_K_STATE_CHANGE_NO  - if the state of the WUT handle did not change
     WUT_K_STATE_CHANGE_YES - if the state of the WUT handle did     change
 
    The state of the WUT handle will change if the user successfully performs
    any of the calls in the callback routine.
 
     WUT_cancel
     WUT_start
     WUT_restart
     WUT_destroy
  
    If the state is not changed by the user, it is marked as WUT_K_EXPIRED
    by the WUT_service.
    \end{verbatim}\normalsize 
 \hypertarget{WUT_8h_a4}{
\index{WUT.h@{WUT.h}!WUT_time@{WUT\_\-time}}
\index{WUT_time@{WUT\_\-time}!WUT.h@{WUT.h}}
\subsubsection[WUT\_\-time]{\setlength{\rightskip}{0pt plus 5cm}WUT\_\-time}}
\label{WUT_8h_a4}


Defines the internal time representation.



The user of the WUT facility generally does not directly manipulate the time. However, the internal time representation is occassionally passed back to the user from a WUT routine. Later, he may pass this value back to another WUT routine. For this reason, the user must know its storage size, but not much else about it. 

\subsection{Enumeration Type Documentation}
\hypertarget{WUT_8h_a29}{
\index{WUT.h@{WUT.h}!_WUT_cb_status@{\_\-WUT\_\-cb\_\-status}}
\index{_WUT_cb_status@{\_\-WUT\_\-cb\_\-status}!WUT.h@{WUT.h}}
\subsubsection[\_\-WUT\_\-cb\_\-status]{\setlength{\rightskip}{0pt plus 5cm}enum \_\-WUT\_\-cb\_\-status}}
\label{WUT_8h_a29}


Enumerates the various values of a WUT callable service routine.



The WUT Interrupt Service Routine is obligated to pass back one of two values. Either WUT\_\-K\_\-STATE\_\-CHANGE\_\-NO, indicating that the user has not changed the state of the WUT control structure, or WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES, indicating he has, for example by calling \hyperlink{WUT_8h_a22}{WUT\_\-restart}() or \hyperlink{WUT_8h_a21}{WUT\_\-destroy}(). \begin{Desc}
\item[Enumeration values:]\par
\begin{description}
\index{WUT_K_STATE_CHANGE_NO@{WUT\_\-K\_\-STATE\_\-CHANGE\_\-NO}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_STATE_CHANGE_NO@{WUT\_\-K\_\-STATE\_\-CHANGE\_\-NO}}\item[{\em 
\hypertarget{WUT_8h_a29a15}{
{\em WUT\_\-K\_\-STATE\_\-CHANGE\_\-NO}}
\label{WUT_8h_a29a15}
}]ISR routine has not changed the state \index{WUT_K_STATE_CHANGE_YES@{WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_STATE_CHANGE_YES@{WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES}}\item[{\em 
\hypertarget{WUT_8h_a29a16}{
{\em WUT\_\-K\_\-STATE\_\-CHANGE\_\-YES}}
\label{WUT_8h_a29a16}
}]ISR routine has changed the state \end{description}
\end{Desc}

\hypertarget{WUT_8h_a28}{
\index{WUT.h@{WUT.h}!_WUT_state@{\_\-WUT\_\-state}}
\index{_WUT_state@{\_\-WUT\_\-state}!WUT.h@{WUT.h}}
\subsubsection[\_\-WUT\_\-state]{\setlength{\rightskip}{0pt plus 5cm}enum \_\-WUT\_\-state}}
\label{WUT_8h_a28}


Enumerate the possible states of a Wake\-Up Timer entry.



 The ownership of a timer handle is divided into two pieces.

When the value of the state is $>$= WUT\_\-K\_\-ALLOCATED, the user has ownership of the WUT handle. When the user has ownership of the WUT handle, it's state will not change except by user request. The user is allowed to request state changes, for example, by WUT\_\-cancel, but there is no guarantee that these state changes will be granted.

When the value of the state is $<$ WUT\_\-K\_\-ALLOCATED, the WUT services have ownership of the WUT handle. When the WUT services have ownership, the state may spontaneously change due to WUT activity. \begin{Desc}
\item[Enumeration values:]\par
\begin{description}
\index{WUT_K_FREE@{WUT\_\-K\_\-FREE}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_FREE@{WUT\_\-K\_\-FREE}}\item[{\em 
\hypertarget{WUT_8h_a28a9}{
{\em WUT\_\-K\_\-FREE}}
\label{WUT_8h_a28a9}
}]It's back in the pool \index{WUT_K_ACTIVE@{WUT\_\-K\_\-ACTIVE}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_ACTIVE@{WUT\_\-K\_\-ACTIVE}}\item[{\em 
\hypertarget{WUT_8h_a28a10}{
{\em WUT\_\-K\_\-ACTIVE}}
\label{WUT_8h_a28a10}
}]It's being serviced \index{WUT_K_QUEUED@{WUT\_\-K\_\-QUEUED}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_QUEUED@{WUT\_\-K\_\-QUEUED}}\item[{\em 
\hypertarget{WUT_8h_a28a11}{
{\em WUT\_\-K\_\-QUEUED}}
\label{WUT_8h_a28a11}
}]On the active queue \index{WUT_K_ALLOCATED@{WUT\_\-K\_\-ALLOCATED}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_ALLOCATED@{WUT\_\-K\_\-ALLOCATED}}\item[{\em 
\hypertarget{WUT_8h_a28a12}{
{\em WUT\_\-K\_\-ALLOCATED}}
\label{WUT_8h_a28a12}
}]It's been allocated \index{WUT_K_CANCELLED@{WUT\_\-K\_\-CANCELLED}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_CANCELLED@{WUT\_\-K\_\-CANCELLED}}\item[{\em 
\hypertarget{WUT_8h_a28a13}{
{\em WUT\_\-K\_\-CANCELLED}}
\label{WUT_8h_a28a13}
}]It's been cancelled \index{WUT_K_EXPIRED@{WUT\_\-K\_\-EXPIRED}!WUT.h@{WUT.h}}\index{WUT.h@{WUT.h}!WUT_K_EXPIRED@{WUT\_\-K\_\-EXPIRED}}\item[{\em 
\hypertarget{WUT_8h_a28a14}{
{\em WUT\_\-K\_\-EXPIRED}}
\label{WUT_8h_a28a14}
}]It's been serviced \end{description}
\end{Desc}

