Added documentation of C++ for OpenCL mode into Clang User Manual and Language Extensions document.
Details
Details
- Reviewers
svenvh mantognini stuart neil.hickey kpet - Commits
- rG263e040cea40: Merging r369749: --------------------------------------------------------------…
rL370031: Merging r369749:
rG976022e35c74: [Docs][OpenCL] Several corrections to C++ for OpenCL
rC369749: [Docs][OpenCL] Several corrections to C++ for OpenCL
rL369749: [Docs][OpenCL] Several corrections to C++ for OpenCL
rG79f4e4770b72: [Docs][OpenCL] Documentation of C++ for OpenCL mode
rL366351: [Docs][OpenCL] Documentation of C++ for OpenCL mode
rC366351: [Docs][OpenCL] Documentation of C++ for OpenCL mode
Diff Detail
Diff Detail
- Repository
- rL LLVM
Event Timeline
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1538 ↗ | (On Diff #208677) | This seems weird, you say the following features are not supported then say Only placement new/delete. I think you mean to say new/delete is not supported except for placement new and delete. |
| 1549 ↗ | (On Diff #208677) | I'd replace ". Therefore" with "; " |
| 1552 ↗ | (On Diff #208677) | need a , between yet and Clang I think, to remove the ambiguity |
Comment Actions
Here are a few comments from me but keep in mind that English is not my primary language
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1562–1565 ↗ | (On Diff #208677) | I would suggest using __generic or generic address space. The later is a bit more verbose, but makes the sentence more natural I think. |
| 1582 ↗ | (On Diff #208677) | s/knowns/known/ |
| 1611–1615 ↗ | (On Diff #208677) | The ref is broken. There's also one too many (. |
| 1613–1614 ↗ | (On Diff #208677) |
This might just be me so this might actually be okay, but I feel the sentence is simpler when rewritten as "Address space compatibility checks are performed when references are bound to values." What do you think?
Present tense should probably be better. Are there actually any differences? If no, I would drop "largely" from the sentence. Otherwise it might be good to actually list the differences. |
| 1617 ↗ | (On Diff #208677) | AS might be better fully spelled out. |
| 1619 ↗ | (On Diff #208677) | take an implicit |
| 1624 ↗ | (On Diff #208677) | ref is broken and there's one too manu (. |
| 1627 ↗ | (On Diff #208677) |
Maybe "For example: to take advantage [...]"? |
| 1662 ↗ | (On Diff #208677) | nitpicking: missing space before {. |
| 1671 ↗ | (On Diff #208677) | Typo: Builtin |
| 1673 ↗ | (On Diff #208677) | "specific" seems to imply to the user will have to explicitly write down the AS. Maybe "requested" or "desired" would fit better? |
| 1679 ↗ | (On Diff #208677) | The reference seems broken as well. |
| 1708 ↗ | (On Diff #208677) | s/foo3/foo/ |
| 1717 ↗ | (On Diff #208677) | nitpicking: indentation. Might as well rename it to ii to match the other example. |
| 1753–1761 ↗ | (On Diff #208677) | Is it expected of the user to call this special kernel, or is it expected that the driver takes care of that? |
| 1768 ↗ | (On Diff #208677) | As it stands, I'm not sure why this command is mentioned in this paragraph. Maybe it's a leftover of things that are now in the User's Manual? |
| 1770 ↗ | (On Diff #208677) | s/end/final/ |
| docs/UsersManual.rst | ||
| 2401 ↗ | (On Diff #208677) | The reference is broken. |
| 2771–2772 ↗ | (On Diff #208677) | I would make to sentences instead of using a ,. |
| 2797 ↗ | (On Diff #208677) | I would remove this code sample; it is already explained above that -cl-std=c++ should be used. |
Comment Actions
Good improvement!
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1758 ↗ | (On Diff #208677) | "<compiled"? |
| docs/UsersManual.rst | ||
| 2774 ↗ | (On Diff #208677) | functionality, |
| 2778 ↗ | (On Diff #208677) | To enable the new mode, pass the following command line option when compiling a `.cl` |
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1772 ↗ | (On Diff #208677) | I think I should add something about dtors too. |
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1673 ↗ | (On Diff #208677) | Ok, specific here is as opposite to generic. |
| 1753–1761 ↗ | (On Diff #208677) | In v2.0 drivers this is a manual step. In v2.2 drivers it is expected to be done automatically. |
| 1758 ↗ | (On Diff #208677) | I think IR linker makes them unique i.e. adds a suffix. Although I think the files (including the path) linked are supposed to be unique. Anyway, good point to look into. No idea about obj linker. We currently don't support this feature. |
| 1768 ↗ | (On Diff #208677) | This is the example I am explaining just below. |
| docs/UsersManual.rst | ||
| 2797 ↗ | (On Diff #208677) | Manual is good for examples. Some new developers might find it useful to have the full line even though it's quite simple. |
Comment Actions
Beside my two comments, I think this looks good.
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1614 ↗ | (On Diff #210101) | ( -> , (there's no matching closing parenthesis.) |
| 1652–1657 ↗ | (On Diff #210101) | foo() isn't actually called here. You probably meant to write this: __local C c1; C c2; __constant C c3; c1.foo(); // will resolve to the first foo c2.foo(); // will resolve to the second foo c3.foo(); // error due to mismatching address spaces - can't convert to __local or __generic |
Comment Actions
Very useful to have all of this documented! Thanks!
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1527 ↗ | (On Diff #210101) | I'm tempted to suggest you merge the first two sentences and tone down the claim in the second. "This functionality [...] and C++17, enabling _some_ regular C++ features [...]. |
| 1527 ↗ | (On Diff #210101) | s/All/Most/? Stating that all functionality from OpenCL C is available right before stating that the differences will be described feels like a contradiction. |
| 1535 ↗ | (On Diff #210101) | Probably worth adding exceptions to the list. |
| 1541 ↗ | (On Diff #210101) | I would remove this last sentence. Only a very small portion of the libray can be supported anyway. |
| 1553 ↗ | (On Diff #210101) | I would remove the "yet", unless we can refer to an on-going and visible effort. |
| 1553 ↗ | (On Diff #210101) | "Clang extends existing concept" feels like it should be re-worded. |
| 1555 ↗ | (On Diff #210101) | "using sets and overlapping" feels incomplete. Pretending I can't guess: sets of what? What is overlapping what? :) |
| 1557 ↗ | (On Diff #210101) | Why use __generic when generic is equally valid and easier on the eyes? The same comment applies to other mentions of address space keywords. |
| 1558 ↗ | (On Diff #210101) | This is ambiguous. One could read that conversions from __generic to __constant are allowed. |
| 1564 ↗ | (On Diff #210101) | Isn't a conversion explicit if a cast operator is used? |
| 1565 ↗ | (On Diff #210101) | At the time of writing addrspace_cast doesn't seem to exist in trunk and C-style casts seem to work. |
| 1565 ↗ | (On Diff #210101) | Didn't you mean "from __generic to named address spaces"? |
| 1577 ↗ | (On Diff #210101) | Makes me wonder whether const members couldn't be in the constant address space. |
| 1626 ↗ | (On Diff #210101) | the address space? |
| 1631 ↗ | (On Diff #210101) | I would remove the "for example to take advantage of memory bank accesses" or make the example clear. |
| 1641 ↗ | (On Diff #210101) | the overload |
| 1652–1657 ↗ | (On Diff #210101) | +1, I was about to make the same comment. |
| 1668 ↗ | (On Diff #210101) | Shouldn't this be C() __generic? Similar comments can be made for the other members. |
| 1684 ↗ | (On Diff #210101) | template parameterS |
| 1702 ↗ | (On Diff #210101) | "such a program" or "such programs" |
| 1760 ↗ | (On Diff #210101) | I would say "must be constructed before the first kernel begins execution" and "may be destroyed once the last kernel has completed its execution". These are requirements for a runtime environment, not functionality provided by Clang. The documentation should only describe the interface with the runtime and the requirements on the runtime. |
| 1761 ↗ | (On Diff #210101) | OpenCL doesn't have an API for this per-se, regardless of the version. The only mechanism currently specified is the SPIR-V Initializer and Finalizer execution modes for entrypoints, either of which currently require an OpenCL 2.2 implementation. |
| 1762 ↗ | (On Diff #210101) | I would say that "applications are required to run all of these initialization kernels before any others if they exist". |
| 1779 ↗ | (On Diff #210101) | This could be managed by the application with a scheme similar to the one you're proposing for constructor functions. |
| docs/UsersManual.rst | ||
| 2400 ↗ | (On Diff #210101) | Shouldn't "Clang9" be "Clang 9"? You may even want to spell it out "version 9 of Clang". |
| 2401 ↗ | (On Diff #210101) | "A C++ mode" or "A non-standard C++ language extension" to be more precise? |
| 2769 ↗ | (On Diff #210101) | No plans that we're aware of ;). For all we know, there could be a company/individual working on this. I think conjectures on people's plans don't belong in the documentation. |
| 2771 ↗ | (On Diff #210101) | Everything is relative. I would keep this 100% factual: "there are restrictions". This is not a sales pitch :). |
| 2779 ↗ | (On Diff #210101) | I find -std=c++ confusing/misleading. Maybe we should change the way -cl-std works so we can have -std=clc++ and -cl-std=c++? |
Comment Actions
Would it be ok if I fix those in a separate commit? I would really like to commit the core part before the release branch is taken.
Comment Actions
Would it be ok if I fix those in a separate commit? I would really like to commit the core part before the release branch is taken.
I'm fine with this as long as we can continue the discussion for open comments in this review. Accepting the revision as I don't seem to be able to go back on my request for another patch.
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 327 ↗ | (On Diff #215106) | FYI, this is not part of my change. It was just hard to produce combined diff. |
| 1541 ↗ | (On Diff #210101) | I think it's valuable especially for metaprogramming. I was being asked about it. |
| 1553 ↗ | (On Diff #210101) | I need to understand what needs re-wording |
| 1557 ↗ | (On Diff #210101) | I prefer to use __ for two reasons (1) it's more official in OpenCL docs and tutorials (2) I sometimes omit the noun and just use it as a short term in the text. |
| 1564 ↗ | (On Diff #210101) | It's complicated to explain but basically some cast operators perform implicit conversions of what they are not expected to do because implicit conversions are allowed everywhere even if the operator isn't intended to do the conversion explicitly. Similar example in C++, most of operators accept converting to const objects. |
| 1565 ↗ | (On Diff #210101) |
I think it's ok to document full extension even if it's WIP. |
| 1577 ↗ | (On Diff #210101) | No constant specify memory region but const indicates that object is not changed during lifetime. You can cast away const but you can't convert constant object to any other address space. |
| 1761 ↗ | (On Diff #210101) | Not sure whether you imply any action here. |
| 1779 ↗ | (On Diff #210101) | The Itanium C++ ABIs for destructors are different and we haven't got it working yet for OpenCL. I would leave the description as is for now. |
| docs/UsersManual.rst | ||
| 2771 ↗ | (On Diff #210101) | I think it's fair to say few restrictions because the majority of C++ just works in OpenCL. |
| docs/LanguageExtensions.rst | ||
|---|---|---|
| 1561 ↗ | (On Diff #215106) | "For OpenCL it means that implicit conversions are allowed from a named address space except for conversion from the `__constant to the __generic` address space." I would omit "that is a superset of all others except for `__constant`" as that is already documented in the OpenCL spec and it might confuse readers here. If you want to keep it, I suggest rephrasing it as a separate sentence. |
| 1563 ↗ | (On Diff #215106) | +The+ `__constant` address space |
| 1570 ↗ | (On Diff #215106) | "C-style casts follow" |
| 1630 ↗ | (On Diff #215106) | +the+ `__generic` address space (also in the next few lines) |
| 1647 ↗ | (On Diff #215106) | +an+ address space qualifier |
| 1650 ↗ | (On Diff #215106) | ithe -> the |
| 1651 ↗ | (On Diff #215106) | Duplicate "to" (to to) |
| 1652 ↗ | (On Diff #215106) | Add comma: |
| 1715 ↗ | (On Diff #215106) | Add comma: |
| 1730 ↗ | (On Diff #215106) | Once a template has been instantiated, regular restrictions for address spaces will apply. |
| 1746 ↗ | (On Diff #215106) | the `__private` address space |
| 1747 ↗ | (On Diff #215106) | some other -> another |
| 1748 ↗ | (On Diff #215106) | it's -> it is add comma: |
| 1776 ↗ | (On Diff #215106) | enqueue *a* constructor |
| 1782 ↗ | (On Diff #215106) | Add comma: |
| 1793 ↗ | (On Diff #215106) | Add comma: |
| 1794 ↗ | (On Diff #215106) | contain +the+ |
| docs/UsersManual.rst | ||
| 2765 ↗ | (On Diff #215106) | Clang9 -> Clang 9 (with space). |
| 2776 ↗ | (On Diff #215106) | I wouldn't say "new" mode as this is part of a persistent user manual. |
| 2778 ↗ | (On Diff #215106) | Again I would avoid "new mode". "To enable the C++ for OpenCL mode," Also: pass *one of* the following command line options when compiling a `.cl` So in total: |
| 2769 ↗ | (On Diff #210101) |
Agreed. |
| 2771 ↗ | (On Diff #210101) | I agree with @kpet and also prefer "There are restrictions" instead of an unquantified statement. |
| docs/UsersManual.rst | ||
|---|---|---|
| 2771 ↗ | (On Diff #210101) | Ok, I don't understand what value does it bring to make information less specific but potentially it's not important enough to continue the argument. The idea of this sentence was indeed to point out that the mode is just very close to C++ with very few restrictions. This isn't a program so it can't have a formal definition for every statement. :P |