1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
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`
News
----
[[Beignet project news|Beignet/NEWS]]
Prerequisite
------------
The project depends on the following external libaries:
- libdrm libraries (libdrm and libdrm\_intel)
- Various LLVM components
- Mesa git master version built with gbm enabled to support extension cl\_khr\_gl\_sharing.
- 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):
- 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/](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. The recommended specified version is r211037.
As LLVM 3.5 hasn't been released and still in active development. Use version
newer than the recommended version may be incompatbiel with beignet.
**Note about OpenCV support**
* We fully tested the OpenCV 2.4 branch with beignet. And the pass rate is about 99%
for beignet 0.9. The preferred LLVM/Clang version is 3.3.
* As some OpenCL kernels run more than 10 seconds, it may be reset by the linux kernel as
the there is 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 Targets
-----------------
* 3rd Generation Intel Core Processors
* Intel “Bay Trail” platforms with Intel HD Graphics
* 4rd Generation Intel Core Processors, need kernel patch currently, see below
for details:
The 4rd Generation Inter Core Processors's support requires some Linux kernel
modification. You need to apply the patch at:
[https://01.org/zh/beignet/downloads/linux-kernel-patch-hsw-support](https://01.org/zh/beignet/downloads/linux-kernel-patch-hsw-support)
Known Issues
------------
* We don't support "extern" keyword on OpenCL kernel side.
* 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.
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. There are some major optimizations need to be done,
Peephole optimization, convert to strcutured BBs and leverage Gen's structured
instructions, and optimize 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]].
- 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/](http://cgit.freedesktop.org/beignet/).
And the intel 01.org:
[https://01.org/beignet](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](http://lists.freedesktop.org/mailman/listinfo/beignet)
Documents for OpenCL application developers
-------------------------------------------
- [[Cross compile|Beignet/howto/cross-compiler-howto]]
- [[Kernel Optimization Guide|Beignet/optimization-guide]]
The wiki url is as below:
[http://www.freedesktop.org/wiki/Software/Beignet/](http://www.freedesktop.org/wiki/Software/Beignet/)
|
