OpenCL 1.1 Software Implementation

Clover is a project started in June 2011 as a Google Summer of Code project. Its goal is to provide an Open Source OpenCL implementation usable by everyone wanting to use or develop for OpenCL without having to use proprietary drivers or SDKs (like the Intel's one).

Clover currently only supports running OpenCL programs in software, on the host CPU, but an interface is there to allow future hardware-based execution engines.

This documentation is meant to be a developer focused one. The public OpenCL API is thoroughly documented by the Khronos Group at http://www.khronos.org/registry/cl/ . What is documented here is the internal architecture of Clover.

Discovering Clover

Clover is a somewhat big project and this section will explain how to get started with the code.

Components

Clover is split in several components:

• core The core of OpenCL, implemented in C++ and containing all the logic used by an OpenCL implementation.
• api The public OpenCL API. It's a binding exposing the Clover's C++ classes to C applications.
• runtime The standard library available to OpenCL programs. An interesting and advanced page speaks about Implementing barriers.

The following components are also present but currently not documented:

• tests Check-based test-cases
• examples Currently one small application playing with clGetXXXInfo functions, thus displaying information about Clover (it can also be used with any compliant OpenCL implementation)

Flow of execution

Discovering and reading a source code may be done in an order close to the "execution flow" of an application using this code. For Clover, it means that it's easier to explore the functions when reading them roughly in the order they get called by a client application.

Here is the recommended order in which to read the functions:

• A small self-contained API is used to get information about the "Platform", in src/api/api_platform.cpp
• Then, the platform is used to query the devices, in src/api/api_devices.cpp . This is the first API file that uses C++ classes. The hardware abstraction layer used is Coal::DeviceInterface. Take a look at the Coal::CPUDevice class, implementing this interface, in src/core/cpu/device.cpp .
• The device is then used to create a Coal::Context, in src/api/api_context.cpp then src/core/context.cpp .
• When a context is built, one can use it to do many thing. For example, it's possible to create buffer objects. Take a look at clCreateBuffer(), and the Coal::Buffer and Coal::CPUBuffer classes.
• A big part of Clover is dedicated to command queues, implemented in the Coal::CommandQueue class. Its special architecture is documented in detail in the Command Queues, Events and Worker Threads page.
• There is also the Coal::Program class, that compiles OpenCL C code into LLVM IR using Coal::Compiler (a simple wrapper around Clang).
• A program contains one or more kernels. Take a look at Coal::Kernel for how they are handled.
• Coal::Program and Coal::Kernel are device-independent classes. They use device-specific classes like Coal::CPUProgram and Coal::CPUKernel. The former translates LLVM IR instructions into machine code using the LLVM's JIT, the latter is a bit more complex and described in the Using Clang and LLVM to Launch Kernels page.