add introduction and glossary to html docs

Author: bratpiorka

scripts/assets/images/intro_architecture.png

@@ -1,5 +1,5 @@
 ==========================================
-Unified Memory Framework API Documentation
+API Documentation
 ==========================================
 
 Globals

scripts/docs_config/api.rst

@@ -0,0 +1,97 @@
+Glossary
+==========================================================
+
+Homogeneous Memory
+  A collection of memory composed of a single memory type, managed by a singular 
+  driver using a uniform approach.
+
+Heterogeneous Memory
+  A set of memory composed of multiple types of memory technologies, each 
+  requiring distinct handling approaches often managed by separate drivers.
+
+Memory Tiering
+  An organization and hierarchy of different types of memory storage within a 
+  system, with each type of memory having distinct characteristics, performance, 
+  and cost attributes. These memory tiers are typically organized in a 
+  hierarchy, with faster, more expensive memory located closer to the processor 
+  and slower, less expensive memory located further away.
+
+Memory Access Initiator 
+  A component in a computer system that initiates or requests access to the 
+  computer's memory subsystem. This could be a CPU, GPU, or other I/O and cache 
+  devices.
+
+Memory Target 
+  Any part of the memory subsystem that can handle memory access requests. This 
+  could be the OS memory (RAM), video memory that resides on the graphics 
+  cards, memory caches, storage, external memory devices connected using 
+  CXL.mem protocol, etc.
+
+Memory Page 
+  A fixed-length contiguous block of virtual memory, described by a single 
+  entry in the page table. It is the smallest unit of data for memory 
+  management in a virtual memory operating system.
+
+Enlightened Application 
+  An application that explicitly manages data allocation distribution among 
+  memory tiers and further data migration. 
+
+Unenlightened Application 
+  An application that coexists with the underlying infrastructure (OS, 
+  frameworks, libraries) that offers various memory tiering and migration 
+  solutions without any code modifications.
+
+Memory Pool 
+  A memory management technique used in computer programming and software 
+  development, where fixed-size blocks of memory are preallocated using one or 
+  more memory providers and then divided into smaller, fixed-size blocks or 
+  chunks. These smaller blocks are then allocated and deallocated by a pool 
+  allocator depending on the needs of the program or application. Thanks to 
+  low fragmentation and constant allocation time, memory pools are used to 
+  optimize memory allocation and deallocation in scenarios where efficiency 
+  and performance are critical.
+
+Pool Allocator 
+  A memory allocator type used to efficiently manage memory pools. 
+
+Memory Provider 
+  A software component responsible for supplying memory or managing memory 
+  targets. A single memory provider kind can efficiently manage the memory 
+  operations for one or multiple devices within the system or other memory 
+  sources like file-backed or user-provided memory.
+
+High Bandwidth Memory (HBM) 
+  A high-speed computer memory. It is used in conjunction with high-performance 
+  graphics accelerators, network devices, and high-performance data centers, as 
+  on-package cache on-package RAM in CPUs, FPGAs, supercomputers, etc.
+
+Compute Express Link (CXL_) 
+  An open standard for high-speed, high-capacity central processing unit 
+  (CPU)-to-device and CPU-to-memory connections, designed for high-performance 
+  data center computers. CXL is built on the serial PCI Express (PCIe) physical 
+  and electrical interface and includes PCIe-based block input/output protocol 
+  (CXL.io), cache-coherent protocols for accessing system memory (CXL.cache), 
+  and device memory (CXL.mem).
+
+oneAPI Threading Building Blocks (oneTBB_)
+  A C++ template library developed by Intel for parallel programming on 
+  multi-core processors. TBB broke down the computation into tasks that can run 
+  in parallel. The library manages and schedules threads to execute these tasks.
+
+jemalloc 
+  A general-purpose malloc implementation that emphasizes fragmentation 
+  avoidance and scalable concurrency support. It provides introspection, memory 
+  management, and tuning features functionalities. Jemalloc_ uses separate pools 
+  (“arenas”) for each CPU which avoids lock contention problems in 
+  multithreading applications and makes them scale linearly with the number of 
+  threads.
+
+Unified Shared Memory (USM) 
+  A programming model which provides a single memory address space that is 
+  shared between CPUs, GPUs, and possibly other accelerators. It simplifies 
+  memory management by transparently handling data migration between the CPU 
+  and the accelerator device as needed.
+
+.. _CXL https://www.computeexpresslink.org/
+.. _oneTBB https://oneapi-src.github.io/oneTBB/
+.. _Jemalloc https://jemalloc.net/

scripts/docs_config/glossary.rst

@@ -7,4 +7,6 @@ Intel Unified Memory Framework documentation
 .. toctree::
    :maxdepth: 3
 
+   introduction.rst
    api.rst
+   glossary.rst

scripts/docs_config/index.rst

@@ -0,0 +1,101 @@
+==============
+ Introduction
+==============
+
+ Motivation
+============
+
+The amount of data associated with modern workloads that need to be processed 
+by modern workloads is continuously growing. To address the increasing demand 
+memory subsystem of modern server platforms is becoming heterogeneous. For 
+example, High-Bandwidth Memory (HBM) introduced in Sapphire Rapids addresses 
+throughput needs; the emerging CXL protocol closes the capacity gap and tends 
+to better memory utilization by memory pooling capabilities. Beyond CPU use 
+cases, there are GPU accelerators with their own memory on board.
+The opportunities provided by modern heterogeneous memory platforms come 
+together with additional challenges. This means that additional software 
+changes might be required to fully leverage new HW capabilities. The are two 
+main problems that modern applications need to deal with. The first one is 
+appropriate data placement and data migration between different types of 
+memory. The second one is how SW should deal with different memory topologies.
+All applications can be divided into two big groups: enlightened and 
+unenlightened. Enlightened applications explicitly manage data allocation 
+distribution among memory tiers and further data migration. Unenlightened 
+applications do not require any code modifications and rely on underlying 
+infrastructure which is in turn enlightened. And underlying infrastructure is 
+not only OS with various memory tiering solutions to migrate memory pages 
+between tiers, but also middleware: frameworks and libraries. 
+
+==============
+ Architecture
+==============
+
+The Unified Memory Framework (UMF) is a library for constructing allocators 
+and memory pools. It also contains broadly useful abstractions and utilities 
+for memory management. UMF allows users to manage multiple memory pools 
+characterized by different attributes, allowing certain allocation types to be 
+isolated from others and allocated using different hardware resources as 
+required. 
+
+A memory pool is a combination of a pool allocator and one or more memory 
+targets accessed by memory providers along with their properties and allocation 
+policies. Specifically, a memory provider is responsible for coarse-grained 
+memory allocations, while the pool allocator controls the pool and handles 
+fine-grained memory allocations. UMF provides distinct interfaces for both pool 
+allocators and memory providers, allowing integration into various 
+applications. 
+
+.. figure:: ../assets/images/intro_architecture.png
+
+The UMF library contains various pool allocators and memory providers  but also 
+allows for the integration of external ones, giving users the flexibility to 
+either use existing solutions or provide their implementations. 
+
+ Memory Providers
+==================
+
+A memory provider is an abstraction for coarse (memory page) allocations and 
+deallocations of target memory types, such as host CPU, GPU, or CXL memory. 
+A single memory provider kind can efficiently manage the memory operations for 
+one or multiple devices within the system or other memory sources like 
+file-backed or user-provided memory.
+
+UMF comes with several bundled memory providers. Please refer to the README.md 
+to see a full list of them. There is also a possibility to use externally 
+defined memory providers if they implement the UMF interface.
+
+To instantiate a memory provider, user must pass an additional context with 
+contains the details about the specific memory target that should be used. This 
+would be a NUMA node mask for the OS memory provider, file path for the 
+file-backed memory provider, etc. After creation, the memory provider context
+can't be changed.
+
+ Pool Allocators
+=================
+
+A pool allocator is an abstraction over object-level memory management based 
+on coarse chunks acquired from the memory provider. It manages the memory pool 
+and services fine-grained malloc/free requests. 
+
+Pool allocators can be implemented for be general purpose or to fulfill 
+specific use cases. Implementations of the pool allocator interface can 
+leverage existing allocators (e.g., jemalloc or oneTBB) or be fully 
+customizable. The pool allocator abstraction could contain basic memory 
+management interfaces, as well as more complex ones that can be used, for 
+example, by the implementation for page monitoring or control (e.g., `madvise`).
+
+UMF comes with several bundled memory providers. Please refer to the README.md 
+to see a full list of them. There is also a possibility to use externally 
+defined pool allocators if they implement the UMF interface.
+
+ Memory Pools
+==============
+
+A Memory pool is a combination of a pool allocator and one or more memory 
+targets accessed by memory providers. In UMF the user could either use some 
+predefined memory pools or construct user-defined ones using the Pool Creation 
+API. 
+
+After construction, memory pools are used by the Allocation API as a first 
+argument. There is also a possibility to retrieve a memory pool from an 
+existing memory pointer that points to a memory previously allocated by UMF.