======== Oclgrind ======== About ----- This project implements a virtual OpenCL device simulator, including an OpenCL runtime with ICD support. The goal is to provide a platform for creating tools to aid OpenCL development. In particular, this project currently implements utilities for debugging memory access errors, detecting data-races and barrier divergence, collecting instruction histograms, and for interactive OpenCL kernel debugging. The simulator is built on an interpreter for LLVM IR. This project is being developed by James Price and Simon McIntosh-Smith at the University of Bristol. Binary releases can be found on the GitHub releases page: https://github.com/jrprice/Oclgrind/releases Building -------- To build this project, you will require the LLVM and Clang 3.6 development libraries and headers. With some modifications, it may also be possible to use other (recent) versions of LLVM. If building LLVM from source, it is recommended to enable optimizations to improve the performance of Oclgrind (configure with --enable-optimized, or set CMAKE_BUILD_TYPE to RelWithDebInfo). You will also need to use a compiler that supports C++11. Building on Linux and OS X -------------------------- If you are building directly from the GitHub repository, you need to run 'autoreconf -i' to generate the necessary build files. This is not required if you are using a released source package. Run ./configure to generate the Makefile, optionally using --prefix=PATH to specify the target installation directory. If you don't have the LLVM/Clang includes and libraries on your search path, you can specify the location of your LLVM installation using the --with-llvm=PATH option. For example: ./configure --prefix=$PWD/build/ --with-llvm=PATH/TO/LLVM/INSTALL This path should be the directory in which LLVM is installed (e.g. the path specified to --prefix or CMAKE_INSTALL_PATH when LLVM was built). Next, build and install with make: make make check make install If installing to a non-default location, you should add the bin/ directory to the PATH environment variable in order to make use of the oclgrind command. If you wish to use Oclgrind via the OpenCL ICD (optional), then you should create an ICD loading point by copying the oclgrind.icd file from the build directory to /etc/OpenCL/vendors/. Building on Windows ------------------- A CMake build system is provided for building Oclgrind on Windows. At present, this only works with Visual Studio 2013 (or newer), and Windows 7. When configuring the CMake build, you may be prompted to supply a value for the LLVM_DIR parameter. This should be set to the directory containing your LLVM installations's LLVMConfig.cmake file, (for example C:\Program Files\LLVM\share\llvm\cmake\). If you wish to use Oclgrind via the OpenCL ICD (optional), then you should also create an ICD loading point. To do this, you should add a REG_DWORD value to the Windows Registry under one or both of the registry keys below, with the name set to the absolute path of the oclgrind-rt-icd.dll library and the value set to 0. Key for 32-bit machines or 64-bit apps on a 64-bit machine: HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors Key for 32-bit apps on a 64-bit machine: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Khronos\OpenCL\Vendors Usage ----- The recommended method of running an application with Oclgrind is to use the oclgrind command, for example: oclgrind ./application This command will make it such the only OpenCL platform and device available to your application is Oclgrind. If you need more control over platform selection then installing an ICD loading point for Oclgrind will cause it to appear when an application calls clGetPlatformIDs(), alongside any other OpenCL platforms installed on your system. If it encounters any invalid memory accesses, Oclgrind will report the details to stderr, for example: > Invalid write of size 4 at global memory address 0x1000000000040 > Kernel: vecadd > Entity: Global(16,0,0) Local(0,0,0) Group(16,0,0) > store i32 %tmp9, i32 addrspace(1)* %tmp15, align 4 > At line 4 of input.cl > c[i] = a[i] + b[i] Since it is interpreting an abstract intermediate representation and bounds-checking each memory access, Oclgrind will run quite slowly (typically a couple of orders of magnitude slower than a regular CPU implementation). Therefore, it is recommended to run your application with a small problem if possible. To enable an interactive, GDB-style debugging session, supply the -i flag to the oclgrind command, or export the environment variable OCLGRIND_INTERACTIVE=1. This will cause Oclgrind to automatically break at the beginning of each kernel invocation, and upon encountering an invalid memory access. Type 'help' for details of available commands. For more detailed information about using Oclgrind please visit the GitHub Wiki: https://github.com/jrprice/Oclgrind/wiki/ Contact ------- If you encounter any issues or have any questions, please use the GitHub issues page: https://github.com/jrprice/Oclgrind/issues You can also contact the primary developer via email: James Price <j.price@bristol.ac.uk>