From 2fcef143524d83dff7d0e0cf7b96eb3a309385d2 Mon Sep 17 00:00:00 2001 From: eschnett Date: Wed, 9 May 2012 13:11:46 +0000 Subject: Add thorn documentation git-svn-id: http://svn.cactuscode.org/projects/ExternalLibraries/OpenCL/trunk@10 4054007a-4839-4648-a056-eb81e030d849 --- doc/documentation.tex | 86 ++++++++++++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 31 deletions(-) (limited to 'doc') diff --git a/doc/documentation.tex b/doc/documentation.tex index 0aa74f1..660cbc7 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -87,7 +87,7 @@ % 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{July 11 2011} +\date{May 9 2012} \maketitle @@ -99,39 +99,63 @@ % 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} -% The following sections are suggestive only. -% Remove them or add your own. - -\section{Introduction} - -\section{Physical System} - -\section{Numerical Implementation} - -\section{Using This Thorn} - -\subsection{Obtaining This Thorn} - -\subsection{Basic Usage} - -\subsection{Special Behaviour} - -\subsection{Interaction With Other Thorns} - -\subsection{Examples} - -\subsection{Support and Feedback} - -\section{History} - -\subsection{Thorn Source Code} - -\subsection{Thorn Documentation} +\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.) -\subsection{Acknowledgements} \begin{thebibliography}{9} -- cgit v1.2.3