[Docs][OpenCL] Release 9.0 notes for OpenCL

[mantognini]

The overall structure seems alright. I'll let people more familiar with the code-base judge whether other important features should be added there as well.

docs/ReleaseNotes.rst

49

"Full experimental" feels like an oxymoron. I would drop the "full".

49

"support of" -> "support for"

138

Support for address space attributes [...] improved (refer [...]

Alternatively, if you don't want to use parenthesis, drop the closing parenthesis on the next line.

142

Inconsistent sentence capitalization between the two bullet points.

173

If the BIF acronym wasn't introduced before, it should be replaced with "builtin functions". It seems we don't have more file context in this review so I cannot tell.

175

I'm not 100% sure about the grammar rule in English, but shouldn't there be a "-" between "frontend" and "only" here to make it an adjective-ish?

183

Simplified the representation of blocks, including their generation into IR. Furthermore, indirect calls [...]

(I'm assuming here that the indirect calls to block function is not the only improvement. And even if it is, "i.e." is less impressive, isn't it?)

194

Maybe this would be better?

Improved math builtin functions with parameters of type long long for x86.

201

Ditto, I would drop "full" here.

202

compatible with

209

Did you meant to indent this bullet point as well?

215

Missing comma: "functions, including"

220

Maybe something along these line would be better?

Methods can be overloaded for different address spaces.

Or, if you want to emphasis the qualifiers,

Method qualifiers now include address space.

222

This seems to be already included in previous point.

226

Which "cast" operators?

226

[...] are now prevented from converting [...]

229

missing comma: "C, including"

232–233

I would suggest this:

OpenCL-specific types, except within blocks: [...]

237–238

Stab? Stub?

Global constructors can be invoked from the host side using a specific, compiler-generated kernel.

240–241

[...] to all atomic builtins(?), including the ones prior to [...]

[svenvh]

docs/ReleaseNotes.rst

173

BIFs -> built-in functions

175

The flag is called -fdeclare-opencl-builtins (not -fadd...).

176

The option does not only "enable a trie" during parsing. I'd suggest to just drop "to enable trie during parsing".

179

Refactored the opencl-c.h header file ...

TableGen trie -> -fdeclare-opencl-builtins.

[Anastasia]

docs/ReleaseNotes.rst

173

builtin is a more common spelling in Clang docs.

176

We don't have to describe all details here btw, but just the main ones. I would like to say what the flag is used for explicitly rather than leaving the room for interpretations.

Btw, would it make sense to document this flag in UserManual? https://clang.llvm.org/docs/UsersManual.html#opencl-specific-options

220

I prefer the second one, as the first one can be read as parameter address space.

222

Do you mean method qualifiers? I don't see the connection?

232–233

I mean with the exception of blocks here.

[mantognini]

docs/ReleaseNotes.rst

287

I think Sphinx/RST wants an empty line here.

Nitpicking for consistency, could you have a ; at then end of each bullet point (except the last one, obviously)? Thanks.

[Anastasia]

• Added empty line and ; as requested on the review.

[mantognini]

Thanks for addressing my comments.

[hans]

lgtm, and many thanks for writing release notes!

Go ahead and commit to the branch directly with SVN or let me know if you'd like me to do it.

docs/ReleaseNotes.rst

 Major New Features
 ------------------
 
+- Experimental support for :ref:`C++ for OpenCL <openclcpp>` has been
+  added.
 - ...
 
 Improvements to Clang's diagnostics

 C++ Language Changes in Clang
 -----------------------------
 
+- Support for the address space attribute in various C++ features was improved,
+  refer to :ref:`C++ for OpenCL <openclcpp>` for more details. The following
+  features deviated from OpenCL:
+
+  (1) Address spaces as method qualifiers are not accepted yet;
+
+  (2) There is no address space deduction.
+
 - ...
 
 C++1z Feature Support

       // clang used to encode this as "^{NSArray=#}" instead of "@".
       const char *s0 = @encode(MyArray *);
 
-OpenCL C Language Changes in Clang
-----------------------------------
+OpenCL Kernel Language Changes in Clang
+---------------------------------------
+
+OpenCL C
+^^^^^^^^
+
+- Enabled use of variadic macro as a Clang extension.
+
+- Added initial support for implicitly including OpenCL builtin
+  fuctions using efficient trie lookup generated by TableGen.
+  A corresponding frontend-only flag ``-fdeclare-opencl-builtins``
+  has been added to enable trie during parsing.
+
+- Refactored header file to be used for common parts between
+  regular header added using ``-finclude-default-header`` and trie
+  based declarations added using ``-fdeclare-opencl-builtins``.
+
+- Improved string formatting diagnostics in printf for vector types.
+
+- Simplified the internal representation of blocks, including their
+  generation in IR. Furthermore, indirect calls to block function
+  has been changed to direct function calls.
+
+- Added diagnostics for conversions of nested pointers with
+  different address spaces.
+
+- Added ``cl_arm_integer_dot_product`` extension.
+
+- Fixed global samplers in OpenCL v2.0.
+
+- Improved math builtin functions with parameters of type ``long
+  long`` for x86. 
+
+.. _openclcpp:
+
+C++ for OpenCL
+^^^^^^^^^^^^^^
+
+Experimental support for C++17 features in OpenCL has been added
+and backwards compatibility with OpenCL C v2.0 was enabled.
+The documentation has been added for supported language features
+into :doc:`LanguageExtensions` and :doc:`UsersManual`. 
+
+Implemented features are:
+- Address space behavior is improved in majority of C++ features:
+
+  - Templates parameters and arguments
+
+  - Reference types;
+
+  - Type deduction;
+
+  - Objects and member functions, including special member
+    functions;
+
+  - Builtin operators;
+
+  - Method qualifiers now include address space;
+
+  - Address space deduction has been extended for C++ use cases;
+
+  - Improved overload ranking rules.
+
+  - All standard cast operators now prevent converting address 
+    spaces (except for conversions allowed implicitly). They
+    can still be cast using C-style cast.
+
+- Vector types as in OpenCL C, including compound vector
+  initialization.
+
+- OpenCL-specific types: images, samplers, events, pipes, are
+  accepted with exception of blocks.
+
+- OpenCL standard header in Clang can be compiled in C++ mode.
+
+- Global constructors can be invoked from the host side using
+  a specific, compiler-generated kernel.
+
+- Overloads with generic address space are added to all atomic
+  builtin functions, including the ones from prior to OpenCL
+  v2.0.
 
-...
 
 ABI Changes in Clang
 --------------------