|author||Zhigang Gong <firstname.lastname@example.org>||2014-02-07 02:17:52 -0800|
|committer||Zhigang Gong <email@example.com>||2014-02-07 02:18:36 -0800|
Sycn with beignet's latest document.
Diffstat (limited to 'Software/Beignet.mdwn')
1 files changed, 67 insertions, 42 deletions
diff --git a/Software/Beignet.mdwn b/Software/Beignet.mdwn
index c0f88de1..824a9393 100644
@@ -3,15 +3,50 @@ Beignet
Beignet is an open source implementaion of the OpenCL specification - a generic
compute oriented API. This code base contains the code to run OpenCL programs on
-Intel GPUs which bsically defines and implements the OpenCL host functions
+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`
-How to build
+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.
+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 any thing older.
+LLVM 3.3 and 3.4 are supported. Till now, the recommended LLVM version is 3.3.
+There are some severe OpenCL related regression in current clang 3.4 version.
+Also note that the code was compiled on GCC 4.6 and GCC 4.7. 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.
+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.
+How to build and install
The project uses CMake with three profiles:
1. Debug (-g)
@@ -26,41 +61,28 @@ Basically, from the root directory of the project
`> cmake ../ # to configure`
-Choose whatever you want for the build.
-Then press 'c' to configure and 'g' to generate the code.
+CMake will check the dependencies and will complain if it does not find them.
-The project depends on several external libraries:
-- 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.
-CMake will check the dependencies and will complain if it does not find them.
-The cmake will also build the backend project. Please refer to:
+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/`.
-Note that the compiler depends on LLVM (Low-Level Virtual Machine project).
-Right now, the code has been compiled with LLVM 3.1/3.2. It will not compile
-with any thing older.
+`> make install`
+It installs the following three files to the beignet/ directory relatively to
+your library installation directory.
+- ocl_stdlib.h, ocl_stdlib.h.pch
-LLVM 3.1,3.2 and 3.3 are supported.
-Also note that the code was compiled on GCC 4.6 and GCC 4.7. 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.
+It installs the OCL icd vendor files to /etc/OpenCL/vendors, if the system support ICD.
How to run
@@ -70,8 +92,10 @@ 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 set the variable `OCL_KERNEL_PATH` to locate the OCL kernels. They
-are with the run-time in `./kernels`.
+You need to call setenv.sh in the utests/ directory to set some environment variables
+firstly as below:
+`> . setenv.sh`
Then in `utests/`:
@@ -86,32 +110,30 @@ will only run `some_unit_test0` and `some_unit_test1` tests
-The code was tested on IVB GT2 with ubuntu and fedora core distribution.
-Currently Only IVB is supported right now. Actually, the code was only run on IVB GT2. You
-may expect some issues with IVB GT1.
+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.
-The run-time is far from being complete. Most of the pieces have been put
-together to test and develop the OpenCL compiler. A partial list of things to
+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.
- Complete cl\_khr\_gl\_sharing support. We lack of some APIs implementation such
as clCreateFromGLBuffer,clCreateFromGLRenderbuffer,clGetGLObjectInfo... Currently,
- the working APIs are clCreateFromGLTexture,clCreateFromGLTexture2D.
-- Support for events.
+ 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
-- Support for nonblocking mode Enqueue\*Buffer. Now we only use the map extension to
- implement those Enqueue\*Buffer functions.
- 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
+ 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.
@@ -122,7 +144,10 @@ does not comply with the standard or it is just missing)
-Right now, we host our project on fdo at: git://anongit.freedesktop.org/beignet.
+Right now, we host our project on fdo at:
+And the intel 01.org: