% *======================================================================*
%  Cactus Thorn template for ThornGuide documentation
%  Author: Ian Kelley
%  Date: Sun Jun 02, 2002
%  $Header$
%
%  Thorn documentation in the latex file doc/documentation.tex
%  will be included in ThornGuides built with the Cactus make system.
%  The scripts employed by the make system automatically include
%  pages about variables, parameters and scheduling parsed from the
%  relevant thorn CCL files.
%
%  This template contains guidelines which help to assure that your
%  documentation will be correctly added to ThornGuides. More
%  information is available in the Cactus UsersGuide.
%
%  Guidelines:
%   - Do not change anything before the line
%       % START CACTUS THORNGUIDE",
%     except for filling in the title, author, date, etc. fields.
%        - Each of these fields should only be on ONE line.
%        - Author names should be separated with a \\ or a comma.
%   - You can define your own macros, but they must appear after
%     the START CACTUS THORNGUIDE line, and must not redefine standard
%     latex commands.
%   - To avoid name clashes with other thorns, 'labels', 'citations',
%     'references', and 'image' names should conform to the following
%     convention:
%       ARRANGEMENT_THORN_LABEL
%     For example, an image wave.eps in the arrangement CactusWave and
%     thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps
%   - Graphics should only be included using the graphicx package.
%     More specifically, with the "\includegraphics" command.  Do
%     not specify any graphic file extensions in your .tex file. This
%     will allow us to create a PDF version of the ThornGuide
%     via pdflatex.
%   - References should be included with the latex "\bibitem" command.
%   - Use \begin{abstract}...\end{abstract} instead of \abstract{...}
%   - Do not use \appendix, instead include any appendices you need as
%     standard sections.
%   - For the benefit of our Perl scripts, and for future extensions,
%     please use simple latex.
%
% *======================================================================*
%
% Example of including a graphic image:
%    \begin{figure}[ht]
% 	\begin{center}
%    	   \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure}
% 	\end{center}
% 	\caption{Illustration of this and that}
% 	\label{MyArrangement_MyThorn_MyLabel}
%    \end{figure}
%
% Example of using a label:
%   \label{MyArrangement_MyThorn_MyLabel}
%
% Example of a citation:
%    \cite{MyArrangement_MyThorn_Author99}
%
% Example of including a reference
%   \bibitem{MyArrangement_MyThorn_Author99}
%   {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999),
%   1--16. {\tt http://www.nowhere.com/}}
%
% *======================================================================*

% If you are using CVS use this line to give version information
% $Header$

\documentclass{article}

% Use the Cactus ThornGuide style file
% (Automatically used from Cactus distribution, if you have a
%  thorn without the Cactus Flesh download this from the Cactus
%  homepage at www.cactuscode.org)
\usepackage{../../../../doc/latex/cactus}

\begin{document}

% The author of the documentation
\author{Erik Schnetter \textless eschnetter@perimeterinstitute.ca\textgreater}

% The title of the document (not necessarily the name of the Thorn)
\title{OpenCL}

% the date your document was last changed, if your document is in CVS,
% please use:
%    \date{$ $Date: 2004-01-07 14:12:39 -0600 (Wed, 07 Jan 2004) $ $}
\date{May 9 2012}

\maketitle

% Do not delete next line
% START CACTUS THORNGUIDE

% Add all definitions used in this documentation here
%   \def\mydef etc

% Add an abstract for this thorn's documentation
\begin{abstract}
  \emph{OpenCL} is a programming standard for heterogeneous systems,
  i.e.\ for programming CPUs, GPUs, and other types of accelerators.
  OpenCL is implemented as a library, and OpenCL codes are compiled at
  run time by passing OpenCL routines, as strings, to the OpenCL
  library. This is different e.g.\ from \texttt{CUDA}, which is
  implemented as a language such as C or C++.
  
  This thorn \texttt{OpenCL} provides the configuration bits that
  ensure that Cactus applications can use OpenCL libraries.
\end{abstract}

\section{OpenCL Programming}

OpenCL is very similar to C\@. However, it differs from C in several
key aspects:
\begin{itemize}
\item much smaller run-time library, consisting mostly of mathematical
  functions (such as sqrt) and printf;
\item built-in support for fine-grained and coarse-grainded
  multi-threading;
\item built-in support for vectorisation.
\end{itemize}
Given this, it is not possible to write a whole application in
OpenCL\@. Instead, only the expensive parts (so-called \emph{compute
  kernels}) are written in OpenCL, and are launched e.g.\ from C or
C++.

In addition, the hardware architecture of GPUs and other accelerators
differs from CPUs in one key aspect:
\begin{itemize}
\item memory is separate from the host (regular CPU) memory.
\end{itemize}
That means that one has to explicitly copy data between the host
memory and the device memory before and/or after calling compute
kernels.

\section{OpenCL Programming in Cactus}

Cactus supports OpenCL programming at several levels. At the lowest
level, one can use this thorn \texttt{OpenCL} directly. While this
works fine, it is somewhat tedious because one has to write a certain
amount of boilerplate code to detect and initialise the device, to
copy data between host and device, and to build and run compute
kernels.

Since OpenCL is implemented as a library, the flesh knows only little
about OpenCL\@. For example, there are no configuration options to
spedify an OpenCL compiler, since code is compiled at run time via a
library call to which the source code is passed as string. There is,
however, one way in which the flesh supports OpenCL: Files with a
\texttt{.cl} suffix are converted into a string and placed into the
executable. These strings have the type \texttt{char~const~*} in C,
and can be accessed at run time under a (globally visible) name
\texttt{OpenCL\_source\_THORN\_FILE}, where \texttt{THORN} and
\texttt{FILE} and are the thorn name and file name, respectively.
(This is also explained in the users' guide.)



\begin{thebibliography}{9}

\end{thebibliography}

% Do not delete next line
% END CACTUS THORNGUIDE

\end{document}