Implement optional error details

Author: callumfare

offload/new-api/API/Common.td

@@ -72,4 +72,20 @@ def : Enum {
     Etor<"ERROR_UNSUPPORTED_ENUMERATION", "[Validation] enumerator argument is not supported by the device">,
     Etor<"ERROR_UNKNOWN", "Unknown or internal error">
   ];
-}
+}
+
+def : Function {
+  let name = "offloadGetErrorDetails";
+  let desc = "Get a detailed error message for the last error that occurred on this thread, if it exists";
+  let details = [
+    "When an Offload API call returns a return value other than OFFLOAD_RESULT_SUCCESS, the implementation *may* set an additional error message.",
+    "If a further Offload call (excluding this function) is made on the same thread without checking "
+    "its detailed error message with this function, that message should be considered lost.",
+    "The returned char* is only valid until the next Offload function call on the same thread (excluding further calls to this function.)"
+  ];
+  let params = [
+    Param<"size_t*", "SizeRet", "Pointer to return the size of the available error message. A size of 0 indicates no message.", PARAM_OUT_OPTIONAL>,
+    Param<"const char**", "DetailStringRet", "Pointer to return the error message string.", PARAM_OUT_OPTIONAL>
+  ];
+  let returns = []; // Only SUCCESS is expected
+}

offload/new-api/CMakeLists.txt

@@ -26,6 +26,7 @@ endif()
 target_include_directories(offload_new PUBLIC
                             ${CMAKE_CURRENT_BINARY_DIR}
                             ${CMAKE_CURRENT_BINARY_DIR}/../include
+                            ${CMAKE_CURRENT_SOURCE_DIR}/include
                             ${CMAKE_CURRENT_SOURCE_DIR}/../include
                             ${CMAKE_CURRENT_SOURCE_DIR}/../plugins-nextgen/common/include)
 

offload/new-api/include/offload_impl.hpp

@@ -0,0 +1,33 @@
+//===- offload_impl.hpp- Implementation helpers for the Offload library ---===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#include <offload_api.h>
+#include <optional>
+#include <string>
+
+#include "llvm/ADT/StringRef.h"
+
+std::optional<std::string> &LastErrorDetails();
+
+struct offload_impl_result_t {
+  offload_impl_result_t() = delete;
+  offload_impl_result_t(offload_result_t Result) : Result(Result) {
+    LastErrorDetails() = std::nullopt;
+  }
+
+  offload_impl_result_t(offload_result_t Result, std::string Details)
+      : Result(Result) {
+    assert(Result != OFFLOAD_RESULT_SUCCESS);
+    LastErrorDetails() = Details;
+  }
+
+  operator offload_result_t() { return Result; }
+
+private:
+  offload_result_t Result;
+};

offload/new-api/src/offload_impl.cpp

@@ -13,6 +13,7 @@
 
 #include "PluginManager.h"
 #include "helpers.hpp"
+#include "offload_impl.hpp"
 #include "llvm/Support/FormatVariadic.h"
 #include <offload_api.h>
 
@@ -66,17 +67,37 @@ void initPlugins() {
   }
 }
 
-offload_result_t offloadPlatformGet_impl(uint32_t NumEntries,
-                                         offload_platform_handle_t *phPlatforms,
-                                         uint32_t *pNumPlatforms) {
+offload_result_t offloadGetErrorDetails_impl(size_t *SizeRet,
+                                             const char **DetailStringRet) {
+  if (auto Details = LastErrorDetails()) {
+    if (SizeRet) {
+      *SizeRet = Details->size();
+    }
+    if (DetailStringRet) {
+      *DetailStringRet = Details->c_str();
+    }
+  } else {
+    if (SizeRet) {
+      *SizeRet = 0;
+    }
+  }
+  return OFFLOAD_RESULT_SUCCESS;
+}
+
+offload_impl_result_t
+offloadPlatformGet_impl(uint32_t NumEntries,
+                        offload_platform_handle_t *phPlatforms,
+                        uint32_t *pNumPlatforms) {
   // It is expected that offloadPlatformGet is the first function to be called.
   // In future it may make sense to have a specific entry point for Offload
   // initialization, or expose explicit initialization of plugins.
   static std::once_flag InitFlag;
   std::call_once(InitFlag, initPlugins);
 
   if (NumEntries > Platforms().size()) {
-    return OFFLOAD_RESULT_ERROR_INVALID_SIZE;
+    return {OFFLOAD_RESULT_ERROR_INVALID_SIZE,
+            formatv("{0} platform(s) available but {1} requested.",
+                    Platforms().size(), NumEntries)};
   }
 
   if (phPlatforms) {
@@ -93,7 +114,7 @@ offload_result_t offloadPlatformGet_impl(uint32_t NumEntries,
   return OFFLOAD_RESULT_SUCCESS;
 }
 
-offload_result_t
+offload_impl_result_t
 offloadPlatformGetInfo_impl(offload_platform_handle_t hPlatform,
                             offload_platform_info_t propName, size_t propSize,
                             void *pPropValue, size_t *pPropSizeRet) {
@@ -126,11 +147,11 @@ offloadPlatformGetInfo_impl(offload_platform_handle_t hPlatform,
   return OFFLOAD_RESULT_SUCCESS;
 }
 
-offload_result_t offloadDeviceGet_impl(offload_platform_handle_t hPlatform,
-                                       offload_device_type_t,
-                                       uint32_t NumEntries,
-                                       offload_device_handle_t *phDevices,
-                                       uint32_t *pNumDevices) {
+offload_impl_result_t offloadDeviceGet_impl(offload_platform_handle_t hPlatform,
+                                            offload_device_type_t,
+                                            uint32_t NumEntries,
+                                            offload_device_handle_t *phDevices,
+                                            uint32_t *pNumDevices) {
 
   if (phDevices) {
     for (uint32_t DeviceIndex = 0; DeviceIndex < NumEntries; DeviceIndex++) {
@@ -145,10 +166,11 @@ offload_result_t offloadDeviceGet_impl(offload_platform_handle_t hPlatform,
   return OFFLOAD_RESULT_SUCCESS;
 }
 
-offload_result_t offloadDeviceGetInfo_impl(offload_device_handle_t hDevice,
-                                           offload_device_info_t propName,
-                                           size_t propSize, void *pPropValue,
-                                           size_t *pPropSizeRet) {
+offload_impl_result_t offloadDeviceGetInfo_impl(offload_device_handle_t hDevice,
+                                                offload_device_info_t propName,
+                                                size_t propSize,
+                                                void *pPropValue,
+                                                size_t *pPropSizeRet) {
 
   ReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
 

offload/new-api/src/offload_lib.cpp

@@ -10,11 +10,20 @@
 //
 //===----------------------------------------------------------------------===//
 
+#include "offload_impl.hpp"
 #include <offload_api.h>
 #include <offload_print.hpp>
 
 #include <iostream>
 
+// Store details for the last error that occurred on this thread. It MAY be set
+// when an implementation function returns a result other than
+// OFFLOAD_RESULT_SUCCESS.
+std::optional<std::string> &LastErrorDetails() {
+  thread_local std::optional<std::string> Details;
+  return Details;
+}
+
 // Pull in the declarations for the implementation funtions. The actual entry
 // points in this file wrap these.
 #include "offload_impl_func_decls.inc"

offload/tools/offload-tblgen/EntryPointGen.cpp

@@ -92,6 +92,10 @@ static void EmitEntryPointFunc(const FunctionRec &F, raw_ostream &OS) {
   OS << formatv("};\n");
   OS << TAB_2 "std::cout << \"(\" << &Params << \")\";\n";
   OS << TAB_2 "std::cout << \"-> \" << result << \"\\n\";\n";
+  OS << TAB_2 "if (result != OFFLOAD_RESULT_SUCCESS && LastErrorDetails()) {\n";
+  OS << TAB_3 "std::cout << \"     *Error Details* \" << *LastErrorDetails() "
+              "<< \" \\n\";\n";
+  OS << TAB_2 "}\n";
   OS << TAB_1 "}\n";
 
   OS << TAB_1 "return result;\n";

offload/tools/offload-tblgen/FuncsGen.cpp

@@ -52,7 +52,13 @@ void EmitOffloadExports(RecordKeeper &Records, raw_ostream &OS) {
 void EmitOffloadImplFuncDecls(RecordKeeper &Records, raw_ostream &OS) {
   for (auto *R : Records.getAllDerivedDefinitions("Function")) {
     FunctionRec F{R};
-    OS << formatv("{0}_result_t {1}_impl(", PrefixLower, F.getName());
+    // The error details function does not set error details itself, so don't
+    // use the impl result type
+    if (F.getName() == "offloadGetErrorDetails") {
+        OS << formatv("{0}_result_t {1}_impl(", PrefixLower, F.getName());
+    } else {
+      OS << formatv("{0}_impl_result_t {1}_impl(", PrefixLower, F.getName());
+    }
     auto Params = F.getParams();
     for (auto &Param : Params) {
       OS << Param.getType() << " " << Param.getName();