Beignet

Beignet is an open source implementation of the OpenCL specification - a generic compute oriented API. This code base contains the code to run OpenCL programs on Intel GPUs which basically defines and implements the OpenCL host functions required to initialize the device, create the command queues, the kernels and the programs and run them on the GPU. The code base also contains the compiler part of the stack which is included in backend/. For more specific information about the compiler, please refer to backend/README.md

Prerequisite

The project depends on the following external libaries:

• Several X components (XLib, Xfixes, Xext)
• libdrm libraries (libdrm and libdrm_intel)
• Various LLVM components
• The compiler backend itself (libgbe)
• Mesa git master version built with gbm enabled to support extension cl_khr_gl_sharing.

And if you want to work with the standard ICD libOpenCL.so, then you need two more packages (the following package name is for Ubuntu):

• ocl-icd-dev
• ocl-icd-libopencl1

If you don't want to enable ICD, or your system doesn't have ICD OpenCL support, you can still link to the beignet OpenCL library. You can find the beignet/libcl.so in your system's library installation directories.

Note that the compiler depends on LLVM (Low-Level Virtual Machine project). Right now, the code has been compiled with LLVM 3.3/3.4. It will not compile with anything older.

http://llvm.org/releases/

LLVM 3.3 , 3.4 and 3.5 are supported. Till now, the recommended LLVM version is 3.3. There are some severe OpenCL related regression in current clang 3.4/3.5 version.

Note about LLVM 3.4

• If you want to try Clang/LLVM 3.4, you need to disable terminfo: --disable-terminfo. It's a llvm 3.4 bug.

Note about LLVM 3.5

• If you want to try Clang/LLVM 3.5, you need to build the clang/llvm with cxx11 enabled: --enable-cxx11.

Note about OpenCV support

• We only fully tested the OpenCV 2.4 branch with beignet. And the pass rate is about 99% for beignet 0.8.0. The preferred LLVM/Clang version is 3.3. One OpenCV patch is needed to work with LLVM/clang, the patch is already submitted to the OpenCV upstream 2.4 repo and is waiting for review: pull request. Before it is merged, you need to apply that patch manually to OpenCV 2.4 branch.

• As some OpenCL kerne (in OpenCV 2.4 OCL test suite) runs more than 10 seconds, it may be reset by the kernel as the kernel has a GPU hangcheck mechanism. You can disable the hangcheck by invoke the following command on Ubuntu system:

  # echo -n 0 > /sys/module/i915/parameters/enable_hangcheck

  But this command is a little bit dangerous, as if your kernel hang, then the gpu will hang forever.

• For the OpenCV 3.0 branch, the pass rate may a little bit lower than the 2.4 branch.

Also note that the code was compiled on GCC 4.6, GCC 4.7 and GCC 4.8. Since the code uses really recent C++11 features, you may expect problems with older compilers. Last time I tried, the code breaks ICC 12 and Clang with internal compiler errors while compiling anonymous nested lambda functions.

How to build and install

The project uses CMake with three profiles:

1. Debug (-g)
2. RelWithDebInfo (-g with optimizations)
3. Release (only optimizations)

Basically, from the root directory of the project

> mkdir build

> cd build

> cmake ../ # to configure

CMake will check the dependencies and will complain if it does not find them.

> make

The cmake will build the backend firstly. Please refer to: [[OpenCL Gen Backend|Beignet/Backend]] to get more dependencies.

Once built, the run-time produces a shared object libcl.so which basically directly implements the OpenCL API. A set of tests are also produced. They may be found in utests/.

Simply invoke: > make install

It installs the following three files to the beignet/ directory relatively to your library installation directory.

• libcl.so
• ocl_stdlib.h, ocl_stdlib.h.pch
• beignet.bc

It installs the OCL icd vendor files to /etc/OpenCL/vendors, if the system support ICD.

• intel-beignet.icd

How to run

Apart from the OpenCL library itself that can be used by any OpenCL application, this code also produces various tests to ensure the compiler and the run-time consistency. This small test framework uses a simple c++ registration system to register all the unit tests.

You need to call setenv.sh in the utests/ directory to set some environment variables firstly as below:

> . setenv.sh

Then in utests/:

> ./utest_run

will run all the unit tests one after the others

> ./utest_run some_unit_test0 some_unit_test1

will only run some_unit_test0 and some_unit_test1 tests

Supported Hardware

The code was tested on IVB GT2 with ubuntu and fedora core distribution. The recommended kernel version is equal or newer than 3.11. Currently Only IVB is supported right now. Actually, the code was run on IVB GT2/GT1, and both system are well supported now.

TODO

Interns of the OpenCL 1.1 spec, beignet is quite complete now. We can pass almost all the piglit OpenCL test cases now. And the pass rate for the OpenCV test suite is also good. There are still some remains work items listed as below, most of them are extension support and performance related.

• Performance tuning. Till now, the focus of beignet project is to implement all the mandatory functions/features specified by the OpenCL spec. There are plenty of things need to do for performance tuning. For example, the extreme slow software based sin/cos/... math functions due to the native math instruction lack of necessary precision. And all the code is inlined which will increase the icache miss rate significantly. And many other things which are specified partially in [[here|Beignet/Backend/TODO]]. We will focus on performance tuning after the version 0.8.

• Complete cl_khr_gl_sharing support. We lack of some APIs implementation such as clCreateFromGLBuffer,clCreateFromGLRenderbuffer,clGetGLObjectInfo... Currently, the working APIs are clCreateFromGLTexture,clCreateFromGLTexture2D. This work highly depends on mesa support. It seems that mesa would not provide such type of extensions, we may have to hack with mesa source code to support this extension.

• Check that NDRangeKernels can be pushed into different queues from several threads.

• No state tracking at all. One batch buffer is created at each "draw call" (i.e. for each NDRangeKernels). This is really inefficient since some expensive pipe controls are issued for each batch buffer.

• Valgrind reports some leaks in libdrm. It sounds like a false positive but it has to be checked. Idem for LLVM. There is one leak here to check.

More generally, everything in the run-time that triggers the "FATAL" macro means that something that must be supported is not implemented properly (either it does not comply with the standard or it is just missing)

Project repository

Right now, we host our project on fdo at: http://cgit.freedesktop.org/beignet/. And the intel 01.org: https://01.org/beignet

The team

Beignet project was created by Ben Segovia. Since 2013, Now we have a team in Intel China OTC graphics team continue to work on this project. The official contact for this project is: Zou Nanhai (nanhai.zou@intel.com).

How to contribute

You are always welcome to contribute to this project, just need to subscribe to the beignet mail list and send patches to it for review. The official mail list is as below: http://lists.freedesktop.org/mailman/listinfo/beignet

The wiki url is as below: http://www.freedesktop.org/wiki/Software/Beignet/