Rename function and make optional

Author: RossBrunton

offload/liboffload/API/Kernel.td

@@ -44,16 +44,17 @@ def : Function {
 }
 
 def : Function {
-    let name = "olGetKernelMaxGroupSize";
-    let desc = "Get the maximum block size needed to achieve maximum occupancy.";
+    let name = "olCalculateMaxOccupancy";
+    let desc = "Given dynamic memory size, query the device for a workgroup size that will result in optimal occupancy.";
     let details = [];
     let params = [
         Param<"ol_device_handle_t", "Device", "device intended to run the kernel", PARAM_IN>,
         Param<"ol_symbol_handle_t", "Kernel", "handle of the kernel", PARAM_IN>,
-        Param<"size_t", "SharedMemory", "dynamic shared memory required", PARAM_IN>,
-        Param<"size_t*", "GroupSize", "maximum block size", PARAM_OUT>
+        Param<"size_t", "SharedMemory", "dynamic shared memory required per work item in bytes", PARAM_IN>,
+        Param<"size_t*", "GroupSize", "optimal block size", PARAM_OUT>
     ];
     let returns = [
         Return<"OL_ERRC_SYMBOL_KIND", ["The provided symbol is not a kernel"]>,
+        Return<"OL_ERRC_UNSUPPORTED", ["The backend cannot provide this information"]>,
     ];
 }

offload/liboffload/src/OffloadImpl.cpp

@@ -696,7 +696,7 @@ Error olDestroyProgram_impl(ol_program_handle_t Program) {
   return olDestroy(Program);
 }
 
-Error olGetKernelMaxGroupSize_impl(ol_device_handle_t Device,
+Error olCalculateMaxOccupancy_impl(ol_device_handle_t Device,
                                    ol_symbol_handle_t Kernel,
                                    size_t DynamicMemSize, size_t *GroupSize) {
   if (Kernel->Kind != OL_SYMBOL_KIND_KERNEL)

offload/plugins-nextgen/amdgpu/src/rtl.cpp

@@ -575,7 +575,9 @@ struct AMDGPUKernelTy : public GenericKernelTy {
   /// TODO: This needs to be implemented for amdgpu
   Expected<uint64_t> maxGroupSize(GenericDeviceTy &GenericDevice,
                                   uint64_t DynamicMemSize) const override {
-    return 1;
+    return Plugin::error(
+        ErrorCode::UNSUPPORTED,
+        "occupancy calculations for AMDGPU are not yet implemented");
   }
 
   /// Print more elaborate kernel launch info for AMDGPU

offload/plugins-nextgen/host/src/rtl.cpp

@@ -117,8 +117,9 @@ struct GenELF64KernelTy : public GenericKernelTy {
   /// Return maximum block size for maximum occupancy
   Expected<uint64_t> maxGroupSize(GenericDeviceTy &Device,
                                   uint64_t DynamicMemSize) const override {
-    // TODO
-    return 1;
+    return Plugin::error(
+        ErrorCode::UNSUPPORTED,
+        "occupancy calculations are not implemented for the host device");
   }
 
 private:

offload/unittests/OffloadAPI/CMakeLists.txt

@@ -20,7 +20,7 @@ add_offload_unittest("init"
 target_compile_definitions("init.unittests" PRIVATE DISABLE_WRAPPER)
 
 add_offload_unittest("kernel"
-    kernel/olGetKernelMaxGroupSize.cpp
+    kernel/olCalculateMaxOccupancy.cpp
     kernel/olLaunchKernel.cpp)
 
 add_offload_unittest("memory"

offload/unittests/OffloadAPI/common/Fixtures.hpp

@@ -26,6 +26,20 @@
   } while (0)
 #endif
 
+#ifndef ASSERT_SUCCESS_OR_UNSUPPORTED
+#define ASSERT_SUCCESS_OR_UNSUPPORTED(ACTUAL)                                  \
+  do {                                                                         \
+    ol_result_t Res = ACTUAL;                                                  \
+    if (Res && Res->Code == OL_ERRC_UNSUPPORTED) {                             \
+      GTEST_SKIP() << #ACTUAL " returned unsupported; skipping test";          \
+      return;                                                                  \
+    } else if (Res && Res->Code != OL_ERRC_SUCCESS) {                          \
+      GTEST_FAIL() << #ACTUAL " returned " << Res->Code << ": "                \
+                   << Res->Details;                                            \
+    }                                                                          \
+  } while (0)
+#endif
+
 // TODO: rework this so the EXPECTED/ACTUAL results are readable
 #ifndef ASSERT_ERROR
 #define ASSERT_ERROR(EXPECTED, ACTUAL)                                         \

offload/unittests/OffloadAPI/kernel/olCalculateMaxOccupancy.cpp

@@ -0,0 +1,43 @@
+//===------- Offload API tests - olCalculateMaxOccupancy ------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+#include "../common/Fixtures.hpp"
+#include <OffloadAPI.h>
+#include <gtest/gtest.h>
+
+using olCalculateMaxOccupancyTest = OffloadKernelTest;
+OFFLOAD_TESTS_INSTANTIATE_DEVICE_FIXTURE(olCalculateMaxOccupancyTest);
+
+TEST_P(olCalculateMaxOccupancyTest, Success) {
+  size_t Size{0};
+  ASSERT_SUCCESS_OR_UNSUPPORTED(olCalculateMaxOccupancy(Device, Kernel, 0, &Size));
+  ASSERT_GT(Size, 0u);
+}
+
+TEST_P(olCalculateMaxOccupancyTest, SuccessMem) {
+  size_t Size{0};
+  ASSERT_SUCCESS_OR_UNSUPPORTED(olCalculateMaxOccupancy(Device, Kernel, 1024, &Size));
+  ASSERT_GT(Size, 0u);
+}
+
+TEST_P(olCalculateMaxOccupancyTest, NullKernel) {
+  size_t Size;
+  ASSERT_ERROR(OL_ERRC_INVALID_NULL_HANDLE,
+               olCalculateMaxOccupancy(Device, nullptr, 0, &Size));
+}
+
+TEST_P(olCalculateMaxOccupancyTest, NullDevice) {
+  size_t Size;
+  ASSERT_ERROR(OL_ERRC_INVALID_NULL_HANDLE,
+               olCalculateMaxOccupancy(nullptr, Kernel, 0, &Size));
+}
+
+TEST_P(olCalculateMaxOccupancyTest, NullOutput) {
+  ASSERT_ERROR(OL_ERRC_INVALID_NULL_POINTER,
+               olCalculateMaxOccupancy(Device, Kernel, 0, nullptr));
+}