OpenCL_helpers/documentation/tools_builder-russian.tex

\subsection{Полный цикл сборки}

\index{OpenCL сборщик}%
\index{oclh_br@\texttt{oclh\_br}}%
Полный цикл сборки осуществляется утилитой \verb|oclh_br|.

\subsubsection{Синопсис}

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

\subsubsection{Описание}

При вызове \verb|oclh_br| осуществляется полный цикл сборки (компиляция и
компоновка) исходного кода из файлов \verbIU{infile}\verb|...| для всех
доступных в системе устройств GPGPU. Если указан ключ
\verb|--dev-idxs=|\verbIU{\#}\verb|,|\verbIU{\#}\verb|,...|, то будет
осуществлена сборка только для устройств с индексами
\verbIU{\#}\Verb|,|\verbIU{\#}\Verb|,...|
(подробнее~см.~п.\ref{subsubsec:br_args}). Если указан ключ
\verb|--dev-name=|\verbIU{mask}, то будет осуществлена сборка только для
устройств, модель которых соответствует маске \verbIU{mask}
(подробнее~см.~п.\ref{subsubsec:br_args}).

\begin{ImpNote}
На первый взгляд использование сборщика выглядит предпочтительнее раздельных
компиляции и компоновки, так как позволяет из исходных кодов получить
исполняемые файлы сразу для всех устройств OpenCL. Однако, есть нюансы, которые
связаны с тем, что работа сборщика определяется библиотекой производителя
устройства OpenCL. Так при тестировании были выявлены следующие проблемы:\par
{\NmCnvDescript\noindent(1) не все сборщики поддерживают создание библиотек,
большинство из них создают исполняемый файл, поэтому для создания именно
библиотеки надо использовать именно компоновщик с ключом \verb|-create-library|
(согласно актуальной спецификации OpenCL);\par}
{\NmCnvDescript\noindent(2) некоторые сборщики по неясной причине игнорируют
объявление функции и интерпретируют только её определение, что приводит к
необходимости в списке файлов с исходными кодами \verbIU{infile}\verb|...|
указывать файлы с определением функции строго до первого использования функции,
несмотря на декларацию функции в заголовках.\par}
\noindent Возможно есть или появятся другие подводные камни при использовании
сборщиков производителей, поэтому рекомендуется использовать раздельные
компиляцию и компоновку.
\end{ImpNote}

Во время работы \verb|oclh_br| ведётся подробный диагностический журнал в
файле \verb|oclh_br.log|, куда сохраняется избыточная информация обо
всех доступных устройствах GPGPU, используемых платформах и созданных для
сборки контекстах. Формат файла-журнала описан в п.\ref{subsec:logformat}.

Так как сборка может осуществляться для нескольких устройств разных
производителей, журнал сборки программы ведётся в отдельных файлах
\verbIU{outfile}\verb|-|\verbI{модель\_устройства\_GPGPU}\verb|-build.log|.

Результат работы сборщика --  исполняемый двоичный файл сохраняется с именем
\verbIU{outfile}\verb|-|\verbI{модель\_устройства\_GPGPU}\verb|.clexe|. Если
указан ключ \verb|--verbatim-output-name|, то результат будет сохранен в файле
\verbIU{outfile}. Иногда возникает ситуация, когда библиотека OpenCL
производителя устройства выдала в качестве результата несколько двоичных блоков,
в таком случае все двоичные блоки будут сохранены, но к именам файлов будет
добавлен постфикс \verb|.|\verbI{N}, где \verbI{N}~--~десятичное число
обозначающее порядковый номер (начиная с ноля) двоичного блока сформированного
компилятором производителя устройства GPGPU. Введение в имя файла данного числа
связано с тем, что при реализации OpenCL производители свободны в выборе формата
вывода скомпилированной программы. Так, например, реализация от Intel создаст и
выведет двоичный блок, который является ELF-файлом; а реализация OpenCL от
NVidia выведет текстовый человекочитаемый блок ptx-кода (вариация Ассемблера для
GPGPU, также называемый IR/IL~--~Intermediate Representation/Intermediate
Language). Причём иногда могут быть сформированы несколько двоичных блоков с
разным содержанием. Узнать до сохранения, что именно содержится в двоичном
блоке, средствами OpenCL не представляется возможным, поэтому двоичные блоки
просто нумеруются по \verbI{N} в порядке их хранения в памяти данной реализацией
OpenCL.

Если ключ \verb|-o| не указан, то \verbIU{outfile} в названии файла будет
заменён на подстроку вида \verb|program_0x|\verbI{HHHH}. В случае если модель
устройства GPGPU средствами OpenCL определить не удалось, тогда
\verbI{модель\_устройства\_GPGPU} будет заменена на подстроку вида
\verb|dev_0x|\verbI{HHHH}. В приведённых подстановках \verbI{HHHH} это
шестнадцатеричное представление последних двух байт адресов программы и
устройства GPGPU, соответственно. Так как для одного запуска адрес программы и
устройства GPGPU уникален, с большой вероятностью два последних байта также
уникальны, поэтому могут быть использованы как подстрока для поиска связанных
записей в файле основного журнала \verb|oclh_br.log|.

Имя файла основного журнала \verb|oclh_br.log| и пути сохранения файлов могут
быть изменены при сборке библиотеки OpenCL helpers в заголовочном файле\\*
\indent\indent\verb|src/inc/oclh_settings.h|\\*
Данное имя и пути сохранения журналов и результатов компиляции определены в
макросах\\*
\indent\indent\verb|#define _GHM_LOG_PATH                  "."|\\*
\indent\indent\verb|#define _GHM_OCLH_BUILDER_LOG_FILENAME "oclh_br.log"|

Сборщику всегда передаётся аргумент \verb|-D_OCLH_OCL_COMPILER_|. Он
прописан в коде библиотеки и введён для возможности использования заголовочных
файлов как в программах для GPGPU, так и для CPU без их изменения. Подробнее см.
п.\ref{subsec:sharedheaders}.

\subsubsection{Аргументы}
\label{subsubsec:br_args}

{\NmCnvDescript\verb|--dev-idxs=|\verbIU{\#}\Verb|,|\verbIU{\#}\verb|,...|\\*
числа \verbIU{\#}\verb|,|\verbIU{\#}\verb|,...|, указанные без пробелов через
запятую после ключа \verb|--dev-idxs=| это порядковые номера (индексы) устройств
GPGPU в системе, для которых будет осуществлена сборка. Индексы начинаются с
ноля. Узнать индекс конкретного устройства можно из файла-журнала, в начальной
секции которого в описании устройства самая первая строка имеет вид\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 где \verbI{N} -- индекс данного устройства.\par}
{\NmCnvDescript\verb|--dev-name=|\verbIU{mask}\\* строка \verbIU{mask},
указанная после ключа \verb|--dev-name=| это маска, которая указывает для каких
моделей устройств, присутствующих в системе будет осуществлена сборка.
Символами подстановки являются:\par
\hspace{2\leftskip}\verb|?| -- замещает один любой символ;\par
\hspace{2\leftskip}\verb|*| -- замещает любое количество любых символов.\par
\noindent При отсутствии символов подстановки \verbIU{mask} рассматривается как
точное наименование модели устройства. Узнать модель конкретного устройства
можно из файла-журнала, в начальной секции которого в описании устройств
присутствует строка вида\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{модель}}\par
\noindent где \verbI{модель}~--~и есть строка, которая проверяется на
соответствие маске \verbIU{mask}.\par}
{\NmCnvDescript\verb|--verbatim-output-name|\\* данный ключ предписывает
сборщику не добавлять к имени выходного файла модель устройства и расширение,
а использовать его именно так как указано. Однако, в случае если результатом
работы сборщика является не один двоичный блок, то к имени будет добавлен
постфикс \verb|.|\verbI{N}, где \verbI{N}~--~десятичное число обозначающее
порядковый номер (начиная с ноля) двоичного блока сформированного сборщиком
производителя устройства GPGPU.\par}
{\NmCnvDescript\verb|-o |\verbIU{outfile}\\* строка \verbIU{outfile}~--~имя
выходного файла. Если не задан ключ \verb|--verbatim-output-name|, то
\verbIU{outfile} используется как префикс имени файла \verbIU{outfile}\verb|-|%
\verbI{модель\_устройства\_GPGPU}\verb|.clexe|, содержащего двоичный блок кода
сформированный в результате сборки. В случае, если ключ
\verb|--verbatim-output-name| указан, то \verbIU{outfile} используется <<как
есть>>, за исключением случаев, когда в результате сборки сформированы
несколько двоичных блоков~--~в таком случае все двоичные блоки будут сохранены с
именами файлов \verbIU{outfile}\verb|.|\verbI{N}, где \verbI{N}~--~порядковый
номер двоичного блока начиная с ноля. Кроме того строка \verbIU{outfile} будет
использована как префикс в имени файла-журнала сборки.\par
\begin{ImpNote}
Пробельные символы в начале и в конце строки \verbIU{outfile} будут удалены.
Пробельные символы внутри строки \verbIU{outfile} будут заменены на знак
подчёркивания~<<\verb|_|>>~(underscore).
\end{ImpNote}
}
{\NmCnvDescript\verb|COMPILER_OPTIONS|\\* аргументы компилятора. В неизменённом
виде и с сохранением последовательности передаются сборщику производителя.
Сами аргументы компилятора описаны в спецификациях OpenCL, кроме того,
сборщик производителя может поддерживать дополнительные аргументы не
отражённые в спецификациях OpenCL.\par}
{\NmCnvDescript\verb|LINKER_OPTIONS|\\* аргументы компоновщика. В неизменённом
виде и с сохранением последовательности передаются сборщику производителя. Сами
аргументы компоновщика описаны в спецификациях OpenCL, кроме того, сборщик
производителя может поддерживать дополнительные аргументы не отражённые в
спецификациях OpenCL.\par}
{\NmCnvDescript\verbIU{infile}\verb|...|\\* список разделённый пробелами с именами файлов содержащих исходный код программы OpenCL C или OpenCL C++. Имя файла не может начинаться с символа~<<\verb|-|>>.\par}