[Offload] Add Error Codes to PluginInterface (llvm#138258)

A new ErrorCode enumeration is present in PluginInterface which can
be used when returning an llvm::Error from offload and PluginInterface
functions.

This enum must be kept up to sync with liboffload's ol_errc_t enum, so
both are automatically generated from liboffload's enum definition.

Some error codes have also been shuffled around to allow for future
work. Note that this patch only adds the machinery; actual error codes
will be added in a future patch.

~~Depends on llvm#137339 , please ignore first commit of this MR.~~ This has
been merged.

Author: RossBrunton

offload/include/Shared/OffloadErrcodes.inc

@@ -0,0 +1,37 @@
+//===- Auto-generated file, part of the LLVM/Offload project --------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef OFFLOAD_ERRC
+#error Please define the macro OFFLOAD_ERRCODE(Name, Desc, Value)
+#endif
+
+// Error codes are shared between PluginInterface and liboffload.
+// To add new error codes, add them to offload/liboffload/API/Common.td and run
+// the GenerateOffload target.
+
+OFFLOAD_ERRC(SUCCESS, "Success", 0)
+OFFLOAD_ERRC(UNKNOWN, "Unknown or internal error", 1)
+OFFLOAD_ERRC(INVALID_NULL_POINTER,
+             "A pointer argument is null when it should not be", 2)
+OFFLOAD_ERRC(INVALID_ARGUMENT, "An argument is invalid", 3)
+OFFLOAD_ERRC(OUT_OF_RESOURCES, "Out of resources", 4)
+OFFLOAD_ERRC(UNSUPPORTED,
+             "generic error code for unsupported features and enums", 5)
+OFFLOAD_ERRC(
+    INVALID_SIZE,
+    "invalid size or dimensions (e.g., must not be zero, or is out of bounds)",
+    6)
+OFFLOAD_ERRC(INVALID_ENUMERATION, "enumerator argument is not valid", 7)
+OFFLOAD_ERRC(INVALID_KERNEL_NAME,
+             "Named kernel not found in the program binary", 8)
+OFFLOAD_ERRC(INVALID_VALUE, "Invalid Value", 9)
+OFFLOAD_ERRC(INVALID_PLATFORM, "Invalid platform", 10)
+OFFLOAD_ERRC(INVALID_DEVICE, "Invalid device", 11)
+OFFLOAD_ERRC(INVALID_QUEUE, "Invalid queue", 12)
+OFFLOAD_ERRC(INVALID_EVENT, "Invalid event", 13)
+OFFLOAD_ERRC(INVALID_NULL_HANDLE, "handle argument is not valid", 14)

offload/include/Shared/OffloadError.h

@@ -0,0 +1,51 @@
+//===- OffloadError.h - Definition of error class -------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef OPENMP_LIBOMPTARGET_PLUGINS_NEXTGEN_COMMON_OFFLOAD_ERROR_H
+#define OPENMP_LIBOMPTARGET_PLUGINS_NEXTGEN_COMMON_OFFLOAD_ERROR_H
+
+#include "llvm/Support/Error.h"
+#include "llvm/Support/ErrorHandling.h"
+
+namespace error {
+
+enum class ErrorCode {
+#define OFFLOAD_ERRC(Name, _, Value) Name = Value,
+#include "Shared/OffloadErrcodes.inc"
+#undef OFFLOAD_ERRC
+};
+
+} // namespace error
+
+namespace std {
+template <> struct is_error_code_enum<error::ErrorCode> : std::true_type {};
+} // namespace std
+
+namespace error {
+
+const std::error_category &OffloadErrCategory();
+
+inline std::error_code make_error_code(ErrorCode E) {
+  return std::error_code(static_cast<int>(E), OffloadErrCategory());
+}
+
+/// Base class for errors originating in DIA SDK, e.g. COM calls
+class OffloadError : public llvm::ErrorInfo<OffloadError, llvm::StringError> {
+public:
+  using ErrorInfo<OffloadError, StringError>::ErrorInfo;
+
+  OffloadError(const llvm::Twine &S) : ErrorInfo(S, ErrorCode::UNKNOWN) {}
+
+  // The definition for this resides in the plugin static library
+  static char ID;
+};
+} // namespace error
+
+#endif

offload/liboffload/API/CMakeLists.txt

@@ -11,13 +11,17 @@ if (CLANG_FORMAT)
     tablegen(OFFLOAD OffloadFuncs.inc -gen-func-names)
     tablegen(OFFLOAD OffloadImplFuncDecls.inc -gen-impl-func-decls)
     tablegen(OFFLOAD OffloadPrint.hpp -gen-print-header)
+    tablegen(OFFLOAD OffloadErrcodes.inc -gen-errcodes)
 
-    set(OFFLOAD_GENERATED_FILES ${TABLEGEN_OUTPUT})
+    set(FILES_TO_COPY "OffloadAPI.h;OffloadEntryPoints.inc;OffloadFuncs.inc;OffloadImplFuncDecls.inc;OffloadPrint.hpp")
+    set(GEN_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../include/generated)
     add_public_tablegen_target(OffloadGenerate)
     add_custom_command(TARGET OffloadGenerate POST_BUILD COMMAND ${CLANG_FORMAT}
-        -i ${OFFLOAD_GENERATED_FILES})
+        -i ${TABLEGEN_OUTPUT})
     add_custom_command(TARGET OffloadGenerate POST_BUILD COMMAND ${CMAKE_COMMAND}
-        -E copy_if_different ${OFFLOAD_GENERATED_FILES} "${CMAKE_CURRENT_SOURCE_DIR}/../include/generated")
+        -E copy_if_different ${FILES_TO_COPY} ${GEN_DIR})
+    add_custom_command(TARGET OffloadGenerate POST_BUILD COMMAND ${CMAKE_COMMAND}
+        -E copy_if_different OffloadErrcodes.inc "${LIBOMPTARGET_INCLUDE_DIR}/Shared/OffloadErrcodes.inc")
 else()
     message(WARNING "clang-format was not found, so the OffloadGenerate target\
         will not be available. Offload will still build, but you will not be\

offload/liboffload/API/Common.td

@@ -83,26 +83,29 @@ def : Typedef {
   let value = "void *";
 }
 
-def : Enum {
+def ErrorCode : Enum {
   let name = "ol_errc_t";
   let desc = "Defines Return/Error codes";
   let etors =[
     Etor<"SUCCESS", "Success">,
+
+    // Universal errors
+    Etor<"UNKNOWN", "Unknown or internal error">,
+    Etor<"INVALID_NULL_POINTER", "A pointer argument is null when it should not be">,
+    Etor<"INVALID_ARGUMENT", "An argument is invalid">,
+    Etor<"OUT_OF_RESOURCES", "Out of resources">,
+    Etor<"UNSUPPORTED", "generic error code for unsupported features and enums">,
+    Etor<"INVALID_SIZE", "invalid size or dimensions (e.g., must not be zero, or is out of bounds)">,
+    Etor<"INVALID_ENUMERATION", "enumerator argument is not valid">,
+    Etor<"INVALID_KERNEL_NAME", "Named kernel not found in the program binary">,
+
+    // Handle related errors - only makes sense for liboffload
     Etor<"INVALID_VALUE", "Invalid Value">,
     Etor<"INVALID_PLATFORM", "Invalid platform">,
     Etor<"INVALID_DEVICE", "Invalid device">,
     Etor<"INVALID_QUEUE", "Invalid queue">,
     Etor<"INVALID_EVENT", "Invalid event">,
-    Etor<"INVALID_KERNEL_NAME", "Named kernel not found in the program binary">,
-    Etor<"OUT_OF_RESOURCES", "Out of resources">,
-    Etor<"UNSUPPORTED_FEATURE", "generic error code for unsupported features">,
-    Etor<"INVALID_ARGUMENT", "generic error code for invalid arguments">,
-    Etor<"INVALID_NULL_HANDLE", "handle argument is not valid">,
-    Etor<"INVALID_NULL_POINTER", "pointer argument may not be nullptr">,
-    Etor<"INVALID_SIZE", "invalid size or dimensions (e.g., must not be zero, or is out of bounds)">,
-    Etor<"INVALID_ENUMERATION", "enumerator argument is not valid">,
-    Etor<"UNSUPPORTED_ENUMERATION", "enumerator argument is not supported by the device">,
-    Etor<"UNKNOWN", "Unknown or internal error">
+    Etor<"INVALID_NULL_HANDLE", "handle argument is not valid">
   ];
 }
 

offload/liboffload/include/OffloadImpl.hpp

@@ -7,6 +7,7 @@
 //===----------------------------------------------------------------------===//
 #pragma once
 
+#include "PluginInterface.h"
 #include <OffloadAPI.h>
 #include <iostream>
 #include <memory>
@@ -93,9 +94,7 @@ struct ol_impl_result_t {
     ol_errc_t ErrCode;
     llvm::StringRef Details;
     llvm::handleAllErrors(std::move(Error), [&](llvm::StringError &Err) {
-      // TODO: PluginInterface doesn't yet have a way to communicate offload
-      // error codes
-      ErrCode = OL_ERRC_UNKNOWN;
+      ErrCode = GetErrorCode(Err.convertToErrorCode());
       Details = errorStrs().insert(Err.getMessage()).first->getKeyData();
     });
 
@@ -105,5 +104,13 @@ struct ol_impl_result_t {
   operator ol_result_t() { return Result; }
 
 private:
+  static ol_errc_t GetErrorCode(std::error_code Code) {
+    if (Code.category() ==
+        error::make_error_code(error::ErrorCode::SUCCESS).category()) {
+      return static_cast<ol_errc_t>(Code.value());
+    }
+    return OL_ERRC_UNKNOWN;
+  }
+
   ol_result_t Result;
 };

offload/liboffload/include/generated/OffloadAPI.h

@@ -17,6 +17,45 @@
 extern "C" {
 #endif
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Defines Return/Error codes
+typedef enum ol_errc_t {
+  /// Success
+  OL_ERRC_SUCCESS = 0,
+  /// Unknown or internal error
+  OL_ERRC_UNKNOWN = 1,
+  /// A pointer argument is null when it should not be
+  OL_ERRC_INVALID_NULL_POINTER = 2,
+  /// An argument is invalid
+  OL_ERRC_INVALID_ARGUMENT = 3,
+  /// Out of resources
+  OL_ERRC_OUT_OF_RESOURCES = 4,
+  /// generic error code for unsupported features and enums
+  OL_ERRC_UNSUPPORTED = 5,
+  /// invalid size or dimensions (e.g., must not be zero, or is out of bounds)
+  OL_ERRC_INVALID_SIZE = 6,
+  /// enumerator argument is not valid
+  OL_ERRC_INVALID_ENUMERATION = 7,
+  /// Named kernel not found in the program binary
+  OL_ERRC_INVALID_KERNEL_NAME = 8,
+  /// Invalid Value
+  OL_ERRC_INVALID_VALUE = 9,
+  /// Invalid platform
+  OL_ERRC_INVALID_PLATFORM = 10,
+  /// Invalid device
+  OL_ERRC_INVALID_DEVICE = 11,
+  /// Invalid queue
+  OL_ERRC_INVALID_QUEUE = 12,
+  /// Invalid event
+  OL_ERRC_INVALID_EVENT = 13,
+  /// handle argument is not valid
+  OL_ERRC_INVALID_NULL_HANDLE = 14,
+  /// @cond
+  OL_ERRC_FORCE_UINT32 = 0x7fffffff
+  /// @endcond
+
+} ol_errc_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 #ifndef OL_VERSION_MAJOR
 /// @brief Major version of the Offload API
@@ -101,47 +140,6 @@ typedef struct ol_program_impl_t *ol_program_handle_t;
 /// @brief Handle of kernel object
 typedef void *ol_kernel_handle_t;
 
-///////////////////////////////////////////////////////////////////////////////
-/// @brief Defines Return/Error codes
-typedef enum ol_errc_t {
-  /// Success
-  OL_ERRC_SUCCESS = 0,
-  /// Invalid Value
-  OL_ERRC_INVALID_VALUE = 1,
-  /// Invalid platform
-  OL_ERRC_INVALID_PLATFORM = 2,
-  /// Invalid device
-  OL_ERRC_INVALID_DEVICE = 3,
-  /// Invalid queue
-  OL_ERRC_INVALID_QUEUE = 4,
-  /// Invalid event
-  OL_ERRC_INVALID_EVENT = 5,
-  /// Named kernel not found in the program binary
-  OL_ERRC_INVALID_KERNEL_NAME = 6,
-  /// Out of resources
-  OL_ERRC_OUT_OF_RESOURCES = 7,
-  /// generic error code for unsupported features
-  OL_ERRC_UNSUPPORTED_FEATURE = 8,
-  /// generic error code for invalid arguments
-  OL_ERRC_INVALID_ARGUMENT = 9,
-  /// handle argument is not valid
-  OL_ERRC_INVALID_NULL_HANDLE = 10,
-  /// pointer argument may not be nullptr
-  OL_ERRC_INVALID_NULL_POINTER = 11,
-  /// invalid size or dimensions (e.g., must not be zero, or is out of bounds)
-  OL_ERRC_INVALID_SIZE = 12,
-  /// enumerator argument is not valid
-  OL_ERRC_INVALID_ENUMERATION = 13,
-  /// enumerator argument is not supported by the device
-  OL_ERRC_UNSUPPORTED_ENUMERATION = 14,
-  /// Unknown or internal error
-  OL_ERRC_UNKNOWN = 15,
-  /// @cond
-  OL_ERRC_FORCE_UINT32 = 0x7fffffff
-  /// @endcond
-
-} ol_errc_t;
-
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Details of the error condition returned by an API call
 typedef struct ol_error_struct_t {
@@ -477,7 +475,8 @@ OL_APIEXPORT ol_result_t OL_APICALL olMemFree(
 /// @brief Enqueue a memcpy operation.
 ///
 /// @details
-///    - For host pointers, use the device returned by olGetHostDevice
+///    - For host pointers, use the host device belonging to the
+///    OL_PLATFORM_BACKEND_HOST platform.
 ///    - If a queue is specified, at least one device must be a non-host device
 ///    - If a queue is not specified, the memcpy happens synchronously
 ///

offload/liboffload/include/generated/OffloadPrint.hpp

@@ -49,6 +49,30 @@ inline llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
   case OL_ERRC_SUCCESS:
     os << "OL_ERRC_SUCCESS";
     break;
+  case OL_ERRC_UNKNOWN:
+    os << "OL_ERRC_UNKNOWN";
+    break;
+  case OL_ERRC_INVALID_NULL_POINTER:
+    os << "OL_ERRC_INVALID_NULL_POINTER";
+    break;
+  case OL_ERRC_INVALID_ARGUMENT:
+    os << "OL_ERRC_INVALID_ARGUMENT";
+    break;
+  case OL_ERRC_OUT_OF_RESOURCES:
+    os << "OL_ERRC_OUT_OF_RESOURCES";
+    break;
+  case OL_ERRC_UNSUPPORTED:
+    os << "OL_ERRC_UNSUPPORTED";
+    break;
+  case OL_ERRC_INVALID_SIZE:
+    os << "OL_ERRC_INVALID_SIZE";
+    break;
+  case OL_ERRC_INVALID_ENUMERATION:
+    os << "OL_ERRC_INVALID_ENUMERATION";
+    break;
+  case OL_ERRC_INVALID_KERNEL_NAME:
+    os << "OL_ERRC_INVALID_KERNEL_NAME";
+    break;
   case OL_ERRC_INVALID_VALUE:
     os << "OL_ERRC_INVALID_VALUE";
     break;
@@ -64,36 +88,9 @@ inline llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
   case OL_ERRC_INVALID_EVENT:
     os << "OL_ERRC_INVALID_EVENT";
     break;
-  case OL_ERRC_INVALID_KERNEL_NAME:
-    os << "OL_ERRC_INVALID_KERNEL_NAME";
-    break;
-  case OL_ERRC_OUT_OF_RESOURCES:
-    os << "OL_ERRC_OUT_OF_RESOURCES";
-    break;
-  case OL_ERRC_UNSUPPORTED_FEATURE:
-    os << "OL_ERRC_UNSUPPORTED_FEATURE";
-    break;
-  case OL_ERRC_INVALID_ARGUMENT:
-    os << "OL_ERRC_INVALID_ARGUMENT";
-    break;
   case OL_ERRC_INVALID_NULL_HANDLE:
     os << "OL_ERRC_INVALID_NULL_HANDLE";
     break;
-  case OL_ERRC_INVALID_NULL_POINTER:
-    os << "OL_ERRC_INVALID_NULL_POINTER";
-    break;
-  case OL_ERRC_INVALID_SIZE:
-    os << "OL_ERRC_INVALID_SIZE";
-    break;
-  case OL_ERRC_INVALID_ENUMERATION:
-    os << "OL_ERRC_INVALID_ENUMERATION";
-    break;
-  case OL_ERRC_UNSUPPORTED_ENUMERATION:
-    os << "OL_ERRC_UNSUPPORTED_ENUMERATION";
-    break;
-  case OL_ERRC_UNKNOWN:
-    os << "OL_ERRC_UNKNOWN";
-    break;
   default:
     os << "unknown enumerator";
     break;

offload/plugins-nextgen/common/CMakeLists.txt

@@ -5,6 +5,7 @@ add_library(PluginCommon OBJECT
   src/GlobalHandler.cpp
   src/JIT.cpp
   src/RPC.cpp
+  src/OffloadError.cpp
   src/Utils/ELF.cpp
 )
 add_dependencies(PluginCommon intrinsics_gen)