[Openmp-commits] [openmp] ad0a306 - [OpenMP][NFC] Change error message on offloading failure to mention documentation

[Joseph Huber via Openmp-commits]

Author: Joseph Huber
Date: 2022-01-31T15:19:52-05:00
New Revision: ad0a306a3852a0f05c9192111cb370dd02fc9e6a

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

LOG: [OpenMP][NFC] Change error message on offloading failure to mention documentation

This patch changes the error message to instead mention the
documentation page for the debugging options provided by libomptarget
and the bitcode runtimes. Add some extra information to the documentation to
help users more quickly identify debugging resources.

Reviewed By: jdoerfert

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

Added: 
    

Modified: 
    openmp/docs/design/Runtimes.rst
    openmp/libomptarget/src/omptarget.cpp

Removed: 
    


################################################################################
diff  --git a/openmp/docs/design/Runtimes.rst b/openmp/docs/design/Runtimes.rst
index d8140ea8cfeb1..bb82cb7106e2c 100644
--- a/openmp/docs/design/Runtimes.rst
+++ b/openmp/docs/design/Runtimes.rst
@@ -3,7 +3,15 @@
 LLVM/OpenMP Runtimes
 ====================
 
-There are four distinct types of LLVM/OpenMP runtimes
+There are four distinct types of LLVM/OpenMP runtimes: the host runtime
+:ref:`libomp`, the target offloading runtime :ref:`libomptarget`, the target
+offloading plugin :ref:`libomptarget_plugin`, and finally the target device
+runtime :ref:`libomptarget_device`.
+
+For general information on debugging OpenMP target offloading applications, see
+:ref:`libomptarget_info` and :ref:`libomptarget_device_debugging`
+
+.. _libomp:
 
 LLVM/OpenMP Host Runtime (``libomp``)
 -------------------------------------
@@ -663,6 +671,8 @@ OpenMP run-time library during program execution.
 
 **Default:** ``true``
 
+.. _libomptarget:
+
 LLVM/OpenMP Target Host Runtime (``libomptarget``)
 --------------------------------------------------
 
@@ -723,6 +733,8 @@ 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
 """""""""""""""""
 
@@ -935,7 +947,7 @@ going wrong.
     Libomptarget error: Copying data from device failed.
     Libomptarget error: Call to targetDataEnd failed, abort target.
     Libomptarget error: Failed to process data after launching the kernel.
-    Libomptarget error: Run with LIBOMPTARGET_INFO=4 to dump host-target pointer mappings.
+    Libomptarget error: Consult https://openmp.llvm.org/design/Runtimes.html for debugging options.
     sum.cpp:5:1: Libomptarget error 1: failure of target construct while offloading is mandatory
 
 This shows that there is an illegal memory access occuring inside the OpenMP
@@ -1020,6 +1032,7 @@ value of the ``LIBOMPTARGET_MAP_FORCE_ATOMIC`` environment variable.
 The default behavior of LLVM 14 is to force atomic maps clauses, prior versions
 of LLVM did not.
 
+.. _libomptarget_plugin:
 
 LLVM/OpenMP Target Host Runtime Plugins (``libomptarget.rtl.XXXX``)
 -------------------------------------------------------------------
@@ -1082,6 +1095,8 @@ LIBOMPTARGET_RPC_LATENCY
 """"""""""""""""""""""""
 This is the maximum amount of time the client will wait for a response from the server.
 
+.. _libomptarget_device:
+
 LLVM/OpenMP Target Device Runtime (``libomptarget-ARCH-SUBARCH.bc``)
 --------------------------------------------------------------------
 
@@ -1089,6 +1104,8 @@ The target device runtime is an LLVM bitcode library that implements OpenMP
 runtime functions on the target device. It is linked with the device code's LLVM
 IR during compilation.
 
+.. _libomptarget_device_debugging:
+
 Debugging
 ^^^^^^^^^
 
@@ -1103,6 +1120,7 @@ debugging features are supported.
 
     * Enable debugging assertions in the device. ``0x01``
     * Enable OpenMP runtime function traces in the device. ``0x2``
+    * Enable diagnosing common problems during offloading . ``0x4``
 
 .. code-block:: c++
 

diff  --git a/openmp/libomptarget/src/omptarget.cpp b/openmp/libomptarget/src/omptarget.cpp
index 71a7a73f1018a..c8504c8ea5ff9 100644
--- a/openmp/libomptarget/src/omptarget.cpp
+++ b/openmp/libomptarget/src/omptarget.cpp
@@ -224,9 +224,8 @@ void handleTargetOutcome(bool Success, ident_t *Loc) {
         for (auto &Device : PM->Devices)
           dumpTargetPointerMappings(Loc, *Device);
       else
-        FAILURE_MESSAGE("Run with LIBOMPTARGET_INFO=%d to dump host-target "
-                        "pointer mappings.\n",
-                        OMP_INFOTYPE_DUMP_TABLE);
+        FAILURE_MESSAGE("Consult https://openmp.llvm.org/design/Runtimes.html "
+                        "for debugging options.\n");
 
       SourceInfo info(Loc);
       if (info.isAvailible())