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">
9
clGetKernelWorkGroupInfo
16
clGetKernelWorkGroupInfo
21
<year>2007-2011</year>
22
<holder>The Khronos Group Inc.
23
Permission is hereby granted, free of charge, to any person obtaining a
24
copy of this software and/or associated documentation files (the
25
"Materials"), to deal in the Materials without restriction, including
26
without limitation the rights to use, copy, modify, merge, publish,
27
distribute, sublicense, and/or sell copies of the Materials, and to
28
permit persons to whom the Materials are furnished to do so, subject to
29
the condition that this copyright notice and permission notice shall be included
30
in all copies or substantial portions of the Materials.</holder>
33
<manvolnum>3</manvolnum>
36
<!-- ================================ SYNOPSIS -->
38
<refnamediv id="clGetKernelWorkGroupInfo">
40
clGetKernelWorkGroupInfo
44
Returns information about the kernel object that may be specific to a device.
48
<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
52
<link xlink:href="scalarDataTypes.html">cl_int</link>
53
<function>clGetKernelWorkGroupInfo</function>
57
<link xlink:href="abstractDataTypes.html">cl_kernel</link>
58
<parameter>kernel</parameter>
62
<link xlink:href="abstractDataTypes.html">cl_device_id</link>
63
<parameter>device</parameter>
67
<link xlink:href="enums.html#cl_kernel_work_group_info">cl_kernel_work_group_info</link>
68
<parameter>param_name</parameter>
72
<link xlink:href="scalarDataTypes.html">size_t</link>
73
<parameter>param_value_size</parameter>
77
<link xlink:href="scalarDataTypes.html">void</link>
78
<parameter>*param_value</parameter>
82
<link xlink:href="scalarDataTypes.html">size_t</link>
83
<parameter>*param_value_size_ret</parameter>
89
<!-- ================================ PARAMETERS -->
91
<refsect1 id="parameters">
92
<title>Parameters</title>
95
<term> <varname> kernel </varname> </term>
98
Specifies the kernel object being queried.
104
<term> <varname> device </varname> </term>
107
Identifies a specific device in the list of devices associated with
108
<varname>kernel</varname>. The list of devices is the list of devices in
109
the OpenCL context that is associated with <varname>kernel</varname>. If
110
the list of devices associated with <varname>kernel</varname> is a single
111
device, <varname>device</varname> can be a NULL value.
117
<term> <varname> param_name </varname> </term>
120
Specifies the information to query. The list of
121
supported <varname>param_name</varname> types and the
122
information returned in <varname>param_value</varname> by
123
<function>clGetKernelWorkGroupInfo</function> is described in the table
130
<term> <varname> param_value </varname> </term>
133
A pointer to memory where the appropriate result being queried is returned.
134
If <varname>param_value</varname> is NULL, it is ignored.
140
<term> <varname> param_value_size </varname> </term>
143
Used to specify the size in bytes of memory pointed to by
144
<varname>param_value</varname>. This size must be ≥ size of return
145
type as described in the table below.
149
<informaltable frame="all">
150
<tgroup cols="3" align="left" colsep="1" rowsep="1">
151
<colspec colname="col1" colnum="1" />
152
<colspec colname="col2" colnum="2" />
153
<colspec colname="col3" colnum="3" />
156
<entry>cl_kernel_work_group_info</entry>
157
<entry>Return Type</entry>
158
<entry>Info. returned in <varname>param_value</varname></entry>
164
<entry><constant>CL_KERNEL_GLOBAL_WORK_SIZE</constant></entry>
165
<entry>size_t[3]</entry>
168
This provides a mechanism for the application to query the maximum global
169
size that can be used to execute a kernel (i.e. <varname>global_work_size</varname>
170
argument to <citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry>)
171
on a custom device given by <varname>device</varname> or a built-in kernel on an OpenCL device
172
given by <varname>device</varname>.
175
If <varname>device</varname> is not a custom device
176
or <varname>kernel</varname> is not a built-in kernel,
177
<citerefentry><refentrytitle>clGetKernelArgInfo</refentrytitle></citerefentry>
178
returns the error <constant>CL_INVALID_VALUE</constant>.
184
<entry><constant>CL_KERNEL_WORK_GROUP_SIZE</constant></entry>
185
<entry>size_t</entry>
187
This provides a mechanism for the application to query the maximum work-group size
188
that can be used to execute a kernel on a specific device given by <varname>device</varname>. The
189
OpenCL implementation uses the resource requirements of the kernel
190
(register usage etc.) to determine what this work-group size should be.
195
<entry><constant>CL_KERNEL_COMPILE_-
196
WORK_GROUP_SIZE</constant></entry>
197
<entry>size_t[3]</entry>
199
Returns the work-group size specified by the
200
<constant>__attribute__((reqd_work_group_size(X, Y, Z)))</constant> qualifier.
201
See <citerefentry href="functionQualifiers"><refentrytitle>Function Qualifiers</refentrytitle></citerefentry>.
202
If the work-group size is not specified using the above attribute qualifier (0, 0, 0) is returned.
207
<entry><constant>CL_KERNEL_LOCAL_MEM_SIZE</constant></entry>
208
<entry>cl_ulong</entry>
211
Returns the amount of local memory in bytes being
212
used by a kernel. This includes local memory that may
213
be needed by an implementation to execute the kernel,
214
variables declared inside the kernel with the <citerefentry
215
href="local"><refentrytitle>__local</refentrytitle></citerefentry>
216
address qualifier and local memory to
217
be allocated for arguments to the kernel
218
declared as pointers with the <citerefentry
219
href="local"><refentrytitle>__local</refentrytitle></citerefentry>
220
address qualifier and whose size is specified with
221
<citerefentry><refentrytitle>clSetKernelArg</refentrytitle></citerefentry>.
225
If the local memory size, for any pointer
226
argument to the kernel declared with the <citerefentry
227
href="local"><refentrytitle>__local</refentrytitle></citerefentry>
228
address qualifier, is not specified, its size is assumed
235
<entry><constant>CL_KERNEL_PREFERRED_WORK_-
236
GROUP_SIZE_MULTIPLE</constant></entry>
237
<entry>size_t</entry>
239
Returns the preferred multiple of workgroup size for launch. This is
240
a performance hint. Specifying a workgroup size that is not a multiple
241
of the value returned by this query as the value of the local work size argument
242
to <citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry>will
243
not fail to enqueue the kernel for execution unless the work-group size specified is
244
larger than the device maximum.
249
<entry><constant>CL_KERNEL_PRIVATE_MEM_SIZE</constant></entry>
250
<entry>cl_ulong</entry>
252
Returns the minimum amount of private memory, in bytes, used by each workitem in the
253
kernel. This value may include any private memory needed by an implementation to
254
execute the kernel, including that used by the language built-ins and variable declared
255
inside the kernel with the
256
<citerefentry href="private"><refentrytitle>__private</refentrytitle></citerefentry> qualifier.
266
<term> <varname> param_value_size_ret </varname> </term>
269
Returns the actual size in bytes of data copied to <varname>param_value</varname>. If
270
<varname>param_value_size_ret</varname> is NULL, it is ignored.
278
<!-- ================================ NOTES -->
279
<!--<refsect1 id="notes"><title>Notes</title>
285
<!-- ================================ ERRORS -->
287
<refsect1 id="errors"><title>Errors</title>
289
Returns <errorname>CL_SUCCESS</errorname> if the function is executed successfully. Otherwise, it returns
290
one of the following errors:
293
<itemizedlist mark="disc">
295
<errorname>CL_INVALID_DEVICE</errorname> if <varname>device</varname> is
296
not in the list of devices associated with <varname>kernel</varname> or if
297
<varname>device</varname> is NULL but there is more than one device associated
298
with <varname>kernel</varname>.
302
<errorname>CL_INVALID_VALUE</errorname> if <varname>param_name</varname> is not
303
valid, or if size in bytes specified by <varname>param_value_size</varname>
304
is < size of return type as described in the table above and
305
<varname>param_value</varname> is not NULL.
309
<errorname>CL_INVALID_VALUE</errorname> if <varname>param_name</varname> is
310
<constant>CL_KERNEL_GLOBAL_WORK_SIZE</constant> and <varname>device</varname>
311
is not a custom device or <varname>kernel</varname> is not a built-in kernel.
315
<errorname>CL_INVALID_KERNEL</errorname> if <varname>kernel</varname> is a not
316
a valid kernel object.
320
<errorname>CL_OUT_OF_RESOURCES</errorname> if there is a failure to allocate
321
resources required by the OpenCL implementation on the device.
325
<errorname>CL_OUT_OF_HOST_MEMORY</errorname> if there is a failure to allocate
326
resources required by the OpenCL implementation on the host.
331
<!-- ================================ EXAMPLE -->
332
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
334
<refsect2 id="example1">
339
<informaltable frame="none">
340
<tgroup cols="1" align="left" colsep="0" rowsep="0">
341
<colspec colname="col1" colnum="1" />
345
Example goes here - it will be set in "code" type with white space preserved.
354
<!-- ================================ SPECIFICATION -->
355
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
357
<refsect1 id="specification"><title>Specification</title>
360
<imagedata fileref="pdficon_small1.gif" format="gif" />
363
<olink uri="clGetKernelWorkGroupInfo">OpenCL Specification</olink>
367
<!-- ================================ ALSO SEE -->
369
<refsect1 id="seealso"><title>Also see</title>
371
<citerefentry><refentrytitle>clCreateKernel</refentrytitle></citerefentry>,
372
<citerefentry><refentrytitle>clCreateKernelsInProgram</refentrytitle></citerefentry>,
373
<citerefentry><refentrytitle>clReleaseKernel</refentrytitle></citerefentry>,
374
<citerefentry><refentrytitle>clRetainKernel</refentrytitle></citerefentry>,
375
<citerefentry><refentrytitle>clSetKernelArg</refentrytitle></citerefentry>,
376
<citerefentry><refentrytitle>clGetKernelInfo</refentrytitle></citerefentry>
380
<!-- ================================ COPYRIGHT -->
381
<!-- Content included from copyright.inc.xsl -->
383
<refsect3 id="Copyright"><title></title>
385
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
added
removed
clGetKernelWorkGroupInfo.xml
