diff --git a/catch/include/hip_test_defgroups.hh b/catch/include/hip_test_defgroups.hh index 680dfa8a0..952719677 100644 --- a/catch/include/hip_test_defgroups.hh +++ b/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. + * @} + */ diff --git a/catch/unit/gl_interop/hipGLGetDevices.cc b/catch/unit/gl_interop/hipGLGetDevices.cc index e9ab9c885..e1cd47fa5 100644 --- a/catch/unit/gl_interop/hipGLGetDevices.cc +++ b/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 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; diff --git a/catch/unit/gl_interop/hipGraphicsGLRegisterBuffer.cc b/catch/unit/gl_interop/hipGraphicsGLRegisterBuffer.cc index 0022a88cf..f465aae33 100644 --- a/catch/unit/gl_interop/hipGraphicsGLRegisterBuffer.cc +++ b/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 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; diff --git a/catch/unit/gl_interop/hipGraphicsGLRegisterImage.cc b/catch/unit/gl_interop/hipGraphicsGLRegisterImage.cc index 0f0546d71..8abec0b4d 100644 --- a/catch/unit/gl_interop/hipGraphicsGLRegisterImage.cc +++ b/catch/unit/gl_interop/hipGraphicsGLRegisterImage.cc @@ -26,6 +26,15 @@ 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 kFlags{ hipGraphicsRegisterFlagsNone, hipGraphicsRegisterFlagsReadOnly, @@ -33,6 +42,17 @@ constexpr std::array kFlags{ 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; diff --git a/catch/unit/gl_interop/hipGraphicsMapResources.cc b/catch/unit/gl_interop/hipGraphicsMapResources.cc index 26babfaf1..cb1e3af9f 100644 --- a/catch/unit/gl_interop/hipGraphicsMapResources.cc +++ b/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; diff --git a/catch/unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc b/catch/unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc index 8bdd5c16c..f78ab62a7 100644 --- a/catch/unit/gl_interop/hipGraphicsResourceGetMappedPointer.cc +++ b/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; diff --git a/catch/unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc b/catch/unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc index 1a48e782b..bbd1c7c88 100644 --- a/catch/unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc +++ b/catch/unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc @@ -26,6 +26,27 @@ THE SOFTWARE. #include "gl_interop_common.hh" +/** + * @addtogroup hipGraphicsSubResourceGetMappedArray hipGraphicsSubResourceGetMappedArray + * @{ + * @ingroup GLTest + * `hipGraphicsSubResourceGetMappedArray(hipArray_t* array, hipGraphicsResource_t resource, + * unsigned int arrayIndex, unsigned int mipLevel)` - + * Get an array through which to access a subresource of a mapped graphics resource. + */ + +/** + * Test Description + * ------------------------ + * - Gets an array through which to access a subresource of a mapped graphics resource. + * - Validates that the array is not `nullptr`. + * Test source + * ------------------------ + * - unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc + * Test requirements + * ------------------------ + * - HIP_VERSION >= 5.2 + */ TEST_CASE("Unit_hipGraphicsSubResourceGetMappedArray_Positive_Basic") { GLContextScopeGuard gl_context; @@ -48,6 +69,31 @@ TEST_CASE("Unit_hipGraphicsSubResourceGetMappedArray_Positive_Basic") { HIP_CHECK(hipGraphicsUnregisterResource(tex_resource)); } +/** + * Test Description + * ------------------------ + * - Validates handling of invalid arguments: + * -# When output pointer to the array is `nullptr` + * - Expected output: return `hipSuccess` + * -# When resource is not a texture + * - Expected output: return `hipErrorNotMappedAsArray` + * -# When resource is unregistered + * - Exptected output: return `hipErrorContextIsDestroyed` + * -# When resource is not mapped + * - Expected output: return `hipErrorNotMapped` + * -# When resource is unmapped + * - Expected output: return `hipErrorNotMapped` + * -# When array index is not valid + * - Expected output: return `hipErrorInvalidValue` + * -# When mip level is not valid + * - Expected output: return `hipErrorInvalidValue` + * Test source + * ------------------------ + * - unit/gl_interop/hipGraphicsSubResourceGetMappedArray.cc + * Test requirements + * ------------------------ + * - HIP_VERSION >= 5.2 + */ TEST_CASE("Unit_hipGraphicsSubResourceGetMappedArray_Negative_Parameters") { GLContextScopeGuard gl_context; diff --git a/catch/unit/gl_interop/hipGraphicsUnmapResources.cc b/catch/unit/gl_interop/hipGraphicsUnmapResources.cc index 529e8d597..5f311bfdc 100644 --- a/catch/unit/gl_interop/hipGraphicsUnmapResources.cc +++ b/catch/unit/gl_interop/hipGraphicsUnmapResources.cc @@ -26,6 +26,39 @@ THE SOFTWARE. #include "gl_interop_common.hh" +/** + * @addtogroup hipGraphicsUnmapResources hipGraphicsUnmapResources + * @{ + * @ingroup GLTest + * `hipGraphicsUnmapResources(int count, hipGraphicsResource_t* resources, + * hipStream_t stream __dparm(0))` - + * Unmaps a graphics resource for hip access. + * ________________________ + * Test cases from other modules: + * - @ref Unit_hipGraphicsMapResources_Positive_Basic + * - @ref Unit_hipGraphicsResourceGetMappedPointer_Positive_Basic + * - @ref Unit_hipGraphicsSubResourceGetMappedArray_Positive_Basic + */ + +/** + * Test Description + * ------------------------ + * - Validates handling of invalid arguments: + * -# When count is 0 + * - Expected output: return `hipErrorInvalidValue` + * -# When resources pointer is `nullptr` + * - Expected output: return `hipErrorInvalidValue` + * -# When resource is not mapped + * - Expected output: return `hipErrorNotMapped` + * -# When stream is not valid + * - Expected output: return `hipErrorContextIsDestroyed` + * Test source + * ------------------------ + * - unit/gl_interop/hipGraphicsUnmapResources.cc + * Test requirements + * ------------------------ + * - HIP_VERSION >= 5.2 + */ TEST_CASE("Unit_hipGraphicsUnmapResources_Negative_Parameters") { GLContextScopeGuard gl_context; diff --git a/catch/unit/gl_interop/hipGraphicsUnregisterResource.cc b/catch/unit/gl_interop/hipGraphicsUnregisterResource.cc index 10fc1f92b..c683a0bb6 100644 --- a/catch/unit/gl_interop/hipGraphicsUnregisterResource.cc +++ b/catch/unit/gl_interop/hipGraphicsUnregisterResource.cc @@ -26,6 +26,36 @@ THE SOFTWARE. #include "gl_interop_common.hh" +/** + * @addtogroup hipGraphicsUnregisterResource hipGraphicsUnregisterResource + * @{ + * @ingroup GLTest + * `hipGraphicsUnregisterResource(hipGraphicsResource_t resource)` - + * Unregisters a graphics resource. + * ________________________ + * Test cases from other modules: + * - @ref Unit_hipGraphicsGLRegisterBuffer_Positive_Basic + * - @ref Unit_hipGraphicsGLRegisterImage_Positive_Basic + * - @ref Unit_hipGraphicsMapResources_Positive_Basic + * - @ref Unit_hipGraphicsResourceGetMappedPointer_Positive_Basic + * - @ref Unit_hipGraphicsSubResourceGetMappedArray_Positive_Basic + */ + +/** + * Test Description + * ------------------------ + * - Validates handling of invalid arguments: + * -# When resource is already unregistered + * - Expected output: return `hipErrorInvalidContext` + * -# When resource is not unmapped + * - Expected output: return `hipErrorAlreadyMapped` + * Test source + * ------------------------ + * - unit/gl_interop/hipGraphicsUnregisterResource.cc + * Test requirements + * ------------------------ + * - HIP_VERSION >= 5.2 + */ TEST_CASE("Unit_hipGraphicsUnregisterResource_Negative_Parameters") { GLContextScopeGuard gl_context;