OpenCL_helpers/documentation/tools_compiler-english.tex

\subsection{Compilation}

\index{OpenCL compiler}%
\index{oclh_cr@\texttt{oclh\_cr}}%
Isolated compilation is performed by \verb|oclh_cr|.

\subsubsection{Synopsis}

\begin{CodeParWithCC}{\\\{\}}
oclh_cr [--dev-idxs=\underline{\smash{\textit{#}}},\underline{\smash{\textit{#}}},... | --dev-name=\underline{\smash{\textit{mask}}}]
        [--verbatim-output-name] [-o \underline{\smash{\textit{outfile}}}]
        [COMPILER_OPTIONS] \underline{\smash{\textit{infile}}}...
\end{CodeParWithCC}

\subsubsection{Description}

When \verb|oclh_сr| is called, source code is compiled from files
\verbIU{infile}\verb|...| for all GPGPU devices available on the system. If the
\verb|--dev-idxs=|\verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| option was
specified, then compilation would be performed only for the GPGPU devices with
the \verbIU{\#}\Verb|,|\verbIU{\#}\Verb|,...| indices (for details, see
s.\ref{subsubsec:cr_args}). If the \verb|--dev-name=|\verbIU{mask} was
specified, then compilation would be performed only for the GPGPU devices whose
model matches the \verbIU{mask} (for details, see s.\ref{subsubsec:cr_args}).

During the execution of the \verb|oclh_сr| tool, a detailed diagnostic log is
being maintained in the \verb|oclh_cr.log| file, where excessive information is
stored on all available GPGPU devices, used platforms, and contexts created for
compilation. In fact, you can run \verb|oclh_сr| with any input file, even with
itself as \verb|./oclh_сr oclh_сr|. The input file, of course, will not be
compiled into an OpenCL object, but the \verb|oclh_сr.log| log file will contain
complete information on GPGPU devices found in the system. The log file format
is human-readable, adapted to search for substrings using the \verb|grep|
command and analogues. The log file format is
described~in~s.\ref{subsec:logformat}.

Considering that compilation may be performed for several devices of different
vendors, the program compilation log is maintained in different log files
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|-trans.log|.

The result of the compiler's work is an unlinked binary object saved in the
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clo| file. If
the option \verb|--verbatim-output-name| was specified, then the result would be
saved in the \verbIU{outfile} file. Sometimes a situation arises when the
vendor's OpenCL library generates several binary objects as a result, in which
case all binary objects will be saved, but the postfix \verb|.|\verbI{N} will be
added to the file names, where \verbI{N} is a decimal number denoting the
sequence number (starting from zero) of the binary object generated by the
compiler of the vendor of the GPGPU device.

If the option \verb|-o| is not specified, then the \verbIU{outfile} in the file
name will be replaced by a substring of the form \verb|program_0x|\verbI{HHHH}.
In case if the GPGPU device model is not identified by the OpenCL means, then
the \verbI{GPGPU\_device\_model} will be replaced by a substring of the form
\verb|dev_0x|\verbI{HHHH}. In the replacements mentioned above, \verbI{HHHH} is
hexadecimal representation of the last two bytes of the program and the GPGPU
device addresses, respectively. Given that addresses of the program and GPGPU
device are unique for one application run, it is highly likely that the
combination of the name of the instance and the last two bytes of its address is
also unique, so can be used as a substring to search related entries in the main
log file \verb|oclh_сr.log|.

The main log file name \verb|oclh_сr.log| and the file saving path can be
changed when building the OpenCL\_helpers library in the header file\\*
\indent\indent\verb|src/inc/oclh_settings.h|\\*
That name and the path to save logs and compilation results are defined in
macrodefinitions\\*
\indent\indent\verb|#define _GHM_LOG_PATH                   "."|\\*
\indent\indent\verb|#define _GHM_OCLH_COMPILER_LOG_FILENAME "oclh_cr.log"|

The compiler always receives the \verb|-D_OCLH_OCL_COMPILER_| argument. It is
hardcoded in the library code and introduced for ability to use header files
both in programs for GPGPU programs and CPU without changing them. For details,
see s.\ref{subsec:sharedheaders}.

\subsubsection{Arguments}
\label{subsubsec:cr_args}

{\NmCnvDescript\verb|--dev-idxs=|\verbIU{\#}\Verb|,|\verbIU{\#}\verb|,...|\\*
the \verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| numbers specified without spaces
separated by commas after the \verb|--dev-idxs=| option are sequence numbers
(indices) of GPGPU devices in the system for which the compilation will be
performed. Indices start with zero. You can find out the indice of a specific
device from the log file, in the first section of which in the device
description the first line has the form\par
{\hspace{2\leftskip}\verbI{YYYY}\verb|-|\verbI{MM}\verb|-|\verbI{DD}%
\verb| |\verbI{hh}\verb|:|\verbI{mm}\verb|:|\verbI{ss}%
\verb| ws_0x|\verbI{HHHH}\verb| dev_0x|\verbI{HHHH}%
\verb+ | Device index: +\verbI{N}}\par
\noindent where \verbI{N} is the indice of this device.\par}
{\NmCnvDescript\verb|--dev-name=|\verbIU{mask}\\* the \verbIU{mask} string
specified after the \verb|--dev-name=| option is a wildcard that defines which
device models present in the system the compilation will be performed for.
Wildcard characters are:\par
\hspace{2\leftskip}\verb|?| -- matches any single character;\par
\hspace{2\leftskip}\verb|*| -- matches any number of any characters including
none.\par
\noindent In the absence of wildcard characters the \verbIU{mask} is considered
to be the exact name of the device model. You can find out the model of a
specific device from the log file, in the first section of which in the device
description there is the line of the form\par
{\hspace{2\leftskip}\verbI{YYYY}\verb|-|\verbI{MM}\verb|-|\verbI{DD}%
\verb| |\verbI{hh}\verb|:|\verbI{mm}\verb|:|\verbI{ss}%
\verb| ws_0x|\verbI{HHHH}\verb| dev_0x|\verbI{HHHH}%
\verb+ | Device name: +\verbI{model}}\par
\noindent where \verbI{model} is the string that is checked for matching with
the \verbIU{mask}.\par}
{\NmCnvDescript\verb|--verbatim-output-name|\\* the given option instructs the
compiler not to add the GPGPU device model and an extension to the output file
name, but to use it exactly as described. But, if the result of the compiler's
work was more than one binary object, then the \verb|.|\verbI{N} postfix would
be added to the file name, where \verbI{N} is decimal number denoting the
sequence number (starting from zero) of the binary object formed by the compiler
of the GPGPU device vendor.\par}
{\NmCnvDescript\verb|-o |\verbIU{outfile}\\* the \verbIU{outfile} string is the
name of the output file. If the \verb|--verbatim-output-name| option was not
specified, then the \verbIU{outfile} string would be used as the prefix of the
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clo| file name, which
contains the binary object generated as the result of compilation. If the
\verb|--verbatim-output-name| option was specified, then the \verbIU{outfile}
string would be used <<as is>>, unless several binary objects was generated as
result of compilation~--~in this case, all binary objects would be saved with
the \verbIU{outfile}\verb|.|\verbI{N} file names, where \verbI{N} is the
sequence number of the binary object starting from zero. Additionally, the
\verbIU{outfile} string is used as the prefix in the name of the compilation log
file.\par
\begin{ImpNote}
Space characters at the beginning and the end of the \verbIU{outfile} string are
deleted. Space characters inside of the \verbIU{outfile} string are replaced
with underscores.
\end{ImpNote}
}
{\NmCnvDescript\verb|COMPILER_OPTIONS|\\* compiler arguments. In unchanged form
and with the preservation of the sequence passed to the compiler of the vendor.
The compiler arguments themselves are described in the OpenCL specifications, in
addition, the vendor's compiler can support additional arguments not fixed in
the OpenCL specifications.\par}
{\NmCnvDescript\verbIU{infile}\verb|...|\\* the list separated by spaces with
the names of the files containing the source code of the OpenCL C or OpenCL C++
program. The file name cannot begin with a~<<\verb|-|>>~character.\par}