[PATCH] D28080: [Docs][OpenCL] Added OpenCL feature description to user manual.

[Pekka Jääskeläinen via Phabricator via cfe-commits]

pekka.jaaskelainen requested changes to this revision.
pekka.jaaskelainen added a comment.
This revision now requires changes to proceed.

Great work.



================
Comment at: docs/UsersManual.rst:44
 -  :ref:`Objective C++ Language <objcxx>`
+-  :ref:`OpenCL Language <opencl>`: v1.0, v1.1, v1.2, v2.0.
 
----------------
Should this be OpenCL C Language?


================
Comment at: docs/UsersManual.rst:2013
+to perform machine code generation.
+
+Clang currently supports OpenCL standards up to v2.0.
----------------
I'd like to add a sentence or two for instructing how to use it for non-SPMD targets and of course advertise pocl here too ;) 

Something along the lines of:

"For "non-SPMD" targets which cannot spawn multiple work-items on the fly using hardware, which covers practically all non-GPU devices such as CPUs and DSPs, additional processing is needed for the kernels to support multiple WI execution. For this, a 3rd party project such as `pocl <http://portablecl.org/>`_ can be used."


================
Comment at: docs/UsersManual.rst:2078
+Overrides the target address space map with a fake map.
+This allows adding address spaces for architectures that do not provide default
+memory segment support. Passing ``-ffake-address-space-map`` will add/override
----------------
I'd convert to something like:

"This allows adding explicit address space ids to the bitcode for architectures without separate IDs for each of the OpenCL logical address spaces."


================
Comment at: docs/UsersManual.rst:2114
+     $ clang -target nvptx64-unknown-unknown test.cl
+
+Generic Targets
----------------
This is an alternative location for my pocl advertisement above with a subtitle:

- For CPU/DSP architectures such as x86, ARM or TCE:
...



================
Comment at: docs/UsersManual.rst:2120
+  that can be used across GPU toolchains. The implementation follows `the SPIR
+  specification <https://www.khronos.org/spir>`_. There are two flavors available
+  for 32 and 64 bits.
----------------
Which version of SPIR is generated?


================
Comment at: docs/UsersManual.rst:2130
+
+- x86 is used by some implementations that are x86 compatible
+  (e.g. `POCL <http://portablecl.org/>`_) and currently remains for backwards
----------------
This is a bit confusing paragraph, probably due to my confusing explanations of the problems with pocl. Currently pocl tries not to use FASM for preserving logical AS IDs to LLVM IR due to the bunch of problems it constantly produces with seemingly little benefits for common CPUs. My patch related to this considered only the argument info switch. Now pocl only derives the logical iDS from kernel arguments (and all other IDs within the body of the IR function are lost for flat machines).  In my patch, the argument info's address space IDs were made constant and identical to SPIR's as previously they were the target's (which meant losing the AS IDs altogether for flat AS machines).

You seem to document the arg-info md switch later, so this paragraph might be removed or converted to my pocl blurb which mentions the need for further processing for CPUs.


================
Comment at: docs/UsersManual.rst:2173
+
+The source-level information put into the metadata follows the SPIR address space
+mapping as defined in the SPIR specification `section 2.2
----------------
Something like: "The IDs used to encode the OpenCL's logical address spaces in the argument info metadata ..." 


================
Comment at: docs/UsersManual.rst:2206
+To make sure no invalid optimizations occur for single program multiple data
+(SPMD)/ single instruction multiple thread (SIMT) Clang provides attributes that
+can be used for special functions that have cross work item semantics.
----------------
add space before /


================
Comment at: docs/UsersManual.rst:2310
+
+- Address space qualifier functions ``to_global``/``to_local``/``to_private``
+  from `section 6.13.9
----------------
+conversion


================
Comment at: www/index.html:19
+  <p>The goal of the Clang project is to create a new C based language
+  front-end: C, C++, Objective C/C++, OpenCL and others for the
+  <a href="http://www.llvm.org/">LLVM</a> compiler.  You can
----------------
OpenCL C. Maybe OpenCL C++ also?


https://reviews.llvm.org/D28080