[llvm-branch-commits] [openmp] 1c19804 - [OpenMP] Add OpenMP Documentation for Libomptarget environment variables

[Joseph Huber via llvm-branch-commits]

Author: Joseph Huber
Date: 2020-12-22T17:41:27-05:00
New Revision: 1c19804ebf4c97666a5c7de86ca7432c6b020205

URL: https://github.com/llvm/llvm-project/commit/1c19804ebf4c97666a5c7de86ca7432c6b020205
DIFF: https://github.com/llvm/llvm-project/commit/1c19804ebf4c97666a5c7de86ca7432c6b020205.diff

LOG: [OpenMP] Add OpenMP Documentation for Libomptarget environment variables

Add support to the OpenMP web pages for environment variables supported
by Libomptarget and their usage.

Reviewed By: jdoerfert

Differential Revision: https://reviews.llvm.org/D93723

Added: 
    

Modified: 
    openmp/docs/design/Runtimes.rst

Removed: 
    


################################################################################
diff  --git a/openmp/docs/design/Runtimes.rst b/openmp/docs/design/Runtimes.rst
index 61491060ea04..39ed256c4856 100644
--- a/openmp/docs/design/Runtimes.rst
+++ b/openmp/docs/design/Runtimes.rst
@@ -16,6 +16,88 @@ the LLVM/OpenMP host runtime, aka.  `libomp.so`, is available as a `pdf
 LLVM/OpenMP Target Host Runtime (``libomptarget``)
 --------------------------------------------------
 
+Environment Variables
+^^^^^^^^^^^^^^^^^^^^^
+
+``libomptarget`` uses environment variables to control 
diff erent features of the
+library at runtime. This allows the user to obtain useful runtime information as
+well as enable or disable certain features. A full list of supported environment
+variables is defined below.
+
+    * ``LIBOMPTARGET_DEBUG=<Num>``
+    * ``LIBOMPTARGET_PROFILE=<Filename>``
+    * ``LIBOMPTARGET_MEMORY_MANAGER_THRESHOLD=<Num>``
+    * ``LIBOMPTARGET_INFO=<Num>``
+
+LIBOMPTARGET_DEBUG
+""""""""""""""""""
+
+``LIBOMPTARGET_DEBUG`` controls whether or not debugging information will be
+displayed. This feature is only availible if ``libomptarget`` was built with
+``-DOMPTARGET_DEBUG``. The debugging output provided is intended for use by
+``libomptarget`` developers. More user-friendly output is presented when using
+``LIBOMPTARGET_INFO``.
+
+LIBOMPTARGET_PROFILE
+""""""""""""""""""""
+``LIBOMPTARGET_PROFILE`` allows ``libomptarget`` to generate time profile output
+similar to Clang's ``-ftime-trace`` option. This generates a JSON file based on
+`Chrome Tracing`_ that can be viewed with ``chrome://tracing`` or the
+`Speedscope App`_. Building this feature depends on the `LLVM Support Library`_
+for time trace output. Using this library is enabled by default when building
+using the CMake option ``OPENMP_ENABLE_LIBOMPTARGET_PROFILING``. The output will
+be saved to the filename specified by the environment variable.
+
+.. _`Chrome Tracing`: https://www.chromium.org/developers/how-tos/trace-event-profiling-tool
+
+.. _`Speedscope App`: https://www.speedscope.app/
+
+.. _`LLVM Support Library`: https://llvm.org/docs/SupportLibrary.html
+
+LIBOMPTARGET_MEMORY_MANAGER_THRESHOLD
+"""""""""""""""""""""""""""""""""""""
+
+``LIBOMPTARGET_MEMORY_MANAGER_THRESHOLD`` sets the threshold size for which the
+``libomptarget`` memory manager will handle the allocation. Any allocations
+larger than this threshold will not use the memory manager and be freed after
+the device kernel exits The default threshold value is ``8Kb``. If
+``LIBOMPTARGET_MEMORY_MANAGER_THRESHOLD`` is set to ``0`` the memory manager
+will be completely disabled.
+
+LIBOMPTARGET_INFO
+"""""""""""""""""
+
+``LIBOMPTARGET_INFO`` allows the user to request 
diff erent types runtime
+information from ``libomptarget``. ``LIBOMPTARGET_INFO`` uses a 32-bit field to
+enable or disable 
diff erent types of information. This includes information
+about data-mappings and kernel execution. It is recommended to build your
+application with debugging information enabled, this will enable filenames and
+variable declarations in the information messages. OpenMP Debugging information
+is enabled at any level of debugging so a full debug runtime is not required.
+For minimal debugging information compile with `-gline-tables-only`, or compile
+with `-g` for full debug information. A full list of flags supported by
+``LIBOMPTARGET_INFO`` is given below. 
+
+    * Print all data arguments upon entering an OpenMP device kernel: ``0x01``
+    * Indicate when a mapped address already exists in the device mapping table:
+      ``0x02``
+    * Dump the contents of the device pointer map at kernel exit: ``0x04``
+    * Print OpenMP kernel information from device plugins: ``0x10``
+
+Any combination of these flags can be used by setting the appropriate bits. For
+example, to enable printing all data active in an OpenMP target region along
+with ``CUDA`` information, run the following ``bash`` command.
+
+.. code-block:: console
+
+   $ env LIBOMPTARGET_INFO=$((1 << 0x1 | 1 << 0x10)) ./your-application
+
+Or, to enable every flag run with every bit set.
+
+.. code-block:: console
+
+   $ env LIBOMPTARGET_INFO=-1 ./your-application
+
 LLVM/OpenMP Target Host Runtime Plugins (``libomptarget.rtl.XXXX``)
 -------------------------------------------------------------------