Rework API to avoid multiple returns, add init/shutdown, general refactor

Author: callumfare

offload/new-api/API/APIDefs.td

@@ -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#"_ERROR_CODE_INVALID_NULL_POINTER")));
+      !or(HasErr, !eq(Ret.value, PREFIX#"_ERRC_INVALID_NULL_POINTER")));
   list<Return> returns_out = !if(returns_has_inv_ptr,
-        AppendConditionsToReturn<Returns, PREFIX # "_ERROR_CODE_INVALID_NULL_POINTER", ptr_param_conds>.ret,
-        !listconcat(Returns, [Return<PREFIX # "_ERROR_CODE_INVALID_NULL_POINTER", ptr_param_conds>])
+        AppendConditionsToReturn<Returns, PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>.ret,
+        !listconcat(Returns, [Return<PREFIX # "_ERRC_INVALID_NULL_POINTER", ptr_param_conds>])
     );
 }
 

offload/new-api/API/Common.td

@@ -84,8 +84,7 @@ def : Typedef {
 }
 
 def : Macro {
-  let name = "OFFLOAD_SUCCESS";
-  let condition = "!defined(OFFLOAD_SUCCESS)";
+  let name = "OFFLOAD_RESULT_SUCCESS";
   let desc = "Success condition";
   let value = "NULL";
 }
@@ -100,3 +99,25 @@ def : Struct {
     StructMember<"uint32_t", "ColumnNumber", "Source code column number">
   ];
 }
+
+def : Function {
+  let name = "offloadInit";
+  let desc = "Perform initialization of the Offload library and plugins";
+  let details = [
+    "This must be the first API call made by a user of the Offload library",
+    "Each call will increment an internal reference count that is decremented by `offloadShutDown`"
+  ];
+  let params = [];
+  let returns = [];
+}
+
+def : Function {
+  let name = "offloadShutDown";
+  let desc = "Release the resources in use by Offload";
+  let details = [
+    "This decrements an internal reference count. When this reaches 0, all resources will be released",
+    "Subsequent API calls made after this are not valid"
+  ];
+  let params = [];
+  let returns = [];
+}

offload/new-api/API/Device.td

@@ -34,41 +34,40 @@ def : Enum {
   ];
 }
 
+def : Function {
+  let name = "offloadDeviceGetCount";
+  let desc = "Retrieves the number of available devices within a platform";
+  let params = [
+    Param<"offload_platform_handle_t", "hPlatform", "handle of the platform instance", PARAM_IN>,
+    Param<"uint32_t*", "pNumDevices", "pointer to the number of devices.", PARAM_OUT>
+  ];
+  let returns = [];
+}
+
 def : Function {
   let name = "offloadDeviceGet";
   let desc = "Retrieves devices within a platform";
   let details = [
     "Multiple calls to this function will return identical device handles, in the same order.",
-    "The number and order of handles returned from this function can be affected by environment variables that filter devices exposed through API.",
-    "The returned devices are taken a reference of and must be released with a subsequent call to olDeviceRelease.",
     "The application may call this function from simultaneous threads, the implementation must be thread-safe"
   ];
   let params = [
     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_ERRC_INVALID_SIZE "
-        "will be returned.", PARAM_IN>,
+    Param<"uint32_t", "NumEntries", "the number of devices to be added to phDevices, which must be greater than zero", 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,
-        Range<"0", "NumEntries">>,
-    Param<"uint32_t*", "pNumDevices", "pointer to the number of devices. "
-        "pNumDevices will be updated with the total number of devices available.", PARAM_OUT_OPTIONAL>
+        "If NumEntries is less than the number of devices available, then this function shall only retrieve that number of devices.", PARAM_OUT,
+        Range<"0", "NumEntries">>
   ];
   let returns = [
     Return<"OFFLOAD_ERRC_INVALID_SIZE", [
-      "`NumEntries == 0 && phDevices != NULL`"
-    ]>,
-    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
-      "`NumEntries > 0 && phDevices == NULL`"
-    ]>,
-    Return<"OFFLOAD_ERRC_INVALID_VALUE">
+      "`NumEntries == 0`"
+    ]>
   ];
 }
 
 def : Function {
   let name = "offloadDeviceGetInfo";
-  let desc = "Retrieves various information about device";
+  let desc = "Queries the given property of the device";
   let details = [
     "The application may call this function from simultaneous threads.",
     "The implementation of this function should be lock-free."
@@ -79,23 +78,36 @@ def : Function {
     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_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>
+                    "pPropValue is not used.", PARAM_OUT, TypeInfo<"propName" , "propSize">>
   ];
   let returns = [
     Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
-      "If `propName` is not supported by the adapter."
+      "If `propName` is not supported by the device."
     ]>,
     Return<"OFFLOAD_ERRC_INVALID_SIZE", [
-      "`propSize == 0 && pPropValue != NULL`",
+      "`propSize == 0`",
       "If `propSize` is less than the real number of bytes needed to return the info."
     ]>,
-    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
-      "`propSize != 0 && pPropValue == NULL`",
-      "`pPropValue == NULL && pPropSizeRet == NULL`"
+    Return<"OFFLOAD_ERRC_INVALID_DEVICE">
+  ];
+}
+
+def : Function {
+  let name = "offloadDeviceGetInfoSize";
+  let desc = "Returns the storage size of the given device query";
+  let details = [
+    "The application may call this function from simultaneous threads.",
+    "The implementation of this function should be lock-free."
+  ];
+  let params = [
+    Param<"offload_device_handle_t", "hDevice", "handle of the device instance", PARAM_IN>,
+    Param<"offload_device_info_t", "propName", "type of the info to retrieve", PARAM_IN>,
+    Param<"size_t*", "pPropSizeRet", "pointer to the number of bytes required to store the query", PARAM_OUT>
+  ];
+  let returns = [
+    Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
+      "If `propName` is not supported by the device."
     ]>,
-    Return<"OFFLOAD_ERRC_INVALID_DEVICE">,
-    Return<"OFFLOAD_ERRC_OUT_OF_RESOURCES">,
-    Return<"OFFLOAD_ERRC_OUT_OF_HOST_MEMORY">
+    Return<"OFFLOAD_ERRC_INVALID_DEVICE">
   ];
 }

offload/new-api/API/Platform.td

@@ -17,25 +17,33 @@ 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_ERRC_INVALID_SIZE "
-      "will be returned.", PARAM_IN>,
+      "The number of platforms to be added to phPlatforms. NumEntries must be "
+      "greater than zero.",
+      PARAM_IN>,
     RangedParam<"offload_platform_handle_t*", "phPlatforms", 
       "Array of handle of platforms. If NumEntries is less than the number of "
       "platforms available, then offloadPlatformGet shall only retrieve that "
       "number of platforms.",
-      PARAM_OUT_OPTIONAL, Range<"0", "NumEntries">>,
-    Param<"uint32_t*",
-      "pNumPlatforms", "returns the total number of platforms available.",
-      PARAM_OUT_OPTIONAL>
+      PARAM_OUT, Range<"0", "NumEntries">>
   ];
   let returns = [
     Return<"OFFLOAD_ERRC_INVALID_SIZE", [
-      "`NumEntries == 0 && phPlatforms != NULL`"
+      "`NumEntries == 0`"
     ]>
   ];
 }
 
+def : Function {
+  let name = "offloadPlatformGetCount";
+  let desc = "Retrieves the number of available platforms";
+  let params = [
+    Param<"uint32_t*",
+      "pNumPlatforms", "returns the total number of platforms available.",
+      PARAM_OUT>
+  ];
+  let returns = [];
+}
+
 def : Enum {
   let name = "offload_platform_info_t";
   let desc = "Supported platform info";
@@ -60,8 +68,10 @@ def : Enum {
 
 def : Function {
   let name = "offloadPlatformGetInfo";
-  let desc = "Retrieves various information about platform";
+  let desc = "Queries the given property of the platform";
   let details = [
+    "`offloadPlatformGetInfoSize` can be used to query the storage size "
+    "required for the given query."
     "The application may call this function from simultaneous threads.",
     "The implementation of this function should be lock-free."
   ];
@@ -71,24 +81,37 @@ 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_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>
+      "then the OFFLOAD_ERRC_INVALID_SIZE error is returned and pPlatformInfo is not used.", PARAM_OUT,
+      TypeInfo<"propName" , "propSize">>
   ];
   let returns = [
     Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
       "If `propName` is not supported by the platform."
     ]>,
     Return<"OFFLOAD_ERRC_INVALID_SIZE", [
-      "`propSize == 0 && pPropValue != NULL`",
+      "`propSize == 0`",
       "If `propSize` is less than the real number of bytes needed to return the info."
     ]>,
-    Return<"OFFLOAD_ERRC_INVALID_NULL_POINTER", [
-      "`propSize != 0 && pPropValue == NULL`",
-      "`pPropValue == NULL && pPropSizeRet == NULL`"
+    Return<"OFFLOAD_ERRC_INVALID_PLATFORM">
+  ];
+}
+
+def : Function {
+  let name = "offloadPlatformGetInfoSize";
+  let desc = "Returns the storage size of the given platform query";
+  let details = [
+    "The application may call this function from simultaneous threads.",
+    "The implementation of this function should be lock-free."
+  ];
+  let params = [
+    Param<"offload_platform_handle_t", "hPlatform", "handle of the platform", PARAM_IN>,
+    Param<"offload_platform_info_t", "propName", "type of the info to query", PARAM_IN>,
+    Param<"size_t*", "pPropSizeRet", "pointer to the number of bytes required to store the query", PARAM_OUT>
+  ];
+  let returns = [
+    Return<"OFFLOAD_ERRC_UNSUPPORTED_ENUMERATION", [
+      "If `propName` is not supported by the platform."
     ]>,
-    Return<"OFFLOAD_ERRC_INVALID_PLATFORM">,
-    Return<"OFFLOAD_ERRC_OUT_OF_RESOURCES">,
-    Return<"OFFLOAD_ERRC_OUT_OF_HOST_MEMORY">
+    Return<"OFFLOAD_ERRC_INVALID_PLATFORM">
   ];
 }