IPC API

include/umf/ipc.h

@@ -0,0 +1,56 @@
+/*
+ *
+ * Copyright (C) 2023-2024 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_IPC_H
+#define UMF_IPC_H 1
+
+#include <umf/base.h>
+#include <umf/memory_pool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct umf_ipc_data_t *umf_ipc_handle_t;
+
+///
+/// @brief Creates an IPC handle for the specified UMF allocation.
+/// @param ptr pointer to the allocated memory.
+/// @param ipcHandle [out] returned IPC handle.
+/// @param size [out] size of IPC handle in bytes.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *ipcHandle,
+                             size_t *size);
+
+///
+/// @brief Release IPC handle retrieved by umfGetIPCHandle.
+/// @param ipcHandle IPC handle.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfPutIPCHandle(umf_ipc_handle_t ipcHandle);
+
+///
+/// @brief Open IPC handle retrieved by umfGetIPCHandle.
+/// @param hPool [in] Pool handle where to open the the IPC handle.
+/// @param ipcHandle [in] IPC handle.
+/// @param ptr [out] pointer to the memory in the current process.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfOpenIPCHandle(umf_memory_pool_handle_t hPool,
+                              umf_ipc_handle_t ipcHandle, void **ptr);
+
+///
+/// @brief Close IPC handle.
+/// @param ptr [in] pointer to the memory.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfCloseIPCHandle(void *ptr);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_IPC_H */

include/umf/memory_provider.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023 Intel Corporation
+ * Copyright (C) 2023-2024 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -136,6 +136,65 @@ umf_result_t umfMemoryProviderPurgeLazy(umf_memory_provider_handle_t hProvider,
 umf_result_t umfMemoryProviderPurgeForce(umf_memory_provider_handle_t hProvider,
                                          void *ptr, size_t size);
 
+///
+/// @brief Retrieve the size of opaque data structure required to store IPC data.
+/// \param hProvider [in] handle to the memory provider.
+/// \param size [out] pointer to the size.
+/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+umf_result_t
+umfMemoryProviderGetIPCHandleSize(umf_memory_provider_handle_t hProvider,
+                                  size_t *size);
+
+///
+/// @brief Retrieve an IPC memory handle for the specified allocation.
+/// \param hProvider [in] handle to the memory provider.
+/// \param ptr [in] beginning of the virtual memory range returned by
+///                 umfMemoryProviderAlloc function.
+/// \param size [in] size of the memory address range.
+/// \param providerIpcData [out] pointer to the preallocated opaque data structure to store IPC handle.
+/// \return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+///         UMF_RESULT_ERROR_INVALID_ARGUMENT if ptr was not allocated by this provider.
+///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+umf_result_t
+umfMemoryProviderGetIPCHandle(umf_memory_provider_handle_t hProvider,
+                              const void *ptr, size_t size,
+                              void *providerIpcData);
+
+///
+/// @brief Release IPC handle retrieved with get_ipc_handle function.
+/// @param hProvider [in] handle to the memory provider.
+/// @param providerIpcData [in] pointer to the IPC opaque data structure.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData was not created by this provider.
+///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+umf_result_t
+umfMemoryProviderPutIPCHandle(umf_memory_provider_handle_t hProvider,
+                              void *providerIpcData);
+
+///
+/// @brief Open IPC handle.
+/// @param hProvider [in] handle to the memory provider.
+/// @param providerIpcData [in] pointer to the IPC opaque data structure.
+/// @param ptr [out] pointer to the memory to be used in the current process.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
+///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+umf_result_t
+umfMemoryProviderOpenIPCHandle(umf_memory_provider_handle_t hProvider,
+                               void *providerIpcData, void **ptr);
+
+///
+/// @brief Close an IPC memory handle.
+/// @param hProvider [in] handle to the memory provider.
+/// @param ptr [in] pointer returned by umfMemoryProviderOpenIPCHandle function.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+///         UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid \p hProvider or \p ptr are passed.
+///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+umf_result_t
+umfMemoryProviderCloseIPCHandle(umf_memory_provider_handle_t hProvider,
+                                void *ptr);
+
 ///
 /// @brief Retrieve name of a given memory \p hProvider.
 /// @param hProvider handle to the memory provider

include/umf/memory_provider_ops.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023 Intel Corporation
+ * Copyright (C) 2023-2024 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -76,6 +76,61 @@ typedef struct umf_memory_provider_ext_ops_t {
 
 } umf_memory_provider_ext_ops_t;
 
+///
+/// @brief This structure comprises optional IPC API. The API allows sharing of
+/// memory objects across different processes. A memory provider implementation can keep them NULL.
+///
+typedef struct umf_memory_provider_ipc_ops_t {
+    ///
+    /// @brief Retrieve the size of opaque data structure required to store IPC data.
+    /// @param provider pointer to the memory provider.
+    /// @param size [out] pointer to the size.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+    umf_result_t (*get_ipc_handle_size)(void *provider, size_t *size);
+
+    ///
+    /// @brief Retrieve an IPC memory handle for the specified allocation.
+    /// @param provider pointer to the memory provider.
+    /// @param ptr beginning of the virtual memory range.
+    /// @param size size of the memory address range.
+    /// @param providerIpcData [out] pointer to the preallocated opaque data structure to store IPC handle.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if ptr was not allocated by this provider.
+    ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+    umf_result_t (*get_ipc_handle)(void *provider, const void *ptr, size_t size,
+                                   void *providerIpcData);
+
+    ///
+    /// @brief Release IPC handle retrieved with get_ipc_handle function.
+    /// @param provider pointer to the memory provider.
+    /// @param providerIpcData pointer to the IPC opaque data structure.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData was not created by this provider.
+    ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+    umf_result_t (*put_ipc_handle)(void *provider, void *providerIpcData);
+
+    ///
+    /// @brief Open IPC handle.
+    /// @param provider pointer to the memory provider.
+    /// @param providerIpcData pointer to the IPC opaque data structure.
+    /// @param ptr [out] pointer to the memory to be used in the current process.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if providerIpcData cannot be handled by the provider.
+    ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+    umf_result_t (*open_ipc_handle)(void *provider, void *providerIpcData,
+                                    void **ptr);
+
+    ///
+    /// @brief Closes an IPC memory handle.
+    /// @param provider pointer to the memory provider.
+    /// @param ptr pointer to the memory retrieved with open_ipc_handle function.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+    ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if invalid \p ptr is passed.
+    ///         UMF_RESULT_ERROR_NOT_SUPPORTED if IPC functionality is not supported by this provider.
+    umf_result_t (*close_ipc_handle)(void *provider, void *ptr);
+} umf_memory_provider_ipc_ops_t;
+
 ///
 /// @brief This structure comprises function pointers used by corresponding
 /// umfMemoryProvider* calls. Each memory provider implementation should
@@ -180,6 +235,11 @@ typedef struct umf_memory_provider_ops_t {
     /// @brief Optional ops
     ///
     umf_memory_provider_ext_ops_t ext;
+
+    ///
+    /// @brief Optional IPC ops. The API allows sharing of memory objects across different processes.
+    ///
+    umf_memory_provider_ipc_ops_t ipc;
 } umf_memory_provider_ops_t;
 
 #ifdef __cplusplus

src/CMakeLists.txt

@@ -53,6 +53,7 @@ set(BA_SOURCES
 
 set(UMF_SOURCES
     ${BA_SOURCES}
+    ipc.c
     memory_pool.c
     memory_provider.c
     memory_provider_get_last_failed.c

src/cpp_helpers.hpp

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023 Intel Corporation
+ * Copyright (C) 2023-2024 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -93,6 +93,11 @@ template <typename T> umf_memory_provider_ops_t providerOpsBase() {
     UMF_ASSIGN_OP(ops.ext, T, purge_force, UMF_RESULT_ERROR_UNKNOWN);
     UMF_ASSIGN_OP(ops.ext, T, allocation_merge, UMF_RESULT_ERROR_UNKNOWN);
     UMF_ASSIGN_OP(ops.ext, T, allocation_split, UMF_RESULT_ERROR_UNKNOWN);
+    UMF_ASSIGN_OP(ops.ipc, T, get_ipc_handle_size, UMF_RESULT_ERROR_UNKNOWN);
+    UMF_ASSIGN_OP(ops.ipc, T, get_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
+    UMF_ASSIGN_OP(ops.ipc, T, put_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
+    UMF_ASSIGN_OP(ops.ipc, T, open_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
+    UMF_ASSIGN_OP(ops.ipc, T, close_ipc_handle, UMF_RESULT_ERROR_UNKNOWN);
     return ops;
 }
 } // namespace detail

src/ipc.c

@@ -0,0 +1,117 @@
+/*
+ *
+ * Copyright (C) 2023-2024 Intel Corporation
+ *
+ * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+ *
+ */
+
+#include <assert.h>
+#include <stdlib.h>
+
+#include <umf/ipc.h>
+
+#include "base_alloc_global.h"
+#include "ipc_internal.h"
+#include "memory_pool_internal.h"
+#include "provider/provider_tracking.h"
+#include "utils_log.h"
+
+umf_result_t umfGetIPCHandle(const void *ptr, umf_ipc_handle_t *umfIPCHandle,
+                             size_t *size) {
+    size_t ipcHandleSize = 0;
+    umf_alloc_info_t allocInfo;
+    umf_result_t ret = umfMemoryTrackerGetAllocInfo(ptr, &allocInfo);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("umfGetIPCHandle: cannot get alloc info for ptr = %p.", ptr);
+        return ret;
+    }
+
+    // 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);
+
+    size_t providerIPCHandleSize;
+    ret = umfMemoryProviderGetIPCHandleSize(provider, &providerIPCHandleSize);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("umfGetIPCHandle: cannot get IPC handle size.");
+        return ret;
+    }
+
+    ipcHandleSize = sizeof(umf_ipc_data_t) + providerIPCHandleSize;
+    umf_ipc_data_t *ipcData = umf_ba_global_alloc(ipcHandleSize);
+    if (!ipcData) {
+        LOG_ERR("umfGetIPCHandle: failed to allocate ipcData");
+        return UMF_RESULT_ERROR_OUT_OF_HOST_MEMORY;
+    }
+
+    ret =
+        umfMemoryProviderGetIPCHandle(provider, allocInfo.base, allocInfo.size,
+                                      (void *)ipcData->providerIpcData);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("umfGetIPCHandle: failed to get IPC handle.");
+        umf_ba_global_free(ipcData);
+        return ret;
+    }
+
+    ipcData->size = allocInfo.size;
+    ipcData->offset = (uintptr_t)ptr - (uintptr_t)allocInfo.base;
+
+    *umfIPCHandle = ipcData;
+    *size = ipcHandleSize;
+
+    return ret;
+}
+
+umf_result_t umfPutIPCHandle(umf_ipc_handle_t umfIPCHandle) {
+    umf_result_t ret = UMF_RESULT_SUCCESS;
+
+    // TODO: Just return SUCCESS because current tracking memory provider
+    //       implementation does nothing in Put function. Tracking memory
+    //       provider relies on IPC cache and actually Put IPC handle back
+    //       to upstream memory provider when umfMemoryProviderFree is called.
+    //       To support incapsulation we should not take into account
+    //       implementation details of tracking memory provider and find the
+    //       approrpiate pool, get memory provider of that pool and call
+    //       umfMemoryProviderPutIPCHandle(hProvider,
+    //                                     umfIPCHandle->providerIpcData);
+    umf_ba_global_free(umfIPCHandle);
+
+    return ret;
+}
+
+umf_result_t umfOpenIPCHandle(umf_memory_pool_handle_t hPool,
+                              umf_ipc_handle_t umfIPCHandle, void **ptr) {
+
+    // We cannot use umfPoolGetMemoryProvider function because it returns
+    // upstream provider but we need tracking one
+    umf_memory_provider_handle_t hProvider = hPool->provider;
+    void *base = NULL;
+
+    umf_result_t ret = umfMemoryProviderOpenIPCHandle(
+        hProvider, (void *)umfIPCHandle->providerIpcData, &base);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("umfOpenIPCHandle: memory provider failed to IPC handle.");
+        return ret;
+    }
+    *ptr = (void *)((uintptr_t)base + umfIPCHandle->offset);
+
+    return UMF_RESULT_SUCCESS;
+}
+
+umf_result_t umfCloseIPCHandle(void *ptr) {
+    umf_alloc_info_t allocInfo;
+    umf_result_t ret = umfMemoryTrackerGetAllocInfo(ptr, &allocInfo);
+    if (ret != UMF_RESULT_SUCCESS) {
+        LOG_ERR("umfCloseIPCHandle: cannot get alloc info for ptr = %p.", ptr);
+        return ret;
+    }
+
+    // We cannot use umfPoolGetMemoryProvider function because it returns
+    // upstream provider but we need tracking one
+    umf_memory_provider_handle_t hProvider = allocInfo.pool->provider;
+
+    return umfMemoryProviderCloseIPCHandle(hProvider, allocInfo.base);
+}

src/ipc_internal.h

@@ -0,0 +1,33 @@
+/*
+ *
+ * Copyright (C) 2023-2024 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_IPC_INTERNAL_H
+#define UMF_IPC_INTERNAL_H 1
+
+#include <umf/base.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// UMF representation of IPC handle. It contains UMF-specific common data
+// and provider-specific IPC data, stored in providerIpcData.
+// providerIpcData is a Flexible Array Member because its size varies
+// depending on the provider.
+typedef struct umf_ipc_data_t {
+    size_t size; // size of base allocation
+    uint64_t offset;
+    char providerIpcData[];
+} umf_ipc_data_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_IPC_INTERNAL_H */