OpenCL_helpers/documentation/tools_compiler-russian.tex

\subsection{Компиляция}

\index{OpenCL компилятор}%
\index{oclh_cr@\texttt{oclh\_cr}}%
Изолированная компиляция осуществляется утилитой \verb|oclh_cr|.

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

\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{Описание}

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


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

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

Результат работы компилятора -- нескомпонованный бинарный объект сохраняется в
файле \verbIU{outfile}\verb|-|\verbI{модель\_устройства\_GPGPU}\verb|.clo|. Если
указан ключ \verb|--verbatim-output-name|, то результат будет сохранен в файле
\verbIU{outfile}. Иногда возникает ситуация, когда библиотека OpenCL
производителя устройства выдала в качестве результата несколько бинарных
объектов, в таком случае все бинарные объекты будут сохранены, но к именам
файлов будет добавлен постфикс \verb|.|\verbI{N}, где \verbI{N}~--~десятичное
число обозначающее порядковый номер (начиная с ноля) двоичного блока
сформированного компилятором производителя устройства GPGPU.

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

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

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

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

{\NmCnvDescript\verb|--dev-idxs=|\verbIU{\#}\Verb|,|\verbIU{\#}\verb|,...|\\*
the numbers \verbIU{\#}\verb|,|\verbIU{\#}\verb|,...| specified without spaces

числа \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|.clo|, содержащего двоичный блок кода
сформированный в результате компиляции. В случае, если ключ
\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\verbIU{infile}\verb|...|\\* список разделённый пробелами с именами файлов содержащих исходный код программы OpenCL C или OpenCL C++. Имя файла не может начинаться с символа~<<\verb|-|>>.\par}