Improvements to align CTS and Spec for Virtual Memory:

- UR_RESULT_ERROR_INVALID_ENUMERATION test for urVirtualMemSetAccess
- Add test for urVirtualMemMap with different access flags
- Add test for urVirtualMemSetAccess with different access flags
- InvalidEnumeration test for urPhysicalMemCreate and changed some tests to only run once - different size values were not needed for these
- Add test for urPhysicalMemCreate with different flags (only one placeholder is available, this is just a fixture for future additions)
- Add new urPhysicalMemGetInfo entry point along with a reference count enum. Added adapter implementations for this
- Add a test for urPhysicalMemGetInfo and modified urPhysicalMemRelease/Retain to use GetInfo to verify reference count is updated accordingly

Author: martygrant

include/ur_api.h

@@ -231,6 +231,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_COMMAND_BUFFER_UPDATE_WAIT_EVENTS_EXP = 244,              ///< Enumerator for ::urCommandBufferUpdateWaitEventsExp
     UR_FUNCTION_BINDLESS_IMAGES_MAP_EXTERNAL_LINEAR_MEMORY_EXP = 245,     ///< Enumerator for ::urBindlessImagesMapExternalLinearMemoryExp
     UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,               ///< Enumerator for ::urEnqueueEventsWaitWithBarrierExt
+    UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 247,                              ///< Enumerator for ::urPhysicalMemGetInfo
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -4126,6 +4127,43 @@ urPhysicalMemRelease(
     ur_physical_mem_handle_t hPhysicalMem ///< [in][release] handle of the physical memory object to release.
 );
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Physical memory range info queries.
+typedef enum ur_physical_mem_info_t {
+    UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT = 0, ///< [uint32_t] Reference count of the physical memory object.
+                                              ///< The reference count returned should be considered immediately stale.
+                                              ///< It is unsuitable for general use in applications. This feature is
+                                              ///< provided for identifying memory leaks.
+    /// @cond
+    UR_PHYSICAL_MEM_INFO_FORCE_UINT32 = 0x7fffffff
+    /// @endcond
+
+} ur_physical_mem_info_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Get information about a physical memory object.
+///
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_UNINITIALIZED
+///     - ::UR_RESULT_ERROR_DEVICE_LOST
+///     - ::UR_RESULT_ERROR_ADAPTER_SPECIFIC
+///     - ::UR_RESULT_ERROR_INVALID_NULL_HANDLE
+///         + `NULL == hPhysicalMem`
+///     - ::UR_RESULT_ERROR_INVALID_ENUMERATION
+///         + `::UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT < propName`
+UR_APIEXPORT ur_result_t UR_APICALL
+urPhysicalMemGetInfo(
+    ur_physical_mem_handle_t hPhysicalMem, ///< [in][] handle of the physical memory object to query.
+    ur_physical_mem_info_t propName,       ///< [in] type of the info to query.
+    size_t propSize,                       ///< [in] size in bytes of the memory pointed to by pPropValue.
+    void *pPropValue,                      ///< [out][optional][typename(propName, propSize)] array of bytes holding
+                                           ///< the info. If propSize is less than the real number of bytes needed to
+                                           ///< return the info then the ::UR_RESULT_ERROR_INVALID_SIZE error is
+                                           ///< returned and pPropValue is not used.
+    size_t *pPropSizeRet                   ///< [out][optional] pointer to the actual size in bytes of the queried propName."
+);
+
 #if !defined(__GNUC__)
 #pragma endregion
 #endif
@@ -11072,6 +11110,18 @@ typedef struct ur_physical_mem_release_params_t {
     ur_physical_mem_handle_t *phPhysicalMem;
 } ur_physical_mem_release_params_t;
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function parameters for urPhysicalMemGetInfo
+/// @details Each entry is a pointer to the parameter passed to the function;
+///     allowing the callback the ability to modify the parameter's value
+typedef struct ur_physical_mem_get_info_params_t {
+    ur_physical_mem_handle_t *phPhysicalMem;
+    ur_physical_mem_info_t *ppropName;
+    size_t *ppropSize;
+    void **ppPropValue;
+    size_t **ppPropSizeRet;
+} ur_physical_mem_get_info_params_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Function parameters for urAdapterGet
 /// @details Each entry is a pointer to the parameter passed to the function;

include/ur_api_funcs.def

@@ -96,6 +96,7 @@ _UR_API(urMemImageGetInfo)
 _UR_API(urPhysicalMemCreate)
 _UR_API(urPhysicalMemRetain)
 _UR_API(urPhysicalMemRelease)
+_UR_API(urPhysicalMemGetInfo)
 _UR_API(urAdapterGet)
 _UR_API(urAdapterRelease)
 _UR_API(urAdapterRetain)

include/ur_ddi.h

@@ -977,12 +977,22 @@ typedef ur_result_t(UR_APICALL *ur_pfnPhysicalMemRetain_t)(
 typedef ur_result_t(UR_APICALL *ur_pfnPhysicalMemRelease_t)(
     ur_physical_mem_handle_t);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Function-pointer for urPhysicalMemGetInfo
+typedef ur_result_t(UR_APICALL *ur_pfnPhysicalMemGetInfo_t)(
+    ur_physical_mem_handle_t,
+    ur_physical_mem_info_t,
+    size_t,
+    void *,
+    size_t *);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Table of PhysicalMem functions pointers
 typedef struct ur_physical_mem_dditable_t {
     ur_pfnPhysicalMemCreate_t pfnCreate;
     ur_pfnPhysicalMemRetain_t pfnRetain;
     ur_pfnPhysicalMemRelease_t pfnRelease;
+    ur_pfnPhysicalMemGetInfo_t pfnGetInfo;
 } ur_physical_mem_dditable_t;
 
 ///////////////////////////////////////////////////////////////////////////////

include/ur_print.h

@@ -594,6 +594,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemFlags(enum ur_physical_mem
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemProperties(const struct ur_physical_mem_properties_t params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_physical_mem_info_t enum
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemInfo(enum ur_physical_mem_info_t value, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_program_metadata_type_t enum
 /// @returns
@@ -1802,6 +1810,14 @@ UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemRetainParams(const struct
 ///         - `buff_size < out_size`
 UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemReleaseParams(const struct ur_physical_mem_release_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_physical_mem_get_info_params_t struct
+/// @returns
+///     - ::UR_RESULT_SUCCESS
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         - `buff_size < out_size`
+UR_APIEXPORT ur_result_t UR_APICALL urPrintPhysicalMemGetInfoParams(const struct ur_physical_mem_get_info_params_t *params, char *buffer, const size_t buff_size, size_t *out_size);
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print ur_adapter_get_params_t struct
 /// @returns

include/ur_print.hpp

@@ -153,6 +153,9 @@ inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_virtual_mem
 template <>
 inline ur_result_t printFlag<ur_physical_mem_flag_t>(std::ostream &os, uint32_t flag);
 
+template <>
+inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_physical_mem_info_t value, size_t size);
+
 inline ur_result_t printUnion(
     std::ostream &os,
     const union ur_program_metadata_value_t params,
@@ -293,6 +296,7 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_virtual_mem_access_fla
 inline std::ostream &operator<<(std::ostream &os, enum ur_virtual_mem_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_physical_mem_flag_t value);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_physical_mem_properties_t params);
+inline std::ostream &operator<<(std::ostream &os, enum ur_physical_mem_info_t value);
 inline std::ostream &operator<<(std::ostream &os, enum ur_program_metadata_type_t value);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_program_metadata_t params);
 inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_program_properties_t params);
@@ -962,6 +966,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT:
         os << "UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT";
         break;
+    case UR_FUNCTION_PHYSICAL_MEM_GET_INFO:
+        os << "UR_FUNCTION_PHYSICAL_MEM_GET_INFO";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -7434,6 +7441,51 @@ inline std::ostream &operator<<(std::ostream &os, const struct ur_physical_mem_p
     os << "}";
     return os;
 }
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_physical_mem_info_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, enum ur_physical_mem_info_t value) {
+    switch (value) {
+    case UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT:
+        os << "UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT";
+        break;
+    default:
+        os << "unknown enumerator";
+        break;
+    }
+    return os;
+}
+namespace ur::details {
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print ur_physical_mem_info_t enum value
+template <>
+inline ur_result_t printTagged(std::ostream &os, const void *ptr, ur_physical_mem_info_t value, size_t size) {
+    if (ptr == NULL) {
+        return printPtr(os, ptr);
+    }
+
+    switch (value) {
+    case UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT: {
+        const uint32_t *tptr = (const uint32_t *)ptr;
+        if (sizeof(uint32_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(uint32_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        os << *tptr;
+
+        os << ")";
+    } break;
+    default:
+        os << "unknown enumerator";
+        return UR_RESULT_ERROR_INVALID_ENUMERATION;
+    }
+    return UR_RESULT_SUCCESS;
+}
+} // namespace ur::details
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_program_metadata_type_t type
 /// @returns
@@ -13085,6 +13137,40 @@ inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct
     return os;
 }
 
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Print operator for the ur_physical_mem_get_info_params_t type
+/// @returns
+///     std::ostream &
+inline std::ostream &operator<<(std::ostream &os, [[maybe_unused]] const struct ur_physical_mem_get_info_params_t *params) {
+
+    os << ".hPhysicalMem = ";
+
+    ur::details::printPtr(os,
+                          *(params->phPhysicalMem));
+
+    os << ", ";
+    os << ".propName = ";
+
+    os << *(params->ppropName);
+
+    os << ", ";
+    os << ".propSize = ";
+
+    os << *(params->ppropSize);
+
+    os << ", ";
+    os << ".pPropValue = ";
+    ur::details::printTagged(os, *(params->ppPropValue), *(params->ppropName), *(params->ppropSize));
+
+    os << ", ";
+    os << ".pPropSizeRet = ";
+
+    ur::details::printPtr(os,
+                          *(params->ppPropSizeRet));
+
+    return os;
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Print operator for the ur_adapter_get_params_t type
 /// @returns
@@ -18528,6 +18614,9 @@ inline ur_result_t UR_APICALL printFunctionParams(std::ostream &os, ur_function_
     case UR_FUNCTION_PHYSICAL_MEM_RELEASE: {
         os << (const struct ur_physical_mem_release_params_t *)params;
     } break;
+    case UR_FUNCTION_PHYSICAL_MEM_GET_INFO: {
+        os << (const struct ur_physical_mem_get_info_params_t *)params;
+    } break;
     case UR_FUNCTION_ADAPTER_GET: {
         os << (const struct ur_adapter_get_params_t *)params;
     } break;

scripts/core/registry.yml

@@ -607,6 +607,9 @@ etors:
 - name: ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT
   desc: Enumerator for $xEnqueueEventsWaitWithBarrierExt
   value: '246'
+- name: PHYSICAL_MEM_GET_INFO
+  desc: Enumerator for $xPhysicalMemGetInfo
+  value: '247'
 ---
 type: enum
 desc: Defines structure types

scripts/core/virtual_memory.yml

@@ -303,3 +303,45 @@ params:
     - type: $x_physical_mem_handle_t
       name: hPhysicalMem
       desc: "[in][release] handle of the physical memory object to release."
+
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Physical memory range info queries."
+class: $xPhysicalMem
+name: $x_physical_mem_info_t
+typed_etors: True
+etors:
+# properties and size too
+    - name: REFERENCE_COUNT
+      desc: |
+            [uint32_t] Reference count of the physical memory object.
+            The reference count returned should be considered immediately stale.
+            It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.
+
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Get information about a physical memory object."
+class: $xPhysicalMem
+name: GetInfo
+params:
+    - type: $x_physical_mem_handle_t
+      name: hPhysicalMem
+      desc: "[in][] handle of the physical memory object to query."
+    - type: $x_physical_mem_info_t
+      name: propName
+      desc: "[in] type of the info to query."
+    - type: size_t
+      name: propSize
+      desc: "[in] size in bytes of the memory pointed to by pPropValue."
+    - type: void*
+      name: pPropValue
+      desc: >
+          [out][optional][typename(propName, propSize)] array of bytes holding
+          the info. If propSize is less than the real number of bytes needed to
+          return the info then the $X_RESULT_ERROR_INVALID_SIZE error is
+          returned and pPropValue is not used.
+    - type: size_t*
+      name: pPropSizeRet
+      desc: >
+          [out][optional] pointer to the actual size in bytes of the queried
+          propName."

source/adapters/cuda/physical_mem.cpp

@@ -66,3 +66,19 @@ urPhysicalMemRelease(ur_physical_mem_handle_t hPhysicalMem) {
   }
   return UR_RESULT_SUCCESS;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL urPhysicalMemGetInfo(
+    ur_physical_mem_handle_t hPhysicalMem, ur_physical_mem_info_t propName,
+    size_t propSize, void *pPropValue, size_t *pPropSizeRet) {
+
+  UrReturnHelper ReturnValue(propSize, pPropValue, pPropSizeRet);
+
+  switch (propName) {
+  case UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT: {
+    return ReturnValue(hPhysicalMem->getReferenceCount());
+  }
+  default:
+    return UR_RESULT_ERROR_UNSUPPORTED_ENUMERATION;
+  }
+  return UR_RESULT_SUCCESS;
+}

source/adapters/cuda/ur_interface_loader.cpp

@@ -400,6 +400,7 @@ UR_DLLEXPORT ur_result_t UR_APICALL urGetPhysicalMemProcAddrTable(
   pDdiTable->pfnCreate = urPhysicalMemCreate;
   pDdiTable->pfnRelease = urPhysicalMemRelease;
   pDdiTable->pfnRetain = urPhysicalMemRetain;
+  pDdiTable->pfnGetInfo = urPhysicalMemGetInfo;
 
   return retVal;
 }

source/adapters/hip/physical_mem.cpp

@@ -28,3 +28,9 @@ UR_APIEXPORT ur_result_t UR_APICALL
 urPhysicalMemRelease(ur_physical_mem_handle_t) {
   return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
 }
+
+UR_APIEXPORT ur_result_t UR_APICALL
+urPhysicalMemGetInfo(ur_physical_mem_handle_t, ur_physical_mem_info_t, size_t,
+                     void *, size_t *) {
+  return UR_RESULT_ERROR_UNSUPPORTED_FEATURE;
+}