| <?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>clBuildProgram</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /> |
| <meta name="keywords" content="clBuildProgram" /> |
| </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="clBuildProgram"></a> |
| <h1>clBuildProgram</h1> |
| <p> |
| Builds (compiles and links) a program executable from the program source or binary. |
| </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">clBuildProgram</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">void</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">(CL_CALLBACK *pfn_notify)(<a class="link" href="abstractDataTypes.html" target="_top">cl_program</a> program, <a class="link" href="scalarDataTypes.html" target="_top">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. |
| </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 program executable is |
| built for all devices associated with <code class="varname">program</code> for which |
| a source or binary has been loaded. If <code class="varname">device_list</code> is |
| a non-NULL value, the program executable is built for devices specified |
| in this list for which a source or binary has been loaded. |
| </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 |
| build options to be used for building the program executable. |
| Certain options are ignored when <code class="varname">program</code> is created with IL. |
| The list |
| of supported options is described below. |
| </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">clBuildProgram</code> does not need to wait for the |
| build to complete and can return immediately once the build operation |
| can begin. The build operation can begin if the context, program whose |
| sources are being compiled and linked, list of devices and build options |
| specified are all valid and appropriate host and device resources needed |
| to perform the build are available. If <code class="varname">pfn_notify</code> |
| is NULL, <code class="function">clBuildProgram</code> does not return until the |
| build 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> |
| Builds (compiles & links) a program executable from the program source |
| or binary for all the devices or a specific device(s) in the OpenCL context |
| associated with <code class="varname">program</code>. OpenCL allows program executables to |
| be built using the source or the binary. <code class="function">clBuildProgram</code> |
| must be called for <code class="varname">program</code> created using either |
| <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>, or |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a> |
| to build the program executable for one or more devices associated with |
| <code class="varname">program</code>. If <code class="varname">program</code> is created with |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a>, |
| then the program binary must be an executable binary (not a compiled binary or library). |
| </p><p> |
| The executable 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><p> |
| <code class="function">clBuildProgram</code> does not return until the build |
| 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><h4><a id="id-1.6.5"></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.7"></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.11"></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.13"></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.18"></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.20"></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.26"></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.29"></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.31"></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.33"></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.34"></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.36"></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.40"></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">clBuildProgram</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">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_BINARY</span> |
| if <code class="varname">program</code> is created with |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a> |
| and devices listed in <code class="varname">device_list</code> do not have a valid program |
| binary loaded. |
| </li> |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_BUILD_OPTIONS</span> if the build 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 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">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 <code class="varname">program</code> is created with |
| <a class="citerefentry" href="clCreateProgramWithSource.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithSource</span></span></a> |
| and a compiler is not available i.e. |
| <span class="errorname">CL_DEVICE_COMPILER_AVAILABLE</span> |
| specified in the table of OpenCL Device Queries for |
| <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a> |
| is set to <span class="errorname">CL_FALSE</span>. |
| </li> |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_BUILD_PROGRAM_FAILURE</span> if there is a failure |
| to build the program executable. This error will be returned if |
| <code class="function">clBuildProgram</code> does not return until the build 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> was not created with |
| <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>, or |
| <a class="citerefentry" href="clCreateProgramWithBinary.html"><span class="citerefentry"><span class="refentrytitle">clCreateProgramWithBinary</span></span></a>. |
| </li> |
| <li class="listitem" style="list-style-type: disc"><span class="errorname">CL_INVALID_OPERATION</span> if |
| the <code class="varname">program</code> requires independent forward |
| progress of sub-groups but one or more of the devices listed in |
| <code class="varname">device_list</code> does not return <code class="constant">CL_TRUE</code> for |
| the <code class="constant">CL_DEVICE_SUBGROUP_INDEPENDENT_FORWARD_PROGRESS</code> query. |
| |
| </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="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#namedest=clBuildProgram" 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="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>, |
| <a class="citerefentry" href="clCompileProgram.html"><span class="citerefentry"><span class="refentrytitle">clCompileProgram</span></span></a>, |
| <a class="citerefentry" href="clLinkProgram.html"><span class="citerefentry"><span class="refentrytitle">clLinkProgram</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> |
