mem props 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:

.github/workflows/reusable_basic.yml

@@ -195,6 +195,8 @@ jobs:
         ${{ matrix.compiler.cxx == 'icpx' && '. /opt/intel/oneapi/setvars.sh' || true }}
         cmake --build ${{env.BUILD_DIR}} -j $(nproc)
 
+    # UMF_LOG="level:debug;flush:debug;output:stderr;pid:no" 
+    # -R "test_provider_os_memory"
     - name: Run tests
       working-directory: ${{env.BUILD_DIR}}
       run: |

docs/config/api.rst

@@ -170,6 +170,12 @@ Memtarget
 .. doxygenfile:: experimental/memtarget.h
     :sections: define enum typedef func
 
+Memory Properties
+==========================================
+
+.. doxygenfile:: memory_props.h
+    :sections: define enum typedef func var
+
 Inter-Process Communication
 ==========================================
 

docs/config/spelling_exceptions.txt

@@ -47,6 +47,7 @@ partList
 pid
 poolable
 preallocated
+propertyId
 providerIpcData
 providential
 ptr
@@ -71,4 +72,5 @@ umfPoolMallocUsableSize
 umfPoolRealloc
 umfMemspaceUserFilter
 umfMemspaceMemtargetAdd
-unfreed
+unfreed
+usm

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_POINTER_TYPE =
+        2, ///< Type of the pointer (umf_usm_memory_type_t)
+    UMF_MEMORY_PROPERTY_BASE_ADDRESS = 3, ///< Base address of the allocation
+    UMF_MEMORY_PROPERTY_BASE_SIZE = 4,    ///< Base size of the allocation
+    UMF_MEMORY_PROPERTY_BUFFER_ID = 5,    ///< Unique identifier for the buffer
+
+    // GPU specific
+    UMF_MEMORY_PROPERTY_CONTEXT = 6, ///< GPU context of the allocation
+    UMF_MEMORY_PROPERTY_DEVICE = 7, ///< 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/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.h

@@ -265,6 +265,21 @@ umf_result_t
 umfMemoryProviderAllocationMerge(umf_memory_provider_handle_t hProvider,
                                  void *lowPtr, void *highPtr, size_t totalSize);
 
+///
+/// @brief Retrieve properties of the memory allocation.
+/// @param hProvider pointer to the memory provider
+/// @param ptr pointer to the allocated memory
+/// @param propertyId identifier of the memory property to retrieve
+/// @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 umfMemoryProviderGetAllocationProperties(
+    umf_memory_provider_handle_t hProvider, const void *ptr,
+    umf_memory_property_id_t propertyId, size_t max_property_size,
+    void *property_value);
+
 #ifdef __cplusplus
 }
 #endif

include/umf/memory_provider_ops.h

@@ -275,6 +275,21 @@ typedef struct umf_memory_provider_ops_t {
                             void *arg, size_t size,
                             umf_ctl_query_type_t queryType);
 
+    ///
+    /// @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 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 (*ext_get_allocation_properties)(
+        void *provider, const void *ptr,
+        umf_memory_property_id_t memory_property_id, size_t max_property_size,
+        void *value);
+
 } umf_memory_provider_ops_t;
 
 #ifdef __cplusplus

scripts/qemu/run-tests.sh

@@ -28,7 +28,9 @@ numactl -H
 
 cd build
 echo "## Running all tests ..."
+#UMF_LOG="level:debug;flush:debug;output:stderr;pid:no" 
 ctest --verbose
+# --output-on-failure -R "memoryPool"
 
 echo "## Running tests bound to a numa node 0 and node 1 ..."
 numactl -N 0 ctest --output-on-failure

src/CMakeLists.txt

@@ -44,6 +44,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