1CLINFO(1)                   General Commands Manual                  CLINFO(1)
2
3
4

NAME

6       clinfo - show OpenCL platforms and devices
7
8

SYNOPSIS

10       clinfo [options ...]
11
12

DESCRIPTION

14       clinfo  prints  all  available  information  about all OpenCL platforms
15       available on the system and the devices they expose.
16
17

OPTIONS

19       clinfo accepts the following options:
20
21       -a, --all-props
22         try to retrieve all properties, even those not  officially  supported
23         (e.g.  because  they require specific extensions), but only show them
24         if the property could be retrieved successfully; see also the LIMITA‐
25         TIONS  section  below;  note  that even though this may reveal hidden
26         properties, there is no guarantee that the returned values are  mean‐
27         ingful,  nor  that the corresponding feature is actually available at
28         all;
29
30       -A, --always-all-props
31         like -a, but also show errors;
32
33       --human
34         produce human-friendly output; this is the default (except  as  noted
35         below);
36
37       --raw
38         produce machine-friendly output; this is the default if clinfo is in‐
39         voked with a name that contains the string “raw”;
40
41       --json
42         outputs the raw data (cf. the --raw option) in JSON  format;  support
43         for this option is experimental, as the representation of some of the
44         values is not finalized;
45
46       --offline
47         shows also offline devices for platforms that expose this feature;
48
49       -l, --list
50         list platforms and devices by name, with no (other) properties;
51
52       -dplatform_index:device_index
53       --device platform_index:device_index
54         only show properties for the specified device in the specified  plat‐
55         form;
56
57       --prop property-name
58         only  show properties whose symbolic name matches (contains as a sub‐
59         string) the given property-name; the name is normalized as upper-case
60         and  with  minus sign (-) replaced by underscore signs (_); when this
61         flag is specified, raw mode is forced;
62
63       -h, -?
64         show usage;
65
66       --version, -v
67         show program version.
68
69

CONFORMING TO

71       OpenCL 1.1, OpenCL 1.2, OpenCL 2.0, OpenCL 2.1, OpenCL 2.2, OpenCL 3.0.
72
73

EXTENSIONS

75       Supported OpenCL extensions:
76
77       cl_khr_device_uuid
78         for the UUID, LUID and node mask of the device;
79
80       cl_khr_extended_versioning
81         for the extended platform, device, extension and IL versioned proper‐
82         ties backported from OpenCL 3.0 to previous OpenCL versions;
83
84       cl_khr_fp16, cl_khr_fp64, cl_amd_fp64, cl_APPLE_fp64_basic_ops
85         for information about support for half-precision and double-precision
86         floating-point data types;
87
88       cl_khr_image2d_from_buffer
89         for information about the base address and pitch  alignment  require‐
90         ments of buffers to be used as base for 2D images;
91
92       cl_khr_il_program
93         for information about the supported IL (Intermediate Language) repre‐
94         sentations;
95
96       cl_khr_spir
97         for information about the supported SPIR (Standard Portable  Interme‐
98         diate Representation) versions;
99
100       cl_khr_icd
101         for the suffix of vendor extensions functions;
102
103       cl_khr_subgroup_named_barrier
104         for the maximum number of named sub-group barriers;
105
106       cl_khr_terminate_context
107         for the terminate capabilities for the device;
108
109       cl_ext_device_fission
110         for device fission support in OpenCL 1.1 devices;
111
112       cl_ext_atomic_counters_32
113       cl_ext_atomic_counters_64
114         for the atomic counter extension;
115
116       cl_ext_cxx_for_opencl
117         for  the  version of the C++ for OpenCL language supported by the de‐
118         vice compiler;
119
120       cl_amd_device_attribute_query
121         for AMD-specific device attributes;
122
123       cl_amd_object_metadata
124         to show the maximum number of keys supported by the platform;
125
126       cl_amd_offline_devices
127         to show offline devices exposed by the platform,  if  requested  (see
128         --offline option);
129
130       cl_amd_copy_buffer_p2p
131         to show the number and IDs of available P2P devices;
132
133       cl_amd_svm
134       cl_arm_shared_virtual_memory
135         for Shared Virtual Memory (SVM) capabilities in OpenCL 1.2 devices;
136
137       cl_arm_core_id
138         to show the (potentially sparse) list of the core IDs that the device
139         may return;
140
141       cl_arm_job_slot_selection
142         to show the (potentially sparse) list of available job slots for com‐
143         mand submission;
144
145       cl_nv_device_attribute_query
146         for NVIDIA-specific device attributes;
147
148       cl_intel_exec_by_local_thread
149         for  the  Intel extension allowing CPU devices to run kernels as part
150         of the current host thread;
151
152       cl_intel_advanced_motion_estimation
153         for the version of the Intel Motion Estimation accelerator version;
154
155       cl_intel_device_side_avc_motion_estimation
156         for the version and supported features of Intel's device-side AVC Mo‐
157         tion;
158
159       cl_intel_planar_yuv
160         for the maximum dimensions of planar YUV images;
161
162       cl_intel_simultaneous_sharing
163         for  simultaneous  CL/GL/DirectX  context  sharing (only partial sup‐
164         port);
165
166       cl_intel_required_subgroup_size
167         to enumerate allowed sub-group sizes;
168
169       cl_altera_device_temperature
170         for the Altera extension to query the core temperature of the device;
171
172       cl_qcom_ext_host_ptr
173         for the QUALCOMM extension to query page size and required padding in
174         external memory allocation.
175
176

NOTES

178       Some  information  is  duplicated when available from multiple sources.
179       Examples:
180
181       • supported device partition types and domains as  obtained  using  the
182         cl_ext_device_fission extension typically match the ones obtained us‐
183         ing the core OpenCL 1.2 device partition feature;
184
185       • the preferred work-group size multiple matches the NVIDIA  warp  size
186         (on NVIDIA devices) or the AMD wavefront width (on AMD devices).
187
188
189       Some floating-point configuration flags may only be meaningful for spe‐
190       cific  precisions  and/or  specific  OpenCL  versions.   For   example,
191       CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT  is only relevant for single preci‐
192       sion in OpenCL 1.2 devices.
193
194
195       The implementation-defined behavior for NULL platform or context  prop‐
196       erties is tested for the following API calls:
197
198       clGetPlatformInfo()
199         by trying to show the platform name;
200
201       clGetDeviceIDs()
202         by  trying  to enumerate devices; the corresponding platform (if any)
203         is then detected by querying the device platform of the first device;
204
205       clCreateteContext()
206         by trying to create a context from a device from  the  previous  list
207         (if any), and a context from a device from a different platform;
208
209       clCreateteContextFromType()
210         by trying to create contexts for each device type (except DEFAULT).
211
212

EXPERIMENTAL FEATURES

214       Support for OpenCL 2.x properties is not fully tested.
215
216
217       Support  for cl_khr_subgroup_named_barrier is experimental due to miss‐
218       ing definitions in the official OpenCL headers.
219
220
221       Raw (machine-parsable) output is considered  experimental,  the  output
222       format might still undergo changes.
223
224
225       The  properties of the ICD loader will also be queried if the clGetICD‐
226       LoaderInfoOCLICD extension function is found.
227
228
229       Support for the properties exposed by cl_amd_copy_buffer_p2p is experi‐
230       mental.
231
232
233       Support  for  some  (documented and undocumented) properties exposed by
234       cl_amd_device_attribute_query is experimental (see also LIMITATIONS).
235
236
237       Support for the interop lists exposed by  cl_intel_simultaneous_sharing
238       is experimental.
239
240
241       The highest OpenCL version supported by the ICD loader is detected with
242       some trivial heuristics (symbols found); a notice is output if this  is
243       lower than the highest platform OpenCL version, or if the detected ver‐
244       sion doesn't match the one declared by the ICD loader itself.
245
246

LIMITATIONS

248       OpenCL provides no explicit mean to detect the supported version of any
249       extension exposed by a device, which makes it impossible to determine a
250       priori if it will be possible to successfully query a  device  about  a
251       specific  property.   Additionally, the actual size and meaning of some
252       properties are not officially declared anywhere.
253
254
255       Most notably, this  affects  extensions  such  as  cl_amd_device_attri‐
256       bute_query,  cl_nv_device_attribute_query  and cl_arm_core_id.  Heuris‐
257       tics based on standard version support are partially used in  the  code
258       to determine which version may be supported.
259
260
261       Properties which are known to be affected by these limitations include:
262
263
264       CL_DEVICE_GLOBAL_FREE_MEMORY_AMD
265         documented in v3 of the cl_amd_device_attribute_query extension spec‐
266         ification as being the global free memory in KBytes, without any  ex‐
267         planation  given  on why there are two values, although in the source
268         code of the ROCm stack the second value is documented  as  being  the
269         largest free block;
270
271       CL_DEVICE_AVAILABLE_ASYNC_QUEUES_AMD
272         documented in v3 of the cl_amd_device_attribute_query extension spec‐
273         ification, but not reported by drivers supporting  other  v3  proper‐
274         ties.  This has now been enabled for drivers assumed to support v4 of
275         the same extension;
276
277       CL_DEVICE_TERMINATE_CAPABILITY_KHR
278         exposed by the cl_khr_terminate_context  has  changed  value  between
279         OpenCL  1.x  and 2.x, and it's allegedly a bitfield, whose values are
280         however not defined anywhere.
281
282

BUGS

284   General
285       Please  report  any  issues  on   the   project   tracker   on   GitHub
286http://github.com/Oblomov/clinfo⟩.
287
288
289   LLVM CommandLine errors
290       If multiple OpenCL platforms using shared LLVM libraries are present in
291       the system, clinfo (and other OpenCL application) may crash with errors
292       to the tune of
293
294              : CommandLine Error: Option '(some option name)' registered more than once!
295              LLVM ERROR: inconsistency in registered CommandLine options
296
297       or  similar.  This is not an issue in clinfo, or in any OpenCL platform
298       or application, but it is due to the way LLVM handles its own  command-
299       line  options  parsing.   The issue has been reported upstream as issue
300       #30587  ⟨https://bugs.llvm.org/show_bug.cgi?id=30587⟩.   See  the  next
301       point  for  possible workarounds and assistance in identifying the con‐
302       flicting platforms.
303
304
305   Segmentation faults
306       Faulty OpenCL platforms may cause segmentation faults in clinfo  during
307       the  information  gathering  phase, sometimes even before any output is
308       shown. There is very little clinfo can do to avoid  this.  If  you  see
309       this  happening,  try disabling all platforms and then re-enabling them
310       one by one until you experience the crash again.  Chances are the  last
311       platform  you  enabled is defective in some way (either by being incom‐
312       patible with other platforms or by missing necessary components and not
313       handling their absence gracefully).
314
315
316       To  selectively  enable/disable platforms, one way is to move or rename
317       the *.icd files present in /etc/OpenCL/vendors/ and then restoring them
318       one by one. When using the free-software ocl-icd OpenCL library, a sim‐
319       ilar effect can  be  achieved  by  setting  the  OPENCL_VENDOR_PATH  or
320       OCL_ICD_VENDORS  environment  variables, as documented in libOpenCL(7).
321       Other implementations of libOpenCL are  known  to  support  OPENCL_VEN‐
322       DOR_PATH too.
323
324
325       Example
326         find  /etc/OpenCL/vendors/  -name  '*.icd'  |  while read OPENCL_VEN‐
327         DOR_PATH ; do clinfo -l > /dev/null ; echo "$? ${OPENCL_VENDOR_PATH}"
328         ; done
329
330
331       This  one liner will run clinfo -l for each platform individually (hid‐
332       ing the normal output), and report the .icd path prefixed by 0 for suc‐
333       cessful runs, and a non-zero value for faulty platforms.
334
335
336
337clinfo 3.0.21.02.21               2021-02-21                         CLINFO(1)
Impressum