Merge pull request #1032 from lukaszstolarczuk/merge-v0.10.x-into-main

Merge v0.10.x into main

CMakeLists.txt

@@ -11,7 +11,7 @@ list(APPEND CMAKE_MODULE_PATH "${UMF_CMAKE_SOURCE_DIR}/cmake")
 include(${UMF_CMAKE_SOURCE_DIR}/cmake/helpers.cmake)
 
 # We use semver aligned version, set via git tags. We parse git output to
-# establih the version of UMF to be used in CMake, Win dll's, and within the
+# establish the version of UMF to be used in CMake, Win dll's, and within the
 # code (e.g. in logger). We have 3-component releases (e.g. 1.5.1) plus release
 # candidates and git info. Function below sets all variables related to version.
 set_version_variables()
@@ -33,36 +33,47 @@ include(CMakePackageConfigHelpers)
 include(GNUInstallDirs)
 find_package(PkgConfig)
 
+# Define a list to store the names of all options
+set(UMF_OPTIONS_LIST "")
+list(APPEND UMF_OPTIONS_LIST CMAKE_BUILD_TYPE)
+
+# Define a macro to wrap the option() command and track the options
+macro(umf_option)
+    list(APPEND UMF_OPTIONS_LIST ${ARGV0})
+    option(${ARGV})
+endmacro()
+
 # Build Options
-option(UMF_BUILD_SHARED_LIBRARY "Build UMF as shared library" OFF)
-option(UMF_BUILD_LEVEL_ZERO_PROVIDER "Build Level Zero memory provider" ON)
-option(UMF_BUILD_CUDA_PROVIDER "Build CUDA memory provider" ON)
-option(UMF_BUILD_LIBUMF_POOL_DISJOINT
-       "Build the libumf_pool_disjoint static library" OFF)
-option(UMF_BUILD_LIBUMF_POOL_JEMALLOC
-       "Build the libumf_pool_jemalloc static library" OFF)
-option(UMF_BUILD_TESTS "Build UMF tests" ON)
-option(UMF_BUILD_GPU_TESTS "Build UMF GPU tests" OFF)
-option(UMF_BUILD_BENCHMARKS "Build UMF benchmarks" OFF)
-option(UMF_BUILD_BENCHMARKS_MT "Build UMF multithreaded benchmarks" OFF)
-option(UMF_BUILD_EXAMPLES "Build UMF examples" ON)
-option(UMF_BUILD_FUZZTESTS "Build UMF fuzz tests" OFF)
-option(UMF_BUILD_GPU_EXAMPLES "Build UMF GPU examples" OFF)
-option(UMF_DEVELOPER_MODE "Enable additional developer checks" OFF)
-option(
+umf_option(UMF_BUILD_SHARED_LIBRARY "Build UMF as shared library" OFF)
+umf_option(UMF_BUILD_LEVEL_ZERO_PROVIDER "Build Level Zero memory provider" ON)
+umf_option(UMF_BUILD_CUDA_PROVIDER "Build CUDA memory provider" ON)
+umf_option(UMF_BUILD_LIBUMF_POOL_DISJOINT
+           "Build the libumf_pool_disjoint static library" OFF)
+umf_option(UMF_BUILD_LIBUMF_POOL_JEMALLOC
+           "Build the libumf_pool_jemalloc static library" OFF)
+umf_option(UMF_BUILD_TESTS "Build UMF tests" ON)
+umf_option(UMF_BUILD_GPU_TESTS "Build UMF GPU tests" OFF)
+umf_option(UMF_BUILD_BENCHMARKS "Build UMF benchmarks" OFF)
+umf_option(UMF_BUILD_BENCHMARKS_MT "Build UMF multithreaded benchmarks" OFF)
+umf_option(UMF_BUILD_EXAMPLES "Build UMF examples" ON)
+umf_option(UMF_BUILD_FUZZTESTS "Build UMF fuzz tests" OFF)
+umf_option(UMF_BUILD_GPU_EXAMPLES "Build UMF GPU examples" OFF)
+umf_option(UMF_DEVELOPER_MODE "Enable additional developer checks" OFF)
+umf_option(
     UMF_DISABLE_HWLOC
     "Disable hwloc and UMF features requiring it (OS provider, memtargets, topology discovery)"
     OFF)
-option(
+umf_option(
     UMF_LINK_HWLOC_STATICALLY
     "Link UMF with HWLOC library statically (proxy library will be disabled on Windows+Debug build)"
     OFF)
-option(UMF_FORMAT_CODE_STYLE
-       "Add clang, cmake, and black -format-check and -format-apply targets"
-       OFF)
+umf_option(
+    UMF_FORMAT_CODE_STYLE
+    "Add clang, cmake, and black -format-check and -format-apply targets" OFF)
 set(UMF_HWLOC_NAME
     "hwloc"
     CACHE STRING "Custom name for hwloc library w/o extension")
+list(APPEND UMF_OPTIONS_LIST UMF_HWLOC_NAME)
 set(UMF_INSTALL_RPATH
     ""
     CACHE
@@ -71,13 +82,13 @@ set(UMF_INSTALL_RPATH
 )
 
 # Only a part of skips is treated as a failure now. TODO: extend to all tests
-option(UMF_TESTS_FAIL_ON_SKIP "Treat skips in tests as fail" OFF)
-option(UMF_USE_ASAN "Enable AddressSanitizer checks" OFF)
-option(UMF_USE_UBSAN "Enable UndefinedBehaviorSanitizer checks" OFF)
-option(UMF_USE_TSAN "Enable ThreadSanitizer checks" OFF)
-option(UMF_USE_MSAN "Enable MemorySanitizer checks" OFF)
-option(UMF_USE_VALGRIND "Enable Valgrind instrumentation" OFF)
-option(UMF_USE_COVERAGE "Build with coverage enabled (Linux only)" OFF)
+umf_option(UMF_TESTS_FAIL_ON_SKIP "Treat skips in tests as fail" OFF)
+umf_option(UMF_USE_ASAN "Enable AddressSanitizer checks" OFF)
+umf_option(UMF_USE_UBSAN "Enable UndefinedBehaviorSanitizer checks" OFF)
+umf_option(UMF_USE_TSAN "Enable ThreadSanitizer checks" OFF)
+umf_option(UMF_USE_MSAN "Enable MemorySanitizer checks" OFF)
+umf_option(UMF_USE_VALGRIND "Enable Valgrind instrumentation" OFF)
+umf_option(UMF_USE_COVERAGE "Build with coverage enabled (Linux only)" OFF)
 
 # set UMF_PROXY_LIB_BASED_ON_POOL to one of: SCALABLE or JEMALLOC
 set(KNOWN_PROXY_LIB_POOLS SCALABLE JEMALLOC)
@@ -87,6 +98,7 @@ set(UMF_PROXY_LIB_BASED_ON_POOL
           "A UMF pool the proxy library is based on (SCALABLE or JEMALLOC)")
 set_property(CACHE UMF_PROXY_LIB_BASED_ON_POOL
              PROPERTY STRINGS ${KNOWN_PROXY_LIB_POOLS})
+list(APPEND UMF_OPTIONS_LIST UMF_PROXY_LIB_BASED_ON_POOL)
 
 if(UMF_BUILD_TESTS
    AND DEFINED ENV{CI}

CONTRIBUTING.md

@@ -2,15 +2,19 @@
 
 
 <!-- TODO: Add [Naming convention](#naming-convention) section -->
-- [Opening new issues](#opening-new-issues)
-- [Submitting Pull Requests](#submitting-pull-requests)
+- [Contributing to UMF (Unified Memory Framework)](#contributing-to-umf-unified-memory-framework)
+  - [Opening new issues](#opening-new-issues)
+  - [Submitting Pull Requests](#submitting-pull-requests)
     - [Building and testing](#building-and-testing)
     - [Code style](#code-style)
-    - [When my PR is merged?](#when-my-PR-is-merged)
+    - [When my PR is merged?](#when-my-pr-is-merged)
     - [Extending public API](#extending-public-api)
     - [License](#license)
     - [Adding new dependency](#adding-new-dependency)
-- [Code coverage](#code-coverage)
+  - [Code coverage](#code-coverage)
+  - [Debugging](#debugging)
+    - [Checking the UMF version and CMake variables (Linux only)](#checking-the-umf-version-and-cmake-variables-linux-only)
+      - [Requirements](#requirements)
 
 Below you'll find instructions on how to contribute to UMF, either with code changes
 or issues. All contributions are most welcome!
@@ -222,3 +226,19 @@ $ apt install lcov
 $ lcov --capture --directory . --output-file coverage.info
 $ genhtml -o html_report coverage.info
 ```
+
+## Debugging
+
+### Checking the UMF version and CMake variables (Linux only)
+
+Strings with the UMF version and useful CMake variables can be grepped in the following way:
+
+```bash
+$ strings libumf.so | grep "@(#)"
+@(#) Intel(R) UMF version: 0.11.0-dev.git66.g89e3831d
+@(#) Intel(R) UMF CMake variables: "CMAKE_BUILD_TYPE:Debug,...
+```
+
+#### Requirements
+
+- binutils package (Linux)

ChangeLog

@@ -1,3 +1,13 @@
+Fri Jan 10 2025 Łukasz Stolarczuk <[email protected]>
+
+	* Version 0.10.1
+
+	This patch release contains:
+	- Set symbol versions 0.10 in def/map files (#1013)
+	- Fix: remove incorrect assert in utils_align_ptr_up_size_down() (#977)
+	- Add strings with UMF version and useful CMake options (#992)
+	- Extended error messages, when providers are disabled (#1012)
+
 Mon Dec 09 2024 Łukasz Stolarczuk <[email protected]>
 
 	* Version 0.10.0

RELEASE_STEPS.md

@@ -38,9 +38,9 @@ Do changes for a release:
     - If previously we decided not to create such branch, create it now, based on the appropriate minor or major tag
   - For major/minor release start from the `main` branch
 - Add an entry to ChangeLog, remember to change the day of the week in the release date
-  - For major releases mention API and ABI compatibility with the previous release
+  - 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)
-- For major releases update ABI version in `.map` and `.def` files
+- 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:
   - `git commit -a -S -m "$VERSION release"`

src/CMakeLists.txt

@@ -11,11 +11,24 @@ set(UMF_CUDA_INCLUDE_DIR
     ""
     CACHE PATH "Directory containing the CUDA headers")
 
+# Compose the UMF_ALL_CMAKE_VARIABLES variable containing CMake options that
+# will be saved in the constant string.
+list(SORT UMF_OPTIONS_LIST ORDER DESCENDING)
+foreach(_var ${UMF_OPTIONS_LIST})
+    # Preprocessor definitions containing '#' cannot be passed on to the
+    # compiler command line because many compilers do not support it.
+    if(NOT "${${_var}}" MATCHES "#")
+        set(UMF_ALL_CMAKE_VARIABLES
+            "${_var}:${${_var}},${UMF_ALL_CMAKE_VARIABLES}")
+    endif()
+endforeach()
+
 # Compile definitions for UMF library.
 #
 # TODO: Cleanup the compile definitions across all the CMake files
-set(UMF_COMMON_COMPILE_DEFINITIONS ${UMF_COMMON_COMPILE_DEFINITIONS}
-                                   UMF_VERSION=${UMF_VERSION})
+set(UMF_COMMON_COMPILE_DEFINITIONS
+    ${UMF_COMMON_COMPILE_DEFINITIONS} UMF_VERSION=${UMF_VERSION}
+    UMF_ALL_CMAKE_VARIABLES="${UMF_ALL_CMAKE_VARIABLES}")
 
 set(BA_SOURCES
     ${CMAKE_CURRENT_SOURCE_DIR}/base_alloc/base_alloc.c

src/libumf.def

@@ -4,9 +4,9 @@
 ; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ;;;;  End Copyright Notice
 
-LIBRARY umf
+LIBRARY UMF
 
-VERSION 1.0
+VERSION 0.11
 
 EXPORTS
     DllMain

src/libumf.map

@@ -2,7 +2,7 @@
 # Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
-UMF_1.0 {
+UMF_0.10 {
     global:
         umfInit;
         umfTearDown;
@@ -25,9 +25,6 @@ UMF_1.0 {
         umfFileMemoryProviderParamsSetPath;
         umfFileMemoryProviderParamsSetProtection;
         umfFileMemoryProviderParamsSetVisibility;
-        umfFixedMemoryProviderOps;
-        umfFixedMemoryProviderParamsCreate;
-        umfFixedMemoryProviderParamsDestroy;
         umfFree;
         umfGetIPCHandle;
         umfGetLastFailedMemoryProvider;
@@ -117,3 +114,9 @@ UMF_1.0 {
     local:
         *;
 };
+
+UMF_0.11 {
+        umfFixedMemoryProviderOps;
+        umfFixedMemoryProviderParamsCreate;
+        umfFixedMemoryProviderParamsDestroy;
+} UMF_0.10;

src/provider/provider_cuda.c

@@ -12,31 +12,37 @@
 #include <umf.h>
 #include <umf/providers/provider_cuda.h>
 
+#include "utils_log.h"
+
 #if defined(UMF_NO_CUDA_PROVIDER)
 
 umf_result_t umfCUDAMemoryProviderParamsCreate(
     umf_cuda_memory_provider_params_handle_t *hParams) {
     (void)hParams;
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfCUDAMemoryProviderParamsDestroy(
     umf_cuda_memory_provider_params_handle_t hParams) {
     (void)hParams;
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfCUDAMemoryProviderParamsSetContext(
     umf_cuda_memory_provider_params_handle_t hParams, void *hContext) {
     (void)hParams;
     (void)hContext;
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfCUDAMemoryProviderParamsSetDevice(
     umf_cuda_memory_provider_params_handle_t hParams, int hDevice) {
     (void)hParams;
     (void)hDevice;
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
@@ -45,11 +51,13 @@ umf_result_t umfCUDAMemoryProviderParamsSetMemoryType(
     umf_usm_memory_type_t memoryType) {
     (void)hParams;
     (void)memoryType;
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_memory_provider_ops_t *umfCUDAMemoryProviderOps(void) {
     // not supported
+    LOG_ERR("CUDA provider is disabled (UMF_BUILD_CUDA_PROVIDER is OFF)!");
     return NULL;
 }
 

src/provider/provider_devdax_memory.c

@@ -17,10 +17,13 @@
 #include <umf/memory_provider_ops.h>
 #include <umf/providers/provider_devdax_memory.h>
 
+#include "utils_log.h"
+
 #if defined(_WIN32) || defined(UMF_NO_HWLOC)
 
 umf_memory_provider_ops_t *umfDevDaxMemoryProviderOps(void) {
     // not supported
+    LOG_ERR("DevDax memory provider is disabled!");
     return NULL;
 }
 
@@ -30,12 +33,14 @@ umf_result_t umfDevDaxMemoryProviderParamsCreate(
     (void)hParams;
     (void)path;
     (void)size;
+    LOG_ERR("DevDax memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfDevDaxMemoryProviderParamsDestroy(
     umf_devdax_memory_provider_params_handle_t hParams) {
     (void)hParams;
+    LOG_ERR("DevDax memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
@@ -45,13 +50,15 @@ umf_result_t umfDevDaxMemoryProviderParamsSetDeviceDax(
     (void)hParams;
     (void)path;
     (void)size;
+    LOG_ERR("DevDax memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfDevDaxMemoryProviderParamsSetProtection(
     umf_devdax_memory_provider_params_handle_t hParams, unsigned protection) {
     (void)hParams;
     (void)protection;
+    LOG_ERR("DevDax memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 

src/provider/provider_file_memory.c

@@ -18,37 +18,44 @@
 #include <umf/memory_provider_ops.h>
 #include <umf/providers/provider_file_memory.h>
 
+#include "utils_log.h"
+
 #if defined(_WIN32) || defined(UMF_NO_HWLOC)
 
 umf_memory_provider_ops_t *umfFileMemoryProviderOps(void) {
     // not supported
+    LOG_ERR("File memory provider is disabled!");
     return NULL;
 }
 
 umf_result_t umfFileMemoryProviderParamsCreate(
     umf_file_memory_provider_params_handle_t *hParams, const char *path) {
     (void)hParams;
     (void)path;
+    LOG_ERR("File memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfFileMemoryProviderParamsDestroy(
     umf_file_memory_provider_params_handle_t hParams) {
     (void)hParams;
+    LOG_ERR("File memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfFileMemoryProviderParamsSetPath(
     umf_file_memory_provider_params_handle_t hParams, const char *path) {
     (void)hParams;
     (void)path;
+    LOG_ERR("File memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
 umf_result_t umfFileMemoryProviderParamsSetProtection(
     umf_file_memory_provider_params_handle_t hParams, unsigned protection) {
     (void)hParams;
     (void)protection;
+    LOG_ERR("File memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }
 
@@ -57,6 +64,7 @@ umf_result_t umfFileMemoryProviderParamsSetVisibility(
     umf_memory_visibility_t visibility) {
     (void)hParams;
     (void)visibility;
+    LOG_ERR("File memory provider is disabled!");
     return UMF_RESULT_ERROR_NOT_SUPPORTED;
 }