beignet-update-docs.patch

   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&section=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&section=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  -------------------------------------------