[Offload] Add Error Codes to PluginInterface

RossBrunton · RossBrunton · commit 8acfa0fcc2bd · 2025-05-02T13:37:06.000+01:00
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.
diff --git a/offload/liboffload/API/APIDefs.td b/offload/liboffload/API/APIDefs.td
@@ -152,9 +152,10 @@ class Function : APIObject {
         AddHandleChecksToReturns<params, returns_with_def>.returns_out>.returns_out;
 }
 
-class Etor<string Name, string Desc> {
+class Etor<string Name, string Desc, int Value=-1> {
   string name = Name;
   string desc = Desc;
+  int value = Value;
   string tagged_type;
 }
 
diff --git a/offload/liboffload/API/CMakeLists.txt b/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 "${LIBOFFLOAD_ROOT}/../plugins-nextgen/common/include/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\
diff --git a/offload/liboffload/API/Common.td b/offload/liboffload/API/Common.td
@@ -83,26 +83,30 @@ 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">,
-    Etor<"INVALID_VALUE", "Invalid Value">,
+    Etor<"SUCCESS", "Success", 0>,
+
+    // Universal errors
+    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">,
+
+    // Liboffload specific errors
+    Etor<"INVALID_VALUE", "Invalid Value", 0x1000>,
     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<"UNKNOWN", "Unknown or internal error", 0x10000>
   ];
 }
 
diff --git a/offload/liboffload/CMakeLists.txt b/offload/liboffload/CMakeLists.txt
@@ -1,3 +1,5 @@
+set(LIBOFFLOAD_ROOT "${CMAKE_CURRENT_SOURCE_DIR}")
+
 add_subdirectory(API)
 
 add_llvm_library(
diff --git a/offload/liboffload/include/OffloadImpl.hpp b/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,14 @@ struct ol_impl_result_t {
   operator ol_result_t() { return Result; }
 
 private:
+  static ol_errc_t GetErrorCode(std::error_code Code) {
+    if (Code.category() == llvm::omp::target::plugin::make_error_code(
+                               llvm::omp::target::plugin::ErrorCode::SUCCESS)
+                               .category()) {
+      return static_cast<ol_errc_t>(Code.value());
+    }
+    return OL_ERRC_UNKNOWN;
+  }
+
   ol_result_t Result;
 };
diff --git a/offload/liboffload/include/generated/OffloadAPI.h b/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,
+  /// A pointer argument is null when it should not be
+  OL_ERRC_INVALID_NULL_POINTER = 1,
+  /// An argument is invalid
+  OL_ERRC_INVALID_ARGUMENT = 2,
+  /// Out of resources
+  OL_ERRC_OUT_OF_RESOURCES = 3,
+  /// generic error code for unsupported features and enums
+  OL_ERRC_UNSUPPORTED = 4,
+  /// Invalid Value
+  OL_ERRC_INVALID_VALUE = 4096,
+  /// Invalid platform
+  OL_ERRC_INVALID_PLATFORM = 4097,
+  /// Invalid device
+  OL_ERRC_INVALID_DEVICE = 4098,
+  /// Invalid queue
+  OL_ERRC_INVALID_QUEUE = 4099,
+  /// Invalid event
+  OL_ERRC_INVALID_EVENT = 4100,
+  /// Named kernel not found in the program binary
+  OL_ERRC_INVALID_KERNEL_NAME = 4101,
+  /// handle argument is not valid
+  OL_ERRC_INVALID_NULL_HANDLE = 4102,
+  /// invalid size or dimensions (e.g., must not be zero, or is out of bounds)
+  OL_ERRC_INVALID_SIZE = 4103,
+  /// enumerator argument is not valid
+  OL_ERRC_INVALID_ENUMERATION = 4104,
+  /// Unknown or internal error
+  OL_ERRC_UNKNOWN = 65536,
+  /// @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
 ///
diff --git a/offload/liboffload/include/generated/OffloadPrint.hpp b/offload/liboffload/include/generated/OffloadPrint.hpp
@@ -49,6 +49,18 @@ inline llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
   case OL_ERRC_SUCCESS:
     os << "OL_ERRC_SUCCESS";
     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_VALUE:
     os << "OL_ERRC_INVALID_VALUE";
     break;
@@ -67,30 +79,15 @@ inline llvm::raw_ostream &operator<<(llvm::raw_ostream &os,
   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;
diff --git a/offload/plugins-nextgen/common/include/OffloadErrcodes.inc b/offload/plugins-nextgen/common/include/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(INVALID_NULL_POINTER,
+             "A pointer argument is null when it should not be", 1)
+OFFLOAD_ERRC(INVALID_ARGUMENT, "An argument is invalid", 2)
+OFFLOAD_ERRC(OUT_OF_RESOURCES, "Out of resources", 3)
+OFFLOAD_ERRC(UNSUPPORTED,
+             "generic error code for unsupported features and enums", 4)
+OFFLOAD_ERRC(INVALID_VALUE, "Invalid Value", 4096)
+OFFLOAD_ERRC(INVALID_PLATFORM, "Invalid platform", 4097)
+OFFLOAD_ERRC(INVALID_DEVICE, "Invalid device", 4098)
+OFFLOAD_ERRC(INVALID_QUEUE, "Invalid queue", 4099)
+OFFLOAD_ERRC(INVALID_EVENT, "Invalid event", 4100)
+OFFLOAD_ERRC(INVALID_KERNEL_NAME,
+             "Named kernel not found in the program binary", 4101)
+OFFLOAD_ERRC(INVALID_NULL_HANDLE, "handle argument is not valid", 4102)
+OFFLOAD_ERRC(
+    INVALID_SIZE,
+    "invalid size or dimensions (e.g., must not be zero, or is out of bounds)",
+    4103)
+OFFLOAD_ERRC(INVALID_ENUMERATION, "enumerator argument is not valid", 4104)
+OFFLOAD_ERRC(UNKNOWN, "Unknown or internal error", 65536)
diff --git a/offload/plugins-nextgen/common/include/PluginInterface.h b/offload/plugins-nextgen/common/include/PluginInterface.h
@@ -58,6 +58,30 @@ struct GenericKernelTy;
 struct GenericDeviceTy;
 struct RecordReplayTy;
 
+enum class ErrorCode {
+#define OFFLOAD_ERRC(Name, _, Value) Name = Value,
+#include "OffloadErrcodes.inc"
+#undef OFFLOAD_ERRC
+};
+
+class OffloadErrorCategory : public std::error_category {
+  const char *name() const noexcept override { return "Offload Error"; }
+  std::string message(int ev) const override {
+    switch (static_cast<ErrorCode>(ev)) {
+#define OFFLOAD_ERRC(Name, Desc, Value)                                        \
+  case ErrorCode::Name:                                                        \
+    return #Desc;
+#include "OffloadErrcodes.inc"
+#undef OFFLOAD_ERRC
+    }
+  }
+};
+
+inline std::error_code make_error_code(ErrorCode EC) {
+  static OffloadErrorCategory Cat{};
+  return {static_cast<int>(EC), Cat};
+}
+
 /// Class that wraps the __tgt_async_info to simply its usage. In case the
 /// object is constructed without a valid __tgt_async_info, the object will use
 /// an internal one and will synchronize the current thread with the pending
@@ -1385,7 +1409,13 @@ static inline Error success() { return Error::success(); }
 /// Create a string error.
 template <typename... ArgsTy>
 static Error error(const char *ErrFmt, ArgsTy... Args) {
-  return createStringError(inconvertibleErrorCode(), ErrFmt, Args...);
+  return createStringError(ErrorCode::UNKNOWN, ErrFmt, Args...);
+}
+
+/// Create a string error.
+template <typename... ArgsTy>
+static Error error(ErrorCode Code, const char *ErrFmt, ArgsTy... Args) {
+  return createStringError(Code, ErrFmt, Args...);
 }
 
 /// Check the plugin-specific error code and return an error or success
@@ -1596,4 +1626,10 @@ template <typename ResourceRef> class GenericDeviceResourceManagerTy {
 } // namespace omp
 } // namespace llvm
 
+namespace std {
+template <>
+struct is_error_code_enum<llvm::omp::target::plugin::ErrorCode>
+    : std::true_type {};
+} // namespace std
+
 #endif // OPENMP_LIBOMPTARGET_PLUGINS_COMMON_PLUGININTERFACE_H
diff --git a/offload/tools/offload-tblgen/APIGen.cpp b/offload/tools/offload-tblgen/APIGen.cpp
@@ -132,6 +132,9 @@ static void ProcessEnum(const EnumRec &Enum, raw_ostream &OS) {
 
   uint32_t EtorVal = 0;
   for (const auto &EnumVal : Enum.getValues()) {
+    if (auto NewVal = EnumVal.getEnumValue()) {
+      EtorVal = *NewVal;
+    }
     if (Enum.isTyped()) {
       OS << MakeComment(
           formatv("[{0}] {1}", EnumVal.getTaggedType(), EnumVal.getDesc())
diff --git a/offload/tools/offload-tblgen/CMakeLists.txt b/offload/tools/offload-tblgen/CMakeLists.txt
@@ -13,7 +13,7 @@ add_tablegen(offload-tblgen OFFLOAD
   EXPORT OFFLOAD
   APIGen.cpp
   EntryPointGen.cpp
-  FuncsGen.cpp
+  MiscGen.cpp
   GenCommon.hpp
   Generators.hpp
   offload-tblgen.cpp
@@ -23,4 +23,3 @@ add_tablegen(offload-tblgen OFFLOAD
 
 set(OFFLOAD_TABLEGEN_EXE "${OFFLOAD_TABLEGEN_EXE}" CACHE INTERNAL "")
 set(OFFLOAD_TABLEGEN_TARGET "${OFFLOAD_TABLEGEN_TARGET}" CACHE INTERNAL "")
-
diff --git a/offload/tools/offload-tblgen/Generators.hpp b/offload/tools/offload-tblgen/Generators.hpp
@@ -21,3 +21,5 @@ void EmitOffloadPrintHeader(const llvm::RecordKeeper &Records,
                             llvm::raw_ostream &OS);
 void EmitOffloadExports(const llvm::RecordKeeper &Records,
                         llvm::raw_ostream &OS);
+void EmitOffloadErrcodes(const llvm::RecordKeeper &Records,
+                         llvm::raw_ostream &OS);
diff --git a/offload/tools/offload-tblgen/MiscGen.cpp b/offload/tools/offload-tblgen/MiscGen.cpp
diff --git a/offload/tools/offload-tblgen/RecordTypes.hpp b/offload/tools/offload-tblgen/RecordTypes.hpp
diff --git a/offload/tools/offload-tblgen/offload-tblgen.cpp b/offload/tools/offload-tblgen/offload-tblgen.cpp

Original file line number	Diff line number	Diff line change
`@@ -152,9 +152,10 @@ class Function : APIObject {`
`152`	`152`	`AddHandleChecksToReturns<params, returns_with_def>.returns_out>.returns_out;`
`153`	`153`	`}`
`154`	`154`
`155`		`-class Etor<string Name, string Desc> {`
	`155`	`+class Etor<string Name, string Desc, int Value=-1> {`
`156`	`156`	`string name = Name;`
`157`	`157`	`string desc = Desc;`
	`158`	`+ int value = Value;`
`158`	`159`	`string tagged_type;`
`159`	`160`	`}`
`160`	`161`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+set(LIBOFFLOAD_ROOT "${CMAKE_CURRENT_SOURCE_DIR}")`
	`2`	`+`
`1`	`3`	`add_subdirectory(API)`
`2`	`4`
`3`	`5`	`add_llvm_library(`