Home My Page Projects Code Snippets Project Openings diderot
Summary Activity Tracker Tasks SCM

SCM Repository

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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3226 - (view) (download) (as text)

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{<stdbool.h>} \\\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}

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0