EXSWHTEC-224 - Test cases ID clean up and documentation for Device Management (#70)

- Test cases ID clean up and documentation for Device Management
- Adjust doxygen comments to fix bugs
- Adjust defgroup comments for test modules

catch/unit/device/hipDeviceSetGetSharedMemConfig.cc

@@ -24,11 +24,30 @@ THE SOFTWARE.
 #include <hip_test_common.hh>
 #include <threaded_zig_zag_test.hh>
 
+/**
+ * @addtogroup hipDeviceSetSharedMemConfig hipDeviceSetSharedMemConfig
+ * @{
+ * @ingroup DeviceTest
+ * `hipDeviceSetSharedMemConfig(hipSharedMemConfig config)` -
+ * The bank width of shared memory on current device is set.
+ */
+
 namespace {
 constexpr std::array<hipSharedMemConfig, 3> kMemConfigs{
     hipSharedMemBankSizeDefault, hipSharedMemBankSizeFourByte, hipSharedMemBankSizeEightByte};
 }  // anonymous namespace
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Checks that all shared memory configs can be set.
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceSetSharedMemConfig_Positive_Basic") {
   const auto device = GENERATE(range(0, HipTest::getDeviceCount()));
   const auto mem_config = GENERATE(from_range(std::begin(kMemConfigs), std::end(kMemConfigs)));
@@ -38,11 +57,49 @@ TEST_CASE("Unit_hipDeviceSetSharedMemConfig_Positive_Basic") {
   HIP_CHECK(hipDeviceSetSharedMemConfig(mem_config));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When shared memory config has ordinal enum number -1:
+ *      - AMD expected output: return `hipErrorNotSupported`
+ *      - NVIDIA expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceSetSharedMemConfig_Negative_Parameters") {
   HIP_CHECK_ERROR(hipDeviceSetSharedMemConfig(static_cast<hipSharedMemConfig>(-1)),
                   hipErrorInvalidValue);
 }
 
+/**
+ * End doxygen group hipDeviceSetSharedMemConfig.
+ * @}
+ */
+
+/**
+ * @addtogroup hipDeviceGetSharedMemConfig hipDeviceGetSharedMemConfig
+ * @{
+ * @ingroup DeviceTest
+ * `hipDeviceGetSharedMemConfig(hipSharedMemConfig* pConfig)` -
+ * Returns bank width of shared memory for current device.
+ */
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Checks that the returned shared memory configuration is the default one.
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Default") {
   const auto device = GENERATE(range(0, HipTest::getDeviceCount()));
   HIP_CHECK(hipSetDevice(device));
@@ -53,6 +110,18 @@ TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Default") {
   REQUIRE(mem_config == hipSharedMemBankSizeFourByte);
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Checks that the returned shared memory configuration is equal
+ *    to the one that is set previously.
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Basic") {
   const auto device = GENERATE(range(0, HipTest::getDeviceCount()));
   const auto mem_config = GENERATE(from_range(std::begin(kMemConfigs), std::end(kMemConfigs)));
@@ -74,6 +143,19 @@ TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Basic") {
   }
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Checks that the returned shared memory configuration from
+ *    the main thread is equal to the one that is set in a separate
+ *    thread previously.
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Threaded") {
   class HipDeviceGetSharedMemConfigTest
       : public ThreadedZigZagTest<HipDeviceGetSharedMemConfigTest> {
@@ -107,6 +189,19 @@ TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Positive_Threaded") {
   test.run();
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Verifies handling of invalid arguments:
+ *    -# When pointer to the output shared memory configuration is `nullptr`:
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/device/hipDeviceSetGetSharedMemConfig.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipDeviceGetSharedMemConfig_Negative_Parameters") {
   HIP_CHECK_ERROR(hipDeviceGetSharedMemConfig(nullptr), hipErrorInvalidValue);
 }