diff --git a/openmp/docs/ReleaseNotes.rst b/openmp/docs/ReleaseNotes.rst --- a/openmp/docs/ReleaseNotes.rst +++ b/openmp/docs/ReleaseNotes.rst @@ -1,19 +1,18 @@ =========================== -OpenMP 11.0.0 Release Notes +OpenMP 12.0.0 Release Notes =========================== -.. contents:: - :local: .. warning:: - These are in-progress notes for the upcoming LLVM 11.0.0 release. + These are in-progress notes for the upcoming LLVM 12.0.0 release. Release notes for previous releases can be found on `the Download Page `_. + Introduction ============ -This document contains the release notes for the OpenMP runtime, release 11.0.0. +This document contains the release notes for the OpenMP runtime, release 12.0.0. Here we describe the status of openmp, including major improvements from the previous release. All openmp releases may be downloaded from the `LLVM releases web site `_. @@ -21,25 +20,4 @@ Non-comprehensive list of changes in this release ================================================= -5.0 features ------------- - -* ... - -5.1 features ------------- - -* ... - -OMPT Improvements ------------------ - -* Added OMPT callbacks for doacross loops, detached tasks -* Added handling for mutexinoutset dependencies - -OMPT-based Tools ----------------- - -* Added ompt-multiplex.h as a header-only OMPT-tool to support nesting of OMPT - tools. (see openmp/tools/multiplex) diff --git a/openmp/docs/SupportAndFAQ.rst b/openmp/docs/SupportAndFAQ.rst new file mode 100644 --- /dev/null +++ b/openmp/docs/SupportAndFAQ.rst @@ -0,0 +1,4 @@ +Support And FAQ +=============== + + diff --git a/openmp/docs/_themes/llvm-openmp-theme/layout.html b/openmp/docs/_themes/llvm-openmp-theme/layout.html new file mode 100644 --- /dev/null +++ b/openmp/docs/_themes/llvm-openmp-theme/layout.html @@ -0,0 +1,109 @@ +{# + llvm-openmp-theme/layout.html + ~~~~~~~~~~~~~~~~~ + + Sphinx layout template for LLVM/OpenMP which as an almost identical clone + of the agogo theme, originally written by Andi Albrecht. + + :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +#} +{%- extends "basic/layout.html" %} + +{% block header %} + +{% endblock %} + + +{%- macro llvm_openmp_sidebar() %} + {%- block sidebartoc %} +

{{ _('Table of Contents') }}

+ {{ toctree(includehidden=True, titles_only=True, maxdepth=2) }} + {%- endblock %} + {%- block sidebarsearch %} +
+

{{ _('Search') }}

+
+ + +
+
+ {%- endblock %} +{% endmacro %} + +{% block content %} +
+
+ {%- if not theme_rightsidebar|tobool %} +
+ {{ llvm_openmp_sidebar() }} +
+ {%- endif %} +
+ {%- block document %} + {{ super() }} + {%- endblock %} +
+ {%- if theme_rightsidebar|tobool %} +
+ {{ llvm_openmp_sidebar() }} +
+ {%- endif %} +
+
+
+{% endblock %} + +{% block footer %} +
+
+
+
+ HOME + {{ reldelim2 }} + {%- for rellink in rellinks|reverse %} + {{ rellink[3] }} + {%- if not loop.last %}{{ reldelim2 }}{% endif %} + {%- endfor %} +
+
+ {%- if show_source and has_source and sourcename %} +
+ {{ _('Show Source') }} + {%- endif %} +
+
+ +
+ {{ super() }} +
+
+
+
+{% endblock %} + +{% block relbar1 %}{% endblock %} +{% block relbar2 %}{% endblock %} diff --git a/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t b/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t new file mode 100644 --- /dev/null +++ b/openmp/docs/_themes/llvm-openmp-theme/static/agogo.css_t @@ -0,0 +1,538 @@ +/* + * agogo.css_t + * ~~~~~~~~~~~ + * + * Sphinx stylesheet -- agogo theme. + * + * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +* { + margin: 0px; + padding: 0px; +} + +body { + font-family: {{ theme_bodyfont }}; + line-height: 1.4em; + color: black; + background-color: {{ theme_bgcolor }}; +} + + +/* Page layout */ + +div.header, div.content, div.footer { + width: {{ theme_pagewidth }}; + margin-left: auto; + margin-right: auto; +} + +div.header-wrapper { + background: {{ theme_headerbg }}; + border-bottom: 3px solid #2e3436; +} + + +/* Default body styles */ +a { + color: {{ theme_linkcolor }}; +} + +div.bodywrapper a, div.footer a { + text-decoration: underline; +} + +.clearer { + clear: both; +} + +.left { + float: left; +} + +.right { + float: right; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +h1, h2, h3, h4 { + font-family: {{ theme_headerfont }}; + font-weight: normal; + color: {{ theme_headercolor2 }}; + margin-bottom: .8em; +} + +h1 { + color: {{ theme_headercolor1 }}; +} + +h2 { + padding-bottom: .5em; + border-bottom: 1px solid {{ theme_headercolor2 }}; +} + +a.headerlink { + visibility: hidden; + color: #dddddd; + padding-left: .3em; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink, +caption:hover > a.headerlink, +p.caption:hover > a.headerlink, +div.code-block-caption:hover > a.headerlink { + visibility: visible; +} + +img { + border: 0; +} + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 2px 7px 1px 7px; + border-left: 0.2em solid black; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +/* Header */ + +div.header { + padding-top: 10px; + padding-bottom: 10px; +} + +div.header .headertitle { + font-family: {{ theme_headerfont }}; + font-weight: normal; + font-size: 180%; + letter-spacing: .08em; + margin-bottom: .8em; +} + +div.header .headertitle a { + color: white; +} + +div.header div.rel { + margin-top: 1em; +} + +div.header div.rel a { + color: {{ theme_headerlinkcolor }}; + letter-spacing: .1em; + text-transform: uppercase; +} + +p.logo { + float: right; +} + +img.logo { + border: 0; +} + + +/* Content */ +div.content-wrapper { + background-color: white; + padding-top: 20px; + padding-bottom: 20px; +} + +div.document { + width: {{ theme_documentwidth }}; + float: left; +} + +div.body { + {%- if theme_rightsidebar|tobool %} + padding-right: 2em; + {%- else %} + padding-left: 2em; + {% endif %} + text-align: {{ theme_textalign }}; +} + +div.document h1 { + line-height: 120%; +} + +div.document ul { + margin: 1.5em; + list-style-type: square; +} + +div.document dd { + margin-left: 1.2em; + margin-top: .4em; + margin-bottom: 1em; +} + +div.document .section { + margin-top: 1.7em; +} +div.document .section:first-child { + margin-top: 0px; +} + +div.document div.highlight { + padding: 3px; + border-top: 2px solid #dddddd; + border-bottom: 2px solid #dddddd; + margin-top: .8em; + margin-bottom: .8em; +} + +div.document div.literal-block-wrapper { + margin-top: .8em; + margin-bottom: .8em; +} + +div.document div.literal-block-wrapper div.highlight { + margin: 0; +} + +div.document div.code-block-caption span.caption-number { + padding: 0.1em 0.3em; + font-style: italic; +} + +div.document div.code-block-caption span.caption-text { +} + +div.document h2 { + margin-top: .7em; +} + +div.document p { + margin-bottom: .5em; +} + +div.document li.toctree-l1 { + margin-bottom: 1em; +} + +div.document .descname { + font-weight: bold; +} + +div.document .sig-paren { + font-size: larger; +} + +div.document .docutils.literal { + background-color: #eeeeec; + padding: 1px; +} + +div.document .docutils.xref.literal { + background-color: transparent; + padding: 0px; +} + +div.document blockquote { + margin: 1em; +} + +div.document ol { + margin: 1.5em; +} + + +/* Sidebar */ + +div.sidebar { + width: {{ theme_sidebarwidth|todim }}; + {%- if theme_rightsidebar|tobool %} + float: right; + {%- else %} + float: left; + {%- endif %} + font-size: .9em; +} + +div.sidebar a, div.header a { + text-decoration: none; +} + +div.sidebar a:hover, div.header a:hover { + text-decoration: underline; +} + +div.sidebar h3 { + color: #2e3436; + text-transform: uppercase; + font-size: 130%; + letter-spacing: .1em; +} + +div.sidebar ul { + list-style-type: none; +} + +div.sidebar li.toctree-l1 a { + display: block; + padding: 1px; + border: 1px solid #dddddd; + background-color: #eeeeec; + margin-bottom: .4em; + padding-left: 3px; + color: #2e3436; +} + +div.sidebar li.toctree-l2 a { + background-color: transparent; + border: none; + margin-left: 1em; + border-bottom: 1px solid #dddddd; +} + +div.sidebar li.toctree-l3 a { + background-color: transparent; + border: none; + margin-left: 2em; + border-bottom: 1px solid #dddddd; +} + +div.sidebar li.toctree-l2:last-child a { + border-bottom: none; +} + +div.sidebar li.toctree-l1.current a { + border-right: 5px solid {{ theme_headerlinkcolor }}; +} + +div.sidebar li.toctree-l1.current li.toctree-l2 a { + border-right: none; +} + +div.sidebar input[type="text"] { + width: 170px; +} + +div.sidebar input[type="submit"] { + width: 30px; +} + + +/* Footer */ + +div.footer-wrapper { + background: {{ theme_footerbg }}; + border-top: 4px solid #babdb6; + padding-top: 10px; + padding-bottom: 10px; + min-height: 80px; +} + +div.footer, div.footer a { + color: #888a85; +} + +div.footer .right { + text-align: right; +} + +div.footer .left { + text-transform: uppercase; +} + + +/* Styles copied from basic theme */ + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +table caption span.caption-number { + font-style: italic; +} + +table caption span.caption-text { +} + +div.figure p.caption span.caption-number { + font-style: italic; +} + +div.figure p.caption span.caption-text { +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable ul { + margin-top: 0; + margin-bottom: 0; + list-style-type: none; +} + +table.indextable > tbody > tr > td > ul { + padding-left: 0em; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- domain module index --------------------------------------------------- */ + +table.modindextable td { + padding: 2px; + border-collapse: collapse; +} + +/* -- viewcode extension ---------------------------------------------------- */ + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family:: {{ theme_bodyfont }}; +} + +div.viewcode-block:target { + margin: -1px -3px; + padding: 0 3px; + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} + +div.code-block-caption { + background-color: #ddd; + color: #333; + padding: 2px 5px; + font-size: small; +} + +/* -- math display ---------------------------------------------------------- */ + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} diff --git a/openmp/docs/_themes/llvm-openmp-theme/static/bgfooter.png b/openmp/docs/_themes/llvm-openmp-theme/static/bgfooter.png new file mode 100644 index 0000000000000000000000000000000000000000..0000000000000000000000000000000000000000 GIT binary patch literal 0 Hc$@`_ for +the LLVM/OpenMP host runtime, aka. `libomp.so`, is available as a `pdf +`_. + + +LLVM/OpenMP Target Host Runtime (``libomptarget``) +-------------------------------------------------- + +LLVM/OpenMP Target Host Runtime Plugins (``libomptarget.rtl.XXXX``) +------------------------------------------------------------------- + +LLVM/OpenMP Target Device Runtime (``libomptarget-ARCH-SUBARCH.bc``) +-------------------------------------------------------------------- + diff --git a/openmp/docs/index.rst b/openmp/docs/index.rst --- a/openmp/docs/index.rst +++ b/openmp/docs/index.rst @@ -1,25 +1,106 @@ -About -===== +.. title:: Welcome to the documentation of OpenMP in LLVM! -Support for the OpenMP parallel programming API in the LLVM compiler -infrastructure. Here you will find helpful links to OpenMP library documentation -and other resources. +.. note:: + This document is a work in progress and most of the expected content is not + yet available. While you can expect changes, we always welcome feedback and + additions. Please contact, e.g., through ``openmp-dev@lists.llvm.org``. -LLVM OpenMP Design & Overview +.. toctree:: + :hidden: + :maxdepth: 1 + + LLVM/OpenMP Documentation + + +LLVM/OpenMP Design & Overview ============================= -This describes the design of the `LLVM OpenMP Runtime Library`_ +OpenMP impacts various parts of the LLVM project, from the frontends (`Clang +`_ and Flang), through +middle-end :ref:`optimizations `, up to the +multitude of available :ref:`OpenMP runtimes `. + +A high-level overview of OpenMP in LLVM can be found :doc:`here `. + +.. toctree:: + :hidden: + :maxdepth: 1 + + design/Overview + + +LLVM/OpenMP Optimizations +========================= + +LLVM, since `version 11 `_ (12 Oct +2020), has an :doc:`OpenMP-Aware optimization pass ` +as well as the ability to :doc:`perform "scalar optimizations" across OpenMP region +boundaries `. + +In-depth discussion of the topic can be found :doc:`here `. + +.. toctree:: + :hidden: + :maxdepth: 1 + + optimizations/Overview + +LLVM/OpenMP Optimization Remarks +================================ -.. _`LLVM OpenMP Runtime Library`: https://openmp.llvm.org/Reference.pdf +LLVM has an elaborate ecosystem around `analysis and optimization remarks +`_ issues during +compilation. The remarks can be enabled from the clang frontend `[1]`_ `[2]`_ +in various formats `[3]`_ `[4]`_ to be used by tools, i.a., `opt-viewer` or +`llvm-opt-report` (dated). + +The OpenMP optimizations in LLVM have been developed with remark support as a +priority. For a list of OpenMP specific remarks and more information on them, +please refer to :doc:`remarks/OptimizationRemarks`. + + +.. _`[1]`: https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports +.. _`[2]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags +.. _`[3]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file +.. _`[4]`: https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record + ++ `[1]`_ https://clang.llvm.org/docs/UsersManual.html#options-to-emit-optimization-reports ++ `[2]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#diagnostic-flags ++ `[3]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-foptimization-record-file ++ `[4]`_ https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-fsave-optimization-record + + +.. toctree:: + :hidden: + :maxdepth: 1 + + remarks/OptimizationRemarks + + +Support & Frequently Asked Questions (FAQ) +========================================== + +Dealing with OpenMP can be complicated. For help with the setup of an OpenMP +(offload) capable compiler toolchain, its usage, and common problems, consult +the :doc:`Support and FAQ ` page. + + +.. toctree:: + :hidden: + :maxdepth: 1 + + SupportAndFAQ Release Notes ============= -Current OpenMP release notes. +The current (in-progress) release notes can be found :doc:`here ` while +release notes for releases, starting with LLVM 12, will be available on `the +Download Page `_. + .. toctree:: :hidden: + :maxdepth: 1 - ReleaseNotes - -* :doc:`ReleaseNotes` + In-Progress ReleaseNotes diff --git a/openmp/docs/optimizations/OpenMPOpt.rst b/openmp/docs/optimizations/OpenMPOpt.rst new file mode 100644 --- /dev/null +++ b/openmp/docs/optimizations/OpenMPOpt.rst @@ -0,0 +1,5 @@ +OpenMP-Aware Optimizations +========================== + +OpenMPOpt +--------- diff --git a/openmp/docs/optimizations/OpenMPUnawareOptimizations.rst b/openmp/docs/optimizations/OpenMPUnawareOptimizations.rst new file mode 100644 --- /dev/null +++ b/openmp/docs/optimizations/OpenMPUnawareOptimizations.rst @@ -0,0 +1,2 @@ +OpenMP-Unaware Optimizations +============================ diff --git a/openmp/docs/optimizations/Overview.rst b/openmp/docs/optimizations/Overview.rst new file mode 100644 --- /dev/null +++ b/openmp/docs/optimizations/Overview.rst @@ -0,0 +1,19 @@ +.. _llvm_openmp_optimizations: + +OpenMP Optimizations in LLVM +============================ + +LLVM, since `version 11 `_ (12 Oct +2020), has an :doc:`OpenMP-Aware optimization pass ` +as well as the ability to :doc:`perform "scalar optimizations" across OpenMP region +boundaries `. + +.. toctree:: + :glob: + :hidden: + :titlesonly: + :maxdepth: 1 + + OpenMPOpt + OpenMPUnawareOptimizations + diff --git a/openmp/docs/remarks/OptimizationRemarks.rst b/openmp/docs/remarks/OptimizationRemarks.rst new file mode 100644 --- /dev/null +++ b/openmp/docs/remarks/OptimizationRemarks.rst @@ -0,0 +1,2 @@ +OpenMP Optimization Remarks +===========================