| <?xml version="1.0" encoding="UTF-8"?> | |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> | |
| <!-- saved from url=(0013)about:internet --> | |
| <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl"> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> | |
| <style xmlns="" type="text/css"> | |
| /* This style sets a margin around the entire page */ | |
| html, body { | |
| margin: 10px; | |
| } | |
| p { | |
| font: normal 16px verdana, sans-serif; | |
| margin: 0; | |
| padding-bottom:12px; | |
| } | |
| h1 { | |
| font: bold 25px verdana, sans-serif; | |
| margin-top: 0; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| h2 { | |
| font: bold 19px verdana, sans-serif; | |
| margin-top: 28px; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| h3 { | |
| font: bold 19px verdana, sans-serif !important; | |
| margin-top: 28px; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| li { | |
| font: normal 16px verdana, sans-serif; | |
| margin-top: 0; | |
| margin-bottom: 18px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| .pdparam { | |
| font: italic 16px verdana, sans-serif; | |
| } | |
| .term { | |
| font: italic 16px verdana, sans-serif; | |
| font-weight: normal; | |
| } | |
| .type { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .parameter { | |
| font-style: italic; | |
| } | |
| a:link, a:visited { | |
| color: blue; | |
| text-decoration: none; | |
| font: normal 16px; | |
| } | |
| a:hover { | |
| background-color: #FFFF99; | |
| font: normal 16px; | |
| } | |
| div.funcsynopsis { | |
| text-align: left; | |
| background-color: #e6e6e6; | |
| font: normal 16px verdana, sans-serif; | |
| padding-top: 10px; | |
| padding-bottom: 10px; | |
| } | |
| div.funcsynopsis table { | |
| border-collapse: separate; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.funcsynopsis td { | |
| background-color: #e6e6e6; | |
| border: 0 solid #000; | |
| padding: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 { | |
| font-family: verdana, sans-serif; | |
| font-size: 16px; | |
| } | |
| code.constant { | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| span.errorname { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| code.function { | |
| font: bold 16px verdana, sans-serif !important; | |
| } | |
| b.fsfunc { | |
| font: bold 16px verdana, sans-serif !important; | |
| } | |
| code.varname { | |
| font: italic 16px verdana, sans-serif; | |
| } | |
| code.replaceable { | |
| font: italic 16px courier new, monospace; | |
| } | |
| code.funcdef { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .citerefentry { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .parameter { | |
| font-style: italic; | |
| } | |
| code.fsfunc { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| /* PARAMETER: This style controls spacing between the terms in Parameter section */ | |
| dt { | |
| margin-top: 15px; | |
| } | |
| /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */ | |
| div.refsect1 table { | |
| width: 100%; | |
| margin-top: 10px; | |
| background-color: #FFF; | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 th { | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: bold 16px verdana, sans-serif; | |
| } | |
| div.refsect1 td { | |
| background-color: #FFF; | |
| padding: 5px; | |
| vertical-align: text-top; | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 p{ | |
| font: normal 16px verdana, sans-serif; | |
| margin-top: 8px; | |
| margin-bottom: 8px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| /* EXAMPLE: These styles apply only to the Example section */ | |
| div.refsect2 { | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| div.refsect2 table { | |
| margin-top: 0; | |
| background-color: #e6e6e6; | |
| width: 100%; | |
| border: 0 solid #000; | |
| padding: 2px; | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| div.refsect2 td { | |
| background-color: #e6e6e6; | |
| font: normal 16px courier new, monospace !important; | |
| white-space:pre; | |
| } | |
| /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */ | |
| div.refsect3 { | |
| font: normal 11px verdana, sans-serif; | |
| margin-top: 50px; | |
| margin-bottom: 20px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| </style> | |
| <title>clCompileProgram</title> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /> | |
| <meta name="keywords" content="clCompileProgram" /> | |
| </head> | |
| <body> | |
| <div class="refentry"> | |
| <a id="id-1"></a> | |
| <div class="titlepage"></div> | |
| <div xmlns="" class="refnamediv"> | |
| <a xmlns="http://www.w3.org/1999/xhtml" id="clCompileProgram"></a> | |
| <h1> | |
| clCompileProgram | |
| </h1> | |
| <p> | |
| Compiles a program’s source for all the devices or a specific device(s) in the OpenCL context | |
| associated with <code xmlns="http://www.w3.org/1999/xhtml" class="varname">program</code>. | |
| </p> | |
| </div> | |
| <div class="refsynopsisdiv"> | |
| <h2></h2> | |
| <div class="funcsynopsis"> | |
| <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> | |
| <tr valign="bottom"> | |
| <td> | |
| <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef"> | |
| <a class="link" href="scalarDataTypes.html" target="pagedisplay">cl_int</a> | |
| <strong class="fsfunc">clCompileProgram</strong> | |
| (</code> | |
| <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="abstractDataTypes.html" target="pagedisplay">cl_program</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">program</var>, </td> | |
| </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">cl_uint</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">num_devices</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td>const <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="abstractDataTypes.html" target="pagedisplay">cl_device_id</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*device_list</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td>const <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">char</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*options</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">cl_uint</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">num_input_headers</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td>const <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">cl_program</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*input_headers</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td>const <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">char</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">**header_include_names</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">void</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">(CL_CALLBACK *pfn_notify)( | |
| <a class="link" href="abstractDataTypes.html" target="pagedisplay">cl_program</a> program, | |
| <a class="link" href="scalarDataTypes.html" target="pagedisplay">void</a> *user_data)</var>, </td> | |
| </tr> | |
| <tr valign="top"> | |
| <td> </td> | |
| <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">void</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*user_data</var><code>)</code></td> | |
| </tr> | |
| </table> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="parameters"></a> | |
| <h2>Parameters</h2> | |
| <div class="variablelist"> | |
| <dl class="variablelist"> | |
| <dt> | |
| <span class="term"> <code class="varname"> program </code> </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| The program object that is the compilation target. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> <code class="varname"> device_list </code> </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| A pointer to a list of devices associated with <code class="varname">program</code>. If | |
| <code class="varname">device_list</code> is a NULL value, the compile is performed for | |
| all devices associated with program. If <code class="varname">device_list</code> is a | |
| non-NULL value, the compile is performed for devices specified in this list. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> <code class="varname"> num_devices </code> </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| The number of devices listed in <code class="varname">device_list</code>. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="varname">options</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| A pointer to a null-terminated string of characters that describes the | |
| compilation options to be used for building the program executable. | |
| Certain options are ignored when | |
| program is created with IL. | |
| The list of supported options is as described below. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="varname">num_input_headers</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Specifies the number of programs that describe headers in the array | |
| referenced by <code class="varname">input_headers</code>. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="varname">input_headers</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| An array of program embedded headers created with | |
| <a class="citerefentry" href="clCreateProgramWithSource.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithSource</span></span></a>. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> | |
| <code class="varname">header_include_names</code> | |
| </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| An array that has a one to one correspondence | |
| with <code class="varname">input_headers</code>. Each entry in | |
| <code class="varname">header_include_names</code> specifies the include name used by | |
| source in <code class="varname">program</code> that comes from an embedded header. | |
| The corresponding entry in <code class="varname">input_headers</code> identifies the | |
| program object which contains the header source to be used. The embedded | |
| headers are first searched before the headers in the list of directories | |
| specified by the –I compile option (as described in section 5.8.4.1). | |
| If multiple entries in <code class="varname">header_include_names</code> refer to | |
| the same header name, the first one encountered will be used. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> <code class="varname"> pfn_notify </code> </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| A function pointer to a notification routine. The notification routine | |
| is a callback function that an application can register and which will | |
| be called when the program executable has been built (successfully | |
| or unsuccessfully). If <code class="varname">pfn_notify</code> is not NULL, | |
| <code class="function">clCompileProgram</code> does not need to wait for the | |
| compiler to complete and can return immediately once the compilation | |
| can begin. The compilation can begin if the context, program whose | |
| sources are being compiled, list of devices, input headers, programs | |
| that describe input headers and compiler options specified are all | |
| valid and appropriate host and device resources needed to perform | |
| the compile are available. If <code class="varname">pfn_notify</code> is NULL, | |
| <code class="function">clCompileProgram</code> does not return until the compiler | |
| has completed. This callback function may be called asynchronously by | |
| the OpenCL implementation. It is the application’s responsibility to | |
| ensure that the callback function is thread-safe. | |
| </p> | |
| </dd> | |
| <dt> | |
| <span class="term"> <code class="varname"> user_data </code> </span> | |
| </dt> | |
| <dd> | |
| <p> | |
| Passed as an argument when <code class="varname">pfn_notify</code> is | |
| called. <code class="varname">user_data</code> can be NULL. | |
| </p> | |
| </dd> | |
| </dl> | |
| </div> | |
| </div> | |
| <div class="refsect1"><a id="notes"></a><h2>Notes</h2><p> | |
| Compiles a program’s source for all the devices or a specific device(s) | |
| in the OpenCL context associated with <code class="varname">program</code>. The | |
| pre-processor runs before the program sources are compiled. The compiled | |
| binary is built for all devices associated with <code class="varname">program</code> | |
| or the list of devices specified. The compiled binary can be queried using | |
| <a class="citerefentry" href="clGetProgramInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetProgramInfo</span></span></a>(<code class="varname">program</code>, | |
| <code class="constant">CL_PROGRAM_BINARIES</code>, ...) and can be specified to | |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a> | |
| to create a new program object. | |
| </p><h4><a id="id-1.6.3"></a>Compiler Options</h4><p> | |
| The compiler options are categorized as pre-processor options, options for math intrinsics, | |
| options that control optimization and miscellaneous options. This specification defines | |
| a standard set of options that must be supported by the OpenCL C compiler when building | |
| program executables online or offline. These may be extended by a set of vendor- or | |
| platform specific options. | |
| </p><h4><a id="id-1.6.5"></a>Preprocessor Options</h4><p> | |
| These options control the OpenCL C preprocessor which is run on each program source before | |
| actual compilation. | |
| </p><p> | |
| -D options are processed in the order they are given in the | |
| <code class="varname">options</code> argument to | |
| <code class="function">clBuildProgram</code> or <code class="function">clCompileProgram</code>. | |
| </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-D name</span></dt><dd><p> | |
| Predefine <code class="varname">name</code> as a macro, with definition 1. | |
| </p></dd><dt><span class="term">-D name=definition</span></dt><dd><p> | |
| The contents of <code class="varname">definition</code> are tokenized and processed as | |
| if they appeared during translation phase three in a '#define' directive. In | |
| particular, the definition will be truncated by embedded newline characters. | |
| </p></dd><dt><span class="term">-I dir</span></dt><dd><p> | |
| Add the directory <code class="varname">dir</code> to the list of directories to be | |
| searched for header files. | |
| </p></dd></dl></div><h4><a id="id-1.6.9"></a>Math Intrinsics Options</h4> | |
| These options control compiler behavior regarding floating-point arithmetic. These options trade | |
| off between speed and correctness. | |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term">-cl-single-precision-constant</span></dt><dd><p> | |
| Treat double precision floating-point constant as single precision constant. | |
| </p></dd><dt><span class="term">-cl-denorms-are-zero</span></dt><dd><p> | |
| This option controls how single precision and double precision denormalized | |
| numbers are handled. If specified as a build option, the single precision | |
| denormalized numbers may be flushed to zero; double precision denormalized | |
| numbers may also be flushed to zero if the optional extension for double | |
| precsion is supported. This is intended to be a performance hint and the | |
| OpenCL compiler can choose not to flush denorms to zero if the device supports | |
| single precision (or double precision) denormalized numbers. | |
| </p><p> | |
| This option is ignored for single precision numbers if the | |
| device does not support single precision denormalized numbers | |
| i.e. <code class="constant">CL_FP_DENORM</code> bit is not set in | |
| <code class="constant">CL_DEVICE_SINGLE_FP_CONFIG</code>. | |
| </p><p> | |
| This option is ignored for double precision numbers if the device | |
| does not support double precision or if it does support double | |
| precison but not double precision denormalized | |
| numbers i.e. <code class="constant">CL_FP_DENORM</code> bit is not set in | |
| <code class="constant">CL_DEVICE_DOUBLE_FP_CONFIG</code>. | |
| </p><p> | |
| This flag only applies for scalar and vector single precision floating-point | |
| variables and computations on these floating-point variables inside a | |
| program. It does not apply to reading from or writing to image objects. | |
| </p></dd><dt><span class="term">-cl-fp32-correctly-rounded-divide-sqrt</span></dt><dd><p> | |
| The <code class="code">-cl-fp32-correctly-rounded-divide-sqrt</code> build option to | |
| <code class="function">clBuildProgram</code> or <code class="function">clCompileProgram</code> | |
| allows an application to specify that single precision floating-point divide | |
| (x/y and 1/x) and sqrt used in the program source are correctly rounded. | |
| If this build option is not specified, the minimum numerical accuracy of | |
| single precision floating-point divide and sqrt are as defined in section | |
| 7.4 of the OpenCL specification. | |
| </p><p> | |
| This build option can only be specified if the | |
| <code class="constant">CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT</code> is set | |
| in <code class="constant">CL_DEVICE_SINGLE_FP_CONFIG</code> (as defined in | |
| in the table of allowed values for <code class="varname">param_name</code> for | |
| <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a>) for | |
| devices that the program is being build. <code class="function">clBuildProgram</code> | |
| or <code class="function">clCompileProgram</code> will fail to compile the program for | |
| a device if the <code class="code">-cl-fp32-correctly-rounded-divide-sqrt</code> option is specified | |
| and <code class="constant">CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT</code> is not set for | |
| the device. | |
| </p></dd></dl></div><h4><a id="id-1.6.11"></a>Optimization Options</h4><p> | |
| These options control various sorts of optimizations. Turning on optimization flags | |
| makes the compiler attempt to improve the performance and/or code size at the expense of | |
| compilation time and possibly the ability to debug the program. | |
| </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-cl-opt-disable</span></dt><dd><p> | |
| This option disables all optimizations. The default is optimizations are enabled. | |
| </p></dd></dl></div><p> | |
| The following options control compiler behavior regarding floating-point arithmetic. These | |
| options trade off between performance and correctness and must be specifically enabled. | |
| These options are not turned on by default since it can result in incorrect output for | |
| programs which depend on an exact implementation of IEEE 754 rules/specifications for | |
| math functions. | |
| </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-cl-mad-enable</span></dt><dd><p> | |
| Allow <code class="code">a * b + c</code> to be replaced by a <code class="code">mad</code>. The | |
| <code class="code">mad</code> computes <code class="code">a * b + c</code> with reduced accuracy. For | |
| example, some OpenCL devices implement <code class="code">mad</code> as truncate the result | |
| of <code class="code">a * b</code> before adding it to <code class="code">c</code>. | |
| </p></dd><dt><span class="term">-cl-no-signed-zeros</span></dt><dd><p> | |
| Allow optimizations for floating-point arithmetic that ignore the signedness of | |
| zero. IEEE 754 arithmetic specifies the distinct behavior of <code class="code">+0.0</code> | |
| and <code class="code">-0.0</code> values, which then prohibits simplification of expressions | |
| such as <code class="code">x+0.0</code> or <code class="code">0.0*x</code> (even with <code class="code">-clfinite-math</code> | |
| only). This option implies that the sign of a zero result isn't significant. | |
| </p></dd><dt><span class="term">-cl-unsafe-math-optimizations</span></dt><dd><p> | |
| Allow optimizations for floating-point arithmetic that (a) assume that | |
| arguments and results are valid, (b) may violate IEEE 754 standard and (c) | |
| may violate the OpenCL numerical compliance requirements as defined in section | |
| 7.4 for single precision and double precision floating-point, and edge case | |
| behavior in section 7.5. This option includes the <code class="code">-cl-no-signed-zeros</code> and | |
| <code class="code">-cl-mad-enable</code> options. | |
| </p></dd><dt><span class="term">-cl-finite-math-only</span></dt><dd><p> | |
| Allow optimizations for floating-point arithmetic that assume that arguments and | |
| results are not NaNs or ±∞. This option may violate the OpenCL | |
| numerical compliance requirements defined in section 7.4 for single precision | |
| and double precision floating point, and edge case behavior in section 7.5. | |
| </p></dd><dt><span class="term">-cl-fast-relaxed-math</span></dt><dd><p> | |
| Sets the optimization options <code class="code">-cl-finite-math-only</code> and | |
| <code class="code">-cl-unsafe-math-optimizations</code>. This allows optimizations for floating-point | |
| arithmetic that may violate the IEEE 754 standard and the OpenCL numerical | |
| compliance requirements defined in the specification in section 7.4 for | |
| single-precision and double precision floating-point, and edge case | |
| behavior in section 7.5. This option also relaxes the precision of commonly | |
| used math functions (refer to | |
| table 7.2 defined in section 7.4). | |
| This option causes the preprocessor macro | |
| <code class="code">__FAST_RELAXED_MATH__</code> to be defined in the OpenCL program. | |
| </p></dd><dt><span class="term">-cl-uniform-work-group-size</span></dt><dd><p> | |
| This requires that the global work-size be | |
| a multiple of the work-group size specified to | |
| <a class="citerefentry" href="clEnqueueNDRangeKernel.html"><span class="citerefentry"><span class="refentrytitle">clEnqueueNDRangeKernel</span></span></a>. | |
| Allow optimizations that are made possible by this restriction. | |
| </p></dd></dl></div><h4><a id="id-1.6.16"></a>Options to Request or Suppress Warnings</h4> | |
| Warnings are diagnostic messages that report constructions which are not inherently erroneous | |
| but which are risky or suggest there may have been an error. The following language independent | |
| options do not enable specific warnings but control the kinds of diagnostics | |
| produced by the OpenCL compiler. | |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term">-w</span></dt><dd><p> | |
| Inhibit all warning messages. | |
| </p></dd><dt><span class="term">-Werror</span></dt><dd><p> | |
| Make all warnings into errors. | |
| </p></dd></dl></div><h4><a id="id-1.6.18"></a>Options Controlling the OpenCL C Version</h4> | |
| The following option controls the version of OpenCL C that the compiler accepts. | |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term">-cl-std=</span></dt><dd><p> | |
| Determine the OpenCL C language version to use. A value for this option must | |
| be provided. Valid values are: | |
| </p><p> | |
| <code class="code">CL1.1</code> - Support all OpenCL C programs that use the OpenCL C language features | |
| defined in section 6 of the OpenCL 1.1 specification. | |
| </p><p> | |
| <code class="code">CL1.2</code> - Support all OpenCL C programs that use the OpenCL C language features | |
| defined in section 6 of the OpenCL 1.2 specification. | |
| </p><p> | |
| <code class="code">CL2.0</code> - Support all OpenCL C programs that use the OpenCL C language features | |
| defined in section 6 of the OpenCL 2.0 specification. | |
| </p></dd></dl></div><p> | |
| Calls to <code class="function">clBuildProgram</code> or <code class="function">clCompileProgram</code> with | |
| the <code class="code">-cl-std=CL1.1</code> option will fail to compile the program for any devices with | |
| <code class="constant">CL_DEVICE_OPENCL_C_VERSION</code> = OpenCL C 1.0. | |
| </p><p> | |
| Calls to <code class="function">clBuildProgram</code> or <code class="function">clCompileProgram</code> with | |
| the <code class="code">-cl-std=CL1.2</code> option will fail to compile the program for any devices with | |
| <code class="constant">CL_DEVICE_OPENCL_C_VERSION</code> = OpenCL C 1.0 or OpenCL C 1.1. | |
| </p><p> | |
| Calls to <code class="function">clBuildProgram</code> or <code class="function">clCompileProgram</code> with | |
| the <code class="code">-cl-std=CL2.0</code> option will fail to compile the program for any devices with | |
| <code class="constant">CL_DEVICE_OPENCL_C_VERSION</code> = OpenCL C 1.0, OpenCL C 1.1, or OpenCL C 1.2. | |
| </p><p> | |
| If the <code class="code">–cl-std</code> build option is not specified, the | |
| highest OpenCL C 1.x language version supported | |
| by each device is used when compiling the program | |
| for each device. Applications are required | |
| to specify the <code class="code">–cl-std=CL2.0</code> option if they want | |
| to compile or build their programs with | |
| OpenCL C 2.0. | |
| </p><h4><a id="id-1.6.24"></a>Options enabled by the cl_khr_spir extension</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">-x spir</span></dt><dd><p> | |
| Indicates that the binary is in SPIR format. | |
| </p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">-spir-std</span></dt><dd><p> | |
| Specifies the version of the SPIR specification that | |
| describes the format and meaning of the binary. For | |
| example, if the binary is as described in | |
| SPIR version 1.2, then <code class="code">-spir-std=1.2</code> must | |
| be specified. Failing to specify these compile options | |
| may result in implementation defined behavior. | |
| </p></dd></dl></div><h4><a id="id-1.6.27"></a>Options for Querying Kernel Argument Information</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">-cl-kernel-arg-info</span></dt><dd><p> | |
| This option allows the compiler to store information about the | |
| arguments of a kernel(s) in the program executable. The argument | |
| information stored includes the argument name, its type, | |
| the address and access qualifiers used. Refer to description of | |
| <a class="citerefentry" href="clGetKernelArgInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetKernelArgInfo</span></span></a> | |
| on how to query this information. | |
| </p></dd></dl></div><h4><a id="id-1.6.29"></a>Options for debugging your program</h4><div class="variablelist"><dl class="variablelist"><dt><span class="term">-g</span></dt><dd><p> | |
| This option can currently be used to generate | |
| additional errors for the built-in functions | |
| that allow you to enqueue commands on a device | |
| (refer to section 6.13.17). | |
| </p></dd></dl></div><h4><a id="id-1.6.31"></a>Linker Options</h4> | |
| This specification defines a standard set of linker options that must be supported by the | |
| OpenCL C compiler when linking compiled programs online or offline. These linker options | |
| are categorized as library linking options and program linking options. These may be | |
| extended by a set of vendor- or platform-specific options. | |
| <h4><a id="id-1.6.32"></a>Library Linking Options</h4> | |
| The following options can be specified when creating a library of compiled binaries. | |
| <div class="variablelist"><dl class="variablelist"><dt><span class="term">-create-library</span></dt><dd><p> | |
| Create a library of compiled binaries specified | |
| in <code class="varname">input_programs</code> argument to | |
| <a class="citerefentry" href="clLinkProgram.html"><span class="citerefentry"><span class="refentrytitle">clLinkProgram</span></span></a>. | |
| </p></dd><dt><span class="term">-enable-link-options</span></dt><dd><p> | |
| Allows the linker to modify the library behavior based on one or more link | |
| options (described in Program Linking Options, below) when this library is | |
| linked with a program executable. This option must be specified with the | |
| <code class="code">-create-library</code> option. | |
| </p></dd></dl></div><h4><a id="id-1.6.34"></a>Program Linking Options</h4> | |
| The following options can be specified when linking a program executable. | |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem" style="list-style-type: disc"><code class="code">-cl-denorms-are-zero</code></li><li class="listitem" style="list-style-type: disc"><code class="code">-cl-no-signed-zeroes</code></li><li class="listitem" style="list-style-type: disc"><code class="code">-cl-unsafe-math-optimizations</code></li><li class="listitem" style="list-style-type: disc"><code class="code">-cl-finite-math-only</code></li><li class="listitem" style="list-style-type: disc"><code class="code">-cl-fast-relaxed-mat</code></li></ul></div> | |
| The linker may apply these options to all compiled program objects specified to | |
| <a class="citerefentry" href="clLinkProgram.html"><span class="citerefentry"><span class="refentrytitle">clLinkProgram</span></span></a>. The linker | |
| may apply these options only to libraries which were created with the | |
| <code class="code">-enable-link-option</code>. | |
| <h4><a id="id-1.6.38"></a>Separate Compilation and Linking of Programs</h4><p> | |
| OpenCL programs are compiled and linked to support the following: | |
| </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem" style="list-style-type: disc"> | |
| Separate compilation and link stages. Program sources can be compiled to generate | |
| a compiled binary object and linked in a separate stage with other compiled program | |
| objects to the program exectuable. | |
| </li><li class="listitem" style="list-style-type: disc"> | |
| Embedded headers. In OpenCL 1.0 and 1.1, the <code class="code">-I</code> build option could be used to | |
| specify the list of directories to be searched for headers files that are included | |
| by a program source(s). OpenCL 1.2 extends this by allowing the header sources to | |
| come from program objects instead of just header files. | |
| </li><li class="listitem" style="list-style-type: disc"> | |
| Libraries. The linker can be used to link compiled objects and libraries into a | |
| program executable or to create a library of compiled binaries. | |
| </li></ul></div></div> | |
| <div class="refsect1"> | |
| <a id="errors"></a> | |
| <h2>Errors</h2> | |
| <p> | |
| <code class="function">clCompileProgram</code> returns <span class="errorname">CL_SUCCESS</span> if | |
| the function is executed successfully. Otherwise, it returns one of the following errors: | |
| </p> | |
| <div class="itemizedlist"> | |
| <ul class="itemizedlist" style="list-style-type: disc; "> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_PROGRAM</span> if <code class="varname">program</code> is not | |
| a valid program object. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_VALUE</span> if <code class="varname">device_list</code> | |
| is NULL and <code class="varname">num_devices</code> is greater than zero, or if | |
| <code class="varname">device_list</code> is not NULL and <code class="varname">num_devices</code> | |
| is zero. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_VALUE</span> if <code class="varname">num_input_headers</code> is | |
| zero and <code class="varname">header_include_names</code> or <code class="varname">input_headers</code> | |
| are not NULL or if <code class="varname">num_input_headers</code> is not zero and | |
| <code class="varname">header_include_names</code> or <code class="varname">input_headers</code> are NULL. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_VALUE</span> if <code class="varname">pfn_notify</code> is NULL | |
| but <code class="varname">user_data</code> is not NULL. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_DEVICE</span> if OpenCL devices listed in | |
| <code class="varname">device_list</code> are not in the list of devices associated with | |
| <code class="varname">program</code>. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_COMPILER_OPTIONS</span> if the compiler options | |
| specified by <code class="varname">options</code> are invalid. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_OPERATION</span> if the compilation or build of a program | |
| executable for any of the devices listed in <code class="varname">device_list</code> | |
| by a previous call to <code class="function">clCompileProgram</code> or | |
| <code class="function">clBuildProgram</code> for <code class="varname">program</code> has not completed. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_COMPILER_NOT_AVAILABLE</span> if a compiler is not | |
| available i.e. <code class="constant">CL_DEVICE_COMPILER_AVAILABLE</code> specified | |
| in in the table of allowed values for <code class="varname">param_name</code> for | |
| <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a> | |
| is set to <code class="constant">CL_FALSE</code>. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_COMPILE_PROGRAM_FAILURE</span> if there is a | |
| failure to compile the program source. This error will be returned if | |
| <code class="function">clCompileProgram</code> does not return until the compile has | |
| completed. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_OPERATION</span> if there are kernel objects attached | |
| to <code class="varname">program</code>. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_OPERATION</span> if <code class="varname">program</code> | |
| has no source or IL available, i.e. it has not been created with | |
| <a class="citerefentry" href="clCreateProgramWithSource.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithSource</span></span></a> or | |
| <a class="citerefentry" href="clCreateProgramWithIL.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithIL</span></span></a>. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_RESOURCES</span> if there is a failure to allocate | |
| resources required by the OpenCL implementation on the device. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_OUT_OF_HOST_MEMORY</span> if there is a failure to allocate | |
| resources required by the OpenCL implementation on the host. | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div class="refsect2"> | |
| <a id="example1"></a> | |
| <h3> | |
| Example | |
| </h3> | |
| <p> | |
| For example, consider the following program source: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| #include <foo.h> | |
| #include <mydir/myinc.h> | |
| __kernel void | |
| image_filter (int n, int m, | |
| __constant float *filter_weights, | |
| __read_only image2d_t src_image, | |
| __write_only image2d_t dst_image) | |
| { | |
| ... | |
| } | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| This kernel includes two headers foo.h and mydir/myinc.h. The following describes | |
| how these headers can be passed as embedded headers in program objects: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| cl_program foo_pg = clCreateProgramWithSource(context, | |
| 1, &foo_header_src, NULL, &err); | |
| cl_program myinc_pg = clCreateProgramWithSource(context, | |
| 1, &myinc_header_src, NULL, &err); | |
| // let’s assume the program source described above is given | |
| // by program_A and is loaded via clCreateProgramWithSource | |
| cl_program input_headers[2] = { foo_pg, myinc_pg }; | |
| char * input_header_names[2] = { “foo.h”, “mydir/myinc.h” }; | |
| clCompileProgram(program_A, | |
| 0, NULL, // num_devices & device_list | |
| NULL, // compile_options | |
| 2, // num_input_headers | |
| input_headers, | |
| input_header_names, | |
| NULL, NULL); // pfn_notify & user_data | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="specification"></a> | |
| <h2>Specification</h2> | |
| <p> | |
| <img src="pdficon_small1.gif" /> | |
| <a href="https://www.khronos.org/registry/cl/specs/opencl-2.1.pdf#page=202" target="OpenCL Spec">OpenCL Specification</a> | |
| </p> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="seealso"></a> | |
| <h2>Also see</h2> | |
| <p> | |
| <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a>, | |
| <a class="citerefentry" href="clLinkProgram.html"><span class="citerefentry"><span class="refentrytitle">clLinkProgram</span></span></a>, | |
| <a class="citerefentry" href="clBuildProgram.html"><span class="citerefentry"><span class="refentrytitle">clBuildProgram</span></span></a>, | |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a>, | |
| <a class="citerefentry" href="clCreateProgramWithSource.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithSource</span></span></a>, | |
| <a class="citerefentry" href="clCreateProgramWithIL.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithIL</span></span></a> | |
| </p> | |
| </div> | |
| <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 The Khronos Group Inc. | |
| Permission is hereby granted, free of charge, to any person obtaining a | |
| copy of this software and/or associated documentation files (the | |
| "Materials"), to deal in the Materials without restriction, including | |
| without limitation the rights to use, copy, modify, merge, publish, | |
| distribute, sublicense, and/or sell copies of the Materials, and to | |
| permit persons to whom the Materials are furnished to do so, subject to | |
| the condition that this copyright notice and permission notice shall be included | |
| in all copies or substantial portions of the Materials. | |
| </div> | |
| </div> | |
| </body> | |
| </html> |