Merge pull request #976 from lplewa/fixed

add fixed provider

Author: lukaszstolarczuk

README.md

@@ -132,12 +132,9 @@ More detailed documentation is available here: https://oneapi-src.github.io/unif
 
 ### Memory providers
 
-#### Coarse Provider
+#### Fixed memory provider
 
-A memory provider that can provide memory from:
-1) a given pre-allocated buffer (the fixed-size memory provider option) or
-2) from an additional upstream provider (e.g. provider that does not support the free() operation
-   like the File memory provider or the DevDax memory provider - see below).
+A memory provider that can provide memory from a given pre-allocated buffer.
 
 #### OS memory provider
 

include/umf/providers/provider_fixed_memory.h

@@ -0,0 +1,64 @@
+/*
+ * Copyright (C) 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_FIXED_MEMORY_PROVIDER_H
+#define UMF_FIXED_MEMORY_PROVIDER_H
+
+#include <umf/providers/provider_os_memory.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// @cond
+#define UMF_FIXED_RESULTS_START_FROM 4000
+/// @endcond
+
+struct umf_fixed_memory_provider_params_t;
+
+typedef struct umf_fixed_memory_provider_params_t
+    *umf_fixed_memory_provider_params_handle_t;
+
+/// @brief  Create a struct to store parameters of the Fixed Memory Provider.
+/// @param  hParams [out] handle to the newly created parameters struct.
+/// @param  ptr [in] pointer to the memory region.
+/// @param  size [in] size of the memory region in bytes.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfFixedMemoryProviderParamsCreate(
+    umf_fixed_memory_provider_params_handle_t *hParams, void *ptr, size_t size);
+
+/// @brief  Set the memory region in params struct. Overwrites the previous value.
+///         It provides an ability to use the same instance of params to create multiple
+///         instances of the provider for different memory regions.
+/// @param  hParams [in] handle to the parameters of the Fixed Memory Provider.
+/// @param  ptr [in] pointer to the memory region.
+/// @param  size [in] size of the memory region in bytes.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfFixedMemoryProviderParamsSetMemory(
+    umf_fixed_memory_provider_params_handle_t hParams, void *ptr, size_t size);
+
+/// @brief  Destroy parameters struct.
+/// @param  hParams [in] handle to the parameters of the Fixed Memory Provider.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfFixedMemoryProviderParamsDestroy(
+    umf_fixed_memory_provider_params_handle_t hParams);
+
+/// @brief Retrieve the operations structure for the Fixed Memory Provider.
+/// @return Pointer to the umf_memory_provider_ops_t structure.
+umf_memory_provider_ops_t *umfFixedMemoryProviderOps(void);
+
+/// @brief Fixed Memory Provider operation results
+typedef enum umf_fixed_memory_provider_native_error {
+    UMF_FIXED_RESULT_SUCCESS = UMF_FIXED_RESULTS_START_FROM, ///< Success
+    UMF_FIXED_RESULT_ERROR_PURGE_FORCE_FAILED, ///< Force purging failed
+} umf_fixed_memory_provider_native_error_t;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_FIXED_MEMORY_PROVIDER_H */

scripts/docs_config/api.rst

@@ -80,17 +80,12 @@ and operate on the provider.
 .. doxygenfile:: memory_provider.h
     :sections: define enum typedef func var
 
-Coarse Provider
+Fixed Memory Provider
 ------------------------------------------
 
-A memory provider that can provide memory from:
+A memory provider that can provide memory from a given pre-allocated buffer.
 
-1) A given pre-allocated buffer (the fixed-size memory provider option) or
-2) From an additional upstream provider (e.g. provider that does not support 
-   the free() operation like the File memory provider or the DevDax memory 
-   provider - see below).
-
-.. doxygenfile:: provider_coarse.h
+.. doxygenfile:: provider_fixed_memory.h
     :sections: define enum typedef func var
 
 OS Memory Provider

src/CMakeLists.txt

@@ -62,6 +62,7 @@ set(UMF_SOURCES
     provider/provider_cuda.c
     provider/provider_devdax_memory.c
     provider/provider_file_memory.c
+    provider/provider_fixed_memory.c
     provider/provider_level_zero.c
     provider/provider_os_memory.c
     provider/provider_tracking.c

src/libumf.def

@@ -25,13 +25,16 @@ EXPORTS
     umfDevDaxMemoryProviderParamsDestroy
     umfDevDaxMemoryProviderParamsSetDeviceDax
     umfDevDaxMemoryProviderParamsSetProtection
-    umfFree
     umfFileMemoryProviderOps
     umfFileMemoryProviderParamsCreate
     umfFileMemoryProviderParamsDestroy
     umfFileMemoryProviderParamsSetPath
     umfFileMemoryProviderParamsSetProtection
     umfFileMemoryProviderParamsSetVisibility
+    umfFixedMemoryProviderOps
+    umfFixedMemoryProviderParamsCreate
+    umfFixedMemoryProviderParamsDestroy
+    umfFree
     umfGetIPCHandle
     umfGetLastFailedMemoryProvider
     umfJemallocPoolOps

src/libumf.map

@@ -19,13 +19,16 @@ UMF_1.0 {
         umfDevDaxMemoryProviderParamsDestroy;
         umfDevDaxMemoryProviderParamsSetDeviceDax;
         umfDevDaxMemoryProviderParamsSetProtection;
-        umfFree;
         umfFileMemoryProviderOps;
         umfFileMemoryProviderParamsCreate;
         umfFileMemoryProviderParamsDestroy;
         umfFileMemoryProviderParamsSetPath;
         umfFileMemoryProviderParamsSetProtection;
         umfFileMemoryProviderParamsSetVisibility;
+        umfFixedMemoryProviderOps;
+        umfFixedMemoryProviderParamsCreate;
+        umfFixedMemoryProviderParamsDestroy;
+        umfFree;
         umfGetIPCHandle;
         umfGetLastFailedMemoryProvider;
         umfJemallocPoolOps;
@@ -81,13 +84,13 @@ UMF_1.0 {
         umfOsMemoryProviderOps;
         umfOsMemoryProviderParamsCreate;
         umfOsMemoryProviderParamsDestroy;
-        umfOsMemoryProviderParamsSetProtection;
-        umfOsMemoryProviderParamsSetVisibility;
-        umfOsMemoryProviderParamsSetShmName;
         umfOsMemoryProviderParamsSetNumaList;
         umfOsMemoryProviderParamsSetNumaMode;
         umfOsMemoryProviderParamsSetPartSize;
         umfOsMemoryProviderParamsSetPartitions;
+        umfOsMemoryProviderParamsSetProtection;
+        umfOsMemoryProviderParamsSetShmName;
+        umfOsMemoryProviderParamsSetVisibility;
         umfPoolAlignedMalloc;
         umfPoolByPtr;
         umfPoolCalloc;