Implement filtered device/platform discovery, demote platforms

Author: callumfare

offload/liboffload/API/APIDefs.td

@@ -199,7 +199,7 @@ class Typedef : APIObject { string value; }
 
 class FptrTypedef : APIObject {
   list<Param> params;
-  list<Return> returns;
+  string return;
 }
 
 class Macro : APIObject {

offload/liboffload/API/Device.td

@@ -36,22 +36,20 @@ def : Enum {
 
 def : Function {
   let name = "olGetDeviceCount";
-  let desc = "Retrieves the number of available devices within a platform.";
+  let desc = "Retrieves the number of available devices.";
   let params = [
-    Param<"ol_platform_handle_t", "Platform", "handle of the platform instance", PARAM_IN>,
     Param<"uint32_t*", "NumDevices", "pointer to the number of devices.", PARAM_OUT>
   ];
   let returns = [];
 }
 
 def : Function {
-  let name = "olGetDevice";
-  let desc = "Retrieves devices within a platform.";
+  let name = "olGetDevices";
+  let desc = "Retrieves devices.";
   let details = [
     "Multiple calls to this function will return identical device handles, in the same order.",
   ];
   let params = [
-    Param<"ol_platform_handle_t", "Platform", "handle of the platform instance", PARAM_IN>,
     Param<"uint32_t", "NumEntries", "the number of devices to be added to phDevices, which must be greater than zero", PARAM_IN>,
     RangedParam<"ol_device_handle_t*", "Devices", "Array of device handles. "
         "If NumEntries is less than the number of devices available, then this function shall only retrieve that number of devices.", PARAM_OUT,
@@ -64,6 +62,58 @@ def : Function {
   ];
 }
 
+def : FptrTypedef {
+  let name = "ol_platform_filter_cb_t";
+  let desc = "User-provided function to determine whether a platform is selected.";
+  let params = [
+    Param<"ol_platform_backend_t", "Backend", "the backend of the platform which is selected for filtering", PARAM_IN>,
+    Param<"const char*", "Name", "the name of the platform which is selected for filtering", PARAM_IN>
+  ];
+  let return = "bool";
+}
+
+def : FptrTypedef {
+  let name = "ol_device_filter_cb_t";
+  let desc = "User-provided function to determine whether a device is selected.";
+  let params = [
+    Param<"ol_device_type_t", "Type", "the type of the device which is selected for filtering", PARAM_IN>
+  ];
+  let return = "bool";
+}
+
+def : Function {
+  let name = "olGetFilteredDevices";
+  let desc = "Retrieve a subset of the available devices";
+  let details = [
+    "Platforms and devices are lazily initialized when they are first filtered",
+    "Use MaxNumDevices to stop device and platform discovery after a fixed number of devices",
+    "Multiple calls to this function will return identical device handles, in the same order.",
+  ];
+  let params = [
+    Param<"uint32_t", "MaxNumDevices", "the maximum number of devices to be added to phDevices, which must be greater than zero", PARAM_IN>,
+    Param<"ol_platform_filter_cb_t", "PlatformFilter", "the callback used to decide whether a platform is included", PARAM_IN>,
+    Param<"ol_device_filter_cb_t", "DeviceFilter", "the callback used to decide whether a platform is included", PARAM_IN>,
+    Param<"ol_device_handle_t*", "FilteredDevices", "output pointer for the selected devices", PARAM_OUT>,
+  ];
+  let returns = [];
+}
+
+def : Function {
+  let name = "olGetFilteredDevicesCount";
+  let desc = "Retrieve the number of devices that would be returned by olGetFilteredDevices with the given filters.";
+  let details = [
+      "Platforms and devices are lazily initialized when they are first filtered",
+      "Use MaxNumDevices to stop device and platform discovery after a fixed number of devices",
+  ];
+  let params = [
+    Param<"uint32_t", "MaxNumDevices", "the maximum number of devices to be added to phDevices; a value of 0 implies no limit.", PARAM_IN>,
+    Param<"ol_platform_filter_cb_t", "PlatformFilter", "the callback used to decide whether a platform is included", PARAM_IN>,
+    Param<"ol_device_filter_cb_t", "DeviceFilter", "the callback used to decide whether a platform is included", PARAM_IN>,
+    Param<"uint32_t*", "NumFilteredDevices", "output pointer for the number of selected devices", PARAM_OUT>
+  ];
+  let returns = [];
+}
+
 def : Function {
   let name = "olGetDeviceInfo";
   let desc = "Queries the given property of the device.";

offload/liboffload/API/Platform.td

@@ -9,40 +9,6 @@
 // This file contains Offload API definitions related to the Platform handle
 //
 //===----------------------------------------------------------------------===//
-def : Function {
-  let name = "olGetPlatform";
-  let desc = "Retrieves all available platforms.";
-  let details = [
-    "Multiple calls to this function will return identical platforms handles, in the same order.",
-  ];
-  let params = [
-    Param<"uint32_t", "NumEntries",
-      "The number of platforms to be added to Platforms. NumEntries must be "
-      "greater than zero.",
-      PARAM_IN>,
-    RangedParam<"ol_platform_handle_t*", "Platforms", 
-      "Array of handle of platforms. If NumEntries is less than the number of "
-      "platforms available, then olGetPlatform shall only retrieve that "
-      "number of platforms.",
-      PARAM_OUT, Range<"0", "NumEntries">>
-  ];
-  let returns = [
-    Return<"OL_ERRC_INVALID_SIZE", [
-      "`NumEntries == 0`"
-    ]>
-  ];
-}
-
-def : Function {
-  let name = "olGetPlatformCount";
-  let desc = "Retrieves the number of available platforms.";
-  let params = [
-    Param<"uint32_t*",
-      "NumPlatforms", "returns the total number of platforms available.",
-      PARAM_OUT>
-  ];
-  let returns = [];
-}
 
 def : Enum {
   let name = "ol_platform_info_t";