Add backward compatibility workflow and tests

Author: bratpiorka

.github/workflows/pr_push.yml

@@ -85,3 +85,11 @@ jobs:
       contents: read
       security-events: write
     uses: ./.github/workflows/reusable_trivy.yml
+  Compatibility:
+    needs: [Build]
+    uses: ./.github/workflows/reusable_compatibility.yml
+    strategy:
+      matrix:
+        tag: ["v0.10.1"]
+    with:
+      tag: ${{matrix.tag}}

.github/workflows/reusable_compatibility.yml

@@ -0,0 +1,125 @@
+# Workflow for checkig the backward compatibility of UMF.
+# Test the latest UMF shared library with binaries compiled using the older UMF 
+# shared library.
+name: Compatibility 
+
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: Check backward compatibility with this tag
+        type: string
+        default: "v0.10.1"
+
+permissions:
+  contents: read
+
+jobs:
+  ubuntu-build:
+    # TODO add other OSes
+    name: Ubuntu
+    runs-on: 'ubuntu-22.04'
+
+    steps:
+      # NOTE: we need jemalloc for older version of UMF
+    - name: Install apt packages
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y clang cmake libnuma-dev libjemalloc-dev libtbb-dev
+
+    - name: Checkout "tag" UMF version
+      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      with:
+        fetch-depth: 0
+        ref: refs/tags/${{inputs.tag}}
+        path: ${{github.workspace}}/tag_version
+
+    - name: Install libhwloc
+      working-directory: ${{github.workspace}}/tag_version
+      run: .github/scripts/install_hwloc.sh
+        
+    - name: Get "tag" UMF version
+      working-directory: ${{github.workspace}}/tag_version
+      run: |
+        VERSION=$(git describe --tags --abbrev=0 | grep -oP '\d+\.\d+\.\d+')
+        echo "tag version: $VERSION"
+
+    - name: Configure "tag" UMF build
+      working-directory: ${{github.workspace}}/tag_version
+      run: >
+        cmake
+        -B ${{github.workspace}}/tag_version/build
+        -DCMAKE_INSTALL_PREFIX="${{github.workspace}}/tag_version/build/install"
+        -DCMAKE_BUILD_TYPE=Debug
+        -DUMF_BUILD_SHARED_LIBRARY=ON
+        -DCMAKE_C_COMPILER=gcc
+        -DCMAKE_CXX_COMPILER=g++
+        -DUMF_BUILD_TESTS=ON
+        -DUMF_BUILD_LEVEL_ZERO_PROVIDER=ON
+        -DUMF_BUILD_CUDA_PROVIDER=ON
+        -DUMF_FORMAT_CODE_STYLE=OFF
+        -DUMF_DEVELOPER_MODE=ON
+        -DUMF_BUILD_LIBUMF_POOL_JEMALLOC=ON
+        -DUMF_BUILD_LIBUMF_POOL_DISJOINT=ON
+        -DUMF_TESTS_FAIL_ON_SKIP=ON
+
+    - name: Build "tag" UMF
+      working-directory: ${{github.workspace}}/tag_version
+      run: |
+        cmake --build ${{github.workspace}}/tag_version/build -j $(nproc)
+        
+    # For UMF < 0.11 set ptrace_scope
+    - name: Set ptrace value for IPC test
+      if: ${{ startsWith(inputs.tag, 'v0.10.') || startsWith(inputs.tag, 'v0.9.') }}
+      run: sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
+
+    - name: Run "tag" UMF tests
+      working-directory: ${{github.workspace}}/tag_version/build
+      run: |
+        LD_LIBRARY_PATH=${{github.workspace}}/tag_version/build/lib/ ctest --output-on-failure
+
+    - name: Checkout latest UMF version
+      uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      with:
+        fetch-depth: 0
+        path: ${{github.workspace}}/latest_version
+        
+    - name: Get latest UMF version
+      working-directory: ${{github.workspace}}/latest_version
+      run: |
+        VERSION=$(git describe --tags --abbrev=0 | grep -oP '\d+\.\d+\.\d+')
+        echo "checked version: $VERSION"
+        
+    - name: Configure latest UMF build
+      working-directory: ${{github.workspace}}/latest_version
+      run: >
+        cmake
+        -B ${{github.workspace}}/latest_version/build
+        -DCMAKE_INSTALL_PREFIX="${{github.workspace}}/latest_version/build/install"
+        -DCMAKE_BUILD_TYPE=Debug
+        -DUMF_BUILD_SHARED_LIBRARY=ON
+        -DCMAKE_C_COMPILER=gcc
+        -DCMAKE_CXX_COMPILER=g++
+        -DUMF_BUILD_TESTS=ON
+        -DUMF_BUILD_LEVEL_ZERO_PROVIDER=ON
+        -DUMF_BUILD_CUDA_PROVIDER=ON
+        -DUMF_FORMAT_CODE_STYLE=OFF
+        -DUMF_DEVELOPER_MODE=ON
+        -DUMF_BUILD_LIBUMF_POOL_JEMALLOC=ON
+        -DUMF_BUILD_LIBUMF_POOL_DISJOINT=ON
+        -DUMF_TESTS_FAIL_ON_SKIP=ON
+
+    - name: Build latest UMF
+      working-directory: ${{github.workspace}}/latest_version
+      run: |
+        cmake --build ${{github.workspace}}/latest_version/build -j $(nproc)
+
+    # NOTE: exclude umf-provider_coarse, umf-disjointCoarseMallocPool, 
+    # umf-jemalloc_coarse_file, umf-scalable_coarse_file as they use Coarse 
+    # Provider which is not supported for UMF > 0.10.0
+    - name: Run "tag" UMF tests with latest UMF libs (warnings enabled)
+      working-directory: ${{github.workspace}}/tag_version/build
+      run: >
+        UMF_LOG="level:warning;flush:debug;output:stderr;pid:no" 
+        LD_LIBRARY_PATH=${{github.workspace}}/latest_version/build/lib/ 
+        ctest --output-on-failure -E "umf-provider_coarse|umf-disjointCoarseMallocPool|umf-jemalloc_coarse_file|umf-scalable_coarse_file"

examples/custom_file_provider/custom_file_provider.c

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2024 Intel Corporation
+ * Copyright (C) 2024-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -234,7 +234,7 @@ static umf_result_t file_get_min_page_size(void *provider, void *ptr,
 
 // File provider operations
 static umf_memory_provider_ops_t file_ops = {
-    .version = UMF_VERSION_CURRENT,
+    .version = UMF_PROVIDER_OPS_VERSION_CURRENT,
     .initialize = file_init,
     .finalize = file_deinit,
     .alloc = file_alloc,

include/umf/memory_pool.h

@@ -11,6 +11,7 @@
 #define UMF_MEMORY_POOL_H 1
 
 #include <umf/base.h>
+#include <umf/memory_pool_ops.h>
 #include <umf/memory_provider.h>
 
 #ifdef __cplusplus
@@ -22,12 +23,6 @@ extern "C" {
 ///        functions
 typedef struct umf_memory_pool_t *umf_memory_pool_handle_t;
 
-/// @brief This structure comprises function pointers used by corresponding umfPool*
-///        calls. Each memory pool implementation should initialize all function
-///        pointers.
-///
-typedef struct umf_memory_pool_ops_t umf_memory_pool_ops_t;
-
 /// @brief Supported pool creation flags
 typedef enum umf_pool_create_flag_t {
     UMF_POOL_CREATE_FLAG_NONE =

include/umf/memory_pool_ops.h

@@ -17,14 +17,19 @@
 extern "C" {
 #endif
 
+/// @brief Version of the Memory Pool ops structure.
+/// NOTE: This is equal to the latest UMF version, in which the ops structure
+/// has been modified.
+#define UMF_POOL_OPS_VERSION_CURRENT UMF_MAKE_VERSION(0, 11)
+
 ///
 /// @brief This structure comprises function pointers used by corresponding umfPool*
 /// calls. Each memory pool implementation should initialize all function
 /// pointers.
 ///
-typedef struct umf_memory_pool_ops_t {
+typedef struct umf_memory_pool_ops_0_11_t {
     /// Version of the ops structure.
-    /// Should be initialized using UMF_VERSION_CURRENT.
+    /// Should be initialized using UMF_POOL_OPS_VERSION_CURRENT.
     uint32_t version;
 
     ///
@@ -120,7 +125,8 @@ typedef struct umf_memory_pool_ops_t {
     ///         The value is undefined if the previous allocation was successful.
     ///
     umf_result_t (*get_last_allocation_error)(void *pool);
-} umf_memory_pool_ops_t;
+} umf_memory_pool_ops_0_11_t;
+typedef umf_memory_pool_ops_0_11_t umf_memory_pool_ops_t;
 
 #ifdef __cplusplus
 }

include/umf/memory_provider_ops.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -16,12 +16,17 @@
 extern "C" {
 #endif
 
+/// @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(0, 11)
+
 ///
 /// @brief This structure comprises optional function pointers used
 /// by corresponding umfMemoryProvider* calls. A memory provider implementation
 /// can keep them NULL.
 ///
-typedef struct umf_memory_provider_ext_ops_t {
+typedef struct umf_memory_provider_ext_ops_0_11_t {
     ///
     /// @brief Discard physical pages within the virtual memory mapping associated at the given addr
     ///        and \p size. This call is asynchronous and may delay purging the pages indefinitely.
@@ -78,13 +83,14 @@ typedef struct umf_memory_provider_ext_ops_t {
     umf_result_t (*allocation_split)(void *hProvider, void *ptr,
                                      size_t totalSize, size_t firstSize);
 
-} umf_memory_provider_ext_ops_t;
+} umf_memory_provider_ext_ops_0_11_t;
+typedef umf_memory_provider_ext_ops_0_11_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 {
+typedef struct umf_memory_provider_ipc_ops_0_11_t {
     ///
     /// @brief Retrieve the size of opaque data structure required to store IPC data.
     /// @param provider pointer to the memory provider.
@@ -134,16 +140,17 @@ typedef struct umf_memory_provider_ipc_ops_t {
     ///         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, size_t size);
-} umf_memory_provider_ipc_ops_t;
+} umf_memory_provider_ipc_ops_0_11_t;
+typedef umf_memory_provider_ipc_ops_0_11_t umf_memory_provider_ipc_ops_t;
 
 ///
 /// @brief This structure comprises function pointers used by corresponding
 /// umfMemoryProvider* calls. Each memory provider implementation should
 /// initialize all function pointers.
 ///
-typedef struct umf_memory_provider_ops_t {
+typedef struct umf_memory_provider_ops_0_11_t {
     /// Version of the ops structure.
-    /// Should be initialized using UMF_VERSION_CURRENT.
+    /// Should be initialized using UMF_PROVIDER_OPS_VERSION_CURRENT.
     uint32_t version;
 
     ///
@@ -245,7 +252,8 @@ typedef struct umf_memory_provider_ops_t {
     /// @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;
+} umf_memory_provider_ops_0_11_t;
+typedef umf_memory_provider_ops_0_11_t umf_memory_provider_ops_t;
 
 #ifdef __cplusplus
 }

include/umf/providers/provider_devdax_memory.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2024 Intel Corporation
+ * Copyright (C) 2024-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -65,6 +65,10 @@ typedef enum umf_devdax_memory_provider_native_error {
     UMF_DEVDAX_RESULT_ERROR_PURGE_FORCE_FAILED, ///< Force purging failed
 } umf_devdax_memory_provider_native_error_t;
 
+/// @cond
+// use 0.11 version of the ops by default
+#define umfDevDaxMemoryProviderOps umfDevDaxMemoryProviderOps_0_11
+/// @endcond
 umf_memory_provider_ops_t *umfDevDaxMemoryProviderOps(void);
 
 #ifdef __cplusplus

include/umf/providers/provider_file_memory.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2024 Intel Corporation
+ * Copyright (C) 2024-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -66,6 +66,10 @@ typedef enum umf_file_memory_provider_native_error {
     UMF_FILE_RESULT_ERROR_PURGE_FORCE_FAILED, ///< Force purging failed
 } umf_file_memory_provider_native_error_t;
 
+/// @cond
+// use 0.11 version of the ops by default
+#define umfFileMemoryProviderOps umfFileMemoryProviderOps_0_11
+/// @endcond
 umf_memory_provider_ops_t *umfFileMemoryProviderOps(void);
 
 #ifdef __cplusplus

src/CMakeLists.txt

@@ -76,9 +76,13 @@ set(UMF_SOURCES
     memspaces/memspace_highest_bandwidth.c
     memspaces/memspace_lowest_latency.c
     memspaces/memspace_numa.c
+    provider/provider_coarse_deprecated.c
     provider/provider_cuda.c
+    provider/provider_deprecated.c
     provider/provider_devdax_memory.c
+    provider/provider_devdax_memory_deprecated.c
     provider/provider_file_memory.c
+    provider/provider_file_memory_deprecated.c
     provider/provider_fixed_memory.c
     provider/provider_level_zero.c
     provider/provider_os_memory.c

src/cpp_helpers.hpp

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -67,7 +67,7 @@ umf_result_t initialize(T *obj, ArgsTuple &&args) {
 
 template <typename T> umf_memory_pool_ops_t poolOpsBase() {
     umf_memory_pool_ops_t ops{};
-    ops.version = UMF_VERSION_CURRENT;
+    ops.version = UMF_POOL_OPS_VERSION_CURRENT;
     ops.finalize = [](void *obj) { delete reinterpret_cast<T *>(obj); };
     UMF_ASSIGN_OP(ops, T, malloc, ((void *)nullptr));
     UMF_ASSIGN_OP(ops, T, calloc, ((void *)nullptr));
@@ -81,7 +81,7 @@ template <typename T> umf_memory_pool_ops_t poolOpsBase() {
 
 template <typename T> constexpr umf_memory_provider_ops_t providerOpsBase() {
     umf_memory_provider_ops_t ops{};
-    ops.version = UMF_VERSION_CURRENT;
+    ops.version = UMF_PROVIDER_OPS_VERSION_CURRENT;
     ops.finalize = [](void *obj) { delete reinterpret_cast<T *>(obj); };
     UMF_ASSIGN_OP(ops, T, alloc, UMF_RESULT_ERROR_UNKNOWN);
     UMF_ASSIGN_OP(ops, T, free, UMF_RESULT_ERROR_UNKNOWN);