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
The project depends on the following external libaries:
- libdrm libraries (libdrm and libdrm_intel)
- Various LLVM components
- If run with X server, beignet needs XLib, Xfixes and Xext installed. Otherwise, no X11 dependency.
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):
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.
A simple command to install all the above dependencies for ubuntu or debian is:
sudo apt-get install cmake pkg-config python ocl-icd-dev
ocl-icd-opencl-dev libdrm-dev libxfixes-dev libxext-dev llvm-3.5-dev
clang-3.5 libclang-3.5-dev libtinfo-dev libedit-dev zlib1g-dev
The recommended LLVM/CLANG version is 3.5 and/or 3.6. Based on our test result, LLVM 3.5 has best pass rate on all the test suites. Compare to LLVM 3.5, LLVM 3.6 has slightly lower pass rate(caused by one front end bug at clang 3.6) but has better performance (3% to 5% up).
For LLVM 3.3 and 3.4, Beignet still support them, but it may be limited to support the build and major functions.
How to build and install
The project uses CMake with three profiles:
- Debug (-g)
- RelWithDebInfo (-g with optimizations)
- Release (only optimizations)
Basically, from the root directory of the project
> mkdir build
> cd build
> cmake ../ # to configure
Please be noted that the code was compiled on GCC 4.6, GCC 4.7 and GCC 4.8 and CLANG 3.5 and ICC 14.0.3. Since the code uses really recent C++11 features, you may expect problems with older compilers. The default compiler should be GCC, and if you want to choose compiler manually, you need to configure it as below:
> cmake -DCOMPILER=[GCC|CLANG|ICC] ../
CMake will check the dependencies and will complain if it does not find them.
The cmake will build the backend firstly. Please refer to: OpenCL Gen 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
> make install
It installs the following six files to the beignet/ directory relatively to your library installation directory. - libcl.so - libgbeinterp.so - libgbe.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
After build and install of beignet, you may need to check whether it works on your platform. Beignet 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
will run all the unit tests one after the others
> ./utest_run some_unit_test0 some_unit_test1
will only run
On all supported target platform, the pass rate should be 100%. If it is not, you may
need to refer the "Known Issues" section. Please be noted, the
. setenv.sh is only
required to run unit test cases. For all other OpenCL applications, don't execute that
Normally, beignet needs to run under X server environment as normal user. If there isn't X server, beignet provides two alternative to run: * Run as root without X. * Enable the drm render nodes by passing drm.rnodes=1 to the kernel boot args, then you can run beignet with non-root and without X.
- 3rd Generation Intel Core Processors
- Intel “Bay Trail” platforms with Intel HD Graphics
- 4th Generation Intel Core Processors "Haswell", need kernel patch currently, see the "Known Issues" section.
- 5th Generation Intel Core Processors "Broadwell".
GPU hang issues. To check whether GPU hang, you could execute dmesg and check whether it has the following message:
[17909.175965] [drm:i915_hangcheck_hung] *ERROR* Hangcheck timer elapsed...
If it does, there was a GPU hang. Usually, this means something wrong in the kernel, as it indicates the OCL kernel hasn't finished for about 6 seconds or even more. If you think the OCL kernel does need to run that long and have confidence with the kernel, you could disable the linux kernel driver's hang check feature to fix this hang issue. Just 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 really hang, then the gpu will lock up forever until a reboot.
This can be fixed by upgrading Linux, or by disabling the whitelist:
# echo 0 > /sys/module/i915/parameters/enable_cmd_parser
On Haswell hardware, Beignet 1.0.1 to 1.0.3 also required the above workaround on later Linux versions, but this should not be required in current (after 83f8739) git master.
"Beignet: self-test failed" and 15-30 unit tests fail on 4th Generation (Haswell) hardware. On Haswell, shared local memory (__local) does not work at all on Linux <= 4.0, and requires the i915.enable_ppgtt=2 boot parameter on Linux 4.1.
This will be fixed in Linux 4.2; older versions can be fixed with this patch.
If you do not need __local, you can override the self-test with
but using __local after this may silently give wrong results.
Precision issue. Currently Gen does not provide native support of high precision math functions required by OpenCL. We provide a software version to achieve high precision, which you can turn on through
# export OCL_STRICT_CONFORMANCE=1.
But be careful, this would make your CL kernel run a little longer.
cl_khr_gl_sharing. This extension 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. This feature used to work with a previous mesa git version. But now, it's simply broken.
Illegal pointer issue. If you met the following error message:
Illegal pointer which is not from a valid memory space.
That means the computing kernel is running into an unsupported feature which is to store/load pointers to/from memory. As we know, this feature has been used in Luxmark 3.0 and maybe the latest BOINC. Beignet could support them currently. We plan to fix it in next major release 1.1.0.
In terms of the OpenCL 1.2 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 which is about 99%. There are still some remains work items listed as below, most of them are extension support and performance related.
Performance tuning. There are some major optimizations need to be done, Peephole optimization, futher tuning the structurized BB transformation to support more pattern such as self loop/while loop. And optimize the 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.
Complete cl_khr_gl_sharing support. We lack of some APIs implementation such as clCreateFromGLBuffer,clCreateFromGLRenderbuffer,clGetGLObjectInfo... Currently, the working APIs are clCreateFromGLTexture,clCreateFromGLTexture2D. We may need to find a graceful way to co-work with mesa.
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.
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)
Beignet project was created by Ben Segovia. Since 2013, Now Intel China OTC graphics
team continue to work on this project. The official contact for this project is:
Zou Nanhai (firstname.lastname@example.org).
Maintainers from Intel:
- Gong, Zhigang
- Yang, Rong
Developers from Intel:
- Song, Ruiling
- He, Junyan
- Luo, Xionghu
- Wen, Chuanbo
- Guo, Yejun
- Lv, Meng
- Rebecca Palmer
- Igor Gnatenko
If I missed any other package maintainers, please feel free to contact the mail list.
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:
The official bugzilla is at: https://bugs.freedesktop.org/enter_bug.cgi?product=Beignet
You are welcome to submit beignet bug. Please be noted, please specify the exact platform information, such as BYT/IVB/HSW/BDW, and GT1/GT2/GT3. You can easily get this information by running the beignet's unit test.
Documents for OpenCL application developers
The wiki URL is as below: http://www.freedesktop.org/wiki/Software/Beignet/