git.oblomov.eu Git - clinfo/blob - man1/clinfo.1

   1 .TH CLINFO 1 "2018-04-06" "clinfo 2.2.18.04.06"
   2
   3 .SH NAME
   4
   5 clinfo \- show OpenCL platforms and devices
   6
   7 .SH SYNOPSIS
   8 .B clinfo
   9 .RI [ "options ..." ]
  10
  11 .SH DESCRIPTION
  12 .B clinfo
  13 prints all available information about all OpenCL platforms
  14 available on the system and the devices they expose.
  15
  16 .SH OPTIONS
  17 .B clinfo
  18 accepts the following options:
  19 .TP 2
  20 .BR -a ", " --all-props
  21 try to retrieve all properties, even those not officially supported
  22 (e.g. because they require specific extensions), but only show them
  23 if the property could be retrieved successfully; see also the
  24 .B LIMITATIONS
  25 section below; note that even though this may reveal hidden properties,
  26 there is no guarantee that the returned values are meaningful, nor that
  27 the corresponding feature is actually available at all;
  28 .TP
  29 .BR -A ", " --always-all-props
  30 like
  31 .BR -a ,
  32 but also show errors;
  33 .TP
  34 .B --human
  35 produce human-friendly output; this is the default (except
  36 as noted below);
  37 .TP
  38 .B --raw
  39 produce machine-friendly output; this is the default if
  40 .B clinfo
  41 is invoked with a name that contains the string
  42 .RI \*(lq raw \*(rq;
  43 .TP
  44 .B --offline
  45 shows also offline devices for platforms that expose this feature;
  46 .TP
  47 .BR -l ", " --list
  48 list platforms and devices by name, with no (other) properties;
  49 .TP
  50 .BR -h ", " -?
  51 show usage;
  52 .TP
  53 .BR --version ", " -v
  54 show program version.
  55
  56 .SH CONFORMING TO
  57
  58 OpenCL 1.1, OpenCL 1.2, OpenCL 2.0, OpenCL 2.1, OpenCL 2.2.
  59
  60 .SH EXTENSIONS
  61
  62 Supported OpenCL extensions:
  63 .TP 2
  64 .BR cl_khr_fp16 ", " cl_khr_fp64 ", " cl_amd_fp64 ", " cl_APPLE_fp64_basic_ops
  65 for information about support for half-precision and double-precision
  66 floating-point data types;
  67 .TP
  68 .B cl_khr_image2d_from_buffer
  69 for information about the base address and pitch alignment requirements
  70 of buffers to be used as base for 2D images;
  71 .TP
  72 .B cl_khr_il_program
  73 for information about the supported IL (Intermediate Language) representations;
  74 .TP
  75 .B cl_khr_spir
  76 for information about the supported SPIR (Standard Portable Intermediate
  77 Representation) versions;
  78 .TP
  79 .B cl_khr_icd
  80 for the suffix of vendor extensions functions;
  81 .TP
  82 .B cl_khr_subgroup_named_barrier
  83 for the maximum number of named sub-group barriers;
  84 .TP
  85 .B cl_khr_terminate_context
  86 for the terminate capabilities for the device;
  87 .TP
  88 .B cl_ext_device_fission
  89 for device fission support in OpenCL 1.1 devices;
  90 .TP
  91 .B cl_ext_atomic_counters_32
  92 .TQ
  93 .B cl_ext_atomic_counters_64
  94 for the atomic counter extension;
  95 .TP
  96 .B cl_amd_device_attribute_query
  97 for AMD-specific device attributes;
  98 .TP
  99 .B cl_amd_object_metadata
 100 to show the maximum number of keys supported by the platform;
 101 .TP
 102 .B cl_amd_offline_devices
 103 to show offline devices exposed by the platform, if requested (see
 104 .B --offline
 105 option);
 106 .TP
 107 .B cl_amd_copy_buffer_p2p
 108 to show the number and IDs of available P2P devices;
 109 .TP
 110 .B cl_amd_svm
 111 .TQ
 112 .B cl_arm_shared_virtual_memory
 113 for Shared Virtual Memory (SVM) capabilities in OpenCL 1.2 devices;
 114 .TP
 115 .B cl_arm_core_id
 116 to show the (potentially sparse) list of the core IDs that the device may
 117 return;
 118 .TP
 119 .B cl_nv_device_attribute_query
 120 for NVIDIA-specific device attributes;
 121 .TP
 122 .B cl_intel_exec_by_local_thread
 123 for the Intel extension allowing CPU devices to run kernels as part of
 124 the current host thread;
 125 .TP
 126 .B cl_intel_advanced_motion_estimation
 127 for the version of the Intel Motion Estimation accelerator version;
 128 .TP
 129 .B cl_intel_device_side_avc_motion_estimation
 130 for the version and supported features of Intel's device-side AVC Motion;
 131 .TP
 132 .B cl_intel_planar_yuv
 133 for the maximum dimensions of planar YUV images;
 134 .TP
 135 .B cl_intel_simultaneous_sharing
 136 for simultaneous CL/GL/DirectX context sharing (only partial support);
 137 .TP
 138 .B cl_intel_required_subgroup_size
 139 to enumerate allowed sub-group sizes;
 140 .TP
 141 .B cl_altera_device_temperature
 142 for the Altera extension to query the core temperature of the device;
 143 .TP
 144 .B cl_qcom_ext_host_ptr
 145 for the QUALCOMM extension to query page size and required padding in external
 146 memory allocation.
 147
 148 .SH NOTES
 149 Some information is duplicated when available from multiple sources.
 150 Examples:
 151 .IP \(bu 2
 152 supported device partition types and domains as obtained using the
 153 .B cl_ext_device_fission
 154 extension typically match the ones obtained using
 155 the core OpenCL 1.2 device partition feature;
 156 .IP \(bu
 157 the preferred work-group size multiple matches the NVIDIA warp size (on
 158 NVIDIA devices) or the AMD wavefront width (on AMD devices).
 159
 160 .P
 161 Some floating-point configuration flags may only be meaningful for
 162 specific precisions and/or specific OpenCL versions. For example,
 163 .B CL_FP_CORRECTLY_ROUNDED_DIVIDE_SQRT
 164 is only relevant for single precision in OpenCL 1.2 devices.
 165
 166 .P
 167 The implementation-defined behavior for NULL platform or context
 168 properties is tested for the following API calls:
 169 .TP 2
 170 .B clGetPlatformInfo()
 171 by trying to show the platform name;
 172 .TP
 173 .B clGetDeviceIDs()
 174 by trying to enumerate devices; the corresponding platform (if any)
 175 is then detected by querying the device platform of the first device;
 176 .TP
 177 .B clCreateteContext()
 178 by trying to create a context from a device from the previous
 179 list (if any), and a context from a device from a different platform;
 180 .TP
 181 .B clCreateteContextFromType()
 182 by trying to create contexts for each device type (except DEFAULT).
 183
 184 .SH EXPERIMENTAL FEATURES
 185 .P
 186 Support for OpenCL 2.x properties is not fully tested.
 187
 188 .P
 189 Support for
 190 .B cl_khr_subgroup_named_barrier
 191 is experimental due to missing definitions in the official OpenCL headers.
 192
 193 .P
 194 Raw (machine-parsable) output is considered experimental, the output format
 195 might still undergo changes.
 196
 197 .P
 198 The properties of the ICD loader will also be queried if the
 199 .B clGetICDLoaderInfoOCLICD
 200 extension function is found.
 201
 202 .P
 203 Support for the properties exposed by
 204 .B cl_amd_copy_buffer_p2p
 205 is experimental.
 206
 207 .P
 208 Support for some (documented and undocumented) properties exposed by
 209 .B cl_amd_device_attribute_query
 210 is experimental (see also
 211 .BR LIMITATIONS ).
 212
 213 .P
 214 Support for the interop lists exposed by
 215 .B cl_intel_simultaneous_sharing
 216 is experimental.
 217
 218 .P
 219 The highest OpenCL version supported by the ICD loader is detected
 220 with some trivial heuristics (symbols found); a notice is output
 221 if this is lower than the highest platform OpenCL version, or
 222 if the detected version doesn't match the one declared by the ICD
 223 loader itself.
 224
 225 .SH LIMITATIONS
 226
 227 .P
 228 OpenCL provides no explicit mean to detect the supported version
 229 of any extension exposed by a device, which makes it impossible to
 230 determine a priori if it will be possible to successfully query
 231 a device about a specific property.
 232 Additionally, the actual size and meaning of some properties are not
 233 officially declared anywhere.
 234
 235 .P
 236 Most notably, this affects extensions such as
 237 .BR cl_amd_device_attribute_query ,
 238 .B cl_nv_device_attribute_query
 239 and
 240 .BR cl_arm_core_id .
 241 Heuristics based on standard version support are partially used in the code to
 242 determine which version may be supported.
 243
 244 .P
 245 Properties which are known to be affected by these limitations include:
 246
 247 .TP 2
 248 .B CL_DEVICE_GLOBAL_FREE_MEMORY_AMD
 249 documented in v3 of the
 250 .B cl_amd_device_attribute_query
 251 extension specification as being the global free memory in KBytes, without
 252 any explanation given on why there are two values;
 253 .TP
 254 .B CL_DEVICE_AVAILABLE_ASYNC_QUEUES_AMD
 255 documented in v3 of the
 256 .B cl_amd_device_attribute_query
 257 extension specification, but not reported by drivers supporting other v3
 258 properties. This has now been enabled for drivers
 259 .I assumed
 260 to support v4 of the same extension;
 261 .TP
 262 .B CL_DEVICE_TERMINATE_CAPABILITY_KHR
 263 exposed by the
 264 .B cl_khr_terminate_context
 265 has changed value between OpenCL 1.x and 2.x, and it's
 266 .I allegedly
 267 a bitfield, whose values are however not defined anywhere.
 268
 269 .SH BUGS
 270
 271 .SS General
 272
 273 .P
 274 Please report any issues on
 275 .UR http://github.com/Oblomov/clinfo
 276 the project tracker on GitHub
 277 .UE .
 278
 279 .SS Segmentation faults
 280
 281 .P
 282 Faulty OpenCL platforms may cause segmentation faults in
 283 .B clinfo
 284 during the information gathering phase, sometimes even
 285 before any output is shown. There is very little
 286 .B clinfo
 287 can do to avoid this. If you see this happening,
 288 try disabling all platforms and then re-enabling
 289 them one by one until you experience the crash again.
 290 Chances are the last platform you enabled is defective
 291 in some way (either by being incompatible with other
 292 platforms or by missing necessary components and
 293 not handling their absence gracefully).
 294
 295 .P
 296 To selectively enable/disable platforms, one
 297 way is to move or rename the
 298 .I *.icd
 299 files present in
 300 .I /etc/OpenCL/vendors/
 301 and then restoring them one by one. When using
 302 the free-software
 303 .B ocl-icd
 304 OpenCL library, a similar effect can be achieved
 305 by setting the
 306 .B OPENCL_VENDOR_PATH
 307 or
 308 .B OCL_ICD_VENDORS
 309 environment variables, as documented in
 310 .BR libOpenCL (7).
 311 Other implementations of
 312 .B libOpenCL
 313 are known to support
 314 .B OPENCL_VENDOR_PATH
 315 too.
 316
 317 .TP 2
 318 .B Example
 319 find /etc/OpenCL/vendors/ -name '*.icd' | while read OPENCL_VENDOR_PATH ; do clinfo -l > /dev/null ; echo "$? ${OPENCL_VENDOR_PATH}" ; done
 320
 321 .P
 322 This one liner will run
 323 .B clinfo -l
 324 for each platform individually (hiding the normal output),
 325 and report the
 326 .I .icd
 327 path prefixed by
 328 .B 0
 329 for successfull runs, and a non-zero value for faulty
 330 platforms.