\hypertarget{TBD_8h}{ \section{TBD.h File Reference} \label{TBD_8h}\index{TBD.h@{TBD.h}} } Task Block of Data manager, function prototypes and public data structures. This graph shows which files directly or indirectly include this file:\begin{figure}[H] \begin{center} \leavevmode \includegraphics[width=89pt]{TBD_8h__dep__incl} \end{center} \end{figure} \subsection*{Functions} \begin{CompactItemize} \item int \hyperlink{TBD_8h_a0}{TBD\_\-initialize} (void) \begin{CompactList}\small\item\em One time TBD system initialization call. \item\end{CompactList}\item int \hyperlink{TBD_8h_a1}{TBD\_\-add} (TBD\_\-ctl $\ast$tbd) \begin{CompactList}\small\item\em Estblishes a pointer to the task specific TBD control structure. \item\end{CompactList}\item int \hyperlink{TBD_8h_a2}{TBD\_\-delete} (void) \begin{CompactList}\small\item\em Deletes the association a pointer to the task specific TBD control structure. \item\end{CompactList}\item int \hyperlink{TBD_8h_a3}{TBD\_\-destroy} (void) \begin{CompactList}\small\item\em Shutdown the TBD facility. \item\end{CompactList}\item void $\ast$ \hyperlink{TBD_8h_a4}{TBD\_\-get} (void $\ast$$\ast$tbd, int index) \begin{CompactList}\small\item\em Returns the value task global data at the specified index. \item\end{CompactList}\item void \hyperlink{TBD_8h_a5}{TBD\_\-put} (void $\ast$$\ast$tbd, int index, void $\ast$value) \begin{CompactList}\small\item\em Puts the data value into the task specific data area at the specified index. \item\end{CompactList}\item void $\ast$$\ast$ \hyperlink{TBD_8h_a6}{TBD\_\-locate} (void) \begin{CompactList}\small\item\em Locates the block of task data. \item\end{CompactList}\item void $\ast$$\ast$ \hyperlink{TBD_8h_a7}{TBD\_\-glocate} (void) \begin{CompactList}\small\item\em Locates the block of task data. \item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Task Block of Data manager, function prototypes and public data structures. \begin{Desc} \item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \footnotesize\begin{verbatim} CVS $Id: TBD.h,v 1.1.1.1 2006/02/10 21:45:36 saxton Exp $ \end{verbatim} \normalsize \subsection{Function Documentation} \hypertarget{TBD_8h_a1}{ \index{TBD.h@{TBD.h}!TBD_add@{TBD\_\-add}} \index{TBD_add@{TBD\_\-add}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-add]{\setlength{\rightskip}{0pt plus 5cm}int TBD\_\-add (TBD\_\-ctl $\ast$ {\em tbd})}} \label{TBD_8h_a1} Estblishes a pointer to the task specific TBD control structure. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tbd}]Pointer to the TBD control structure for this TASK. \end{description} \end{Desc} \begin{Desc} \item[Returns:]Status\end{Desc} This routine is generally called once at task initialization time to establish a pointer to the TBD control structure for the calling task. When using tasks created by the TASK facility in PBS, this call is made automatically.\hypertarget{TBD_8h_a2}{ \index{TBD.h@{TBD.h}!TBD_delete@{TBD\_\-delete}} \index{TBD_delete@{TBD\_\-delete}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-delete]{\setlength{\rightskip}{0pt plus 5cm}int TBD\_\-delete (void)}} \label{TBD_8h_a2} Deletes the association a pointer to the task specific TBD control structure. \begin{Desc} \item[Returns:]Status\end{Desc} This routine is generally called once at {\bf task} exit time to dissolve the association of the pointer to the TBD control structure with the calling task. Note that freeing the memory of the managed area is the user's responsibility. When using tasks created by the TASK facility in PBS, this call is made automatically at task exit. The memory of the managed area is also freed.\hypertarget{TBD_8h_a3}{ \index{TBD.h@{TBD.h}!TBD_destroy@{TBD\_\-destroy}} \index{TBD_destroy@{TBD\_\-destroy}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int TBD\_\-destroy (void)}} \label{TBD_8h_a3} Shutdown the TBD facility. \begin{Desc} \item[Returns:]Status\end{Desc} This routine is generally called once at {\bf system} exit time to remove the global pointer (key).\hypertarget{TBD_8h_a4}{ \index{TBD.h@{TBD.h}!TBD_get@{TBD\_\-get}} \index{TBD_get@{TBD\_\-get}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-get]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ TBD\_\-get (void $\ast$$\ast$ {\em tbd}, int {\em index})}} \label{TBD_8h_a4} Returns the value task global data at the specified index. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tbd}]The table location, from a call to {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/} or one of its cousins. \item[{\em index}]The index of the requested data value. \end{description} \end{Desc} \begin{Desc} \item[Returns:]The data value at the specified index.\end{Desc} The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 3 instructions. It is highly recommended that the inline form of this function be used. \begin{Desc} \item[Warning:]If you have any doubt the TBD facility has not been initialized for the task you a making the call in, make sure to check the value returned from {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/} or one of its cousins for NULL before calling \hyperlink{TBD_8h_a4}{TBD\_\-get()}.\end{Desc} \hypertarget{TBD_8h_a7}{ \index{TBD.h@{TBD.h}!TBD_glocate@{TBD\_\-glocate}} \index{TBD_glocate@{TBD\_\-glocate}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-glocate]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$$\ast$ TBD\_\-glocate (void)}} \label{TBD_8h_a7} Locates the block of task data. \begin{Desc} \item[Returns:]Handle of the managed data area or NULL if called from a task that did not establish a managed data area.\end{Desc} This call is similar to {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/}, but, if called in ISR context, returns a handle to the ISR specfic managed data area. Because the implementation of this function on Vx\-Work's platforms is only in the 6-8 instruction area, the user is encouraged to use the inline version of this routine. \begin{Desc} \item[Warning:]While this function will return non-NULL in an ISR context, it still may return a NULL handle if called from a task that has not established a task specific managed data area.\end{Desc} If you have any doubts about whether the calling context has a managed area associated with it, make sure to check this handle being non-NULL before using it. If the caller knows that the calling context is always at task level, the TBD\_\-locate is more efficient. See {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/} for a usage example.\hypertarget{TBD_8h_a0}{ \index{TBD.h@{TBD.h}!TBD_initialize@{TBD\_\-initialize}} \index{TBD_initialize@{TBD\_\-initialize}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-initialize]{\setlength{\rightskip}{0pt plus 5cm}int TBD\_\-initialize (void)}} \label{TBD_8h_a0} One time TBD system initialization call. \begin{Desc} \item[Returns:]Status\end{Desc} This is not part of the runtime interface, but the documentation is provided for completeness. While the implementation of this routine is platform dependent, generally speaking, this routine establishes the address of the TBD maintained data structure as a task specific piece of data. The underlying OS then ensures that a pointer to the calling task's TBD data structure is made available.\hypertarget{TBD_8h_a6}{ \index{TBD.h@{TBD.h}!TBD_locate@{TBD\_\-locate}} \index{TBD_locate@{TBD\_\-locate}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-locate]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$$\ast$ TBD\_\-locate (void)}} \label{TBD_8h_a6} Locates the block of task data. \begin{Desc} \item[Returns:]Handle of the managed data area or NULL if called from a task that did not establish a managed data area or if called from an ISR (interrupt level).\end{Desc} This function returns a handle to the managed area for the current task. This handle is passed to {\em \hyperlink{TBD_8h_a5}{TBD\_\-put()}\/} and {\em \hyperlink{TBD_8h_a4}{TBD\_\-get()}\/} to perform reads and writes to selected locations. The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 2 instructions. It is highly recommended that the inline form of this function be used. \begin{Desc} \item[Warning:]If you have any doubts about whether the calling context has a managed area associated with it, make sure to check this handle being non-NULL before using it. If desired, one may use {\em \hyperlink{TBD_8ih_a1}{TBD\_\-\_\-glocate()}\/}, which will return a handle to a ISR specific data area. If, however, the caller knows the call is being made in the context of a task, \hyperlink{TBD_8h_a6}{TBD\_\-locate()} is more efficient.\end{Desc} {\bf EXAMPLE} \par {\bf -------} \par \footnotesize\begin{verbatim} void **tbd = TBD__locate (); / * Check for NULL * / if (tbd != NULL) { int org_1 = TBD__get (tbd, DATA_IDX_1); int org_2 = TBD__get (tbd, DATA_IDX_2]; TBD__put (tbd, DATA_IDX_1, 0xdeadbeef); TBD__put (tbd, DATA_IDX_2, 0xabadcafe); } \end{verbatim} \normalsize \hypertarget{TBD_8h_a5}{ \index{TBD.h@{TBD.h}!TBD_put@{TBD\_\-put}} \index{TBD_put@{TBD\_\-put}!TBD.h@{TBD.h}} \subsubsection[TBD\_\-put]{\setlength{\rightskip}{0pt plus 5cm}void TBD\_\-put (void $\ast$$\ast$ {\em tbd}, int {\em index}, void $\ast$ {\em value})}} \label{TBD_8h_a5} Puts the data value into the task specific data area at the specified index. \begin{Desc} \item[Parameters:] \begin{description} \item[{\em tbd}]The table location, from a call to {\em TBD\_\-locate\/} () \item[{\em index}]The index of the target data word \item[{\em value}]The value to put into the target data word\end{description} \end{Desc} Puts (writes) {\em value\/} into the task specific data area at the specified {\em index\/}. The implementation of this function is very efficient of the VXWORKS platform, requiring approximately 3 instructions. It is highly recommended that the inline form of this function be used.