[Openmp-commits] [PATCH] D93723: [OpenMP] Add OpenMP Documentation for Libomptarget environment variables

[Joseph Huber via Phabricator via Openmp-commits]

jhuber6 created this revision.
jhuber6 added a reviewer: jdoerfert.
Herald added subscribers: guansong, yaxunl.
jhuber6 requested review of this revision.
Herald added subscribers: openmp-commits, sstefan1.
Herald added a project: OpenMP.

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


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D93723

Files:
  openmp/docs/design/Runtimes.rst


Index: openmp/docs/design/Runtimes.rst
===================================================================
--- openmp/docs/design/Runtimes.rst
+++ openmp/docs/design/Runtimes.rst
@@ -16,6 +16,86 @@
 LLVM/OpenMP Target Host Runtime (``libomptarget``)
 --------------------------------------------------
 
+Environment Variables
+^^^^^^^^^^^^^^^^^^^^^
+
+``libomptarget`` uses environment variables to control different 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 different types runtime
+information from ``libomptarget``. ``LIBOMPTARGET_INFO`` uses a 31-bit field to
+enable or disable different 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. A full list of available
+flags 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. The highest order bit is
+reserved in the implementation.
+
+.. code-block:: console
+
+   $ env LIBOMPTARGET_INFO=$((1 << 31 - 1)) ./your-application
+
 LLVM/OpenMP Target Host Runtime Plugins (``libomptarget.rtl.XXXX``)
 -------------------------------------------------------------------
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D93723.313404.patch
Type: text/x-patch
Size: 4010 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/openmp-commits/attachments/20201222/25e924d2/attachment.bin>