%!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}%

% 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}