EXSWHTEC-224 - Test cases ID clean up and documentation for GL Interop

catch/include/hip_test_defgroups.hh

@@ -192,3 +192,10 @@ THE SOFTWARE.
  * This section describes tests for the Complex type functions.
  * @}
  */
+
+/**
+ * @defgroup GLTest Interop
+ * @{
+ * This section describes tests for the GL interop functions of HIP runtime API.
+ * @}
+ */

catch/unit/gl_interop/hipGLGetDevices.cc

@@ -26,11 +26,32 @@ THE SOFTWARE.
 
 #include "gl_interop_common.hh"
 
+/**
+ * @addtogroup hipGLGetDevices hipGLGetDevices
+ * @{
+ * @ingroup GLTest
+ * `hipGLGetDevices(unsigned int* pHipDeviceCount, int* pHipDevices,
+ * unsigned int hipDeviceCount, hipGLDeviceList deviceList)` -
+ * Queries devices associated with GL Context.
+ */
+
 namespace {
 constexpr std::array<hipGLDeviceList, 3> kDeviceLists{
     hipGLDeviceListAll, hipGLDeviceListCurrentFrame, hipGLDeviceListNextFrame};
 }  // anonymous namespace
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Queries devices for each GL Context.
+ *  - Expects that each GL Context return only one device.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGLGetDevices.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGLGetDevices_Positive_Basic") {
   GLContextScopeGuard gl_context;
 
@@ -47,6 +68,23 @@ TEST_CASE("Unit_hipGLGetDevices_Positive_Basic") {
   REQUIRE(gl_devices.at(0) == 0);
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of different scenarios:
+ *    -# When output pointer to the HIP Device count is `nullptr`
+ *      - Expected output: return `hipSuccess`
+ *    -# When output pointer to the HIP devices is `nullptr`
+ *      - Expected output: return `hipSuccess`
+ *    -# When the total number of HIP devices is 0
+ *      - Expected output: return `hipSuccess`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGLGetDevices.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGLGetDevices_Positive_Parameters") {
   GLContextScopeGuard gl_context;
 
@@ -72,6 +110,19 @@ TEST_CASE("Unit_hipGLGetDevices_Positive_Parameters") {
   }
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When device list enumeration is invalid (-1)
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGLGetDevices.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGLGetDevices_Negative_Parameters") {
   GLContextScopeGuard gl_context;
 

catch/unit/gl_interop/hipGraphicsGLRegisterBuffer.cc

@@ -26,12 +26,32 @@ THE SOFTWARE.
 
 #include "gl_interop_common.hh"
 
+/**
+ * @addtogroup hipGraphicsGLRegisterBuffer hipGraphicsGLRegisterBuffer
+ * @{
+ * @ingroup GLTest
+ * `hipGraphicsGLRegisterBuffer(hipGraphicsResource** resource,
+ * GLuint buffer, unsigned int flags)` -
+ * Registers a GL Buffer for interop and returns corresponding graphics resource.
+ */
+
 namespace {
 constexpr std::array<unsigned int, 3> kFlags{hipGraphicsRegisterFlagsNone,
                                              hipGraphicsRegisterFlagsReadOnly,
                                              hipGraphicsRegisterFlagsWriteDiscard};
 }  // anonymous namespace
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Registers a GL buffer for each supported register flag.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterBuffer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterBuffer_Positive_Basic") {
   GLContextScopeGuard gl_context;
 
@@ -46,6 +66,18 @@ TEST_CASE("Unit_hipGraphicsGLRegisterBuffer_Positive_Basic") {
   HIP_CHECK(hipGraphicsUnregisterResource(vbo_resource));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Registers the same GL buffer twice.
+ *  - Stores the result in two different graphics resources.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterBuffer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterBuffer_Positive_Register_Twice") {
   GLContextScopeGuard gl_context;
 
@@ -60,6 +92,27 @@ TEST_CASE("Unit_hipGraphicsGLRegisterBuffer_Positive_Register_Twice") {
   HIP_CHECK(hipGraphicsUnregisterResource(vbo_resource_2));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When output pointer to the graphics resource is `nullptr`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When GL buffer is not valid
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When flags are not valid
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When flag is `hipGraphicsRegisterFlagsSurfaceLoadStore`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When flag is `hipGraphicsRegisterFlagsTextureGather`
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterBuffer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterBuffer_Negative_Parameters") {
   GLContextScopeGuard gl_context;
 

catch/unit/gl_interop/hipGraphicsGLRegisterImage.cc

@@ -26,13 +26,33 @@ THE SOFTWARE.
 
 #include "gl_interop_common.hh"
 
+/**
+ * @addtogroup hipGraphicsGLRegisterImage hipGraphicsGLRegisterImage
+ * @{
+ * @ingroup GLTest
+ * `hipGraphicsGLRegisterImage(hipGraphicsResource** resource, GLuint image,
+ * GLenum target, unsigned int flags)` -
+ * Register a GL Image for interop and returns the corresponding graphic resource.
+ */
+
 namespace {
 constexpr std::array<unsigned int, 5> kFlags{
     hipGraphicsRegisterFlagsNone, hipGraphicsRegisterFlagsReadOnly,
     hipGraphicsRegisterFlagsWriteDiscard, hipGraphicsRegisterFlagsSurfaceLoadStore,
     hipGraphicsRegisterFlagsTextureGather};
 }  // anonymous namespace
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Registers a GL image for each supported flag.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterImage.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterImage_Positive_Basic") {
   GLContextScopeGuard gl_context;
 
@@ -47,6 +67,18 @@ TEST_CASE("Unit_hipGraphicsGLRegisterImage_Positive_Basic") {
   HIP_CHECK(hipGraphicsUnregisterResource(tex_resource));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Registers the same GL image twice.
+ *  - Stores the result in two different graphics resources.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterImage.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterImage_Positive_Register_Twice") {
   GLContextScopeGuard gl_context;
 
@@ -63,6 +95,27 @@ TEST_CASE("Unit_hipGraphicsGLRegisterImage_Positive_Register_Twice") {
   HIP_CHECK(hipGraphicsUnregisterResource(tex_resource_2));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When output pointer to the graphics resource is `nullptr`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When GL image is not valid
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When target is not valid - buffer instead of image
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When target does not match the object
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When flags are not valid
+ *      - Expected output: return `hipErrorInvalidValue`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsGLRegisterImage.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsGLRegisterImage_Negative_Parameters") {
   GLContextScopeGuard gl_context;
 

catch/unit/gl_interop/hipGraphicsMapResources.cc

@@ -26,6 +26,28 @@ THE SOFTWARE.
 
 #include "gl_interop_common.hh"
 
+/**
+ * @addtogroup hipGraphicsMapResources hipGraphicsMapResources
+ * @{
+ * @ingroup GLTest
+ * `hipGraphicsMapResources(int count, hipGraphicsResource_t* resources,
+ * hipStream_t stream  __dparm(0) )` -
+ * Maps a graphics resource for hip access.
+ */
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Maps graphics resources for HIP access:
+ *    - GL buffer
+ *    - GL image
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsMapResources.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsMapResources_Positive_Basic") {
   GLContextScopeGuard gl_context;
 
@@ -51,6 +73,27 @@ TEST_CASE("Unit_hipGraphicsMapResources_Positive_Basic") {
   HIP_CHECK(hipGraphicsUnregisterResource(resources.at(1)));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When resources count is 0
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When resources array is `nullptr`
+ *      - Expected output: return `hipErrorInvalidValue`
+ *    -# When resources are not registered
+ *      - Expected output: return `hipErrorInvalidHandle`
+ *    -# When resources are already mapped
+ *      - Expected output: return `hipErrorAlreadyMapped`
+ *    -# When the stream is not valid
+ *      - Expected output: return `hipErrorContextIsDestroyed`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsMapResources.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsMapResources_Negative_Parameters") {
   GLContextScopeGuard gl_context;
 

catch/unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc

@@ -26,6 +26,27 @@ THE SOFTWARE.
 
 #include "gl_interop_common.hh"
 
+/**
+ * @addtogroup hipGraphicsResourceGetMappedPointer hipGraphicsResourceGetMappedPointer
+ * @{
+ * @ingroup GLTest
+ * `hipGraphicsResourceGetMappedPointer(void** devPtr, size_t* size,
+ * hipGraphicsResource_t resource)` -
+ * Gets device accessible address of a graphics resource.
+ */
+
+/**
+ * Test Description
+ * ------------------------
+ *  - Gets device accessible address of a graphics resource.
+ *  - Validates that the device accessible address is not `nullptr`.
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsResourceGetMappedPointer_Positive_Basic") {
   GLContextScopeGuard gl_context;
 
@@ -51,6 +72,22 @@ TEST_CASE("Unit_hipGraphicsResourceGetMappedPointer_Positive_Basic") {
   HIP_CHECK(hipGraphicsUnregisterResource(vbo_resource));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of different scenarios:
+ *    -# When output pointer to the device accessible address is `nullptr`.
+ *      - Expected output: return `hipSuccess`
+ *    -# When size is `nullptr`
+ *      - Expected output: return `hipSuccess`
+ *      - Device accessible address is not `nullptr`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsResourceGetMappedPointer_Positive_Parameters") {
   GLContextScopeGuard gl_context;
 
@@ -81,6 +118,25 @@ TEST_CASE("Unit_hipGraphicsResourceGetMappedPointer_Positive_Parameters") {
   HIP_CHECK(hipGraphicsUnregisterResource(vbo_resource));
 }
 
+/**
+ * Test Description
+ * ------------------------
+ *  - Validates handling of invalid arguments:
+ *    -# When resource is non-pointer
+ *      - Expected output: return `hipErrorNotMappedAsPointer`
+ *    -# When resource is unregistered
+ *      - Expected output: return `hipErrorContextIsDestroyed`
+ *    -# When resource is not mapped
+ *      - Expected output: return `hipErrorNotMapped`
+ *    -# When resource is unmapped
+ *      - Expected output: return `hipErrorNotMapped`
+ * Test source
+ * ------------------------
+ *  - unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc
+ * Test requirements
+ * ------------------------
+ *  - HIP_VERSION >= 5.2
+ */
 TEST_CASE("Unit_hipGraphicsResourceGetMappedPointer_Negative_Parameters") {
   GLContextScopeGuard gl_context;