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

SCM Repository

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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2728 - (download) (as text) (annotate)
Thu Sep 25 13:13:02 2014 UTC (6 years, 7 months ago) by jhr
File size: 5781 byte(s)
  added some discussion of how libraries are initialized
%!TEX root = report.tex
%

\chapter{Interfacing to a Diderot program}

The Diderot compiler has two modes of operation.
By default, it produces an object file that can be linked into a user's program, but one can
also use the ``\texttt{--exec}'' command-line option to generate a standalone executable.
In this chapter, we describe the interface to a Diderot program in both of these modes.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The Library API}

\subsection{Namespace prefix}
To allow multiple Diderot programs to be embedded in a single application, the Diderot compiler
prefixes external symbols with a ``namespace'' tag.
The default value of this tag is \texttt{Diderot} but this value can be specified using
the \texttt{--namespace} command-line option.
In this chapter, we use \texttt{\textit{NS}} to represent the specified namespace.

\subsection{Preprocessor definitions}
The generated header file will include definitions for three C preprocessor symbols, which
encode information about the target that was specified on the command line.
The following table describes which symbols are defined based on the command-line options:
\begin{center}
  \begin{tabular}{|l|c|c|}
    \hline
    Floating-point precision & \textit{default} & \texttt{DIDEROT\char`\_FLOAT\char`\_PRECISION} \\
      & \texttt{--double} & \texttt{DIDEROT\char`\_DOUBLE\char`\_PRECISION} \\\hline
    Integer precision & \textit{default} & \texttt{DIDEROT\char`\_LONGINT} \\
      & \texttt{--longint} & \texttt{DIDEROT\char`\_LONGINT} \\\hline
    Target & \texttt{--target=c} (\textit{default}) & \texttt{DIDEROT\char`\_TARGET\char`\_C} \\
           & \texttt{--target=pthread} & \texttt{DIDEROT\char`\_TARGET\char`\_PARALLEL} \\
           & \texttt{--target=cl} & \texttt{DIDEROT\char`\_TARGET\char`\_CL} \\
           & \texttt{--target=cuda} & \texttt{DIDEROT\char`\_TARGET\char`\_CUDA} \\\hline
  \end{tabular}%
\end{center}%
\NOTE{should we use the namespace qualifier for these symbols?}

\subsection{Generated header file}
In normal operation, the Diderot compiler generates a binary object file and an associated
header file that defines the public interface to the Diderot program.
The interface includes the following parts:
\begin{itemize}
  \item
    types and functions for initializing the runtime system.
  \item
    functions for handling Diderot input variables
  \item
    functions to initialize and run the Diderot computation
  \item
    functions to retrieve the results of the computation
  \item
    functions to shutdown and deallocation the runtime system structures.
\end{itemize}%

\subsection{Initialization}
Initialization of a Diderot program involves several steps.
First, one must create a world object using the \texttt{New} function:\footnote{
  In this example, we are assuming that the option \texttt{--namespace=NS} option
  was specified on the \texttt{diderotc} command line.
}
\begin{quote}
\begin{lstlisting}[language=C]
NS_World_t *wrld = NS_New ();
if (wrld == 0) { /* error */ }
\end{lstlisting}%
\end{quote}%

Once the world has been created, we can set generic runtime properties, such
as verbosity.
For parallel and GPU targets, we can query the available hardware resources and
specify the desired runtime properties.
\begin{quote}
\begin{lstlisting}[language=C]
NS_SetVerbose (wrld, true);
#ifdef DIDEROT_TARGET_PARALLEL
  NS_SetNumWorkers(wrld, 0); /* use all available processors */
#endif
\end{lstlisting}%
\end{quote}%

The next step in intialization is to allocate the computational resources
needed to support the program's execution, which is done using the \texttt{Init}
function.
\begin{quote}
\begin{lstlisting}[language=C]
if (NS_Init (wrld)) { /* error */ }
\end{lstlisting}%
\end{quote}%

Once the world is initialized, we can then set program inputs using the
generated functions.

The final step of initialization is to create the initial grid or collection
of strands.
\begin{quote}
\begin{lstlisting}[language=C]
if (NS_Initially (wrld)) { /* error */ }
\end{lstlisting}%
\end{quote}%
This function call initializes the Diderot globals and allocates the initial strands.

% structure of header file
% world creation
% initializing inputs; descriptions; defaults
% initializing globals
% running the program
% getting outputs
% shutdown

\subsection{Types}
\begin{center}
  \begin{tabular}{|c|c|p{2.5in}|}
    \hline
    \textbf{Diderot type} & \textbf{C type} & \multicolumn{1}{c|}{\textbf{Notes}} \\\hline
    \kw{bool} & \texttt{bool} & \textit{from} \texttt{<stdbool.h>} \\\hline
    \kw{int} & \texttt{int32\char`\_t} \textit{or} \texttt{int64\char`\_t}
      & \textit{type is controlled by command-line flag} \\\hline
    \kw{string} & \texttt{char *} & \\\hline
    \kw{real} & \texttt{float} \textit{or} \texttt{double}
      & \textit{type is controlled by command-line flag} \\\hline
    \kw{image(}$d$\kw{)[}$\sigma$\kw{]} & \texttt{Nrrd *}
      & \textit{see \secref{sec:nrrd-files} for details} \\\hline
    \kw{tensor[}$\sigma$\kw{]}
      & \texttt{float[}$n$\texttt{]} \textit{or} \texttt{double[}$n$\texttt{]} & 
        \textit{where $n = \Pi \sigma$} \\
    \hline
  \end{tabular}%
\end{center}%

%A tensor type \kw{tensor[}$d_1,d_2,\ldots,d_k$\kw{]} will be represented by a flat array
%of $n$ floating point values, where $n = d_1 \times d_2 \times \cdots \times d_k$.

\subsection{Target-specific functions}
% parallel target: {Get,Set}NumWorkers

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Standalone executables}

% inputs map to command-line options
% outputs map to nrrd files

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Nrrd files}
\label{sec:nrrd-files}

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