1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
8
<keyword>clCreateProgramWithBinary</keyword>
14
clCreateProgramWithBinary
19
<year>2007-2011</year>
20
<holder>The Khronos Group Inc.
21
Permission is hereby granted, free of charge, to any person obtaining a
22
copy of this software and/or associated documentation files (the
23
"Materials"), to deal in the Materials without restriction, including
24
without limitation the rights to use, copy, modify, merge, publish,
25
distribute, sublicense, and/or sell copies of the Materials, and to
26
permit persons to whom the Materials are furnished to do so, subject to
27
the condition that this copyright notice and permission notice shall be included
28
in all copies or substantial portions of the Materials.</holder>
31
<manvolnum>3</manvolnum>
34
<!-- ================================ SYNOPSIS -->
36
<refnamediv id="clCreateProgramWithBinary">
38
clCreateProgramWithBinary
42
Creates a program object for a context, and loads the binary bits specified by
43
<varname>binary</varname> into the program object.
47
<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
51
<link xlink:href="abstractDataTypes.html">cl_program</link> <function>clCreateProgramWithBinary</function>
53
<paramdef><link xlink:href="abstractDataTypes.html">cl_context</link><parameter>context</parameter></paramdef>
54
<paramdef><link xlink:href="scalarDataTypes.html">cl_uint</link><parameter>num_devices</parameter></paramdef>
55
<paramdef>const <link xlink:href="abstractDataTypes.html">cl_device_id</link><parameter>*device_list</parameter></paramdef>
56
<paramdef>const <link xlink:href="scalarDataTypes.html">size_t</link><parameter>*lengths</parameter></paramdef>
57
<paramdef>const <link xlink:href="scalarDataTypes.html">unsigned char</link><parameter>**binaries</parameter></paramdef>
58
<paramdef><link xlink:href="scalarDataTypes.html">cl_int</link><parameter>*binary_status</parameter></paramdef>
59
<paramdef><link xlink:href="scalarDataTypes.html">cl_int</link><parameter>*errcode_ret</parameter></paramdef>
64
<!-- ================================ PARAMETERS -->
66
<refsect1 id="parameters">
67
<title>Parameters</title>
71
<term> <varname> context </varname> </term>
74
Must be a valid OpenCL context.
80
<term> <varname> device_list </varname> </term>
83
A pointer to a list of devices that are in <varname>context</varname>.
84
<varname>device_list</varname> must be a non-NULL
85
value. The binaries are loaded for devices specified in this list.
91
<term> <varname> num_devices </varname> </term>
94
The number of devices listed in <varname>device_list</varname>.
98
The devices associated with the program object will be the list of devices specified by
99
<varname>device_list</varname>. The list of devices specified by <varname>device_list</varname>
100
must be devices associated with <varname>context</varname>.
106
<term> <varname> lengths </varname> </term>
109
An array of the size in bytes of the program binaries
110
to be loaded for devices specified by <varname>device_list</varname>.
117
<term> <varname> binaries </varname> </term>
120
An array of pointers to program binaries to be loaded for devices
121
specified by <varname>device_list</varname>. For each device given
122
by <varname>device_list</varname>[i], the pointer to the program
123
binary for that device is given by <varname>binaries</varname>[i]
124
and the length of this corresponding binary is given by
125
<varname>lengths</varname>[i]. <varname>lengths</varname>[i] cannot be
126
zero and <varname>binaries</varname>[i] cannot be a NULL pointer.
130
The program binaries specified by <varname>binaries</varname>
131
contain the bits that describe one of the following:
133
<itemizedlist mark="disc">
135
a program executable to be run on the device(s) associated
136
with <varname>context</varname>.
140
a compiled program for device(s) associated with <varname>context</varname>.
144
a library of compiled programs for device(s) associated with
145
<varname>context</varname>.
151
The program binary can consist of either or both of device-specific
152
code and/or implementation-specific intermediate representation (IR)
153
which will be converted to the device-specific code.
159
<term> <varname> binary_status </varname> </term>
162
Returns whether the program binary for each device specified
163
in <varname>device_list</varname> was loaded successfully
164
or not. It is an array of <varname>num_devices</varname>
165
entries and returns <constant>CL_SUCCESS</constant> in
166
<varname>binary_status</varname>[i] if binary was successfully
167
loaded for device specified by <varname>device_list</varname>[i];
168
otherwise returns <constant>CL_INVALID_VALUE</constant> if
169
<varname>lengths</varname>[i] is zero or if <varname>binaries</varname>[i]
170
is a NULL value or <constant>CL_INVALID_BINARY</constant> in
171
<varname>binary_status</varname>[i] if program binary is not a valid
172
binary for the specified device. If <varname>binary_status</varname>
173
is NULL, it is ignored.
179
<term> <varname> errcode_ret </varname> </term>
182
Returns an appropriate error code. If <varname>errcode_ret</varname>
183
is NULL, no error code is returned.
190
<!-- ================================ NOTES -->
192
<refsect1 id="notes"><title>Notes</title>
194
OpenCL allows applications to create a program object using the program source or
195
binary and build appropriate program executables. This can be very useful as it
196
allows applications to load program source and then compile and link to generate a
197
program executable online on its first instance for appropriate OpenCL devices in
198
the system. These executables can now be queried and cached by the application.
199
Future instances of the application launching will no longer need to compile and
200
link the program executables. The cached executables can be read and loaded by the
201
application, which can help significantly reduce the application initialization time.
205
<!-- ================================ ERRORS -->
207
<refsect1 id="errors"><title>Errors</title>
209
Returns a valid non-zero program object and <varname>errcode_ret</varname> is set to
210
<errorname>CL_SUCCESS</errorname> if the program object is created successfully.
211
Otherwise, it returns a NULL value with one of the following error values returned in
212
<varname>errcode_ret</varname>:
215
<itemizedlist mark="disc">
217
<errorname>CL_INVALID_CONTEXT</errorname> if <varname>context</varname> is not
222
<errorname>CL_INVALID_VALUE</errorname> if <varname>device_list</varname> is NULL
223
or <varname>num_devices</varname> is zero;
227
<errorname>CL_INVALID_DEVICE</errorname> if OpenCL devices listed in
228
<varname>device_list</varname> are not in the list of devices associated with
229
<varname>context</varname>.
233
<errorname>CL_INVALID_VALUE</errorname> if or if <varname>lengths</varname> or
234
<varname>binaries</varname> are NULL or if any entry in <varname>lengths</varname>[i]
235
or <varname>binaries</varname>[i] is NULL.
239
<errorname>CL_INVALID_BINARY</errorname> if an invalid program binary was encountered
240
for any device. <varname>binary_status</varname> will return specific status for
245
<errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate
246
resources required by the OpenCL implementation on the device.
250
<errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate
251
resources required by the OpenCL implementation on the host.
256
<!-- ================================ EXAMPLE -->
257
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
259
<refsect2 id="example1">
264
<informaltable frame="none">
265
<tgroup cols="1" align="left" colsep="0" rowsep="0">
266
<colspec colname="col1" colnum="1" />
270
Example goes here - it will be set in "code" type with white space preserved.
279
<!-- ================================ SPECIFICATION -->
280
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
282
<refsect1 id="specification"><title>Specification</title>
285
<imagedata fileref="pdficon_small1.gif" format="gif" />
288
<olink uri="clCreateProgramWithBinary">OpenCL Specification</olink>
292
<!-- ================================ ALSO SEE -->
294
<refsect1 id="seealso"><title>Also see</title>
296
<citerefentry><refentrytitle>clCreateProgramWithSource</refentrytitle></citerefentry>,
297
<citerefentry><refentrytitle>clReleaseProgram</refentrytitle></citerefentry>,
298
<citerefentry><refentrytitle>clRetainProgram</refentrytitle></citerefentry>,
299
<citerefentry href="classDiagram"><refentrytitle>Cardinality Diagram</refentrytitle></citerefentry>
303
<!-- ================================ COPYRIGHT -->
304
<!-- Content included from copyright.inc.xsl -->
306
<refsect3 id="Copyright"><title></title>
308
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
added
removed
clCreateProgramWithBinary.xml
