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,19 @@ Memtarget
 .. doxygenfile:: experimental/memtarget.h
     :sections: define enum typedef func
 
+Memory Properties
+==========================================
+
+TODO: Add general information about memory properties.
+
+.. note::
+   The memory properties APIs are experimental and may change in future releases.
+
+Memory Properties
+------------------------------------------
+.. doxygenfile::  experimental/memory_props.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
@@ -47,8 +49,9 @@ partList
 pid
 poolable
 preallocated
-providerIpcData
+propertyId
 providential
+providerIpcData
 ptr
 realloc
 Scalable
@@ -57,18 +60,22 @@ stdout
 Tiering
 tiering
 topologies
+uint
+uintptr
 umf
 umfGetIPCHandle
 umfMemoryProviderAlloc
 umfMemoryProviderGetLastNativeError
 umfMemoryProviderOpenIPCHandle
+umfMemspaceMemtargetAdd
+umfMemspaceUserFilter
 umfOsMemoryProviderParamsDestroy
 umfPool
 umfPoolCalloc
 umfPoolDestroy
 umfPoolGetTag
 umfPoolMallocUsableSize
 umfPoolRealloc
-umfMemspaceUserFilter
-umfMemspaceMemtargetAdd
-unfreed
+unfreed
+usm
+ze

include/umf/base.h

@@ -51,6 +51,39 @@ 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 (void*)
+    UMF_MEMORY_PROPERTY_POOL_HANDLE = 1, ///< Handle to the memory pool (void*)
+
+    // generic pointer properties
+    UMF_MEMORY_PROPERTY_BASE_ADDRESS =
+        10, ///< Base address of the allocation (uintptr_t)
+    UMF_MEMORY_PROPERTY_BASE_SIZE =
+        11, ///< Base size of the allocation (size_t)
+    UMF_MEMORY_PROPERTY_BUFFER_ID =
+        12, ///< Unique identifier for the buffer (uint64_t)
+
+    // GPU specific
+    UMF_MEMORY_PROPERTY_POINTER_TYPE =
+        20, ///< Type of the pointer (umf_usm_memory_type_t)
+    UMF_MEMORY_PROPERTY_CONTEXT =
+        21, ///< GPU context of the allocation (depending on GPU provider, e.g. ze_context_handle_t, CUcontext)
+    UMF_MEMORY_PROPERTY_DEVICE =
+        22, ///< GPU device where the allocation resides (depending on GPU provider, e.g. ze_device_handle_t, CUdevice)
+
+    /// @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_props.h

@@ -0,0 +1,46 @@
+/*
+ *
+ * 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_PROPS_H
+#define UMF_MEMORY_PROPS_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 a specific memory property from the properties handle
+/// @param props_handle handle to the memory properties
+/// @param memory_property_id ID of the memory property to get
+/// @param max_property_size size of the property value buffer
+/// @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 umfGetMemoryProperty(umf_memory_properties_handle_t props_handle,
+                                  umf_memory_property_id_t memory_property_id,
+                                  size_t max_property_size,
+                                  void *property_value);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_MEMORY_PROPS_H */

include/umf/memory_provider_ops.h

@@ -278,6 +278,21 @@ typedef struct umf_memory_provider_ops_t {
                             const char *name, void *arg, size_t size,
                             umf_ctl_query_type_t queryType, va_list args);
 
+    ///
+    /// @brief Retrieve properties of the memory allocation.
+    /// @param provider pointer to the memory provider
+    /// @param ptr pointer to the allocated memory
+    /// @param memory_property_id identifier of the memory property to retrieve
+    /// @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 (*ext_get_allocation_properties)(
+        void *provider, const void *ptr,
+        umf_memory_property_id_t memory_property_id, void *property_value,
+        size_t max_property_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_props.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

@@ -144,3 +144,6 @@ EXPORTS
     umfJemallocPoolParamsDestroy
     umfJemallocPoolParamsSetNumArenas
     umfPoolGetName
+; Added in UMF_1.1
+    umfGetMemoryPropertiesHandle
+    umfGetMemoryProperty

src/libumf.map

@@ -141,3 +141,8 @@ UMF_1.0 {
     local:
         *;
 };
+
+UMF_1.1 {
+        umfGetMemoryPropertiesHandle;
+        umfGetMemoryProperty;
+} UMF_1.0;