Skip to content

Add backward compatibility workflow and tests #1063

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/pr_push.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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}}
224 changes: 224 additions & 0 deletions .github/workflows/reusable_compatibility.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,224 @@
# 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:
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)
echo "tag version: $VERSION"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why "cut it"? Just running git describe --tags should suffice

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


- name: Configure "tag" UMF build
working-directory: ${{github.workspace}}/tag_version
run: >
cmake
-B ${{github.workspace}}/tag_version/build
-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)
echo "checked version: $VERSION"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


- name: Configure latest UMF build
working-directory: ${{github.workspace}}/latest_version
run: >
cmake
-B ${{github.workspace}}/latest_version/build
-DCMAKE_BUILD_TYPE=Debug
-DUMF_BUILD_SHARED_LIBRARY=ON
-DCMAKE_C_COMPILER=gcc
-DCMAKE_CXX_COMPILER=g++
-DUMF_BUILD_TESTS=OFF
-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"

windows-build:
name: Windows
env:
VCPKG_PATH: "${{github.workspace}}/vcpkg/packages/hwloc_x64-windows;${{github.workspace}}/vcpkg/packages/tbb_x64-windows;${{github.workspace}}/vcpkg/packages/jemalloc_x64-windows"
runs-on: "windows-2022"

steps:
- 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: Initialize vcpkg
uses: lukka/run-vcpkg@5e0cab206a5ea620130caf672fce3e4a6b5666a1 # v11.5
with:
vcpkgGitCommitId: 3dd44b931481d7a8e9ba412621fa810232b66289
vcpkgDirectory: ${{github.workspace}}/vcpkg
vcpkgJsonGlob: '**/vcpkg.json'

- name: Install dependencies
working-directory: ${{github.workspace}}/tag_version
run: vcpkg install
shell: pwsh # Specifies PowerShell as the shell for running the script.

- name: Get "tag" UMF version
working-directory: ${{github.workspace}}/tag_version
run: |
$version = (git describe --tags)
echo "tag version: $VERSION"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


- name: Configure "tag" UMF build
working-directory: ${{github.workspace}}/tag_version
run: >
cmake
-B "${{github.workspace}}/tag_version/build"
-DCMAKE_PREFIX_PATH="${{env.VCPKG_PATH}}"
-DCMAKE_C_COMPILER=cl
-DCMAKE_CXX_COMPILER=cl
-DUMF_BUILD_SHARED_LIBRARY=ON
-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
run: cmake --build "${{github.workspace}}/tag_version/build" --config Debug -j $Env:NUMBER_OF_PROCESSORS

- name: Run "tag" UMF tests
working-directory: "${{github.workspace}}/tag_version/build"
run: ctest -C Debug --output-on-failure --test-dir test

- name: Checkout latest UMF version
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
with:
fetch-depth: 0
path: ${{github.workspace}}/latest_version

# NOTE we use vcpkg setup from "tag" version
- name: Get latest UMF version
working-directory: ${{github.workspace}}/latest_version
run: |
$version = (git describe --tags)
echo "latest version: $VERSION"

- name: Configure latest UMF build
working-directory: ${{github.workspace}}/latest_version
run: >
cmake
-B "${{github.workspace}}/latest_version/build"
-DCMAKE_PREFIX_PATH="${{env.VCPKG_PATH}}"
-DCMAKE_C_COMPILER=cl
-DCMAKE_CXX_COMPILER=cl
-DUMF_BUILD_SHARED_LIBRARY=ON
-DUMF_BUILD_TESTS=OFF
-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
run: cmake --build "${{github.workspace}}/latest_version/build" --config Debug -j $Env:NUMBER_OF_PROCESSORS

# 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
# NOTE2: on Windows we simply overwrite the umf.dll
- name: Run "tag" UMF tests with latest UMF libs (warnings enabled)
working-directory: ${{github.workspace}}/tag_version/build
run: |
$env:UMF_LOG="level:warning;flush:debug;output:stderr;pid:no"
cp ${{github.workspace}}/latest_version/build/bin/Debug/umf.dll ${{github.workspace}}/tag_version/build/bin/Debug/umf.dll
ctest -C Debug --output-on-failure --test-dir test -E "umf-provider_coarse|umf-disjointCoarseMallocPool|umf-jemalloc_coarse_file|umf-scalable_coarse_file"
3 changes: 3 additions & 0 deletions RELEASE_STEPS.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ Do changes for a release:
- Add an entry to ChangeLog, remember to change the day of the week in the release date
- For major and minor (prior 1.0.0) releases mention API and ABI compatibility with the previous release
- For major and minor releases, update `UMF_VERSION_CURRENT` in `include/umf/base.h` (the API version)
- In case of any changes to the memory provider or pool operations structures,
ensure that you also update the corresponding `UMF_PROVIDER_OPS_VERSION_CURRENT`
or `UMF_POOL_OPS_VERSION_CURRENT`. Additionally, make sure to implement backward compatibility with older versions
- For major and minor (prior 1.0.0) releases update ABI version in `.map` and `.def` files
- These files are defined for all public libraries (`libumf` and `proxy_lib`, at the moment)
- Commit these changes and tag the release:
Expand Down
4 changes: 2 additions & 2 deletions examples/custom_file_provider/custom_file_provider.c
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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,
Expand Down
7 changes: 1 addition & 6 deletions include/umf/memory_pool.h
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 =
Expand Down
12 changes: 9 additions & 3 deletions include/umf/memory_pool_ops.h
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should RELEASE_STEPS include this info..?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added


///
/// @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;

///
Expand Down Expand Up @@ -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
}
Expand Down
24 changes: 16 additions & 8 deletions include/umf/memory_provider_ops.h
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;

///
Expand Down Expand Up @@ -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
}
Expand Down
Loading
Loading