[UR] clarify sampler spec and and CTS

Petr Vesely · Petr Vesely · commit fd70d8dbb40c · 2023-05-29T08:53:30.000+01:00
diff --git a/include/ur_api.h b/include/ur_api.h
@@ -2289,9 +2289,6 @@ urSamplerRelease(
 ///         + `NULL == hSampler`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_SAMPLER_INFO_FILTER_MODE < propName`
-///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == pPropValue`
-///         + `NULL == pPropSizeRet`
 ///     - ::UR_RESULT_ERROR_INVALID_SAMPLER
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
@@ -2301,8 +2298,9 @@ urSamplerGetInfo(
     ur_sampler_handle_t hSampler, ///< [in] handle of the sampler object
     ur_sampler_info_t propName,   ///< [in] name of the sampler property to query
     size_t propSize,              ///< [in] size in bytes of the sampler property value provided
-    void *pPropValue,             ///< [out][typename(propName, propSize)] value of the sampler property
-    size_t *pPropSizeRet          ///< [out] size in bytes returned in sampler property value
+    void *pPropValue,             ///< [out][typename(propName, propSize)][optional] value of the sampler
+                                  ///< property
+    size_t *pPropSizeRet          ///< [out][optional] size in bytes returned in sampler property value
 );
 
 ///////////////////////////////////////////////////////////////////////////////
diff --git a/scripts/core/sampler.yml b/scripts/core/sampler.yml
@@ -155,10 +155,10 @@ params:
       desc: "[in] size in bytes of the sampler property value provided"
     - type: "void*"
       name: pPropValue
-      desc: "[out][typename(propName, propSize)] value of the sampler property"
+      desc: "[out][typename(propName, propSize)][optional] value of the sampler property"
     - type: "size_t*"
       name: pPropSizeRet
-      desc: "[out] size in bytes returned in sampler property value"
+      desc: "[out][optional] size in bytes returned in sampler property value"
 returns:
     - $X_RESULT_ERROR_INVALID_SAMPLER
     - $X_RESULT_ERROR_INVALID_VALUE
diff --git a/source/adapters/null/ur_nullddi.cpp b/source/adapters/null/ur_nullddi.cpp
@@ -1019,9 +1019,10 @@ __urdlllocal ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
     ) try {
     ur_result_t result = UR_RESULT_SUCCESS;
 
diff --git a/source/loader/layers/tracing/ur_trcddi.cpp b/source/loader/layers/tracing/ur_trcddi.cpp
@@ -1152,9 +1152,10 @@ __urdlllocal ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
 ) {
     auto pfnGetInfo = context.urDdiTable.Sampler.pfnGetInfo;
 
diff --git a/source/loader/layers/validation/ur_valddi.cpp b/source/loader/layers/validation/ur_valddi.cpp
@@ -1335,9 +1335,10 @@ __urdlllocal ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
 ) {
     auto pfnGetInfo = context.urDdiTable.Sampler.pfnGetInfo;
 
@@ -1350,14 +1351,6 @@ __urdlllocal ur_result_t UR_APICALL urSamplerGetInfo(
             return UR_RESULT_ERROR_INVALID_NULL_HANDLE;
         }
 
-        if (NULL == pPropValue) {
-            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
-        }
-
-        if (NULL == pPropSizeRet) {
-            return UR_RESULT_ERROR_INVALID_NULL_POINTER;
-        }
-
         if (UR_SAMPLER_INFO_FILTER_MODE < propName) {
             return UR_RESULT_ERROR_INVALID_ENUMERATION;
         }
diff --git a/source/loader/ur_ldrddi.cpp b/source/loader/ur_ldrddi.cpp
@@ -1366,9 +1366,10 @@ __urdlllocal ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
 
diff --git a/source/loader/ur_libapi.cpp b/source/loader/ur_libapi.cpp
@@ -1538,9 +1538,6 @@ ur_result_t UR_APICALL urSamplerRelease(
 ///         + `NULL == hSampler`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_SAMPLER_INFO_FILTER_MODE < propName`
-///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == pPropValue`
-///         + `NULL == pPropSizeRet`
 ///     - ::UR_RESULT_ERROR_INVALID_SAMPLER
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
@@ -1551,9 +1548,10 @@ ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
     ) try {
     auto pfnGetInfo = ur_lib::context->urDdiTable.Sampler.pfnGetInfo;
     if (nullptr == pfnGetInfo) {
diff --git a/source/ur_api.cpp b/source/ur_api.cpp
@@ -1277,9 +1277,6 @@ ur_result_t UR_APICALL urSamplerRelease(
 ///         + `NULL == hSampler`
 ///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
 ///         + `::UR_SAMPLER_INFO_FILTER_MODE < propName`
-///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
-///         + `NULL == pPropValue`
-///         + `NULL == pPropSizeRet`
 ///     - ::UR_RESULT_ERROR_INVALID_SAMPLER
 ///     - ::UR_RESULT_ERROR_INVALID_VALUE
 ///     - ::UR_RESULT_ERROR_OUT_OF_HOST_MEMORY
@@ -1290,9 +1287,10 @@ ur_result_t UR_APICALL urSamplerGetInfo(
     size_t
         propSize, ///< [in] size in bytes of the sampler property value provided
     void *
-        pPropValue, ///< [out][typename(propName, propSize)] value of the sampler property
+        pPropValue, ///< [out][typename(propName, propSize)][optional] value of the sampler
+                    ///< property
     size_t *
-        pPropSizeRet ///< [out] size in bytes returned in sampler property value
+        pPropSizeRet ///< [out][optional] size in bytes returned in sampler property value
 ) {
     ur_result_t result = UR_RESULT_SUCCESS;
     return result;
diff --git a/test/conformance/CMakeLists.txt b/test/conformance/CMakeLists.txt
@@ -50,6 +50,7 @@ add_subdirectory(memory)
 add_subdirectory(usm)
 add_subdirectory(event)
 add_subdirectory(queue)
+add_subdirectory(sampler)
 add_subdirectory(enqueue)
 
 if(DEFINED UR_DPCXX)
diff --git a/test/conformance/sampler/CMakeLists.txt b/test/conformance/sampler/CMakeLists.txt
@@ -0,0 +1,11 @@
+# Copyright (C) 2023 Intel Corporation
+# SPDX-License-Identifier: MIT
+
+add_conformance_test_with_devices_environment(sampler 
+    urSamplerCreate.cpp
+    urSamplerCreateWithNativeHandle.cpp 
+    urSamplerGetInfo.cpp 
+    urSamplerGetNativeHandle.cpp 
+    urSamplerRelease.cpp 
+    urSamplerRetain.cpp
+)
diff --git a/test/conformance/sampler/urSamplerCreate.cpp b/test/conformance/sampler/urSamplerCreate.cpp
@@ -0,0 +1,102 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: MIT
+
+#include <uur/fixtures.h>
+
+using SamplerCreateParamTy =
+    std::tuple<bool, ur_sampler_addressing_mode_t, ur_sampler_filter_mode_t>;
+
+struct urSamplerCreateTestWithParam
+    : uur::urContextTestWithParam<SamplerCreateParamTy> {};
+
+namespace uur {
+template <>
+std::string deviceTestWithParamPrinter(
+    const ::testing::TestParamInfo<
+        std::tuple<ur_device_handle_t, SamplerCreateParamTy>> &info) {
+    auto device = std::get<0>(info.param);
+    auto param = std::get<1>(info.param);
+
+    const auto normalized = std::get<0>(param);
+    const auto addr_mode = std::get<1>(param);
+    const auto filter_mode = std::get<2>(param);
+
+    std::stringstream ss;
+    ss << normalized << "_" << addr_mode << "_" << filter_mode;
+    return uur::GetPlatformAndDeviceName(device) + "__" + ss.str();
+}
+} // namespace uur
+UUR_TEST_SUITE_P(
+    urSamplerCreateTestWithParam,
+    ::testing::Combine(
+        ::testing::Values(true, false),
+        ::testing::Values(UR_SAMPLER_ADDRESSING_MODE_NONE,
+                          UR_SAMPLER_ADDRESSING_MODE_CLAMP_TO_EDGE,
+                          UR_SAMPLER_ADDRESSING_MODE_CLAMP,
+                          UR_SAMPLER_ADDRESSING_MODE_REPEAT,
+                          UR_SAMPLER_ADDRESSING_MODE_MIRRORED_REPEAT),
+        ::testing::Values(UR_SAMPLER_FILTER_MODE_NEAREST,
+                          UR_SAMPLER_FILTER_MODE_LINEAR)),
+    uur::deviceTestWithParamPrinter<SamplerCreateParamTy>);
+
+TEST_P(urSamplerCreateTestWithParam, Success) {
+
+    const auto param = getParam();
+    const auto normalized = std::get<0>(param);
+    const auto addr_mode = std::get<1>(param);
+    const auto filter_mode = std::get<2>(param);
+
+    ur_sampler_desc_t sampler_desc{
+        UR_STRUCTURE_TYPE_SAMPLER_DESC, /* stype */
+        nullptr,                        /* pNext */
+        normalized,                     /* normalizedCoords */
+        addr_mode,                      /* addressing mode */
+        filter_mode,                    /* filterMode */
+    };
+
+    ur_sampler_handle_t hSampler = nullptr;
+    ASSERT_SUCCESS(urSamplerCreate(context, &sampler_desc, &hSampler));
+    ASSERT_NE(hSampler, nullptr);
+    EXPECT_SUCCESS(urSamplerRelease(hSampler));
+}
+
+using urSamplerCreateTest = uur::urContextTest;
+UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(urSamplerCreateTest);
+
+TEST_P(urSamplerCreateTest, InvalidNullHandleContext) {
+    ur_sampler_desc_t sampler_desc{
+        UR_STRUCTURE_TYPE_SAMPLER_DESC,   /* stype */
+        nullptr,                          /* pNext */
+        true,                             /* normalizedCoords */
+        UR_SAMPLER_ADDRESSING_MODE_CLAMP, /* addressing mode */
+        UR_SAMPLER_FILTER_MODE_LINEAR,    /* filterMode */
+    };
+    ur_sampler_handle_t hSampler = nullptr;
+    ASSERT_EQ_RESULT(urSamplerCreate(nullptr, &sampler_desc, &hSampler),
+                     UR_RESULT_ERROR_INVALID_NULL_HANDLE);
+}
+
+TEST_P(urSamplerCreateTest, InvalidEnumerationAddrMode) {
+    ur_sampler_desc_t sampler_desc{
+        UR_STRUCTURE_TYPE_SAMPLER_DESC,          /* stype */
+        nullptr,                                 /* pNext */
+        true,                                    /* normalizedCoords */
+        UR_SAMPLER_ADDRESSING_MODE_FORCE_UINT32, /* addressing mode */
+        UR_SAMPLER_FILTER_MODE_LINEAR,           /* filterMode */
+    };
+    ur_sampler_handle_t hSampler = nullptr;
+    ASSERT_EQ_RESULT(urSamplerCreate(context, &sampler_desc, &hSampler),
+                     UR_RESULT_ERROR_INVALID_ENUMERATION);
+}
+TEST_P(urSamplerCreateTest, InvalidEnumerationFilterMode) {
+    ur_sampler_desc_t sampler_desc{
+        UR_STRUCTURE_TYPE_SAMPLER_DESC,      /* stype */
+        nullptr,                             /* pNext */
+        true,                                /* normalizedCoords */
+        UR_SAMPLER_ADDRESSING_MODE_CLAMP,    /* addressing mode */
+        UR_SAMPLER_FILTER_MODE_FORCE_UINT32, /* filterMode */
+    };
+    ur_sampler_handle_t hSampler = nullptr;
+    ASSERT_EQ_RESULT(urSamplerCreate(context, &sampler_desc, &hSampler),
+                     UR_RESULT_ERROR_INVALID_ENUMERATION);
+}
diff --git a/test/conformance/sampler/urSamplerCreateWithNativeHandle.cpp b/test/conformance/sampler/urSamplerCreateWithNativeHandle.cpp
@@ -0,0 +1,16 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: MIT
+
+#include <uur/fixtures.h>
+
+using urSamplerCreateWithNativeHandleTest = uur::urContextTest;
+
+UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(urSamplerCreateWithNativeHandleTest);
+
+TEST_P(urSamplerCreateWithNativeHandleTest, InvalidNullHandleNativeHandle) {
+    ur_sampler_handle_t sampler = nullptr;
+    ur_sampler_native_properties_t props{};
+    ASSERT_EQ_RESULT(
+        UR_RESULT_ERROR_INVALID_NULL_HANDLE,
+        urSamplerCreateWithNativeHandle(nullptr, context, &props, &sampler));
+}
diff --git a/test/conformance/sampler/urSamplerGetInfo.cpp b/test/conformance/sampler/urSamplerGetInfo.cpp
@@ -0,0 +1,78 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: MIT
+
+#include <uur/fixtures.h>
+
+using urSamplerGetInfoTestWithParam =
+    uur::urSamplerTestWithParam<ur_sampler_info_t>;
+UUR_TEST_SUITE_P(urSamplerGetInfoTestWithParam,
+                 ::testing::Values(UR_SAMPLER_INFO_REFERENCE_COUNT,
+                                   UR_SAMPLER_INFO_CONTEXT,
+                                   UR_SAMPLER_INFO_NORMALIZED_COORDS,
+                                   UR_SAMPLER_INFO_ADDRESSING_MODE,
+                                   UR_SAMPLER_INFO_FILTER_MODE),
+                 uur::deviceTestWithParamPrinter<ur_sampler_info_t>);
+
+TEST_P(urSamplerGetInfoTestWithParam, Success) {
+    size_t size = 0;
+    ur_sampler_info_t info = getParam();
+    ASSERT_SUCCESS(urSamplerGetInfo(sampler, info, 0, nullptr, &size));
+    ASSERT_NE(size, 0);
+    std::vector<uint8_t> infoData(size);
+    ASSERT_SUCCESS(
+        urSamplerGetInfo(sampler, info, size, infoData.data(), nullptr));
+
+    switch (info) {
+    case UR_SAMPLER_INFO_REFERENCE_COUNT: {
+        auto *value = reinterpret_cast<uint32_t *>(infoData.data());
+        ASSERT_TRUE(*value > 0);
+        break;
+    }
+    case UR_SAMPLER_INFO_CONTEXT: {
+        auto *value = reinterpret_cast<ur_context_handle_t *>(infoData.data());
+        ASSERT_EQ(*value, this->context);
+        break;
+    }
+    case UR_SAMPLER_INFO_NORMALIZED_COORDS: {
+        auto *value = reinterpret_cast<ur_bool_t *>(infoData.data());
+        ASSERT_EQ(*value, sampler_desc.normalizedCoords);
+        break;
+    }
+    case UR_SAMPLER_INFO_ADDRESSING_MODE: {
+        auto *value =
+            reinterpret_cast<ur_sampler_addressing_mode_t *>(infoData.data());
+        ASSERT_EQ(*value, sampler_desc.addressingMode);
+        break;
+    }
+    case UR_SAMPLER_INFO_FILTER_MODE: {
+        auto *value =
+            reinterpret_cast<ur_sampler_filter_mode_t *>(infoData.data());
+        ASSERT_EQ(*value, sampler_desc.filterMode);
+    }
+    default:
+        break;
+    }
+}
+
+using urSamplerGetInfoTest = uur::urSamplerTest;
+UUR_INSTANTIATE_DEVICE_TEST_SUITE_P(urSamplerGetInfoTest);
+
+TEST_P(urSamplerGetInfoTest, InvalidNullHandleSampler) {
+    uint32_t refcount = 0;
+    ASSERT_EQ_RESULT(urSamplerGetInfo(nullptr, UR_SAMPLER_INFO_REFERENCE_COUNT,
+                                      sizeof(refcount), &refcount, nullptr),
+                     UR_RESULT_ERROR_INVALID_NULL_HANDLE);
+}
+
+TEST_P(urSamplerGetInfoTest, InvalidEnumerationInfo) {
+    size_t size = 0;
+    ASSERT_EQ_RESULT(urSamplerGetInfo(sampler, UR_SAMPLER_INFO_FORCE_UINT32, 0,
+                                      nullptr, &size),
+                     UR_RESULT_ERROR_INVALID_ENUMERATION);
+}
+
+TEST_P(urSamplerGetInfoTest, InvalidValueNull) {
+    ASSERT_EQ_RESULT(urSamplerGetInfo(sampler, UR_SAMPLER_INFO_ADDRESSING_MODE,
+                                      0, nullptr, nullptr),
+                     UR_RESULT_ERROR_INVALID_VALUE);
+}
diff --git a/test/conformance/sampler/urSamplerGetNativeHandle.cpp b/test/conformance/sampler/urSamplerGetNativeHandle.cpp
diff --git a/test/conformance/sampler/urSamplerRelease.cpp b/test/conformance/sampler/urSamplerRelease.cpp
diff --git a/test/conformance/sampler/urSamplerRetain.cpp b/test/conformance/sampler/urSamplerRetain.cpp
diff --git a/test/conformance/testing/include/uur/fixtures.h b/test/conformance/testing/include/uur/fixtures.h
