clang/docs/OpenMPSupport.rst

   1 .. raw:: html
   2
   3   <style type="text/css">
   4     .none { background-color: #FFCCCC }
   5     .part { background-color: #FFFF99 }
   6     .good { background-color: #CCFF99 }
   7   </style>
   8
   9 .. role:: none
  10 .. role:: part
  11 .. role:: good
  12
  13 .. contents::
  14    :local:
  15
  16 OpenMP Support
  17 ==============
  18
  19 Clang fully supports OpenMP 4.5. Clang supports offloading to X86_64, AArch64,
  20 PPC64[LE] and has `basic support for Cuda devices`_.
  21
  22 * #pragma omp declare simd: :part:`Partial`.  We support parsing/semantic
  23   analysis + generation of special attributes for X86 target, but still
  24   missing the LLVM pass for vectorization.
  25
  26 In addition, the LLVM OpenMP runtime `libomp` supports the OpenMP Tools
  27 Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS.
  28
  29 For the list of supported features from OpenMP 5.0 see `OpenMP implementation details`_.
  30
  31 General improvements
  32 ====================
  33 - New collapse clause scheme to avoid expensive remainder operations.
  34   Compute loop index variables after collapsing a loop nest via the
  35   collapse clause by replacing the expensive remainder operation with
  36   multiplications and additions.
  37
  38 - The default schedules for the `distribute` and `for` constructs in a
  39   parallel region and in SPMD mode have changed to ensure coalesced
  40   accesses. For the `distribute` construct, a static schedule is used
  41   with a chunk size equal to the number of threads per team (default
  42   value of threads or as specified by the `thread_limit` clause if
  43   present). For the `for` construct, the schedule is static with chunk
  44   size of one.
  45
  46 - Simplified SPMD code generation for `distribute parallel for` when
  47   the new default schedules are applicable.
  48
  49 - When using the collapse clause on a loop nest the default behavior
  50   is to automatically extend the representation of the loop counter to
  51   64 bits for the cases where the sizes of the collapsed loops are not
  52   known at compile time. To prevent this conservative choice and use
  53   at most 32 bits, compile your program with the
  54   `-fopenmp-optimistic-collapse`.
  55
  56 .. _basic support for Cuda devices:
  57
  58 Cuda devices support
  59 ====================
  60
  61 Directives execution modes
  62 --------------------------
  63
  64 Clang code generation for target regions supports two modes: the SPMD and
  65 non-SPMD modes. Clang chooses one of these two modes automatically based on the
  66 way directives and clauses on those directives are used. The SPMD mode uses a
  67 simplified set of runtime functions thus increasing performance at the cost of
  68 supporting some OpenMP features. The non-SPMD mode is the most generic mode and
  69 supports all currently available OpenMP features. The compiler will always
  70 attempt to use the SPMD mode wherever possible. SPMD mode will not be used if:
  71
  72    - The target region contains user code (other than OpenMP-specific
  73      directives) in between the `target` and the `parallel` directives.
  74
  75 Data-sharing modes
  76 ------------------
  77
  78 Clang supports two data-sharing models for Cuda devices: `Generic` and `Cuda`
  79 modes. The default mode is `Generic`. `Cuda` mode can give an additional
  80 performance and can be activated using the `-fopenmp-cuda-mode` flag. In
  81 `Generic` mode all local variables that can be shared in the parallel regions
  82 are stored in the global memory. In `Cuda` mode local variables are not shared
  83 between the threads and it is user responsibility to share the required data
  84 between the threads in the parallel regions.
  85
  86
  87 Features not supported or with limited support for Cuda devices
  88 ---------------------------------------------------------------
  89
  90 - Cancellation constructs are not supported.
  91
  92 - Doacross loop nest is not supported.
  93
  94 - User-defined reductions are supported only for trivial types.
  95
  96 - Nested parallelism: inner parallel regions are executed sequentially.
  97
  98 - Static linking of libraries containing device code is not supported yet.
  99
 100 - Automatic translation of math functions in target regions to device-specific
 101   math functions is not implemented yet.
 102
 103 - Debug information for OpenMP target regions is supported, but sometimes it may
 104   be required to manually specify the address class of the inspected variables.
 105   In some cases the local variables are actually allocated in the global memory,
 106   but the debug info may be not aware of it.
 107
 108
 109 .. _OpenMP implementation details:
 110
 111 OpenMP 5.0 Implementation Details
 112 =================================
 113
 114 The following table provides a quick overview over various OpenMP 5.0 features
 115 and their implementation status. Please contact *openmp-dev* at
 116 *lists.llvm.org* for more information or if you want to help with the
 117 implementation.
 118
 119 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 120 |Category                      | Feature                                                      | Status                   | Reviews                                                               |
 121 +==============================+==============================================================+==========================+=======================================================================+
 122 | loop extension               | support != in the canonical loop form                        | :good:`done`             | D54441                                                                |
 123 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 124 | loop extension               | #pragma omp loop (directive)                                 | :part:`worked on`        |                                                                       |
 125 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 126 | loop extension               | collapse imperfectly nested loop                             | :good:`done`             |                                                                       |
 127 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 128 | loop extension               | collapse non-rectangular nested loop                         | :good:`done`             |                                                                       |
 129 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 130 | loop extension               | C++ range-base for loop                                      | :good:`done`             |                                                                       |
 131 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 132 | loop extension               | clause: if for SIMD directives                               | :good:`done`             |                                                                       |
 133 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 134 | loop extension               | inclusive scan extension (matching C++17 PSTL)               | :none:`unclaimed`        |                                                                       |
 135 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 136 | memory mangagement           | memory allocators                                            | :good:`done`             | r341687,r357929                                                       |
 137 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 138 | memory mangagement           | allocate directive and allocate clause                       | :good:`done`             | r355614,r335952                                                       |
 139 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 140 | OMPD                         | OMPD interfaces                                              | :part:`not upstream`     | https://github.com/OpenMPToolsInterface/LLVM-openmp/tree/ompd-tests   |
 141 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 142 | OMPT                         | OMPT interfaces                                              | :part:`mostly done`      |                                                                       |
 143 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 144 | thread affinity extension    | thread affinity extension                                    | :good:`done`             |                                                                       |
 145 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 146 | task extension               | taskloop reduction                                           | :good:`done`             |                                                                       |
 147 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 148 | task extension               | task affinity                                                | :part:`not upstream`     |                                                                       |
 149 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 150 | task extension               | clause: depend on the taskwait construct                     | :part:`worked on`        |                                                                       |
 151 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 152 | task extension               | depend objects and detachable tasks                          | :part:`worked on`        |                                                                       |
 153 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 154 | task extension               | mutexinoutset dependence-type for tasks                      | :good:`done`             | D53380,D57576                                                         |
 155 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 156 | task extension               | combined taskloop constructs                                 | :good:`done`             |                                                                       |
 157 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 158 | task extension               | master taskloop                                              | :good:`done`             |                                                                       |
 159 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 160 | task extension               | parallel master taskloop                                     | :good:`done`             |                                                                       |
 161 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 162 | task extension               | master taskloop simd                                         | :good:`done`             |                                                                       |
 163 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 164 | task extension               | parallel master taskloop simd                                | :good:`done`             |                                                                       |
 165 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 166 | SIMD extension               | atomic and simd constructs inside SIMD code                  | :good:`done`             |                                                                       |
 167 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 168 | SIMD extension               | SIMD nontemporal                                             | :good:`done`             |                                                                       |
 169 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 170 | device extension             | infer target functions from initializers                     | :part:`worked on`        |                                                                       |
 171 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 172 | device extension             | infer target variables from initializers                     | :part:`worked on`        |                                                                       |
 173 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 174 | device extension             | OMP_TARGET_OFFLOAD environment variable                      | :good:`done`             | D50522                                                                |
 175 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 176 | device extension             | support full 'defaultmap' functionality                      | :good:`done`             | D69204                                                                |
 177 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 178 | device extension             | device specific functions                                    | :good:`done`             |                                                                       |
 179 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 180 | device extension             | clause: device_type                                          | :good:`done`             |                                                                       |
 181 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 182 | device extension             | clause: in_reduction                                         | :part:`worked on`        | r308768                                                               |
 183 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 184 | device extension             | omp_get_device_num()                                         | :part:`worked on`        | D54342                                                                |
 185 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 186 | device extension             | structure mapping of references                              | :none:`unclaimed`        |                                                                       |
 187 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 188 | device extension             | nested target declare                                        | :good:`done`             | D51378                                                                |
 189 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 190 | device extension             | implicitly map 'this' (this[:1])                             | :good:`done`             | D55982                                                                |
 191 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 192 | device extension             | allow access to the reference count (omp_target_is_present)  | :part:`worked on`        |                                                                       |
 193 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 194 | device extension             | requires directive (unified shared memory)                   | :good:`done`             |                                                                       |
 195 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 196 | device extension             | clause: unified_address, unified_shared_memory               | :good:`done`             | D52625,D52359                                                         |
 197 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 198 | device extension             | clause: reverse_offload                                      | :none:`unclaimed parts`  | D52780                                                                |
 199 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 200 | device extension             | clause: atomic_default_mem_order                             | :none:`unclaimed parts`  | D53513                                                                |
 201 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 202 | device extension             | clause: dynamic_allocators                                   | :none:`unclaimed parts`  | D53079                                                                |
 203 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 204 | device extension             | user-defined mappers                                         | :part:`worked on`        | D56326,D58638,D58523,D58074,D60972,D59474                             |
 205 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 206 | device extension             | mapping lambda expression                                    | :good:`done`             | D51107                                                                |
 207 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 208 | device extension             | clause: use_device_addr for target data                      | :part:`worked on`        |                                                                       |
 209 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 210 | device extension             | map(replicate) or map(local) when requires unified_shared_me | :part:`worked on`        | D55719,D55892                                                         |
 211 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 212 | device extension             | teams construct on the host device                           | :part:`worked on`        | Clang part is done, r371553.                                          |
 213 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 214 | device extension             | support non-contiguous array sections for target update      | :part:`worked on`        |                                                                       |
 215 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 216 | atomic extension             | hints for the atomic construct                               | :part:`worked on`        | D51233                                                                |
 217 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 218 | base language                | C11 support                                                  | :none:`unclaimed`        |                                                                       |
 219 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 220 | base language                | C++11/14/17 support                                          | :part:`worked on`        |                                                                       |
 221 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 222 | base language                | lambda support                                               | :good:`done`             |                                                                       |
 223 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 224 | misc extension               | array shaping                                                | :none:`unclaimed`        |                                                                       |
 225 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 226 | misc extension               | library shutdown (omp_pause_resource[_all])                  | :none:`unclaimed parts`  | D55078                                                                |
 227 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 228 | misc extension               | metadirectives                                               | :none:`worked on`        |                                                                       |
 229 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 230 | misc extension               | conditional modifier for lastprivate clause                  | :part:`worked on`        |                                                                       |
 231 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 232 | misc extension               | user-defined function variants                               | :part:`worked on`        | D67294, D64095                                                        |
 233 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 234 | misc extensions              | pointer/reference to pointer based array reductions          | :none:`unclaimed`        |                                                                       |
 235 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 236 | misc extensions              | prevent new type definitions in clauses                      | :none:`unclaimed`        |                                                                       |
 237 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 238
 239
 240 OpenMP 5.1 Implementation Details
 241 =================================
 242
 243 The following table provides a quick overview over various OpenMP 5.1 features
 244 and their implementation status, as defined in the technical report 8 (TR8).
 245 Please contact *openmp-dev* at *lists.llvm.org* for more information or if you
 246 want to help with the implementation.
 247
 248 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 249 |Category                      | Feature                                                      | Status                   | Reviews                                                               |
 250 +==============================+==============================================================+==========================+=======================================================================+
 251 | misc extension               | user-defined function variants with #ifdef protection        | :part:`worked on`        | D71179                                                                |
 252 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 253 | loop extension               | Loop tiling transformation                                   | :part:`claimed`          |                                                                       |
 254 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+