Home My Page Projects Code Snippets Project Openings diderot

# SCM Repository

[diderot] Annotation of /branches/vis12-cl/doc/report/api.tex
 [diderot] / branches / vis12-cl / doc / report / api.tex

# Annotation of /branches/vis12-cl/doc/report/api.tex

 1 : jhr 1804 %!TEX root = report.tex 2 : % 3 : 4 : \chapter{Interfacing to a Diderot program} 5 : 6 : The Diderot compiler has two modes of operation. 7 : By default, it produces an object file that can be linked into a user's program, but one can 8 : also use the \texttt{--exec}'' command-line option to generate a standalone executable. 9 : In this chapter, we describe the interface to a Diderot program in both of these modes. 10 : 11 : jhr 1821 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 12 : jhr 1804 \section{The Library API} 13 : 14 : jhr 1821 \subsection{Namespace prefix} 15 : To allow multiple Diderot programs to be embedded in a single application, the Diderot compiler 16 : prefixes external symbols with a namespace'' tag. 17 : The default value of this tag is \texttt{Diderot} but this value can be specified using 18 : the \texttt{--namespace} command-line option. 19 : In this chapter, we use \texttt{\textit{NS}} to represent the specified namespace. 20 : 21 : \subsection{Preprocessor definitions} 22 : The generated header file will include definitions for three C preprocessor symbols, which 23 : encode information about the target that was specified on the command line. 24 : The following table describes which symbols are defined based on the command-line options: 25 : \begin{center} 26 : \begin{tabular}{|l|c|c|} 27 : \hline 28 : Floating-point precision & \textit{default} & \texttt{DIDEROT\char\_FLOAT\char\_PRECISION} \\ 29 : & \texttt{--double} & \texttt{DIDEROT\char\_DOUBLE\char\_PRECISION} \\\hline 30 : Integer precision & \textit{default} & \texttt{DIDEROT\char\_LONGINT} \\ 31 : & \texttt{--longint} & \texttt{DIDEROT\char\_LONGINT} \\\hline 32 : Target & \texttt{--target=c} (\textit{default}) & \texttt{DIDEROT\char\_TARGET\char\_C} \\ 33 : & \texttt{--target=pthread} & \texttt{DIDEROT\char\_TARGET\char\_PARALLEL} \\ 34 : & \texttt{--target=cl} & \texttt{DIDEROT\char\_TARGET\char\_CL} \\ 35 : & \texttt{--target=cuda} & \texttt{DIDEROT\char\_TARGET\char\_CUDA} \\\hline 36 : \end{tabular}% 37 : \end{center}% 38 : \NOTE{should we use the namespace qualifier for these symbols?} 39 : 40 : jhr 1846 \subsection{Generated header file} 41 : In normal operation, the Diderot compiler generates a binary object file and an associated 42 : header file that defines the public interface to the Diderot program. 43 : The interface includes the following parts: 44 : \begin{itemize} 45 : \item 46 : types and functions for initializing the runtime system. 47 : \item 48 : functions for handling Diderot input variables 49 : \item 50 : functions to initialize and run the Diderot computation 51 : \item 52 : functions to retrieve the results of the computation 53 : \item 54 : functions to shutdown and deallocation the runtime system structures. 55 : \end{itemize}% 56 : 57 : jhr 2728 \subsection{Initialization} 58 : Initialization of a Diderot program involves several steps. 59 : First, one must create a world object using the \texttt{New} function:\footnote{ 60 : In this example, we are assuming that the option \texttt{--namespace=NS} option 61 : was specified on the \texttt{diderotc} command line. 62 : } 63 : \begin{quote} 64 : \begin{lstlisting}[language=C] 65 : NS_World_t *wrld = NS_New (); 66 : if (wrld == 0) { /* error */ } 67 : \end{lstlisting}% 68 : \end{quote}% 69 : 70 : Once the world has been created, we can set generic runtime properties, such 71 : as verbosity. 72 : For parallel and GPU targets, we can query the available hardware resources and 73 : specify the desired runtime properties. 74 : \begin{quote} 75 : \begin{lstlisting}[language=C] 76 : NS_SetVerbose (wrld, true); 77 : #ifdef DIDEROT_TARGET_PARALLEL 78 : NS_SetNumWorkers(wrld, 0); /* use all available processors */ 79 : #endif 80 : \end{lstlisting}% 81 : \end{quote}% 82 : 83 : jhr 3226 The next step in initialization is to allocate the computational resources 84 : jhr 2728 needed to support the program's execution, which is done using the \texttt{Init} 85 : function. 86 : \begin{quote} 87 : \begin{lstlisting}[language=C] 88 : if (NS_Init (wrld)) { /* error */ } 89 : \end{lstlisting}% 90 : \end{quote}% 91 : Once the world is initialized, we can then set program inputs using the 92 : jhr 3226 generated functions as described in \secref{sec:communication}. 93 : jhr 2728 94 : The final step of initialization is to create the initial grid or collection 95 : of strands. 96 : \begin{quote} 97 : \begin{lstlisting}[language=C] 98 : if (NS_Initially (wrld)) { /* error */ } 99 : \end{lstlisting}% 100 : \end{quote}% 101 : This function call initializes the Diderot globals and allocates the initial strands. 102 : 103 : jhr 1804 % structure of header file 104 : % world creation 105 : % initializing inputs; descriptions; defaults 106 : % initializing globals 107 : % running the program 108 : % getting outputs 109 : % shutdown 110 : 111 : jhr 3226 \subsection{Running the program} 112 : After initialization, the program can be run using the \texttt{Run} function. 113 : \begin{quote} 114 : \begin{lstlisting}[language=C] 115 : uint32_t nSteps = NS_Run (wrld, 0); 116 : \end{lstlisting}% 117 : \end{quote}% 118 : The second argument to this function is a limit on the number of steps to execute the 119 : Diderot program; specifying \texttt{0} means no limit (\ie{}, run the program to completion). 120 : Using the step mechanism plus snapshots of the Diderot state, one can animate the progress of 121 : the program. 122 : 123 : \subsection{Communicating with the Diderot program} 124 : \label{sec:communication} 125 : 126 : jhr 1846 \begin{center} 127 : \begin{tabular}{|c|c|p{2.5in}|} 128 : \hline 129 : \textbf{Diderot type} & \textbf{C type} & \multicolumn{1}{c|}{\textbf{Notes}} \\\hline 130 : \kw{bool} & \texttt{bool} & \textit{from} \texttt{} \\\hline 131 : \kw{int} & \texttt{int32\char\_t} \textit{or} \texttt{int64\char\_t} 132 : & \textit{type is controlled by command-line flag} \\\hline 133 : \kw{string} & \texttt{char *} & \\\hline 134 : \kw{real} & \texttt{float} \textit{or} \texttt{double} 135 : & \textit{type is controlled by command-line flag} \\\hline 136 : \kw{image(}$d$\kw{)[}$\sigma$\kw{]} & \texttt{Nrrd *} 137 : & \textit{see \secref{sec:nrrd-files} for details} \\\hline 138 : \kw{tensor[}$\sigma$\kw{]} 139 : & \texttt{float[}$n$\texttt{]} \textit{or} \texttt{double[}$n$\texttt{]} & 140 : \textit{where $n = \Pi \sigma$} \\ 141 : \hline 142 : \end{tabular}% 143 : \end{center}% 144 : jhr 1821 145 : jhr 1846 %A tensor type \kw{tensor[}$d_1,d_2,\ldots,d_k$\kw{]} will be represented by a flat array 146 : %of $n$ floating point values, where $n = d_1 \times d_2 \times \cdots \times d_k$. 147 : jhr 1821 148 : jhr 1846 \subsection{Target-specific functions} 149 : % parallel target: {Get,Set}NumWorkers 150 : 151 : jhr 1821 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 152 : jhr 1804 \section{Standalone executables} 153 : 154 : % inputs map to command-line options 155 : % outputs map to nrrd files 156 : jhr 1846 157 : %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 158 : \section{Nrrd files} 159 : \label{sec:nrrd-files}