Merge pull request #1301 from bratpiorka/rrudnick_props_api

add memory properties API

Author: bratpiorka

.github/workflows/.spellcheck-conf.toml

@@ -1,6 +1,6 @@
 [default]
 # Don't correct the following words:
-extend-ignore-words-re = ["ASSER", "Tne", "ba", "BA", "PN"]
+extend-ignore-words-re = ["ASSER", "Tne", "ba", "BA", "PN", "usm"]
 
 [files]
 # completely exclude those files from consideration:

docs/config/api.rst

@@ -170,6 +170,26 @@ Memtarget
 .. doxygenfile:: experimental/memtarget.h
     :sections: define enum typedef func
 
+Memory Properties
+==========================================
+
+Memory properties in UMF describe the characteristics and capabilities of 
+different memory regions or allocations. These properties can include 
+information such as memory type, allocation size, context and device used for 
+allocation, and other attributes that are relevant for memory management.
+
+The Memory Properties API allows users to retrieve and interpret these 
+attributes for memory managed by UMF, enabling advanced memory management 
+strategies and improved interoperability with heterogeneous systems.
+
+.. note::
+   The memory properties APIs are experimental and may change in future releases.
+
+Memory Properties
+------------------------------------------
+.. doxygenfile::  experimental/memory_properties.h
+    :sections: define enum typedef func var
+
 Inter-Process Communication
 ==========================================
 

docs/config/spelling_exceptions.txt

@@ -3,22 +3,24 @@ allocatable
 allocator
 allocators
 calloc
-CXL
 copyable
+CUcontext
+CUdevice
 customizable
+CXL
 daxX
-deallocation
 deallocating
+deallocation
 deallocations
-Devdax
 dev
+Devdax
 Globals
+highPtr
 hMemtarget
 hPool
 hProvider
-highPtr
-io
 interprocess
+io
 ipc
 jemalloc
 lowPtr
@@ -48,8 +50,9 @@ partList
 pid
 poolable
 preallocated
-providerIpcData
+propertyId
 providential
+providerIpcData
 ptr
 realloc
 Scalable
@@ -58,11 +61,16 @@ stdout
 Tiering
 tiering
 topologies
+uint
+uintptr
 umf
 umfGetIPCHandle
+umfGetMemoryPropertySize
 umfMemoryProviderAlloc
 umfMemoryProviderGetLastNativeError
 umfMemoryProviderOpenIPCHandle
+umfMemspaceMemtargetAdd
+umfMemspaceUserFilter
 umfOsMemoryProviderParamsDestroy
 umfPool
 umfPoolCalloc
@@ -73,4 +81,6 @@ umfPoolRealloc
 umfMemspaceUserFilter
 umfMemspaceMemtargetAdd
 unfreed
+usm
 zA
+ze

include/umf/base.h

@@ -51,6 +51,33 @@ typedef enum umf_result_t {
     UMF_RESULT_ERROR_UNKNOWN = 0x7ffffffe  ///< Unknown error
 } umf_result_t;
 
+/// @brief Handle to the memory properties structure
+typedef struct umf_memory_properties_t *umf_memory_properties_handle_t;
+
+/// @brief ID of the memory property
+typedef enum umf_memory_property_id_t {
+    UMF_MEMORY_PROPERTY_INVALID = -1, ///< Invalid property
+
+    // UMF specific
+    UMF_MEMORY_PROPERTY_PROVIDER_HANDLE = 0, ///< Handle to the memory provider
+    UMF_MEMORY_PROPERTY_POOL_HANDLE = 1,     ///< Handle to the memory pool
+
+    // generic pointer properties
+    UMF_MEMORY_PROPERTY_BASE_ADDRESS = 10, ///< Base address of the allocation
+    UMF_MEMORY_PROPERTY_BASE_SIZE = 11,    ///< Base size of the allocation
+    UMF_MEMORY_PROPERTY_BUFFER_ID = 12,    ///< Unique identifier for the buffer
+
+    // GPU specific
+    UMF_MEMORY_PROPERTY_POINTER_TYPE = 20, ///< Type of the pointer
+    UMF_MEMORY_PROPERTY_CONTEXT = 21,      ///< GPU context of the allocation
+    UMF_MEMORY_PROPERTY_DEVICE =
+        22, ///< GPU device where the allocation resides
+
+    /// @cond
+    UMF_MEMORY_PROPERTY_MAX_RESERVED = 0x1000, ///< Maximum reserved value
+    /// @endcond
+} umf_memory_property_id_t;
+
 /// @brief Type of the CTL query
 typedef enum umf_ctl_query_type {
     CTL_QUERY_READ,

include/umf/experimental/memory_properties.h

@@ -0,0 +1,64 @@
+/*
+ *
+ * Copyright (C) 2025 Intel Corporation
+ *
+ * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ */
+
+#ifndef UMF_MEMORY_PROPERTIES_H
+#define UMF_MEMORY_PROPERTIES_H 1
+
+#include <umf/base.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// @brief Get the memory properties handle for a given pointer
+/// \details
+///     The handle returned by this function is valid until the memory pointed
+///     to by the pointer is freed.
+/// @param ptr pointer to the allocated memory
+/// @param props_handle [out] pointer to the memory properties handle
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+umf_result_t
+umfGetMemoryPropertiesHandle(const void *ptr,
+                             umf_memory_properties_handle_t *props_handle);
+
+/// @brief Get the size of a specific memory property
+/// \details
+///     The size of the property should be used to allocate a buffer to hold the
+///     value of the property.
+/// @param props_handle handle to the memory properties
+/// @param memory_property_id ID of the memory property to get the size of
+/// @param size [out] pointer to the size of the property
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+umf_result_t
+umfGetMemoryPropertySize(umf_memory_properties_handle_t props_handle,
+                         umf_memory_property_id_t memory_property_id,
+                         size_t *size);
+
+/// @brief Get a specific memory property from the properties handle
+/// \details
+///    The type of the property value depends on the property ID. The size of
+///    the property value buffer must be large enough to hold the
+///    value of the property. The size of the property can be obtained by
+///    calling umfGetMemoryPropertySize() with the same property ID.
+/// @param props_handle handle to the memory properties
+/// @param memory_property_id ID of the memory property to get
+/// @param property_value [out] pointer to the value of the memory property
+///         which will be filled
+/// @param max_property_size size of the property value buffer
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+umf_result_t umfGetMemoryProperty(umf_memory_properties_handle_t props_handle,
+                                  umf_memory_property_id_t memory_property_id,
+                                  void *property_value,
+                                  size_t max_property_size);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_MEMORY_PROPERTIES_H */

include/umf/memory_provider_ops.h

@@ -21,7 +21,7 @@ extern "C" {
 /// @brief Version of the Memory Provider ops structure.
 /// NOTE: This is equal to the latest UMF version, in which the ops structure
 /// has been modified.
-#define UMF_PROVIDER_OPS_VERSION_CURRENT UMF_MAKE_VERSION(1, 0)
+#define UMF_PROVIDER_OPS_VERSION_CURRENT UMF_MAKE_VERSION(1, 1)
 
 ///
 /// @brief This structure comprises function pointers used by corresponding
@@ -288,6 +288,40 @@ typedef struct umf_memory_provider_ops_t {
                             const char *name, void *arg, size_t size,
                             umf_ctl_query_type_t queryType, va_list args);
 
+    // The following operations were added in ops version 1.1
+
+    ///
+    /// @brief Retrieve provider-specific properties of the memory allocation.
+    /// \details
+    ///     If provider supports allocation properties,
+    ///     ext_get_allocation_properties and ext_get_allocation_properties_size,
+    ///     must either be all set or all NULL.
+    /// @param provider pointer to the memory provider
+    /// @param ptr pointer to the allocated memory
+    /// @param memory_property_id ID of the memory property
+    /// @param property_value [out] pointer to the value of the memory property
+    ///         which will be filled
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+    ///
+    umf_result_t (*ext_get_allocation_properties)(
+        void *provider, const void *ptr,
+        umf_memory_property_id_t memory_property_id, void *property_value);
+
+    /// @brief Retrieve size of the provider-specific properties of the memory
+    ///        allocation.
+    /// \details
+    ///     If provider supports allocation properties,
+    ///     ext_get_allocation_properties and ext_get_allocation_properties_size,
+    ///     must either be all set or all NULL.
+    /// @param provider pointer to the memory provider
+    /// @param memory_property_id ID of the memory property to get the size of
+    /// @param size [out] pointer to the size of the property
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+    ///
+    umf_result_t (*ext_get_allocation_properties_size)(
+        void *provider, umf_memory_property_id_t memory_property_id,
+        size_t *size);
+
 } umf_memory_provider_ops_t;
 
 #ifdef __cplusplus

src/CMakeLists.txt

@@ -42,6 +42,7 @@ set(UMF_SOURCES
     ipc.c
     ipc_cache.c
     memory_pool.c
+    memory_properties.c
     memory_provider.c
     memory_provider_get_last_failed.c
     memtarget.c

src/ipc.c

@@ -58,14 +58,19 @@ umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *umfIPCHandle,
     }
 
     size_t ipcHandleSize = 0;
-    umf_alloc_info_t allocInfo;
-    umf_result_t ret = umfMemoryTrackerGetAllocInfo(ptr, &allocInfo);
+    umf_memory_properties_handle_t props = NULL;
+    umf_result_t ret = umfGetMemoryPropertiesHandle(ptr, &props);
     if (ret != UMF_RESULT_SUCCESS) {
-        LOG_ERR("cannot get alloc info for ptr = %p.", ptr);
+        LOG_ERR("cannot get alloc props for ptr = %p.", ptr);
         return ret;
     }
 
-    ret = umfPoolGetIPCHandleSize(allocInfo.pool, &ipcHandleSize);
+    if (props == NULL || props->pool == NULL) {
+        LOG_ERR("cannot get pool from alloc info for ptr = %p.", ptr);
+        return UMF_RESULT_ERROR_UNKNOWN;
+    }
+
+    ret = umfPoolGetIPCHandleSize(props->pool, &ipcHandleSize);
     if (ret != UMF_RESULT_SUCCESS) {
         LOG_ERR("cannot get IPC handle size.");
         return ret;
@@ -79,11 +84,14 @@ umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *umfIPCHandle,
 
     // We cannot use umfPoolGetMemoryProvider function because it returns
     // upstream provider but we need tracking one
-    umf_memory_provider_handle_t provider = allocInfo.pool->provider;
-    assert(provider);
+    if (props->pool->provider == NULL) {
+        LOG_ERR("cannot get memory provider from pool");
+        umf_ba_global_free(ipcData);
+        return UMF_RESULT_ERROR_UNKNOWN;
+    }
+    umf_memory_provider_handle_t provider = props->pool->provider;
 
-    ret = umfMemoryProviderGetIPCHandle(provider, allocInfo.base,
-                                        allocInfo.baseSize,
+    ret = umfMemoryProviderGetIPCHandle(provider, props->base, props->base_size,
                                         (void *)ipcData->providerIpcData);
     if (ret != UMF_RESULT_SUCCESS) {
         LOG_ERR("failed to get IPC handle.");
@@ -92,10 +100,10 @@ umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *umfIPCHandle,
     }
 
     // ipcData->handle_id is filled by tracking provider
-    ipcData->base = allocInfo.base;
+    ipcData->base = props->base;
     ipcData->pid = utils_getpid();
-    ipcData->baseSize = allocInfo.baseSize;
-    ipcData->offset = (uintptr_t)ptr - (uintptr_t)allocInfo.base;
+    ipcData->baseSize = props->base_size;
+    ipcData->offset = (uintptr_t)ptr - (uintptr_t)props->base;
 
     *umfIPCHandle = ipcData;
     *size = ipcHandleSize;

src/libumf.def

@@ -6,7 +6,7 @@
 
 LIBRARY UMF
 
-VERSION 1.0
+VERSION 1.1
 
 EXPORTS
     DllMain
@@ -149,6 +149,9 @@ EXPORTS
     umfDevDaxMemoryProviderParamsSetName
     umfFileMemoryProviderParamsSetName
     umfFixedMemoryProviderParamsSetName
+    umfGetMemoryPropertiesHandle
+    umfGetMemoryProperty
+    umfGetMemoryPropertySize
     umfJemallocPoolParamsSetName
     umfLevelZeroMemoryProviderParamsSetName
     umfOsMemoryProviderParamsSetName

src/libumf.map

@@ -147,6 +147,9 @@ UMF_1.1 {
     umfDevDaxMemoryProviderParamsSetName;
     umfFileMemoryProviderParamsSetName;
     umfFixedMemoryProviderParamsSetName;
+    umfGetMemoryPropertiesHandle;
+    umfGetMemoryProperty;
+    umfGetMemoryPropertySize;
     umfJemallocPoolParamsSetName;
     umfLevelZeroMemoryProviderParamsSetName;
     umfOsMemoryProviderParamsSetName;