]>
Commit | Line | Data |
---|---|---|
7d3d7cb5 JB |
1 | Description: Update documentation |
2 | ||
3 | Reflect #767148 fix, high precision now being default, and releases. | |
4 | Clarify what hardware is supported. | |
5 | Add Debian specific information; recommend the Debian BTS rather than | |
6 | mostly-inactive upstream contact points. | |
7 | ||
8 | Author: Rebecca N. Palmer <rebecca_palmer@zoho.com> | |
9 | Forwarded: partially, most recently https://lists.freedesktop.org/archives/beignet/2019-January/009225.html | |
10 | ||
11 | --- a/src/cl_device_id.c | |
12 | +++ b/src/cl_device_id.c | |
13 | @@ -907,7 +907,7 @@ cl_self_test(cl_device_id device, cl_sel | |
14 | } else { | |
15 | ret = SELF_TEST_SLM_FAIL; | |
16 | printf("Beignet: self-test failed: (3, 7, 5) + (5, 7, 3) returned (%i, %i, %i)\n" | |
17 | - "See README.md or http://www.freedesktop.org/wiki/Software/Beignet/\n", | |
18 | + "This can usually be fixed by upgrading Linux to >= 4.2,\nsee /usr/share/doc/beignet-dev/Beignet.html or https://www.freedesktop.org/wiki/Software/Beignet/\n", | |
19 | test_data[0], test_data[1], test_data[2]); | |
20 | ||
21 | } | |
22 | --- a/docs/Beignet/Backend.mdwn | |
23 | +++ b/docs/Beignet/Backend.mdwn | |
24 | @@ -37,9 +37,7 @@ Environment variables are used all over | |
25 | precision math instructions compliant with OpenCL Spec. So we provide a | |
26 | software version to meet the high precision requirement. Obviously the | |
27 | software version's performance is not as good as native version supported by | |
28 | - GEN hardware. What's more, most graphics application don't need this high | |
29 | - precision, so we choose 0 as the default value. So OpenCL apps do not suffer | |
30 | - the performance penalty for using high precision math functions. | |
31 | + GEN hardware. | |
32 | ||
33 | - `OCL_SIMD_WIDTH` `(8 or 16)`. Select the number of lanes per hardware thread, | |
34 | Normally, you don't need to set it, we will select suitable simd width for | |
35 | --- /dev/null | |
36 | +++ b/docs/index.mdwn | |
37 | @@ -0,0 +1 @@ | |
38 | +[[!map pages="* and !ikiwiki/*" show=title]] | |
39 | --- a/docs/Beignet.mdwn | |
40 | +++ b/docs/Beignet.mdwn | |
41 | @@ -16,6 +16,8 @@ News | |
42 | Prerequisite | |
43 | ------------ | |
44 | ||
45 | +(for building the upstream source; Debian packages handle this automatically) | |
46 | + | |
47 | The project depends on the following external libraries: | |
48 | ||
49 | - libdrm libraries (libdrm and libdrm\_intel) | |
50 | @@ -84,7 +86,7 @@ you need to configure it as below: | |
51 | ||
52 | CMake will check the dependencies and will complain if it does not find them. | |
53 | ||
54 | -`> make` | |
55 | +`> make utest` | |
56 | ||
57 | The cmake will build the backend firstly. Please refer to: | |
58 | [[OpenCL Gen Backend|Beignet/Backend]] to get more dependencies. | |
59 | @@ -123,25 +125,17 @@ platform. Beignet also produces various | |
60 | consistency. This small test framework uses a simple c++ registration system to | |
61 | register all the unit tests. | |
62 | ||
63 | -You need to call setenv.sh in the utests/ directory to set some environment variables | |
64 | -firstly as below: | |
65 | - | |
66 | -`> . setenv.sh` | |
67 | - | |
68 | -Then in `utests/`: | |
69 | +In Debian beignet, the testing tool is in the _beignet-dev_ package, and is run with: | |
70 | ||
71 | -`> ./utest_run` | |
72 | +`> /usr/lib/\`dpkg-architecture -qDEB_HOST_MULTIARCH\`/beignet/utest_run` | |
73 | ||
74 | -will run all the unit tests one after the others | |
75 | +(this name and path may change in future releases - please do not rely on it). It will test the first OpenCL GPU device it finds (which does _not_ have to be a Beignet device). If you want to test a different device, uninstall all other ICDs. To see more options, pass `-h`. | |
76 | ||
77 | -`> ./utest_run some_unit_test` | |
78 | +If you compiled Beignet yourself, you will find this tool in `utests`, and will need to set some environment variables to use it (see `setenv.sh`). | |
79 | ||
80 | -will only run `some_unit_test` test. | |
81 | ||
82 | On all supported target platform, the pass rate should be 100%. If it is not, you may | |
83 | -need to refer the "Known Issues" section. Please be noted, the `. setenv.sh` is only | |
84 | -required to run unit test cases. For all other OpenCL applications, don't execute that | |
85 | -command. | |
86 | +need to refer the "Known Issues" section. | |
87 | ||
88 | Normally, beignet needs to run under X server environment as normal user. If there isn't X server, | |
89 | beignet provides two alternative to run: | |
90 | @@ -151,14 +145,23 @@ beignet provides two alternative to run: | |
91 | Supported Targets | |
92 | ----------------- | |
93 | ||
94 | +Beignet aims to support Gen7 to Gen9 Intel HD (not PowerVR) integrated GPUs. It is the only OpenCL in Debian for the GPUs of: | |
95 | + | |
96 | * 3rd Generation Intel Core Processors "Ivybridge". | |
97 | * 3rd Generation Intel Atom Processors "BayTrail". | |
98 | * 4th Generation Intel Core Processors "Haswell", need kernel patch if your linux kernel older than 4.2, see the "Known Issues" section. | |
99 | + | |
100 | +Beignet should also work on the following, but if CL-GL sharing is not required, [Intel Compute Runtime (Neo)](https://01.org/compute-runtime) (Debian package [intel-opencl-icd](https://packages.debian.org/search?keywords=intel-opencl-icd&searchon=names&exact=1&suite=all§ion=all)) may be better: | |
101 | + | |
102 | * 5th Generation Intel Core Processors "Broadwell". | |
103 | * 5th Generation Intel Atom Processors "Braswell". | |
104 | - * 6th Generation Intel Core Processors "Skylake" and "Kabylake". | |
105 | * 5th Generation Intel Atom Processors "Broxten" or "Apollolake". | |
106 | + * 6th+ Generation Intel Core Processors "Skylake", "Kaby Lake", "Coffee Lake", "Comet Lake", "Amber Lake". | |
107 | ||
108 | +Not all processor models have an integrated GPU (Beignet does _not_ support running OpenCL on the CPU itself - see [pocl-opencl-icd](https://packages.debian.org/search?keywords=pocl-opencl-icd&searchon=names&exact=1&suite=all§ion=all) for that). Systems that also have a discrete GPU may disable the integrated GPU: check _xrandr --listproviders_ or see [here](https://nouveau.freedesktop.org/wiki/Optimus/). | |
109 | + | |
110 | +Attempting to run Beignet on unsupported hardware should return CL_DEVICE_NOT_FOUND; if it does anything else (especially crashing) please [report a bug](#howtocontribute). | |
111 | + | |
112 | OpenCL 2.0 | |
113 | ---------- | |
114 | From release v1.3.0, beignet supports OpenCL 2.0 on Skylake and later hardware. | |
115 | @@ -188,7 +191,7 @@ Known Issues | |
116 | forever until a reboot. | |
117 | ||
118 | * "Beignet: self-test failed" and almost all unit tests fail. | |
119 | - Linux 3.15 and 3.16 (commits [f0a346b](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=f0a346bdafaf6fc4a51df9ddf1548fd888f860d8) | |
120 | + Linux 3.15 and upstream 3.16 (_not_ Debian jessie 3.16; commits [f0a346b](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=f0a346bdafaf6fc4a51df9ddf1548fd888f860d8) | |
121 | to [c9224fa](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c9224faa59c3071ecfa2d4b24592f4eb61e57069)) | |
122 | enable the register whitelist by default but miss some registers needed | |
123 | for Beignet. | |
124 | @@ -224,10 +227,15 @@ Known Issues | |
125 | This extension is partially implemented(the most commonly used part), and we will implement | |
126 | other parts based on requirement. | |
127 | ||
128 | +* Programs using Intel-specific extensions fail to compile. | |
129 | + | |
130 | + Debian opencl-c-headers is the standard (Khronos) headers, which splits some of these into separate files | |
131 | + (e.g. cl\_ext\_intel.h): search /usr/include/CL. cl\_intel.h is in the beignet-dev package. | |
132 | + | |
133 | Project repository | |
134 | ------------------ | |
135 | Right now, we host our project on fdo at: | |
136 | -[http://cgit.freedesktop.org/beignet/](http://cgit.freedesktop.org/beignet/). | |
137 | +[https://gitlab.freedesktop.org/beignet/beignet](https://gitlab.freedesktop.org/beignet/beignet). | |
138 | And the Intel 01.org: | |
139 | [https://01.org/beignet](https://01.org/beignet) | |
140 | ||
141 | @@ -263,15 +271,11 @@ If I missed any other package maintainer | |
142 | ||
143 | How to contribute | |
144 | ----------------- | |
145 | -You are always welcome to contribute to this project, just need to subscribe | |
146 | -to the beignet mail list and send patches to it for review. | |
147 | -The official mail list is as below: | |
148 | -[http://lists.freedesktop.org/mailman/listinfo/beignet](http://lists.freedesktop.org/mailman/listinfo/beignet) | |
149 | -The official bugzilla is at: | |
150 | -[https://bugs.freedesktop.org/enter_bug.cgi?product=Beignet](https://bugs.freedesktop.org/enter_bug.cgi?product=Beignet) | |
151 | -You are welcome to submit beignet bug. Please be noted, please specify the exact platform | |
152 | -information, such as BYT/IVB/HSW/BDW, and GT1/GT2/GT3. You can easily get this information | |
153 | -by running the beignet's unit test. | |
154 | +Please [report bugs to Debian](https://www.debian.org/Bugs/Reporting) package beignet-opencl-icd. | |
155 | + | |
156 | +Please specify your hardware when reporting a bug: _reportbug beignet-opencl-icd_ will automatically include this information. | |
157 | + | |
158 | +The upstream [email list](http://lists.freedesktop.org/mailman/listinfo/beignet) and [bug tracker](https://gitlab.freedesktop.org/beignet/beignet/issues) are still available, but as upstream is mostly inactive, it may be some time before they respond. | |
159 | ||
160 | Documents for OpenCL application developers | |
161 | ------------------------------------------- |