Rework Offload API errors

Author: callumfare

offload/new-api/API/APIDefs.td

@@ -106,11 +106,11 @@ class AddHandleChecksToReturns<list<Param> Params, list<Return> Returns> {
   // Does the list of returns already contain ERROR_INVALID_NULL_HANDLE?
   bit returns_has_inv_handle = !foldl(
       0, Returns, HasErr, Ret,
-      !or(HasErr, !eq(Ret.value, PREFIX#"_RESULT_ERROR_INVALID_NULL_HANDLE")));
+      !or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_HANDLE")));
 
   list<Return> returns_out = !if(returns_has_inv_handle,
-        AppendConditionsToReturn<Returns, PREFIX # "_RESULT_ERROR_INVALID_NULL_HANDLE", handle_param_conds>.ret,
-        !listconcat(Returns, [Return<PREFIX # "_RESULT_ERROR_INVALID_NULL_HANDLE", handle_param_conds>])
+        AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>.ret,
+        !listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_HANDLE", handle_param_conds>])
     );
 }
 
@@ -125,10 +125,10 @@ class AddPointerChecksToReturns<list<Param> Params, list<Return> Returns> {
   // Does the list of returns already contain ERROR_INVALID_NULL_POINTER?
   bit returns_has_inv_ptr = !foldl(
       0, Returns, HasErr, Ret,
-      !or(HasErr, !eq(Ret.value, PREFIX#"_RESULT_ERROR_INVALID_NULL_POINTER")));
+      !or(HasErr, !eq(Ret.value, PREFIX#"_ERROR_CODE_INVALID_NULL_POINTER")));
   list<Return> returns_out = !if(returns_has_inv_ptr,
-        AppendConditionsToReturn<Returns, PREFIX # "_RESULT_ERROR_INVALID_NULL_POINTER", ptr_param_conds>.ret,
-        !listconcat(Returns, [Return<PREFIX # "_RESULT_ERROR_INVALID_NULL_POINTER", ptr_param_conds>])
+        AppendConditionsToReturn<Returns, PREFIX # "_ERROR_CODE_INVALID_NULL_POINTER", ptr_param_conds>.ret,
+        !listconcat(Returns, [Return<PREFIX # "_ERROR_CODE_INVALID_NULL_POINTER", ptr_param_conds>])
     );
 }
 

offload/new-api/API/Common.td

@@ -45,41 +45,47 @@ def : Handle {
 }
 
 def : Enum {
-  let name = "offload_result_t";
+  let name = "offload_errc_t";
   let desc = "Defines Return/Error codes";
   let etors =[
     Etor<"SUCCESS", "Success">,
-    Etor<"ERROR_INVALID_VALUE", "Invalid Value">,
-    Etor<"ERROR_INVALID_PLATFORM", "Invalid platform">,
-    Etor<"ERROR_DEVICE_NOT_FOUND", "Device not found">,
-    Etor<"ERROR_INVALID_DEVICE", "Invalid device">,
-    Etor<"ERROR_DEVICE_LOST", "Device hung, reset, was removed, or driver update occurred">,
-    Etor<"ERROR_UNINITIALIZED", "plugin is not initialized or specific entry-point is not implemented">,
-    Etor<"ERROR_OUT_OF_RESOURCES", "Out of resources">,
-    Etor<"ERROR_UNSUPPORTED_VERSION", "generic error code for unsupported versions">,
-    Etor<"ERROR_UNSUPPORTED_FEATURE", "generic error code for unsupported features">,
-    Etor<"ERROR_INVALID_ARGUMENT", "generic error code for invalid arguments">,
-    Etor<"ERROR_INVALID_NULL_HANDLE", "handle argument is not valid">,
-    Etor<"ERROR_INVALID_NULL_POINTER", "pointer argument may not be nullptr">,
-    Etor<"ERROR_INVALID_SIZE", "invalid size or dimensions (e.g., must not be zero, or is out of bounds)">,
-    Etor<"ERROR_INVALID_ENUMERATION", "enumerator argument is not valid">,
-    Etor<"ERROR_UNSUPPORTED_ENUMERATION", "enumerator argument is not supported by the device">,
-    Etor<"ERROR_UNKNOWN", "Unknown or internal error">
+    Etor<"INVALID_VALUE", "Invalid Value">,
+    Etor<"INVALID_PLATFORM", "Invalid platform">,
+    Etor<"DEVICE_NOT_FOUND", "Device not found">,
+    Etor<"INVALID_DEVICE", "Invalid device">,
+    Etor<"DEVICE_LOST", "Device hung, reset, was removed, or driver update occurred">,
+    Etor<"UNINITIALIZED", "plugin is not initialized or specific entry-point is not implemented">,
+    Etor<"OUT_OF_RESOURCES", "Out of resources">,
+    Etor<"UNSUPPORTED_VERSION", "generic error code for unsupported versions">,
+    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">
   ];
 }
 
-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>
+def : Struct {
+  let name = "offload_error_struct_t";
+  let desc = "Details of the error condition returned by an API call";
+  let members = [
+    StructMember<"offload_errc_t", "code", "The error code">,
+    StructMember<"const char*", "details", "String containing error details">
   ];
-  let returns = []; // Only SUCCESS is expected
+}
+
+def : Typedef {
+  let name = "offload_result_t";
+  let desc = "Result type returned by all entry points.";
+  let value = "const offload_error_struct_t*";
+}
+
+def : Macro {
+  let name = "OFFLOAD_SUCCESS";
+  let condition = "!defined(OFFLOAD_SUCCESS)";
+  let desc = "Success condition";
+  let value = "NULL";
 }

offload/new-api/API/Device.td

@@ -47,7 +47,7 @@ def : Function {
     Param<"offload_platform_handle_t", "hPlatform", "handle of the platform instance", PARAM_IN>,
     Param<"offload_device_type_t", "DeviceType", "the type of the devices.", PARAM_IN>,
     Param<"uint32_t", "NumEntries", "the number of devices to be added to phDevices. "
-        "If phDevices is not NULL, then NumEntries should be greater than zero. Otherwise OFFLOAD_RESULT_ERROR_INVALID_SIZE "
+        "If phDevices is not NULL, then NumEntries should be greater than zero. Otherwise OFFLOAD_ERRC_INVALID_SIZE "
         "will be returned.", PARAM_IN>,
     RangedParam<"offload_device_handle_t*", "phDevices", "Array of device handles. "
         "If NumEntries is less than the number of devices available, then platform shall only retrieve that number of devices.", PARAM_OUT_OPTIONAL,
@@ -56,13 +56,13 @@ def : Function {
         "pNumDevices will be updated with the total number of devices available.", PARAM_OUT_OPTIONAL>
   ];
   let returns = [
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_SIZE", [
+    Return<"OFFLOAD_ERRC_INVALID_SIZE", [
       "`NumEntries == 0 && phDevices != NULL`"
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_NULL_POINTER", [
+    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
       "`NumEntries > 0 && phDevices == NULL`"
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_VALUE">
+    Return<"OFFLOAD_ERRC_INVALID_VALUE">
   ];
 }
 
@@ -78,24 +78,24 @@ def : Function {
     Param<"offload_device_info_t", "propName", "type of the info to retrieve", PARAM_IN>,
     Param<"size_t", "propSize", "the number of bytes pointed to by pPropValue.", PARAM_IN>,
     TypeTaggedParam<"void*", "pPropValue", "array of bytes holding the info. If propSize is not equal to or greater than the real "
-                    "number of bytes needed to return the info then the OFFLOAD_RESULT_ERROR_INVALID_SIZE error is returned and "
+                    "number of bytes needed to return the info then the OFFLOAD_ERRC_INVALID_SIZE error is returned and "
                     "pPropValue is not used.", PARAM_OUT_OPTIONAL, TypeInfo<"propName" , "propSize">>,
     Param<"size_t*", "pPropSizeRet", "pointer to the actual size in bytes of the queried propName.", PARAM_OUT_OPTIONAL>
   ];
   let returns = [
-    Return<"OFFLOAD_RESULT_ERROR_UNSUPPORTED_ENUMERATION", [
+    Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
       "If `propName` is not supported by the adapter."
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_SIZE", [
+    Return<"OFFLOAD_ERRC_INVALID_SIZE", [
       "`propSize == 0 && pPropValue != NULL`",
       "If `propSize` is less than the real number of bytes needed to return the info."
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_NULL_POINTER", [
+    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
       "`propSize != 0 && pPropValue == NULL`",
       "`pPropValue == NULL && pPropSizeRet == NULL`"
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_DEVICE">,
-    Return<"OFFLOAD_RESULT_ERROR_OUT_OF_RESOURCES">,
-    Return<"OFFLOAD_RESULT_ERROR_OUT_OF_HOST_MEMORY">
+    Return<"OFFLOAD_ERRC_INVALID_DEVICE">,
+    Return<"OFFLOAD_ERRC_OUT_OF_RESOURCES">,
+    Return<"OFFLOAD_ERRC_OUT_OF_HOST_MEMORY">
   ];
 }

offload/new-api/API/Platform.td

@@ -18,7 +18,7 @@ def : Function {
   let params = [
     Param<"uint32_t", "NumEntries",
       "The number of platforms to be added to phPlatforms. If phPlatforms is not NULL, then "
-      "NumEntries should be greater than zero, otherwise OFFLOAD_RESULT_ERROR_INVALID_SIZE "
+      "NumEntries should be greater than zero, otherwise OFFLOAD_ERRC_INVALID_SIZE "
       "will be returned.", PARAM_IN>,
     RangedParam<"offload_platform_handle_t*", "phPlatforms", 
       "Array of handle of platforms. If NumEntries is less than the number of "
@@ -30,7 +30,7 @@ def : Function {
       PARAM_OUT_OPTIONAL>
   ];
   let returns = [
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_SIZE", [
+    Return<"OFFLOAD_ERRC_INVALID_SIZE", [
       "`NumEntries == 0 && phPlatforms != NULL`"
     ]>
   ];
@@ -71,24 +71,24 @@ def : Function {
     Param<"size_t", "propSize", "the number of bytes pointed to by pPlatformInfo.", PARAM_IN>,
     TypeTaggedParam<"void*", "pPropValue", "array of bytes holding the info. "
       "If Size is not equal to or greater to the real number of bytes needed to return the info "
-      "then the OFFLOAD_RESULT_ERROR_INVALID_SIZE error is returned and pPlatformInfo is not used.", PARAM_OUT_OPTIONAL,
+      "then the OFFLOAD_ERRC_INVALID_SIZE error is returned and pPlatformInfo is not used.", PARAM_OUT_OPTIONAL,
       TypeInfo<"propName" , "propSize">>,
     Param<"size_t*", "pPropSizeRet", "pointer to the actual number of bytes being queried by pPlatformInfo.", PARAM_OUT_OPTIONAL>
   ];
   let returns = [
-    Return<"OFFLOAD_RESULT_ERROR_UNSUPPORTED_ENUMERATION", [
+    Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
       "If `propName` is not supported by the platform."
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_SIZE", [
+    Return<"OFFLOAD_ERRC_INVALID_SIZE", [
       "`propSize == 0 && pPropValue != NULL`",
       "If `propSize` is less than the real number of bytes needed to return the info."
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_NULL_POINTER", [
+    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
       "`propSize != 0 && pPropValue == NULL`",
       "`pPropValue == NULL && pPropSizeRet == NULL`"
     ]>,
-    Return<"OFFLOAD_RESULT_ERROR_INVALID_PLATFORM">,
-    Return<"OFFLOAD_RESULT_ERROR_OUT_OF_RESOURCES">,
-    Return<"OFFLOAD_RESULT_ERROR_OUT_OF_HOST_MEMORY">
+    Return<"OFFLOAD_ERRC_INVALID_PLATFORM">,
+    Return<"OFFLOAD_ERRC_OUT_OF_RESOURCES">,
+    Return<"OFFLOAD_ERRC_OUT_OF_HOST_MEMORY">
   ];
 }