[beignet] 03/06: Update and clarify documentation

Tue May 19 10:12:47 UTC 2015

This is an automated email from the git hooks/post-receive script.

rnpalmer-guest pushed a commit to branch master
in repository beignet.

commit 9cb076698b469dcad8bd06bfcc153fafdec2c01b
Author: Rebecca N. Palmer <rebecca_palmer at zoho.com>
Date:   Tue May 19 08:54:20 2015 +0100

    Update and clarify documentation
---
 debian/README.Debian             | 25 ++++++---------
 debian/patches/series            |  1 +
 debian/patches/update-docs.patch | 67 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 15 deletions(-)

diff --git a/debian/README.Debian b/debian/README.Debian
index 905d2b9..4b775b9 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,21 +1,16 @@
-Haswell issues
---------------
+"Beignet: self-test failed" / no device 
+---------------------------------------
 
-On Haswell (mostly Core ix-4xxx) hardware, beignet interacts badly with a
-Linux security mechanism, leading to these errors:
+On Haswell (mostly Core ix-4xxx) hardware, shared local memory (__local)
+does not work at all on Linux <= 4.0, and requires the i915.enable_ppgtt=2
+boot parameter (https://wiki.ubuntu.com/Kernel/KernelBootParameters)
+on Linux 4.1.  This will be fixed in Linux 4.2.
 
-* drm_intel_gem_bo_context_exec() failed: Invalid argument
+To avoid silently wrong results, beignet performs a self-test on load and
+hides devices where __local does not work.  If you do not need __local,
+you can override the self-test with
 
-Occurs on all computations; can be avoided by setting
-i915.enable_cmd_parser=0, either at boot, or later with:
-
-  sudo echo 0 > /sys/module/i915/parameters/enable_cmd_parser
-
-* Beignet: Shared local memory does not work on Haswell
-
-Occurs on using the __local memory space.  To avoid this, apply the patch at
-https://01.org/zh/beignet/downloads/linux-kernel-patch-hsw-support to Linux,
-remove haswell.patch from beignet, and recompile both.
+  export OCL_IGNORE_SELF_TEST=1
 
 Precision vs. Speed
 -------------------
diff --git a/debian/patches/series b/debian/patches/series
index 60b32b1..414e8dc 100644
--- a/debian/patches/series
+++ b/debian/patches/series
@@ -9,3 +9,4 @@ tgamma-accuracy.patch
 python3.patch
 self-test.patch
 disable-broken-fast-atomics.patch
+update-docs.patch
diff --git a/debian/patches/update-docs.patch b/debian/patches/update-docs.patch
new file mode 100644
index 0000000..c799ba1
--- /dev/null
+++ b/debian/patches/update-docs.patch
@@ -0,0 +1,67 @@
+Description: Update documentation
+
+Reflect self-test.patch, disable-broken-fast-atomics.patch and
+#767148 fix, plus general cleanup.
+
+Author: Rebecca N. Palmer <rebecca_palmer at zoho.com>
+Forwarded: http://cgit.freedesktop.org/beignet/commit/?id=6aae2e8000b421f390b19404486a75b005720f12
+
+--- beignet-1.0.3.orig/docs/Beignet.mdwn
++++ beignet-1.0.3/docs/Beignet.mdwn
+@@ -142,7 +142,7 @@ Supported Targets
+ 
+  * 3rd Generation Intel Core Processors
+  * Intel “Bay Trail” platforms with Intel HD Graphics
+- * 4th Generation Intel Core Processors, need kernel patch currently, see the "Known Issues" section.
++ * 4th Generation Intel Core Processors "Haswell", need kernel patch currently, see the "Known Issues" section.
+  * 5th Generation Intel Core Processors "Broadwell".
+ 
+ Known Issues
+@@ -163,22 +163,34 @@ Known Issues
+   But this command is a little bit dangerous, as if your kernel really hang, then the gpu will lock up
+   forever until a reboot.
+ 
+-* Almost all unit tests fail.
+-  There is a known issue in some versions of linux kernel which enable register whitelist feature
+-  but miss some necessary registers which are required for beignet. For non-HSW platforms, the
+-  problematic version are around 3.15 and 3.16 which have commit f0a346b... but haven't commit
+-  c9224f... If it is the case, you can apply c9224f... manually and rebuild the kernel or just
+-  disable the parse command by invoke the following command (use Ubuntu as an example):
++* "Beignet: self-test failed" and almost all unit tests fail.
++  Linux commits [f0a346b](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=f0a346bdafaf6fc4a51df9ddf1548fd888f860d8)
++  to [c9224fa](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=c9224faa59c3071ecfa2d4b24592f4eb61e57069)
++  (roughly 3.15 and 3.16, but _not_ Debian jessie's 3.16)
++  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`
+ 
+-  For HSW platforms, this issue exists in all linux kernel version after 3.15. We always need
+-  to execute the above command.
+-
+-* Some unit test cases, maybe 20 to 30, fail on 4th Generation (HSW) platform.
+-  _The 4th Generation Intel 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)
++  On Haswell hardware, Beignet 1.0.1-1 to 1.0.2-2 also required the
++  above workaround on later Linux versions, but this _should not_ be
++  required in this version of Beignet.
++
++* "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](https://wiki.ubuntu.com/Kernel/KernelBootParameters)
++  on Linux 4.1.
++  
++  This will be fixed in Linux 4.2; older versions can be fixed with
++  [this patch](https://01.org/zh/beignet/downloads/linux-kernel-patch-hsw-support).
++  
++  If you do not need \_\_local, you can override the self-test with
++  
++  `export OCL_IGNORE_SELF_TEST=1`
++  
++  but using \_\_local after this may silently give wrong results.
+ 
+ * Precision issue.
+   Currently Gen does not provide native support of high precision math functions

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-opencl/beignet.git

