========
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 SPIR. This is
a side-project is being undertaken by James Price (a PhD student 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 a version of Clang that is
capable of generating SPIR. The Khronos working group has made a
patched version of Clang 3.2 that can generate SPIR available on
GitHub:

    https://github.com/KhronosGroup/SPIR

Follow the instructions in the README.md file in that repository to
build the Clang/SPIR generator. To improve the performance of
Oclgrind, it is recommended to build for release mode (i.e. set
CMAKE_BUILD_TYPE to RelWithDebInfo).


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 Clang/SPIR generator includes and libraries on your
search path, you can specify the location of the generator using the
--with-spir=PATH option. For example:

./configure --prefix=$PWD/build/ --with-spir=PATH/TO/CLANG/SPIR/INSTALL

This path should be the directory in which the Clang/SPIR generator is
installed (e.g. the path specified to --prefix or CMAKE_INSTALL_PATH).

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 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 will be prompted to supply a
value for the SPIR_ROOT parameter. This should be set to the root
directory of the Clang/SPIR generator installation, (for example
C:\Program Files\LLVM).

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 read of size 4 at global memory address 1000000000040
>         Work-item:  Global(16,0,0) Local(0,0,0)
>         Work-group: (16,0,0)
>         Kernel:     vecadd
>         %tmp8 = load float addrspace(1)* %tmp7, align 4, !dbg !47
>         At line 16 of input.cl

Since it is interpreting an abstract intermediate representation and
bounds-checking each memory access, Oclgrind will run very slowly
(typically a few orders of magnitude slower than a regular CPU
implementation). Therefore, it is recommended to run 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 developer via email:
James Price <j.price@bristol.ac.uk>