EXSWHTEC-224 - Test cases ID clean up and documentation for Occupancy

catch/include/hip_test_defgroups.hh

@@ -0,0 +1,44 @@
+/*
+Copyright (c) 2021 - 2022 Advanced Micro Devices, Inc. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+// Test groups are named based on the group names from hip_api_runtime.h, with adding "Test" suffix
+
+/**
+ * @defgroup CallbackTest Callback Activity APIs
+ * @{
+ * This section describes tests for the callback/Activity of HIP runtime API.
+ * @}
+ */
+
+/**
+ * @defgroup GraphTest Graph Management
+ * @{
+ * This section describes the graph management types & functions of HIP runtime API.
+ * @}
+ */
+
+/**
+ * @defgroup OccupancyTest Occupancy
+ * @{
+ * This section describes tests for the occupancy functions of HIP runtime API.
+ * @}
+ */

catch/unit/occupancy/CMakeLists.txt

@@ -1,9 +1,23 @@
 # Common Tests - Test independent of all platforms
 set(TEST_SRC
   hipOccupancyMaxActiveBlocksPerMultiprocessor.cc
+  hipOccupancyMaxActiveBlocksPerMultiprocessor_old.cc
   hipOccupancyMaxPotentialBlockSize.cc
+  hipOccupancyMaxPotentialBlockSize_old.cc
+  hipModuleOccupancyMaxPotentialBlockSize.cc
+  hipModuleOccupancyMaxPotentialBlockSizeWithFlags.cc
+  hipModuleOccupancyMaxActiveBlocksPerMultiprocessor.cc
+  hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags.cc
 )
 
+add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/simple_kernel.code
+                   COMMAND ${CMAKE_CXX_COMPILER} --genco --std=c++17 ${CMAKE_CURRENT_SOURCE_DIR}/simple_kernel.cc -o simple_kernel.code
+                   DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/simple_kernel.cc)
+
+add_custom_target(simple_kernel ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/simple_kernel.code)
+
 hip_add_exe_to_target(NAME OccupancyTest
                       TEST_SRC ${TEST_SRC}
                       TEST_TARGET_NAME build_tests)
+
+add_dependencies(OccupancyTest simple_kernel)

catch/unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessor.cc

@@ -0,0 +1,125 @@
+/*
+Copyright (c) 2022 Advanced Micro Devices, Inc. All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "occupancy_common.hh"
+
+/**
+ * @addtogroup hipModuleOccupancyMaxActiveBlocksPerMultiprocessor hipModuleOccupancyMaxActiveBlocksPerMultiprocessor
+ * @{
+ * @ingroup OccupancyTest
+ * `hipModuleOccupancyMaxActiveBlocksPerMultiprocessor(int* numBlocks, hipFunction_t f,
+ * int blockSize, size_t dynSharedMemPerBlk)` -
+ * Returns occupancy for a device function.
+ */
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When output pointer to the grid size is `nullptr`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When block size is 0
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessor.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
+TEST_CASE("Unit_hipModuleOccupancyMaxActiveBlocksPerMultiprocessor_Negative_Parameters") {
+  hipModule_t module;
+  hipFunction_t function;
+  int blockSize = 0;
+  int gridSize = 0;
+
+  HIP_CHECK(hipFree(nullptr));
+
+  HIP_CHECK(hipModuleLoad(&module, "simple_kernel.code"));
+  HIPCHECK(hipModuleGetFunction(&function, module, "SimpleKernel"));
+
+  // Get potential blocksize
+  HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function, 0, 0));
+
+  // Common negative tests
+  MaxActiveBlocksPerMultiprocessorNegative(
+      [&function](int* numBlocks, int blockSize, size_t dynSharedMemPerBlk) {
+        return hipModuleOccupancyMaxActiveBlocksPerMultiprocessor(numBlocks, function, blockSize,
+                                                                  dynSharedMemPerBlk);
+      },
+      blockSize);
+
+  HIP_CHECK(hipModuleUnload(module));
+}
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Check if grid size and block size are within valid range using basic kernel functions:
+ *    -# When `dynSharedMemPerBlk = 0`
+ *      - Expected output: return `hipSuccess`
+ *    -# When `dynSharedMemPerBlk = sharedMemPerBlock`
+ *      - Expected output: return `hipSuccess`
+ * Test source
+ * ------------------------
+ *  - unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessor.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
+TEST_CASE("Unit_hipModuleOccupancyMaxActiveBlocksPerMultiprocessor_Positive_RangeValidation") {
+  hipDeviceProp_t devProp;
+  hipModule_t module;
+  hipFunction_t function;
+  int blockSize = 0;
+  int gridSize = 0;
+
+  HIP_CHECK(hipFree(nullptr));
+
+  HIP_CHECK(hipModuleLoad(&module, "simple_kernel.code"));
+  HIPCHECK(hipModuleGetFunction(&function, module, "SimpleKernel"));
+
+  HIP_CHECK(hipGetDeviceProperties(&devProp, 0));
+
+  SECTION("dynSharedMemPerBlk = 0") {
+    // Get potential blocksize
+    HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function, 0, 0));
+
+    MaxActiveBlocksPerMultiprocessor(
+        [blockSize, &function](int* numBlocks) {
+          return hipModuleOccupancyMaxActiveBlocksPerMultiprocessor(numBlocks, function, blockSize,
+                                                                    0);
+        },
+        blockSize, devProp.maxThreadsPerMultiProcessor);
+  }
+  SECTION("dynSharedMemPerBlk = sharedMemPerBlock") {
+    // Get potential blocksize
+    HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function,
+                                                      devProp.sharedMemPerBlock, 0));
+
+    MaxActiveBlocksPerMultiprocessor(
+        [blockSize, devProp, &function](int* numBlocks) {
+          return hipModuleOccupancyMaxActiveBlocksPerMultiprocessor(numBlocks, function, blockSize,
+                                                                    devProp.sharedMemPerBlock);
+        },
+        blockSize, devProp.maxThreadsPerMultiProcessor);
+  }
+
+  HIP_CHECK(hipModuleUnload(module));
+}

catch/unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags.cc

@@ -0,0 +1,139 @@
+/*
+Copyright (c) 2022 Advanced Micro Devices, Inc. All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+*/
+
+#include "occupancy_common.hh"
+
+/**
+ * @addtogroup hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags
+ * @{
+ * @ingroup OccupancyTest
+ * `hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(int* numBlocks, hipFunction_t f,
+ * int blockSize, size_t dynSharedMemPerBlk, unsigned int flags)` -
+ * Returns occupancy for a device function.
+ */
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When output pointer to the grid size is `nullptr`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When block size is 0
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When flag is invalid, because only default flag is supported
+ *      - Platform specific (NVIDIA)
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
+TEST_CASE("Unit_hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags_Negative_Parameters") {
+  hipModule_t module;
+  hipFunction_t function;
+  int numBlocks = 0;
+  int blockSize = 0;
+  int gridSize = 0;
+
+  HIP_CHECK(hipFree(nullptr));
+
+  HIP_CHECK(hipModuleLoad(&module, "simple_kernel.code"));
+  HIPCHECK(hipModuleGetFunction(&function, module, "SimpleKernel"));
+
+  // Get potential blocksize
+  HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function, 0, 0));
+
+  // Common negative tests
+  MaxActiveBlocksPerMultiprocessorNegative(
+      [&function](int* numBlocks, int blockSize, size_t dynSharedMemPerBlk) {
+        return hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(
+            numBlocks, function, blockSize, dynSharedMemPerBlk, hipOccupancyDefault);
+      },
+      blockSize);
+
+#if HT_NVIDIA // EXSWHTEC-219
+  SECTION("Flag is invalid") {
+    // Only default flag is supported
+    HIP_CHECK_ERROR(hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(
+                        &numBlocks, function, blockSize, 0, 2),
+                    hipErrorInvalidValue);
+  }
+#endif
+
+  HIP_CHECK(hipModuleUnload(module));
+}
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Check if grid size and block size are within valid range using basic kernel functions:
+ *    -# When `dynSharedMemPerBlk = 0`
+ *      - Expected output: return `hipSuccess`
+ *    -# When `dynSharedMemPerBlk = sharedMemPerBlock`
+ *      - Expected output: return `hipSuccess`
+ * Test source
+ * ------------------------
+ *  - unit/occupancy/hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
+TEST_CASE(
+    "Unit_hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags_Positive_RangeValidation") {
+  hipDeviceProp_t devProp;
+  hipModule_t module;
+  hipFunction_t function;
+  int blockSize = 0;
+  int gridSize = 0;
+
+  HIP_CHECK(hipFree(nullptr));
+
+  HIP_CHECK(hipModuleLoad(&module, "simple_kernel.code"));
+  HIPCHECK(hipModuleGetFunction(&function, module, "SimpleKernel"));
+
+  HIP_CHECK(hipGetDeviceProperties(&devProp, 0));
+
+  SECTION("dynSharedMemPerBlk = 0") {
+    // Get potential blocksize
+    HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function, 0, 0));
+
+    MaxActiveBlocksPerMultiprocessor(
+        [blockSize, &function](int* numBlocks) {
+          return hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(
+              numBlocks, function, blockSize, 0, hipOccupancyDefault);
+        },
+        blockSize, devProp.maxThreadsPerMultiProcessor);
+  }
+  SECTION("dynSharedMemPerBlk = sharedMemPerBlock") {
+    // Get potential blocksize
+    HIP_CHECK(hipModuleOccupancyMaxPotentialBlockSize(&gridSize, &blockSize, function,
+                                                      devProp.sharedMemPerBlock, 0));
+
+    MaxActiveBlocksPerMultiprocessor(
+        [blockSize, devProp, &function](int* numBlocks) {
+          return hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags(
+              numBlocks, function, blockSize, devProp.sharedMemPerBlock, hipOccupancyDefault);
+        },
+        blockSize, devProp.maxThreadsPerMultiProcessor);
+  }
+
+  HIP_CHECK(hipModuleUnload(module));
+}