\chapter{Memory Management}\label{chap:memmanage}

This chapter specifices the memory management functionality in targetDP.

\newpage
\section{targetMalloc}

\subsection{Description}

The \verb+targetMalloc+ function allocates memory on the target.

\subsection{Syntax}
\begin{verbatim}
void targetMalloc(void** targetPtr, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetptr+: A pointer to the allocated memory.
\item \verb+n+: The number of bytes to be allocated.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalelaunch:targetMalloc} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.
\subsection{Implementation}
\subsubsection{C}
\verb+malloc+
\subsubsection{CUDA}
\verb+cudaMalloc+

\newpage
\section{targetCalloc}

\subsection{Description}

The \verb+targetCalloc+ function allocates, and initialises to zero, memory on the target.

\subsection{Syntax}
\begin{verbatim}
void targetCalloc(void** targetPtr, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetptr+: A pointer to the allocated memory.
\item \verb+n+: The number of bytes to be allocated.
\end{itemize}


\subsection{Example}
Analogous to Line \ref{example:scalelaunch:targetMalloc} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+calloc+
\subsubsection{CUDA}
\verb+cudaMalloc+ followed by \verb+cudaMemset+

\newpage

\section{targetMallocUnified}

\subsection{Description}

The \verb+targetMallocUnified+ function allocates unified memory that can be accessed on the host or the target. This should be used with caution since it may result in poor performance relative to use of \verb+targetMalloc+.


\subsection{Syntax}
\begin{verbatim}
void targetMallocUnified(void** targetPtr, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetptr+: A pointer to the allocated memory.
\item \verb+n+: The number of bytes to be allocated.
\end{itemize}


\subsection{Example}
Analogous to Line \ref{example:scalelaunch:targetMalloc} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.
\subsection{Implementation}
\subsubsection{C}
\verb+malloc+
\subsubsection{CUDA}
\verb+cudaMallocManaged+

\newpage
\section{targetCallocUnified}

\subsection{Description}


The \verb+targetCallocUnified+ function allocates, and initialises to zero, unified memory that can be accessed on the host or the target. This should be used with caution since it may result in poor performance relative to use of \verb+targetCalloc+.

\subsection{Syntax}
\begin{verbatim}
void targetCallocUnified(void** targetPtr, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetptr+: A pointer to the allocated memory.
\item \verb+n+: The number of bytes to be allocated.
\end{itemize}


\subsection{Example}
Analogous to Line \ref{example:scalelaunch:targetMalloc} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+calloc+
\subsubsection{CUDA}
\verb+cudaMallocManaged+ followed by \verb+cudaMemset+


\newpage
\section{targetFree}

\subsection{Description}

The \verb+targetFree+ function deallocates memory on the target.

\subsection{Syntax}
\begin{verbatim}
void targetFree(void* targetPtr);
\end{verbatim}

\begin{itemize}
\item \verb+targetPtr+: A pointer to the memory to be freed.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalelaunch:targetFree} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+free+
\subsubsection{CUDA}
\verb+cudaFree+

\newpage
\section{copyToTarget}

\subsection{Description}

The \verb+copyToTarget+ function copies data from the host to the target.

\subsection{Syntax}
\begin{verbatim}
void copyToTarget(void* targetData, const void* data, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetData+: A pointer to the destination array on the target.
\item \verb+data+: A pointer to the source array on the host.
\item \verb+n+: The number of bytes to be copied.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalelaunch:copyToTarget} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+memcpy+
\subsubsection{CUDA}
\verb+cudaMemcpy+

\newpage
\section{copyFromTarget}

\subsection{Description}

The \verb+copyFromTarget+ function copies data from the target to the host.

\subsection{Syntax}
\begin{verbatim}
void copyFromTarget(void* data, const void* targetData, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+data+: A pointer to the destination array on the host.
\item \verb+targetData+: A pointer to the source array on the target.
\item \verb+n+: The number of bytes to be copied.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalelaunch:copyFromTarget} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+memcpy+
\subsubsection{CUDA}
\verb+cudaMemcpy+



\newpage
\section{copyDeepDoubleArrayToTarget}

\subsection{Description}

The \verb+copyDeepDoubleArrayToTarget+ function copies an array of double precision values from the host to the target, where the array is contained within another object.

\subsection{Syntax}
\begin{verbatim}
void copyDeepDoubleArrayToTarget(void* targetObjectAddress,
    void* hostObjectAddress,void* hostComponentAddress,size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetObjectAddress+: A pointer to the target copy of the object that contains the data array.
\item \verb+hostObjectAddress+: A pointer to the host copy of the object that contains the data array.
\item \verb+hostComponentAddress+: A pointer to the host copy of the start of the array contained within the object.
\item \verb+n+: The number of elements to be copied.
\end{itemize}

\subsection{Implementation}
\subsubsection{C}
Pointer arithmetic to determine memory locations, followed by \verb+memcpy+
\subsubsection{CUDA}
Pointer arithmetic to determine memory locations, followed by \verb+cudaMemcpy+

\newpage
\section{copyDeepDoubleArrayFromTarget}

\subsection{Description}

The \verb+copyDeepDoubleArrayTFromTarget+ function copies an array of double precision values from the target to the host, where the array is contained within another object.

\subsection{Syntax}
\begin{verbatim}
void copyDeepDoubleArrayFromTarget(void* hostObjectAddress,
   void* targetObjectAddress,void* hostComponentAddress,size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+hostObjectAddress+: A pointer to the host copy of the object that contains the data array.
\item \verb+targetObjectAddress+: A pointer to the target copy of the object that contains the data array.
\item \verb+hostComponentAddress+: A pointer to the host copy of the start of the array contained within the object.
\item \verb+n+: The number of elements to be copied.
\end{itemize}

\subsection{Implementation}
\subsubsection{C}
Pointer arithmetic to determine memory locations, followed by \verb+memcpy+
\subsubsection{CUDA}
Pointer arithmetic to determine memory locations, followed by \verb+cudaMemcpy+


\newpage
\section{targetZero}

\subsection{Description}

The \verb+targetZero+ function sets a (double precision) array on the target to zero.

\subsection{Syntax}
\begin{verbatim}
void targetZero(double* targetData, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetData+: A pointer to the array on the target.
\item \verb+n+: The number of elements in the array.
\end{itemize}

\subsection{Implementation}
\subsubsection{C}
A loop to zero each element.
\subsubsection{CUDA}
A kernel to zero each element.


\newpage
\section{targetSetConstant}

\subsection{Description}

The \verb+targetSetConstant+ function sets each element of a (double precision) array on the target to the specified constant value.

\subsection{Syntax}
\begin{verbatim}
void targetSetConstant(double* targetData, double value, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetData+: A pointer to the array on the target.
\item \verb+value+: The value.
\item \verb+n+: The number of elements in the array.
\end{itemize}

\subsection{Implementation}
\subsubsection{C}
A loop to set each element.
\subsubsection{CUDA}
A kernel to set each element.

\newpage
\section{targetConst}
\subsection{Description}

The \verb+__targetConst__+ keyword is used in a variable or array declaration
to specify that the corresponding data can be treated as constant (read-only) on the target.

\subsection{Syntax}
\begin{verbatim}
__targetConst__ type variableName
\end{verbatim}

\begin{itemize}
\item \verb+variableName+: The name of the variable or array.
\item \verb+type+: The type of variable or array.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalekernel:targetConst} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.
\subsection{Implementation}
\subsubsection{C}
Holds no value
\subsubsection{CUDA}
\verb+__constant__+

\newpage
\section{copyConstToTarget}

\subsection{Description}

The \verb+copyConstToTarget+ function copies data from the host to the target, where the data will remain constant (read-only) during the execution of functions on the target.

\subsection{Syntax}
\begin{verbatim}
void copyConstToTarget(void* targetData, const void* data, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+targetData+: A pointer to the destination array on the target. This must have been declared using the \verb+__targetConst__ + keyword.
\item \verb+data+: A pointer to the source array on the host.
\item \verb+n+: The number of bytes to be copied.
\end{itemize}


\subsection{Example}
See Line \ref{example:scalelaunch:copyConstToTarget} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.
\subsection{Implementation}
\subsubsection{C}
\verb+memcpy+
\subsubsection{CUDA}
\verb+cudaMemcpyToSymbol+

\newpage
\section{copyConstFromTarget}

\subsection{Description}

The \verb+copyConstFromTarget+ function copies data from a constant data location on the target to the host.

\subsection{Syntax}
\begin{verbatim}
void copyConstToTarget(void* targetData, const void* data, size_t n);
\end{verbatim}

\begin{itemize}
\item \verb+data+: A pointer to the destination array on the host.
\item \verb+targetData+: A pointer to the source array on the target. This must have been declared using the \verb+__targetConst__ + keyword.
\item \verb+n+: The number of bytes to be copied.
\end{itemize}


\subsection{Example}
Analogous to Line \ref{example:scalelaunch:copyConstToTarget} in Figure \ref{fig:scalelaunch} in Section \ref{chapter:examples}.

\subsection{Implementation}
\subsubsection{C}
\verb+memcpy+
\subsubsection{CUDA}
\verb+cudaMemcpyFromSymbol+

\newpage
\section{targetConstAddress}

\subsection{Description}

The \verb+targetConstAddress+ function provides the target address for a constant object.

\subsection{Syntax}
\begin{verbatim}
void targetConstAddress(void** address, objectType object);
\end{verbatim}

\begin{itemize}
\item \verb+address+ (output): The pointer to the constant object on the target.
\item \verb+objectType+: The type of the object.
\item \verb+object+ (input): The constant object on the target. This should have been declared using the \verb+__targetConst__+ keyword.
\end{itemize}

\subsection{Implementation}
\subsubsection{C}
Explicit copying of address.
\subsubsection{CUDA}
\verb+cudaGetSymbolAddress+

\newpage
\section{targetInit3D}

\subsection{Description}

The \verb+targetInit3D+ initialises the environment required to perform any of the ``3D'' operations described in the rest of this chapter.

\subsection{Syntax}
\begin{verbatim}
void targetInit3D(size_t extent, size_t nFields);
\end{verbatim}

\begin{itemize}
\item \verb+extent+: The total extent of data parallelism (e.g. the number of lattice sites).
\item \verb+nFields+: The extent of data resident within each parallel partition (e.g. the number of fields per lattice site).
\end{itemize}


\newpage
\section{targetFinalize3D}

\subsection{Description}

The \verb+targetFinalize3D+ finalises the targetDP 3D environment.

\subsection{Syntax}
\begin{verbatim}
void targetFinalize3D();
\end{verbatim}


%% \newpage
%% \section{copyToTargetBoundary3D}

%% \subsection{Description}

%% The \verb+copyToTargetBoundary3D+ function copies the data corresponding to the boundaries of a 3D lattice from the host to the target.

%% \subsection{Syntax}
%% \begin{verbatim}
%% void copyToTargetBoundary3D(void* targetData, const void* data, 
%%               size_t extent3D[3], size_t nField, 
%%               size_t offset, size_t depth);
%% \end{verbatim}

%% \begin{itemize}
%% \item \verb+targetData+: A pointer to the destination array on the target.
%% \item \verb+data+: A pointer to the source array on the host.
%% \item \verb+extent3D+: An array of 3 integers corresponding to the 3D dimensions of the lattice.
%% \item \verb+nFields+: The number of fields per lattice site.
%% \item \verb+offset+: The number of sites from the lattice edge at which each boundary face should start.
%% \item \verb+depth+: The depth of each boundary face.
%% \end{itemize}


%% \newpage
%% \section{copyFromTargetBoundary3D}

%% \subsection{Description}

%% The \verb+copyFromTargetBoundary3D+ function copies the data corresponding to the boundaries of a 3D lattice from the target to the host.

%% \subsection{Syntax}
%% \begin{verbatim}
%% void copyFromTargetBoundary3D(void* data, const void* targetData, 
%%                  size_t extent3D[3], size_t nField, 
%%                  size_t offset, size_t depth);
%% \end{verbatim}

%% \begin{itemize}
%% \item \verb+data+: A pointer to the destination array on the host.
%% \item \verb+targetData+: A pointer to the source array on the target.
%% \item \verb+extent3D+: An array of 3 integers corresponding to the 3D dimensions of the lattice.
%% \item \verb+nFields+: The number of fields per lattice site.
%% \item \verb+offset+: The number of sites from the lattice edge at which each boundary face should start.
%% \item \verb+depth+: The depth of each boundary face.
%% \end{itemize}

\newpage
\section{copyToTargetPointerMap3D}

\subsection{Description}

The \verb+copyToTargetPointerMap3D+ function copies a subset of lattice data from the host to the target. The sites to be included are defined using an array of pointers passed as input.

\subsection{Syntax}
\begin{verbatim}
void copyToTargetPointerMap3D(void* targetData, const void* data, 
           size_t extent3D[3], size_t nField, 
           int includeNeighbours, void** pointerArray);
\end{verbatim}

\begin{itemize}
\item \verb+targetData+: A pointer to the destination array on the target.
\item \verb+data+: A pointer to the source array on the host.
\item \verb+extent3D+: An array of 3 integers corresponding to the 3D dimensions of the lattice.
\item \verb+nField+: The number of fields per lattice site.
\item \verb+includeNeighbours+: A Boolean switch to specify whether each included site should also have it's neighbours included (in the 19-point 3D stencil).
\item \verb+pointerArray+: An array of \verb+nSite+ pointers, where \verb+nSite+ is the total number of lattice sites. Each lattice site should be included unless the pointer corresponding to that site is \verb+NULL+.  
\end{itemize}

\newpage
\section{copyFromTargetPointerMap3D}

\subsection{Description}

The \verb+copyFromTargetPointerMap3D+ function copies a subset of lattice data from the target to the host. The sites to be included are defined using an array of pointers passed as input.

\subsection{Syntax}
\begin{verbatim}
void copyFromTargetPointerMap3D(void* data, const void* targetData, 
           size_t extent3D[3], size_t nField, 
           int includeNeighbours, void** pointerArray);
\end{verbatim}

\begin{itemize}
\item \verb+data+: A pointer to the destination array on the host.
\item \verb+targetData+: A pointer to the source array on the target.
\item \verb+extent3D+: An array of 3 integers corresponding to the 3D dimensions of the lattice.
\item \verb+nField+: The number of fields per lattice site.
\item \verb+includeNeighbours+: A Boolean switch to specify whether each included site should also have it's neighbours included (in the 19-point 3D stencil).
\item \verb+pointerArray+: An array of \verb+nSite+ pointers, where \verb+nSite+ is the total number of lattice sites. Each lattice site should be included unless the pointer corresponding to that site is \verb+NULL+.  
\end{itemize}


