[OpenMP][Docs] Provide implementation status details

[jdoerfert]

Summary

This adds a more fine-grained list of OpenMP features with their
implementation status and associated reviews/commits.

[ABataev]

The scheme itself looks good in general. Just as an improvement, it would be good to use coloring for the feature status.
Also, what's the difference between claimed, mostly done and done?

clang/docs/OpenMPSupport.rst

153 ↗

(On Diff #208530)

I'm working on this feature, but don't know when it's going to be ready.

219 ↗

(On Diff #208530)

Do we really need Fortran stuff here?

237 ↗

(On Diff #208530)

Not sure 100%, but seems to me it is not done.

[jdoerfert]

In D64375#1574662, @ABataev wrote:

The scheme itself looks good in general.

Good. Once we agreed on a scheme we can improve the actual process, excel sheet, generator script, etc. (see also below).

Just as an improvement, it would be good to use coloring for the feature status.

I'll try to add coloring.

Also, what's the difference between claimed, mostly done and done?

Disclaimer: I used a script to determine what the columns in the excel document mean. There is a good chance I got some wrong and it only reflects the information in the document.

I basically used the following logic in this order:

1. If all non-empty columns contain the word "done", mark it as "done".
2. If all non-empty columns contain "mostly complete", mark it as "mostly done".
3. If there are non-empty columns, mark it as "claimed", e.g., someone is working on it.
4. If there are only empty columns, mark it as "unclaimed", e.g., not being worked on right now.

I think when we go through the excel document now with this use case in mind and fill the empty columns appropriately, some errors will dissapear.

clang/docs/OpenMPSupport.rst

153 ↗

(On Diff #208530)

That will then be noted in the excel sheet (see general comment).

219 ↗

(On Diff #208530)

No, I already filtered by hand, my mistake. Will automate it.

[ABataev]

In D64375#1574698, @jdoerfert wrote:

In D64375#1574662, @ABataev wrote:

The scheme itself looks good in general.

Good. Once we agreed on a scheme we can improve the actual process, excel sheet, generator script, etc. (see also below).

Just as an improvement, it would be good to use coloring for the feature status.

I'll try to add coloring.

Also, what's the difference between claimed, mostly done and done?

Disclaimer: I used a script to determine what the columns in the excel document mean. There is a good chance I got some wrong and it only reflects the information in the document.

I basically used the following logic in this order:

1. If all non-empty columns contain the word "done", mark it as "done".
2. If all non-empty columns contain "mostly complete", mark it as "mostly done".
3. If there are non-empty columns, mark it as "claimed", e.g., someone is working on it.
4. If there are only empty columns, mark it as "unclaimed", e.g., not being worked on right now.

I think when we go through the excel document now with this use case in mind and fill the empty columns appropriately, some errors will dissapear.

Ok, I see. I will provide more correct feature status tomorrow, if you want. Currently it is not quite correct/full.

[lebedev.ri]

Nice, thank you for working on this!

It would be also good to have a not OpenMP-5 specific, but an overview table - which OpenMP thingy was supported starting
with which Clang version, very much like https://clang.llvm.org/cxx_status.html / https://libcxx.llvm.org/cxx1z_status.html,
i needed that a few times.

[Hahnfeld]

clang/docs/OpenMPSupport.rst

165 ↗

(On Diff #208530)

This is not correct, at least it's not yet upstream.

173 ↗

(On Diff #208530)

This is wrong as well, at least not upstream (we have multiple versions in local repositories).

[ABataev]

clang/docs/OpenMPSupport.rst

161 ↗

(On Diff #208530)

Done

163 ↗

(On Diff #208530)

Done

175–177 ↗

(On Diff #208530)

I don't remember anything related to these items. Seems to me, they are unclaimed

201 ↗

(On Diff #208530)

Seems to me it is unclaimed

205 ↗

(On Diff #208530)

Can't find this in the standard.

207 ↗

(On Diff #208530)

Done.

213 ↗

(On Diff #208530)

Done

215 ↗

(On Diff #208530)

Done

233 ↗

(On Diff #208530)

Done

243 ↗

(On Diff #208530)

This is just the runtime part, the compiler does not support this

245–247 ↗

(On Diff #208530)

Not sure that there are special requirements for this in the standard

249 ↗

(On Diff #208530)

lambdas are supported.

[kkwli0]

clang/docs/OpenMPSupport.rst

205 ↗

(On Diff #208530)

Section 2.12.7

233 ↗

(On Diff #208530)

Do we support the behavior in 318:7-14?

237 ↗

(On Diff #208530)

I think we still need the codegen patch and I am not sure about the runtime part.

243 ↗

(On Diff #208530)

Since it is a hint according to the specification, I guess it is up to us whether we want to declare this feature done or not. If we do that, we should mention it in the limitation section.

[ABataev]

clang/docs/OpenMPSupport.rst

205 ↗

(On Diff #208530)

Then it is unclaimed, I think.

233 ↗

(On Diff #208530)

Yes.

237 ↗

(On Diff #208530)

I don't think it works with unified memory since we don't fully support unified memory.

243 ↗

(On Diff #208530)

Still, compiler does not use this. WE can mark this as partial, but definitely not done.

[jdoerfert]

I will update the table (hopefully tomorrow) and we can then see if we commit it and change it in-place or if we have more initial feedback.

Thanks everyone for providing all this information!

@lebedev.ri I'd like to see if we can transition this one into a more generic one with version numbers etc. Is that OK?

[lebedev.ri]

In D64375#1577153, @jdoerfert wrote:

@lebedev.ri I'd like to see if we can transition this one into a more generic one with version numbers etc. Is that OK?

I have no further comment at the moment.

[jdoerfert]

Add colors, updates according to comments

[jdoerfert]

clang/docs/OpenMPSupport.rst

163 ↗

(On Diff #208530)

Here and above, if there are more revisions, please feel free to add them.

165 ↗

(On Diff #208530)

Is there anything upstreamed? What should I put for status and revisions/reviews?

205 ↗

(On Diff #208530)

The excel sheet did assign some of the claimed tasks to people/companies so I will keep them claimed for now and we should ask if they are actually being worked on or not.

207 ↗

(On Diff #208530)

I only found a 2017 patch which I added but is this completely done? The category suggest this is device related but I did not find device related code.

[kkwli0]

clang/docs/OpenMPSupport.rst

184 ↗

(On Diff #209073)

parallell -> parallel

188 ↗

(On Diff #209073)

parallell -> parallel

[ABataev]

clang/docs/OpenMPSupport.rst

207 ↗

(On Diff #208530)

Ah, I missed that this is device extension. Then it is unclaimed.

[kkwli0]

clang/docs/OpenMPSupport.rst

198 ↗

(On Diff #209073)

Change OMP_TARGET_FALLBACK to OMP_TARGET_OFFLOAD which is in the spec.

[jdoerfert]

Fixes according to comments

[Hahnfeld]

clang/docs/OpenMPSupport.rst

250 ↗

(On Diff #209089)

I think this should say partial, it's present in libomp after D55078.

198 ↗

(On Diff #209073)

This is done, see the linked revision.

165 ↗

(On Diff #208530)

I don't think there's a review yet. @protze.joachim ?

[jdoerfert]

I'll add @Hahnfeld comments, anything else? If not, can someone approve this and we do separate reviews for improvements?

[ABataev]

In D64375#1601163, @jdoerfert wrote:

I'll add @Hahnfeld comments, anything else? If not, can someone approve this and we do separate reviews for improvements?

Update revision and I'll approve it.

[jdoerfert]

Improve based on two comments by @Hahnfeld

[Hahnfeld]

clang/docs/OpenMPSupport.rst

222–226 ↗

(On Diff #212957)

Do we have CodeGen for this? I only remember Sema support...

Also, reverse_offload is listed again below as unclaimed.

250 ↗

(On Diff #209089)

ping, I still think partial is more correct

233 ↗

(On Diff #208530)

ping @jdoerfert

[ABataev]

clang/docs/OpenMPSupport.rst

222–226 ↗

(On Diff #212957)

We don't have codegen for this. Same for the reverse_offload and atomic_default_mem_order

[RaviNarayanaswamy]

clang/docs/OpenMPSupport.rst

222–226 ↗

(On Diff #212957)

As Alexey said codegen is not done so maybe change it to partial.
Regardng reverse_offload, it is debate able whether keep it unclaimed or make it partial. Yes Sema is done but the hard part for which nobody has claimed is codegen and libomptarget. At least for the getting this initial document checked in we should keep it as unclaimed. Do you have a strong objection against this.

[jdoerfert]

Update according to comments

[ABataev]

clang/docs/OpenMPSupport.rst

204 ↗

(On Diff #217631)

This feature is implemented already

[jdoerfert]

clang/docs/OpenMPSupport.rst

204 ↗

(On Diff #217631)

If we wait longer, we can always update this patch. Maybe we should upstream it and update it online.

@RaviNarayanaswamy @kkwli0 @ABataev

[ABataev]

LG

clang/docs/OpenMPSupport.rst

204 ↗

(On Diff #217631)

Add the latest info and commit it.

[kkwli0]

clang/docs/OpenMPSupport.rst

204 ↗

(On Diff #217631)

Agreed.

[protze.joachim]

clang/docs/OpenMPSupport.rst

165 ↗

(On Diff #208530)

There is no review yet. Implementation is available in
https://github.com/OpenMPToolsInterface/LLVM-openmp/tree/ompd-tests

cfe/trunk/docs/OpenMPSupport.rst

 .. raw:: html
 
   <style type="text/css">
     .none { background-color: #FFCCCC }
-    .partial { background-color: #FFFF99 }
+    .part { background-color: #FFFF99 }
     .good { background-color: #CCFF99 }
   </style>
 
 .. role:: none
-.. role:: partial
+.. role:: part
 .. role:: good
 
 .. contents::
    :local:
 
 ==================
 OpenMP Support
 ==================
 
-Clang supports the following OpenMP 5.0 features
+Clang supports the following OpenMP 5.0 features (see also `OpenMP implementation details`_):
 
 * The `reduction`-based clauses in the `task` and `target`-based directives.
 
 * Support relational-op != (not-equal) as one of the canonical forms of random
   access iterator.
 
 * Support for mapping of the lambdas in target regions.
 
 * Parsing/sema analysis for the requires directive.
 
 * Nested declare target directives.
 
 * Make the `this` pointer implicitly mapped as `map(this[:1])`.
 
 * The `close` *map-type-modifier*.
 
 Clang fully supports OpenMP 4.5. Clang supports offloading to X86_64, AArch64,
 PPC64[LE] and has `basic support for Cuda devices`_.
 
-* #pragma omp declare simd: :partial:`Partial`.  We support parsing/semantic
+* #pragma omp declare simd: :part:`Partial`.  We support parsing/semantic
   analysis + generation of special attributes for X86 target, but still
   missing the LLVM pass for vectorization.
 
 In addition, the LLVM OpenMP runtime `libomp` supports the OpenMP Tools
 Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS.
 
 General improvements
 --------------------

 - Automatic translation of math functions in target regions to device-specific
   math functions is not implemented yet.
 
 - Debug information for OpenMP target regions is supported, but sometimes it may
   be required to manually specify the address class of the inspected variables.
   In some cases the local variables are actually allocated in the global memory,
   but the debug info may be not aware of it.
 
+
+.. _OpenMP implementation details:
+
+OpenMP 5.0 Implementation Details
+---------------------------------
+
+The following table provides a quick overview over various OpenMP 5.0 features
+and their implementation status. Please contact *openmp-dev* at
+*lists.llvm.org* for more information or if you want to help with the
+implementation.
+
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+|Category                      | Feature                                                      | Status                   | Reviews                                                               |
++==============================+==============================================================+==========================+=======================================================================+
+| loop extension               | support != in the canonical loop form                        | :good:`done`             | D54441                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | #pragma omp loop (directive)                                 | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | collapse imperfectly nested loop                             | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | collapse non-rectangular nested loop                         | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | C++ range-base for loop                                      | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | clause: nosimd for SIMD directives                           | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| loop extension               | inclusive scan extension (matching C++17 PSTL)               | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| memory mangagement           | memory allocators                                            | :good:`done`             | r341687,r357929                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| memory mangagement           | allocate directive and allocate clause                       | :good:`done`             | r355614,r335952                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| OMPD                         | OMPD interfaces                                              | :part:`not upstream`     | https://github.com/OpenMPToolsInterface/LLVM-openmp/tree/ompd-tests   |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| OMPT                         | OMPT interfaces                                              | :part:`mostly done`      |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| thread affinity extension    | thread affinity extension                                    | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | taskloop reduction                                           | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | task affinity                                                | :part:`not upstream`     |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | clause: depend on the taskwait construct                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | depend objects and detachable tasks                          | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | mutexinoutset dependence-type for tasks                      | :good:`done`             | D53380,D57576                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | combined taskloop constructs                                 | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | master taskloop                                              | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | parallel master taskloop                                     | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | master taskloop simd                                         | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| task extension               | parallel master taskloop simd                                | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| SIMD extension               | atomic and critical constructs inside SIMD code              | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| SIMD extension               | SIMD nontemporal                                             | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | infer target functions from initializers                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | infer target variables from initializers                     | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | OMP_TARGET_OFFLOAD environment variable                      | :good:`done`             | D50522                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | support full 'defaultmap' functionality                      | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | device specific functions                                    | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: device_type                                          | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: in_reduction                                         | :none:`unclaimed`        | r308768                                                               |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | omp_get_device_num()                                         | :part:`worked on`        | D54342                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | structure mapping of references                              | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | nested target declare                                        | :good:`done`             | D51378                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | implicitly map 'this' (this[:1])                             | :good:`done`             | D55982                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | allow access to the reference count (omp_target_is_present)  | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | requires directive (unified shared memory)                   | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: unified_address, unified_shared_memory               | :part:`worked on`        | D52625,D52359                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: reverse_offload                                      | :none:`unclaimed parts`  | D52780                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: atomic_default_mem_order                             | :none:`unclaimed parts`  | D53513                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: dynamic_allocators                                   | :none:`unclaimed parts`  | D53079                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | user-defined mappers                                         | :part:`worked on`        | D56326,D58638,D58523,D58074,D60972,D59474                             |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | mapping lambda expression                                    | :good:`done`             | D51107                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | clause: use_device_addr for target data                      | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | map(replicate) or map(local) when requires unified_shared_me | :part:`worked on`        | D55719,D55892                                                         |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| device extension             | teams construct on the host device                           | :part:`worked on`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| atomic extension             | hints for the atomic construct                               | :part:`worked on`        | D51233                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | C11 support                                                  | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | C++11/14/17 support                                          | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| base language                | lambda support                                               | :good:`done`             |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | array shaping                                                | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | library shutdown (omp_pause_resource[_all])                  | :none:`unclaimed parts`  | D55078                                                                |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | metadirectives                                               | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | conditional modifier for lastprivate clause                  | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extension               | user-defined function variants                               | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extensions              | pointer/reference to pointer based array reductions          | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
+| misc extensions              | prevent new type definitions in clauses                      | :none:`unclaimed`        |                                                                       |
++------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+