add pools and providers to the web docs

Author: bratpiorka

include/umf/memory_pool.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
@@ -22,27 +22,28 @@ extern "C" {
 ///        functions
 typedef struct umf_memory_pool_t *umf_memory_pool_handle_t;
 
-struct umf_memory_pool_ops_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 uint32_t umf_pool_create_flags_t;
 typedef enum umf_pool_create_flag_t {
-    UMF_POOL_CREATE_FLAG_NONE = 0,
+    UMF_POOL_CREATE_FLAG_NONE =
+        0, ///< Pool will be created with no additional flags
     UMF_POOL_CREATE_FLAG_OWN_PROVIDER =
         (1
-         << 0), ///< pool will own the specified provider and destroy it in umfPoolDestroy
+         << 0), ///< Pool will own the specified provider and destroy it in umfPoolDestroy
     /// @cond
     UMF_POOL_CREATE_FLAG_FORCE_UINT32 = 0x7fffffff
     /// @endcond
 
 } umf_pool_create_flag_t;
 
+/// @brief Type for combinations of pool creation flags
+typedef uint32_t umf_pool_create_flags_t;
+
 ///
 /// @brief Creates new memory pool.
 /// @param ops instance of umf_memory_pool_ops_t

include/umf/pools/pool_disjoint.h

@@ -1,4 +1,4 @@
-// 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
 
@@ -29,7 +29,7 @@ umfDisjointPoolSharedLimitsCreate(size_t MaxSize);
 void umfDisjointPoolSharedLimitsDestroy(
     umf_disjoint_pool_shared_limits_t *PoolLimits);
 
-/// Configuration of Disjoint Pool
+/// @brief Configuration of Disjoint Pool
 typedef struct umf_disjoint_pool_params_t {
     /// Minimum allocation size that will be requested from the system.
     /// By default this is the minimum allocation size of each memory type.

include/umf/providers/provider_level_zero.h

@@ -16,10 +16,10 @@ extern "C" {
 
 /// @brief USM memory allocation type
 typedef enum umf_usm_memory_type_t {
-    UMF_MEMORY_TYPE_UNKNOWN = 0,
-    UMF_MEMORY_TYPE_HOST,
-    UMF_MEMORY_TYPE_DEVICE,
-    UMF_MEMORY_TYPE_SHARED,
+    UMF_MEMORY_TYPE_UNKNOWN = 0, ///< The memory pointed to is of unknown type
+    UMF_MEMORY_TYPE_HOST,        ///< The memory pointed to is a host allocation
+    UMF_MEMORY_TYPE_DEVICE, ///< The memory pointed to is a device allocation
+    UMF_MEMORY_TYPE_SHARED, ///< The memory pointed to is a shared ownership allocation
 } umf_usm_memory_type_t;
 
 /// @brief Level Zero Memory Provider settings struct

include/umf/providers/provider_os_memory.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2022-2023 Intel Corporation
+ * Copyright (C) 2022-2024 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -14,65 +14,78 @@
 extern "C" {
 #endif
 
+/// @cond
 #define UMF_OS_RESULTS_START_FROM 1000
+/// @endcond
 
 /// @brief Protection of the memory allocations
 typedef enum umf_mem_protection_flags_t {
     UMF_PROTECTION_NONE = (1 << 0),  ///< Memory allocations can not be accessed
     UMF_PROTECTION_READ = (1 << 1),  ///< Memory allocations can be read.
     UMF_PROTECTION_WRITE = (1 << 2), ///< Memory allocations can be written.
     UMF_PROTECTION_EXEC = (1 << 3),  ///< Memory allocations can be executed.
-
+    /// @cond
     UMF_PROTECTION_MAX // must be the last one
+    /// @endcond
 } umf_mem_protection_flags_t;
 
 /// @brief Memory binding mode
-///
 /// Specifies how memory is bound to NUMA nodes on systems that support NUMA.
 /// Not every mode is supported on every system.
 typedef enum umf_numa_mode_t {
-    UMF_NUMA_MODE_DEFAULT, ///< Default binding mode. Actual binding policy is system-specific.
-    ///  On linux this corresponds to MPOL_DEFAULT. If this mode is specified,
-    ///  nodemask must be NULL and maxnode must be 0.
-    UMF_NUMA_MODE_BIND, ///< Restricts memory allocation to nodes specified in nodemask. Allocations
-    ///  might come from any of the allowed nodes. Nodemask must specify at least one node.
-    UMF_NUMA_MODE_INTERLEAVE, ///< Interleaves memory allocations across the set of nodes specified in nodemask.
-                              /// Nodemask must specify at least one node.
-    UMF_NUMA_MODE_PREFERRED, ///< Specifies preferred node for allocation. If allocation cannot be fulfilled,
-    ///  memory will be allocated from other nodes.
-    UMF_NUMA_MODE_LOCAL, ///< The memory is allocated on the node of the CPU that triggered the allocation.
-    ///  If this mode is specified, nodemask must be NULL and maxnode must be 0.
-    /// TODO: should this be a hint or strict policy?
+    /// Default binding mode. Actual binding policy is system-specific. On
+    /// linux this corresponds to MPOL_DEFAULT. If this mode is specified,
+    /// nodemask must be NULL and maxnode must be 0.
+    UMF_NUMA_MODE_DEFAULT,
+
+    /// Restricts memory allocation to nodes specified in nodemask. Allocations
+    /// might come from any of the allowed nodes. Nodemask must specify at
+    // least one node.
+    UMF_NUMA_MODE_BIND,
+
+    /// Interleaves memory allocations across the set of nodes specified in
+    /// nodemask. Nodemask must specify at least one node.
+    UMF_NUMA_MODE_INTERLEAVE,
+
+    /// Specifies preferred node for allocation. If allocation cannot be
+    /// fulfilled, memory will be allocated from other nodes.
+    UMF_NUMA_MODE_PREFERRED,
+
+    /// The memory is allocated on the node of the CPU that triggered the
+    /// allocation. If this mode is specified, nodemask must be NULL and
+    /// maxnode must be 0.
+    UMF_NUMA_MODE_LOCAL, // TODO: should this be a hint or strict policy?
 } umf_numa_mode_t;
 
 /// @brief Memory provider settings struct
 typedef struct umf_os_memory_provider_params_t {
-    /// combination of 'umf_mem_protection_flags_t' flags
+    /// Combination of 'umf_mem_protection_flags_t' flags
     unsigned protection;
 
     // NUMA config
-    /// points to a bit mask of nodes containing up to maxnode bits, depending on
+    /// Points to a bit mask of nodes containing up to maxnode bits, depending on
     /// selected numa_mode newly allocated memory will be bound to those nodes
     unsigned long *nodemask;
-    /// max number of bits in nodemask
+    /// Max number of bits in nodemask
     unsigned long maxnode;
-    /// describes how nodemask is interpreted
+    /// Describes how nodemask is interpreted
     umf_numa_mode_t numa_mode;
 
     // others
-    /// log level of debug traces
+    /// Log level of debug traces
     int traces;
 } umf_os_memory_provider_params_t;
 
+/// @brief OS Memory Provider operation results
 typedef enum umf_os_memory_provider_native_error {
-    UMF_OS_RESULT_SUCCESS = UMF_OS_RESULTS_START_FROM,
-    UMF_OS_RESULT_ERROR_ALLOC_FAILED,
-    UMF_OS_RESULT_ERROR_ADDRESS_NOT_ALIGNED,
-    UMF_OS_RESULT_ERROR_BIND_FAILED,
-    UMF_OS_RESULT_ERROR_FREE_FAILED,
-    UMF_OS_RESULT_ERROR_PURGE_LAZY_FAILED,
-    UMF_OS_RESULT_ERROR_PURGE_FORCE_FAILED,
-    UMF_OS_RESULT_ERROR_TOPO_DISCOVERY_FAILED,
+    UMF_OS_RESULT_SUCCESS = UMF_OS_RESULTS_START_FROM, ///< Success
+    UMF_OS_RESULT_ERROR_ALLOC_FAILED,        ///< Memory allocation failed
+    UMF_OS_RESULT_ERROR_ADDRESS_NOT_ALIGNED, ///< Allocated address is not aligned
+    UMF_OS_RESULT_ERROR_BIND_FAILED, ///< Binding memory to NUMA node failed
+    UMF_OS_RESULT_ERROR_FREE_FAILED, ///< Memory deallocation failed
+    UMF_OS_RESULT_ERROR_PURGE_LAZY_FAILED,     ///< Lazy purging failed
+    UMF_OS_RESULT_ERROR_PURGE_FORCE_FAILED,    ///< Force purging failed
+    UMF_OS_RESULT_ERROR_TOPO_DISCOVERY_FAILED, ///< HWLOC topology discovery failed
 } umf_os_memory_provider_native_error_t;
 
 umf_memory_provider_ops_t *umfOsMemoryProviderOps(void);

scripts/docs_config/api.rst

@@ -3,22 +3,103 @@ API Documentation
 ==========================================
 
 Globals
-----------------------------------------------------------
+==========================================
 .. doxygenfile:: base.h
-    :sections: enum
+    :sections: define enum
 
 Pools
-----------------------------------------------------------
-Disjoint Pool
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. doxygenfile:: pool_disjoint.h
-    :sections: enum typedef func var
+==========================================
+
+The UMF memory pool is a combination of a pool allocator and a memory provider. 
+The pool allocator controls the memory pool and handles fine-grained memory 
+allocations memory allocations.
+
+UMF includes predefined pool allocators. UMF can also work with user-defined 
+pools which implement the memory pool API.
 
 Memory Pool
-----------------------------------------------------------
+------------------------------------------
+
+The memory pool API provides a malloc-like API for allocating and deallocating 
+memory as well as functions that create, destroy and operate on the pool.
+
 .. doxygenfile:: memory_pool.h
-    :sections: enum typedef func var
+    :sections: define enum typedef func var
+    
+Disjoint Pool
+------------------------------------------
+
+The Disjoint Pool allocates user data using the configured provider, while also 
+preserving metadata in DRAM.
+
+.. doxygenfile:: pool_disjoint.h
+    :sections: define enum typedef func var
+
+Jemalloc Pool
+------------------------------------------
+
+A jemalloc-based memory pool manager. More info about jemalloc could be found
+here: https://github.com/jemalloc/jemalloc.
+
+.. doxygenfile:: pool_jemalloc.h
+    :sections: define enum typedef func var
+
+Proxy Pool
+------------------------------------------
+
+Proxy Pool forwards all requests to the underlying memory provider. Currently 
+umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions are not 
+supported by the Proxy Pool.
+
+.. doxygenfile:: pool_proxy.h
+    :sections: define enum typedef func var
+
+Scalable Pool
+------------------------------------------
+.. doxygenfile:: pool_scalable.h
+    :sections: define enum typedef func var
+
+Providers
+==========================================
+
+The memory provider is responsible for coarse-grained memory allocations and 
+memory page management. 
+
+UMF includes predefined providers, but can also work with providers which 
+implement the memory provider API.
 
 Memory Provider
-----------------------------------------------------------
+------------------------------------------
+
+The memory provider API provides a functions for allocating, deallocating and 
+manipulating coarse-grained memory as well as functions that create, destroy 
+and operate on the provider.
+
 .. doxygenfile:: memory_provider.h
+    :sections: define enum typedef func var
+
+OS Memory Provider
+------------------------------------------
+
+A memory provider that provides memory from an operating system.
+
+.. doxygenfile:: provider_os_memory.h
+    :sections: define enum typedef func var
+
+Level Zero Provider
+------------------------------------------
+
+A memory provider that provides memory from L0 device.
+
+.. doxygenfile:: provider_level_zero.h
+    :sections: define enum typedef func var
+
+Memspace
+==========================================
+
+TODO: Add general information about memspaces.
+
+Memspace
+------------------------------------------
+.. doxygenfile:: memspace.h
+    :sections: define enum typedef func var

scripts/docs_config/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "Intel Unified Memory Framework"
-copyright = "2023, Intel"
+copyright = "2023-2024, Intel"
 author = "Intel"
 
 # The full version, including alpha/beta/rc tags