git.oblomov.eu Git - clinfo/blob - README.md

   1 # What is this?
   2
   3 clinfo is a simple command-line application that enumerates all possible
   4 (known) properties of the OpenCL platform and devices available on the
   5 system.
   6
   7 Inspired by AMD's program of the same name, it is coded in pure C and it
   8 tries to output all possible information, including those provided by
   9 platform-specific extensions, trying not to crash on unsupported
  10 properties (e.g. 1.2 properties on 1.1 platforms).
  11
  12 # Usage
  13
  14     clinfo [options...]
  15
  16 Common used options are `-l` to show a synthetic summary of the
  17 available devices (without properties), and `-a`, to try and show
  18 properties even if `clinfo` would otherwise think they aren't supported
  19 by the platform or device.
  20
  21 Refer to the man page for further information.
  22
  23 ## Use cases
  24
  25 * verify that your OpenCL environment is set up correctly;
  26   if `clinfo` cannot find any platform or devices (or fails to load
  27   the OpenCL dispatcher library), chances are high no other OpenCL
  28   application will run;
  29 * verify that your OpenCL _development_ environment is set up
  30   correctly: if `clinfo` fails to build, chances are high no
  31   other OpenCL application will build;
  32 * explore/report the actual properties of the available device(s).
  33
  34 ## Segmentation faults
  35
  36 Some faulty OpenCL platforms may cause `clinfo` to crash. There isn't
  37 much `clinfo` itself can do about it, but you can try and isolate the
  38 platform responsible for this. On POSIX systems, you can generally find
  39 the platform responsible for the fault with the following one-liner:
  40
  41     find /etc/OpenCL/vendors/ -name '*.icd' | while read OPENCL_VENDOR_PATH ; do clinfo -l > /dev/null ; echo "$? ${OPENCL_VENDOR_PATH}" ; done
  42
  43 ## Missing information
  44
  45 If you know of device properties that are exposed in OpenCL (either as core
  46 properties or as extensions), but are not shown by `clinfo`, please [open
  47 an issue](https://github.com/Oblomov/clinfo/issues) providing as much
  48 information as you can. Patches and pull requests accepted too.
  49
  50
  51 # Building
  52
  53 <img
  54 src='https://api.travis-ci.org/Oblomov/clinfo.svg?branch=master'
  55 alt='Build status on Travis'
  56 style='float: right'>
  57
  58 Building requires an OpenCL SDK (or at least OpenCL headers and
  59 development files), and the standard build environment for the platform.
  60 No special build system is used (autotools, CMake, meson, ninja, etc),
  61 as I feel adding more dependencies for such a simple program would be
  62 excessive. Simply running `make` at the project root should work.
  63
  64 ## Android support
  65
  66 ### Local build via Termux
  67
  68 One way to build the application on Android, pioneered by
  69 [truboxl][truboxl] and described [here][issue46], requires the
  70 installation of [Termux][termux], that can be installed via Google Play
  71 as well as via F-Droid.
  72
  73 [truboxl]: https://github.com/truboxl
  74 [issue46]: https://github.com/Oblomov/clinfo/issues/46
  75 [termux]: https://termux.com/
  76
  77 Inside Termux, you will first need to install some common tools:
  78
  79         pkg install git make clang -y
  80
  81
  82 You will also need to clone the `clinfo` repository, and fetch the
  83 OpenCL headers (we'll use the official `KhronosGroup/OpenCL-Headers`
  84 repository for that):
  85
  86         git clone https://github.com/Oblomov/clinfo
  87         git clone https://github.com/KhronosGroup/OpenCL-Headers
  88
  89 (I prefer doing this from a `src` directory I have created for
  90 development, but as long as `clinfo` and `OpenCL-Headers` are sibling
  91 directories, the headers will be found. If not, you will have to
  92 override `CPPFLAGS` with e.g. `export CPPFLAGS=-I/path/to/where/headers/are`
  93 before running `make`.
  94 Of course `/path/to/where/headers/are` should be replaced with the actual
  95 path to which the `OpenCL-Headers` repository was cloned.)
  96
  97 You can then `cd clinfo` and build the application. You can try simply
  98 running `make` since Android should be autodetected now, buf it
  99 this fails you can also force the detectio with
 100
 101         make OS=Android
 102
 103 If linking fails due to a missing `libOpenCL.so`, then your Android
 104 machine probably doesn't support OpenCL. Otherwise, you should have a
 105 working `clinfo` you can run. You will most probably need to set
 106 `LD_LIBRARY_PATH` to let the program know where the OpenCL library is at
 107 runtime: you will need at least `${ANDROID_ROOT}/vendor/lib64`, but on
 108 some machine the OpenCL library actually maps to a different library
 109 (e.g., on one of my systems, it maps to the GLES library, which is in a
 110 different subdirectory).
 111
 112 Due to this requirement, on Android the actual binary is now called
 113 `clinfo.real`, and the produced `clinfo` is just a shell script that
 114 will run the actual binary after setting `LD_LIBRARY_PATH`. If this
 115 is not sufficient on your installation, please open an issue and we'll
 116 try to improve the shell script to cover your use case as well.
 117
 118 ## Windows support
 119
 120 The application can usually be built in Windows too (support for which
 121 required way more time than I should have spent, really, but I digress),
 122 by running `make` in a Developer Command Prompt for Visual Studio,
 123 provided an OpenCL SDK (such as the Intel or AMD one) is installed.
 124
 125 Precompiled Windows executable are available as artefacts of the
 126 AppVeyor CI.
 127
 128 <table style='margin: 1em auto; width: 100%; max-width: 33em'>
 129 <tr><th>Build status</th><th colspan=2>Windows binaries</th></tr>
 130 <tr>
 131 <td><a href='https://ci.appveyor.com/project/Oblomov/clinfo/'><img
 132 src='https://ci.appveyor.com/api/projects/status/github/Oblomov/clinfo?svg=true'
 133 alt='Build status on AppVeyor'></a></td>
 134 <td><a href='https://ci.appveyor.com/api/projects/oblomov/clinfo/artifacts/clinfo.exe?job=platform%3a+x86'>32-bit</a></td>
 135 <td><a href='https://ci.appveyor.com/api/projects/oblomov/clinfo/artifacts/clinfo.exe?job=platform%3a+x64'>64-bit</a></td>
 136 </tr>
 137 </table>