Updated README, ISSUES, TODO files for v1.2 release of Shamrock

Also updated detailed analysis of Khronos failing tests for posterity.

Signed-off-by: Gil Pitney <gil.pitney@linaro.org>

6 files changed, 126 insertions, 49 deletions

diff --git a/ISSUES b/ISSUES
new file mode 100644
index 0000000..c462ab1
--- /dev/null
+++ b/ISSUES
@@ -0,0 +1,42 @@
+Issues:
+=======
+
+
+1. Khronos tests:
+
+  The majority of basic v1.2 Khronos tests pass, proving that MCJIT is working
+  pretty well for ARM.
+
+  The following results were obtained with Shamrock on a Chromebook 2
+  running Ubuntu 13.10 (ARMv7, 4 active cores).
+
+  computeinfo:  1/1   PASS
+  api:		71/72 PASS
+  basic:	86/95 PASS
+  buffers:	90/93 PASS
+  commonfns:	17/17 PASS
+
+  The Khronos test failures were diagnosed and documented here:
+
+  tests/basic_test_failures.lst
+  tests/api_test_failures.lst
+  tests/buffer_test_failures.lst
+
+2. piglit tests:
+
+   The piglit tests were run on a HiKey board (ARMv8).
+
+   1530/1543 tests passed.
+
+   The failures included 8 API tests, and 5 for the builtin vector-conversion
+   test (which passes on ARMv7).
+
+
+3. DSP Device support:
+
+  This requires extra TI DSP compiler, DSP side files and builtin library
+  support which is released by TI as part of its Keystone II MCSDK-HPC product.
+
+  Though the CMake files allow building for TI devices, all the DSP side files
+  may not yet be at git.ti.com/opencl, so the build defaults to 
+  SHAMROCK build type, building for CPU Device (ARM) only.
diff --git a/README b/README
index a88da93..09e4481 100644
--- a/README
+++ b/README
@@ -50,7 +50,7 @@ Usage: cmake <project_src_dir> <optional_defines>*
 
 If LLVM lives in a private path:
    -DLLVM_CONFIG_EXECUTABLE=<path to private llvm-config version>
-If your Clang is installed to a different location than LLVM,
+If Clang is installed to a different location than LLVM,
 then define CLANG_INCLUDE_DIR and CLANG_LIB_DIR on the cmake cmd line:
   -DCLANG_INCLUDE_DIR=/opt/clang/include -DCLANG_LIB_DIR=/opt/clang/lib
 
diff --git a/TODO b/TODO
index 6a0f399..c5fd17c 100644
--- a/TODO
+++ b/TODO
@@ -1,64 +1,36 @@
 Things To Do:
-
-
-Roadmap
-=======
+=============
 
 1. Resync with git.ti.com/opencl.
 
    Update to latest common code from the TI repo.
 
-2. Merge TI OpenCL DSP Device support from git.ti.com/opencl.
-
-   Get the CPU and DSP device support to act as plugins to a common
-   framework, so that they may coexist.
-
-3. Validate CPU Device for ARMv8, x86_64
-
-   Ensure same tests that pass on ARM also work on x86.
-
-4. Update to OpenCL v 1.2
+2. Add ICD support
 
-5. Move to SPIR.
+   Adding ICD support requires embedding an ICD Dispatch structure
+   into each public OpenCL object, and registering the vendor's
+   implementation with the system so an ICD loader can find and invoke it.
 
-   Once a SPIR to ARM backend becomes available, move to SPIR as a more
-   standard IR.
-
-Issues:
-=======
-
-1. Khronos tests:
-
-  The majority of Khronos basic tests pass, proving that MCJIT is working
-  pretty well for ARM.
+   Though the effort does not appear too difficult, the payoff is really
+   when there are other ICD-compatible OpenCL drivers for other
+   devices (GPUs, DSPs) available with which to run concurrently.
 
-  The remaining Khronos 'basic' test failures (ARM only), documented here:
+3. Merge TI OpenCL DSP Device support from git.ti.com/opencl.
 
-  tests/basic_test_failures.lst
-
-  Some of the other Khronos tests behond "basic" have been run on ARM,
-  but the failures have yet to be analysed.
-  computeinfo:  PASS
-  api:		55/61 PASS
-  basic:	87/95 PASS
-  buffers:	78/81 PASS
-  commonfns:	17/17 PASS
+   Get the CPU and DSP device support to act as plugins to a common
+   framework, so that they may coexist.
 
-2. Builtins:
+4. Builtins:
 
-  atomic builtins not yet implemented.
-  math builtins implemented (using libm or builtins), but not all pass the
-  Khronos criteria for accuracy.
+   The current clc.h has its roots in LLVM libclc, but has diverged.  It
+   may be interesting to resync with that project, if those builtins
+   actually pass the Khronos tests.
 
-  The current clc.h has its roots in LLVM libclc, but has diverged.  It
-  may be interesting to resync with that project, if those builtins
-  actually pass the Khronos tests.
+5. Update to OpenCL v 2.0
 
-3. DSP Device support:
+   An HSA compliant platform would benefit this effort.
 
-  This requires extra TI DSP compiler, DSP side files and builtin library
-  support which is released by TI as part of its Keystone II MCSDK-HPC product.
+6. Move to SPIR, or SPIR-V.
 
-  Though the CMake files allow building for TI devices, all the DSP side files
-  are not in opensource, so the build defaults to SHAMROCK build type,
-  building for CPU Device only.
+   Once a SPIR to ARM backend becomes available, could move to SPIR as a more
+   standard IR.
diff --git a/tests/api_test_failures.lst b/tests/api_test_failures.lst
new file mode 100644
index 0000000..f4c52f5
--- /dev/null
+++ b/tests/api_test_failures.lst
@@ -0,0 +1,36 @@
+Khronos API Test Failures
+===========================
+Khronos Test Version: OpenCL 1.2
+
+Usage:  
+% cd opencl_conformance/test_conformance/api
+% test_api <test-name>
+
+
+<test-name>: 
+Failure Mode:
+Analysis:
+
+binary_create
+=============
+Failure Mode:   
+------------
+ERROR: Unable to build binary program! (CL_INVALID_OPERATION from /home/gpitney/opencl_1_2_conformance/test_conformance/api/test_binary.cpp:113)
+
+
+Analysis:
+---------
+This is expected.  It is my claim that this test is violating the spec, by
+attempting to build a proram with kernels already attached to the program.
+
+See this comment in src/core/program.cpp:
+// Per the v1.2 spec for clBuildProgram() and clCompileProgram():
+// "Returns: CL_INVALID_OPERATION if there are kernel objects attached to program."
+// Note this causes some Khronos tests to fail, like 
+// test_compiler options_build_macro options_build_macro_existence options_include_directory, and
+// test_api binary_create, as they all violate the spec in this regard.
+    if (getNumKernels() > 0) {
+	p_state = Failed;
+        return(CL_INVALID_OPERATION);
+    }
+
diff --git a/tests/basic_test_failures.lst b/tests/basic_test_failures.lst
index e10ff5b..65eafb8 100644
--- a/tests/basic_test_failures.lst
+++ b/tests/basic_test_failures.lst
@@ -13,6 +13,7 @@ Analysis:
 
 hiloeo
 astype
+prefetch
 ======
 Failure Mode:   
 ------------
diff --git a/tests/buffer_test_failures.lst b/tests/buffer_test_failures.lst
new file mode 100644
index 0000000..177e34b
--- /dev/null
+++ b/tests/buffer_test_failures.lst
@@ -0,0 +1,26 @@
+Khronos Buffer Test Failures
+===========================
+Khronos Test Version: OpenCL 1.2
+
+Usage:  
+% cd opencl_conformance/test_conformance/api
+% test_buffers <test-name>
+
+
+<test-name>: 
+Failure Mode:
+Analysis:
+
+
+buffer_read_half
+buffer_write_half
+mem_alloc_ref_flags
+=============
+Failure Mode:   
+------------
+test currently not implemented
+
+Analysis:
+---------
+The Khronos test is not implemented, so just reports "Not Implemented" instead
+of passing.