OpenCL_helpers/documentation/tools_linker-english.tex

\subsection{Linking}

\index{OpenCL linker}%
\index{oclh_lr@\texttt{oclh\_lr}}%
Isolated linking is performed by \verb|oclh_lr|.

\subsubsection{Synopsis}

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

\subsubsection{Description}

When \verb|oclh_lr| is called, OpenCL objects are linked from files
\verbIU{infile}\verb|...| for all GPGPU devices available on the system. It
should be understood that only objects compiled for one GPGPU architecture can
be linked, and GPGPU architectures can differ even from one vendor's devices. An
attempt to link object compiled for an architecture different from the device
architecture will result in error \verb|-42|
OpenCL API:\\*
\centerline{\Verb|oclerr: clCreateProgramWithBinary returned error -42 - CL\_INVALID\_BINARY|}\\*
According to mentioned above, it is recommended to run the linker for only one device or device model using option
\verb|--dev-idxs=|\verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| or
\verb|--dev-name=|\verbIU{mask}. If the
\verb|--dev-idxs=|\verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| option was
specified, then linking would be performed only for the GPGPU devices with
the \verbIU{\#}\Verb|,|\verbIU{\#}\Verb|,...| indices (for details, see
s.\ref{subsubsec:lr_args}). If the \verb|--dev-name=|\verbIU{mask} was
specified, then linking would be performed only for the GPGPU devices whose
model matches the \verbIU{mask} (for details, see s.\ref{subsubsec:lr_args}).

During the execution of the \verb|oclh_lr| tool, a detailed diagnostic log is
being maintained in the \verb|oclh_lr.log| file, where excessive information is
stored on all available GPGPU devices, used platforms, and contexts created for
linking. The log file format is described~in~s.\ref{subsec:logformat}.

The linking log is maintained in log files
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|-link.log|.

The result of the linker's work is an executable binary object or a shared
binary object (library) saved in the
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clexe| or
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clso| file,
respectively. 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 linker 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_lr.log|.

The main log file name \verb|oclh_lr.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 linking results are defined in
macrodefinitions\\*
\indent\indent\verb|#define _GHM_LOG_PATH                 "."|\\*
\indent\indent\verb|#define _GHM_OCLH_LINKER_LOG_FILENAME "oclh_lr.log"|

\subsubsection{Arguments}
\label{subsubsec:lr_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 linking 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 linking 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
linker 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 linker'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 linker
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|.clexe| or
\verbIU{outfile}\verb|-|\verbI{GPGPU\_device\_model}\verb|.clso| file name,
which contains the binary object generated as the result of linking. 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 linking~--~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 linking 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|LINKER_OPTIONS|\\* linker arguments. In unchanged form
and with the preservation of the sequence passed to the linker of the vendor.
The linker arguments themselves are described in the OpenCL specifications, in
addition, the vendor's linker 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 OpenCL compiled objects. The file name
cannot begin with a~<<\verb|-|>>~character.\par}