Merge pull request #2272 from martygrant/martin/virtual-memory-cts-spec-gap

Improvements to align CTS and Spec for Virtual Memory

Author: martygrant

include/ur_api.h

@@ -233,6 +233,7 @@ typedef enum ur_function_t {
     UR_FUNCTION_ENQUEUE_EVENTS_WAIT_WITH_BARRIER_EXT = 246,               ///< Enumerator for ::urEnqueueEventsWaitWithBarrierExt
     UR_FUNCTION_TENSOR_MAP_ENCODE_IM_2_COL_EXP = 247,                     ///< Enumerator for ::urTensorMapEncodeIm2ColExp
     UR_FUNCTION_TENSOR_MAP_ENCODE_TILED_EXP = 248,                        ///< Enumerator for ::urTensorMapEncodeTiledExp
+    UR_FUNCTION_PHYSICAL_MEM_GET_INFO = 249,                              ///< Enumerator for ::urPhysicalMemGetInfo
     /// @cond
     UR_FUNCTION_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -2525,7 +2526,7 @@ typedef enum ur_mem_type_t {
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Memory Information type
 typedef enum ur_mem_info_t {
-    UR_MEM_INFO_SIZE = 0,            ///< [size_t] actual size of of memory object in bytes
+    UR_MEM_INFO_SIZE = 0,            ///< [size_t] actual size of the memory object in bytes
     UR_MEM_INFO_CONTEXT = 1,         ///< [::ur_context_handle_t] context in which the memory object was created
     UR_MEM_INFO_REFERENCE_COUNT = 2, ///< [uint32_t] Reference count of the memory object.
                                      ///< The reference count returned should be considered immediately stale.
@@ -4138,6 +4139,50 @@ 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_CONTEXT = 0,         ///< [::ur_context_handle_t] context in which the physical memory object
+                                              ///< was created.
+    UR_PHYSICAL_MEM_INFO_DEVICE = 1,          ///< [::ur_device_handle_t] device associated with this physical memory
+                                              ///< object.
+    UR_PHYSICAL_MEM_INFO_SIZE = 2,            ///< [size_t] actual size of the physical memory object in bytes.
+    UR_PHYSICAL_MEM_INFO_PROPERTIES = 3,      ///< [::ur_physical_mem_properties_t] properties set when creating this
+                                              ///< physical memory object.
+    UR_PHYSICAL_MEM_INFO_REFERENCE_COUNT = 4, ///< [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
@@ -11317,6 +11362,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

@@ -978,12 +978,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
@@ -1850,6 +1858,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

@@ -155,6 +155,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,
@@ -313,6 +316,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);
@@ -994,6 +998,9 @@ inline std::ostream &operator<<(std::ostream &os, enum ur_function_t value) {
     case UR_FUNCTION_TENSOR_MAP_ENCODE_TILED_EXP:
         os << "UR_FUNCTION_TENSOR_MAP_ENCODE_TILED_EXP";
         break;
+    case UR_FUNCTION_PHYSICAL_MEM_GET_INFO:
+        os << "UR_FUNCTION_PHYSICAL_MEM_GET_INFO";
+        break;
     default:
         os << "unknown enumerator";
         break;
@@ -7498,6 +7505,113 @@ 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_CONTEXT:
+        os << "UR_PHYSICAL_MEM_INFO_CONTEXT";
+        break;
+    case UR_PHYSICAL_MEM_INFO_DEVICE:
+        os << "UR_PHYSICAL_MEM_INFO_DEVICE";
+        break;
+    case UR_PHYSICAL_MEM_INFO_SIZE:
+        os << "UR_PHYSICAL_MEM_INFO_SIZE";
+        break;
+    case UR_PHYSICAL_MEM_INFO_PROPERTIES:
+        os << "UR_PHYSICAL_MEM_INFO_PROPERTIES";
+        break;
+    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_CONTEXT: {
+        const ur_context_handle_t *tptr = (const ur_context_handle_t *)ptr;
+        if (sizeof(ur_context_handle_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_context_handle_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        ur::details::printPtr(os,
+                              *tptr);
+
+        os << ")";
+    } break;
+    case UR_PHYSICAL_MEM_INFO_DEVICE: {
+        const ur_device_handle_t *tptr = (const ur_device_handle_t *)ptr;
+        if (sizeof(ur_device_handle_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_device_handle_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        ur::details::printPtr(os,
+                              *tptr);
+
+        os << ")";
+    } break;
+    case UR_PHYSICAL_MEM_INFO_SIZE: {
+        const size_t *tptr = (const size_t *)ptr;
+        if (sizeof(size_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(size_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        os << *tptr;
+
+        os << ")";
+    } break;
+    case UR_PHYSICAL_MEM_INFO_PROPERTIES: {
+        const ur_physical_mem_properties_t *tptr = (const ur_physical_mem_properties_t *)ptr;
+        if (sizeof(ur_physical_mem_properties_t) > size) {
+            os << "invalid size (is: " << size << ", expected: >=" << sizeof(ur_physical_mem_properties_t) << ")";
+            return UR_RESULT_ERROR_INVALID_SIZE;
+        }
+        os << (const void *)(tptr) << " (";
+
+        os << *tptr;
+
+        os << ")";
+    } break;
+    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
@@ -13805,6 +13919,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
@@ -19652,6 +19800,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/memory.yml

@@ -59,7 +59,7 @@ name: $x_mem_info_t
 typed_etors: True
 etors:
     - name: SIZE
-      desc: "[size_t] actual size of of memory object in bytes"
+      desc: "[size_t] actual size of the memory object in bytes"
     - name: CONTEXT
       desc: "[$x_context_handle_t] context in which the memory object was created"
     - name: REFERENCE_COUNT

scripts/core/registry.yml

@@ -613,6 +613,9 @@ etors:
 - name: TENSOR_MAP_ENCODE_TILED_EXP
   desc: Enumerator for $xTensorMapEncodeTiledExp
   value: '248'
+- name: PHYSICAL_MEM_GET_INFO
+  desc: Enumerator for $xPhysicalMemGetInfo
+  value: '249'
 ---
 type: enum
 desc: Defines structure types