diff options
1 files changed, 58 insertions, 89 deletions
diff --git a/Software/Beignet.mdwn b/Software/Beignet.mdwn
index 710fc982..f29b4e6d 100644
--- a/Software/Beignet.mdwn
+++ b/Software/Beignet.mdwn
@@ -32,24 +32,29 @@ 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/
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.
+Note that the compiler depends on LLVM (Low-Level Virtual Machine project), and the
+project normally support 3 latest LLVM released version.
+Right now, the code has been compiled with LLVM 3.6, 3.7 and 3.8. With older
+version LLVM from 3.3, build still support, but no full tests cover.
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`
+`sudo apt-get install cmake pkg-config python ocl-icd-dev libegl1-mesa-dev`
+` ocl-icd-opencl-dev libdrm-dev libxfixes-dev libxext-dev llvm-3.6-dev`
+` clang-3.6 libclang-3.6-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
+**The recommended LLVM/CLANG version is 3.6 and/or 3.7**
+Based on our test result, LLVM 3.6 and 3.7 has best pass rate on all the test suites. Compare
+to LLVM 3.6 and 3.7, if you used LLVM 3.8, you should pay attention to float immediate. For example,
+if you use 1.0 in the kernel, LLVM 3.6 will treate it as 1.0f, a single float, because the project
+don't support double float. but LLVM 3.8 will treate it as 1.0, a double foat, at the last it may cause
+error. So we recommend use 1.0f instead of 1.0 if you don't need double float.
+For LLVM 3.4 and 3.5, Beignet still support them, but it may be limited to support the
build and major functions.
How to build and install
@@ -84,8 +89,11 @@ 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 which basically
-directly implements the OpenCL API. A set of tests are also produced. They may
-be found in `utests/`.
+directly implements the OpenCL API.
+`> make`
+A set of tests are also produced. They may be found in `utests/`.
Simply invoke:
@@ -102,6 +110,10 @@ your library installation directory.
It installs the OCL icd vendor files to /etc/OpenCL/vendors, if the system support ICD.
- intel-beignet.icd
+`> make package`
+It packages the driver binaries, you may copy&install the package to another machine with simillar system.
How to run
@@ -121,9 +133,9 @@ Then in `utests/`:
will run all the unit tests one after the others
-`> ./utest_run some_unit_test0 some_unit_test1`
+`> ./utest_run some_unit_test`
-will only run `some_unit_test0` and `some_unit_test1` tests
+will only run `some_unit_test` test.
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 `.` is only
@@ -138,10 +150,13 @@ beignet provides two alternative to run:
Supported Targets
- * 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.
+ * 3rd Generation Intel Core Processors "Ivybridge".
+ * 3rd Generation Intel Atom Processors "BayTrail".
+ * 4th Generation Intel Core Processors "Haswell", need kernel patch if your linux kernel older than 4.2, see the "Known Issues" section.
* 5th Generation Intel Core Processors "Broadwell".
+ * 5th Generation Intel Atom Processors "Braswell".
+ * 6th Generation Intel Core Processors "Skylake" and "Kabylake".
+ * 5th Generation Intel Atom Processors "Broxten" or "Apollolake".
Known Issues
@@ -166,38 +181,33 @@ Known Issues
to [c9224fa](
enable the register whitelist by default but miss some registers needed
for Beignet.
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 is 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
+ which you can turn off through
- But be careful, this would make your CL kernel run a little longer.
+ This would lost some precision but gain performance.
* cl\_khr\_gl\_sharing.
This extension highly depends on mesa support. It seems that mesa would not provide
@@ -205,81 +215,38 @@ Known Issues
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.`
- `Aborting...`
- 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|Beignet/Backend/TODO]].
-- 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)
Project repository
Right now, we host our project on fdo at:
And the Intel
The team
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 (<>).
+team continue to work on this project. The official contact for this project is:
+Zou Nanhai (<>).
Maintainers from Intel:
* Gong, Zhigang
* Yang, Rong
-Developers from Intel:
+Developers from Intel:
* Song, Ruiling
* He, Junyan
* Luo, Xionghu
* Wen, Chuanbo
* Guo, Yejun
-* Lv, Meng
+* Pan, Xiuli
-Debian Maintainer:
+Debian Maintainer:
* Rebecca Palmer
-Fedora Maintainer:
+Fedora Maintainer:
* Igor Gnatenko
@@ -289,21 +256,23 @@ 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 mail list is as below:
The official bugzilla is at:
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
-- [[Cross compile|Beignet/howto/cross-compiler-howto]]
+- [[Cross compile (yocto)|Beignet/howto/cross-compiler-howto]]
- [[Work with old system without c++11|Beignet/howto/oldgcc-howto]]
- [[Kernel Optimization Guide|Beignet/optimization-guide]]
- [[Libva Buffer Sharing|Beignet/howto/libva-buffer-sharing-howto]]
+- [[V4l2 Buffer Sharing|Beignet/howto/v4l2-buffer-sharing-howto]]
+- [[Video Motion Estimation|Beignet/howto/video-motion-estimation-howto]]
+- [[Stand Alone Unit Test|Beignet/howto/stand-alone-utest-howto]]
The wiki URL is as below: