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

SCM Repository

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

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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1846 - (download) (as text) (annotate)
Mon Apr 16 13:55:40 2012 UTC (10 years, 2 months ago) by jhr
File size: 4252 byte(s)
  Working on documentation
%!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:
    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
\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:
    types and functions for initializing the runtime system.
    functions for handling Diderot input variables
    functions to initialize and run the Diderot computation
    functions to retrieve the results of the computation
    functions to shutdown and deallocation the runtime system structures.

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

    \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
      & \texttt{float[}$n$\texttt{]} \textit{or} \texttt{double[}$n$\texttt{]} & 
        \textit{where $n = \Pi \sigma$} \\

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

ViewVC Help
Powered by ViewVC 1.0.0