openmp/docs/index.rst

   1 .. title:: Welcome to the documentation of OpenMP in LLVM!
   2
   3 .. note::
   4    This document is a work in progress and most of the expected content is not
   5    yet available. While you can expect changes, we always welcome feedback and
   6    additions. Please post on the `Discourse forums (Runtimes -
   7    OpenMP) <https://discourse.llvm.org/c/runtimes/openmp/35>`__..
   8
   9 .. toctree::
  10    :hidden:
  11    :maxdepth: 1
  12
  13    LLVM/OpenMP Documentation <self>
  14
  15
  16 LLVM/OpenMP Design & Overview
  17 =============================
  18
  19 OpenMP impacts various parts of the LLVM project, from the frontends (`Clang
  20 <https://clang.llvm.org/docs/OpenMPSupport.html>`_ and Flang), through
  21 middle-end :ref:`optimizations <llvm_openmp_optimizations>`, up to the
  22 multitude of available :ref:`OpenMP runtimes <openmp_runtimes>`.
  23
  24 A high-level overview of OpenMP in LLVM can be found :doc:`here <design/Overview>`.
  25
  26 .. toctree::
  27    :hidden:
  28    :maxdepth: 1
  29
  30    design/Overview
  31
  32 OpenACC Support
  33 ===============
  34
  35 :doc:`OpenACC support <openacc/Overview>` is under development for
  36 both Flang and Clang.  For this purpose, LLVM's OpenMP runtimes are
  37 being extended to serve as OpenACC runtimes.  In some cases, Clang
  38 supports :doc:`OpenMP extensions <openacc/OpenMPExtensions>` to make
  39 the additional functionality also available in OpenMP applications.
  40
  41 .. toctree::
  42    :hidden:
  43    :maxdepth: 1
  44
  45    openacc/Overview
  46
  47 LLVM/OpenMP Optimizations
  48 =========================
  49
  50 LLVM, since `version 11 <https://releases.llvm.org/download.html#11.0.0>`_ (12 Oct
  51 2020), has an :doc:`OpenMP-Aware optimization pass <optimizations/OpenMPOpt>`
  52 as well as the ability to :doc:`perform "scalar optimizations" across OpenMP region
  53 boundaries <optimizations/OpenMPUnawareOptimizations>`.
  54
  55 In-depth discussion of the topic can be found :doc:`here <optimizations/Overview>`.
  56
  57 .. toctree::
  58    :hidden:
  59    :maxdepth: 1
  60
  61    optimizations/Overview
  62
  63 LLVM/OpenMP Optimization Remarks
  64 ================================
  65
  66 LLVM has an elaborate ecosystem around `analysis and optimization remarks
  67 <https://llvm.org/docs/Remarks.html>`_ issues during
  68 compilation. The remarks can be enabled from the clang frontend `[1]`_ `[2]`_
  69 in various formats `[3]`_ `[4]`_ to be used by tools, i.a., `opt-viewer` or
  70 `llvm-opt-report` (dated).
  71
  72 The OpenMP optimizations in LLVM have been developed with remark support as a
  73 priority. For a list of OpenMP specific remarks and more information on them,
  74 please refer to :doc:`remarks/OptimizationRemarks`.
  75
  76
  77 .. _`[1]`: https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports
  78 .. _`[2]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags
  79 .. _`[3]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file
  80 .. _`[4]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record
  81
  82 + `[1]`_ https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports
  83 + `[2]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags
  84 + `[3]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file
  85 + `[4]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record
  86
  87
  88 .. toctree::
  89    :hidden:
  90    :maxdepth: 1
  91
  92    remarks/OptimizationRemarks
  93
  94 OpenMP Command-Line Argument Reference
  95 ======================================
  96 In addition to the
  97 `Clang command-line argument reference <https://clang.llvm.org/docs/ClangCommandLineReference.html>`_
  98 we also recommend the OpenMP
  99 :doc:`command-line argument reference <CommandLineArgumentReference>`
 100 page that offers a detailed overview of options specific to OpenMP. It also
 101 contains a list of OpenMP offloading related command-line arguments.
 102
 103
 104 .. toctree::
 105    :hidden:
 106    :maxdepth: 1
 107
 108    CommandLineArgumentReference
 109
 110 Support, Getting Involved, and Frequently Asked Questions (FAQ)
 111 ===============================================================
 112
 113 Dealing with OpenMP can be complicated. For help with the setup of an OpenMP
 114 (offload) capable compiler toolchain, its usage, and common problems, consult
 115 the :doc:`Support and FAQ <SupportAndFAQ>` page.
 116
 117 We also encourage everyone interested in OpenMP in LLVM to :doc:`get involved
 118 <SupportAndFAQ>`.
 119
 120
 121 .. toctree::
 122    :hidden:
 123    :maxdepth: 1
 124
 125    SupportAndFAQ
 126
 127 Release Notes
 128 =============
 129
 130 The current (in-progress) release notes can be found :doc:`here <ReleaseNotes>` while
 131 release notes for releases, starting with LLVM 12, will be available on `the
 132 Download Page <https://releases.llvm.org/download.html>`_.
 133
 134
 135 .. toctree::
 136    :hidden:
 137    :maxdepth: 1
 138
 139    In-Progress ReleaseNotes <ReleaseNotes>