========
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>