Skip to content

Commit 82bb9fc

Browse files
PatKaminPatKamin
committed
Add Getting Started section in main README file
- reorganize README.md
1 parent 310dbe1 commit 82bb9fc

File tree

1 file changed

+104
-88
lines changed

1 file changed

+104
-88
lines changed

‎README.md

Lines changed: 104 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -8,23 +8,11 @@
88
[![Nightly](https://github.com/oneapi-src/unified-memory-framework/actions/workflows/nightly.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-memory-framework/actions/workflows/nightly.yml)
99
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/oneapi-src/unified-memory-framework/badge)](https://securityscorecards.dev/viewer/?uri=github.com/oneapi-src/unified-memory-framework)
1010

11-
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.
12-
13-
# Architecture: memory pools and providers
14-
15-
A UMF memory pool is a combination of a pool allocator and a memory provider. A memory provider is responsible for coarse-grained memory allocations and management of memory pages, while the pool allocator controls memory pooling and handles fine-grained memory allocations.
16-
17-
Pool allocator can leverage existing allocators (e.g. jemalloc or tbbmalloc) or be written from scratch.
18-
19-
UMF comes with predefined pool allocators (see include/pool) and providers (see include/provider). UMF can also work with user-defined pools and providers that implement a specific interface (see include/umf/memory_pool_ops.h and include/umf/memory_provider_ops.h).
20-
21-
More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
11+
## Getting started
2212

23-
## Memory providers
24-
25-
### OS memory provider (Linux-only yet)
13+
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.
2614

27-
A memory provider that provides memory from an operating system.
15+
### Build
2816

2917
#### Requirements
3018

@@ -35,48 +23,6 @@ A memory provider that provides memory from an operating system.
3523
4) Required packages for tests:
3624
- libnuma-dev
3725

38-
## Memory pool managers
39-
40-
### proxy_pool (part of libumf)
41-
42-
This memory pool is distributed as part of libumf. It forwards all requests to the underlying
43-
memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions
44-
are not supported by the proxy pool.
45-
46-
### libumf_pool_disjoint
47-
48-
TODO: Add a description
49-
50-
#### Requirements
51-
52-
To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be turned `ON`.
53-
54-
### libumf_pool_jemalloc (Linux-only)
55-
56-
libumf_pool_jemalloc is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory pool manager built as a separate static library.
57-
The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
58-
59-
#### Requirements
60-
61-
1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
62-
2) Required packages:
63-
- libjemalloc-dev
64-
65-
### libumf_pool_scalable (Linux-only)
66-
67-
libumf_pool_scalable is a [oneTBB](https://github.com/oneapi-src/oneTBB)-based memory pool manager built as a separate static library.
68-
The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this library.
69-
70-
#### Requirements
71-
72-
1) The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option turned `ON`
73-
2) Required packages:
74-
- libtbb-dev (libraries: libtbbmalloc.so.2)
75-
76-
## Building
77-
78-
### Requirements
79-
8026
Required packages:
8127
- C compiler
8228
- [CMake](https://cmake.org/) >= 3.14.0
@@ -87,33 +33,33 @@ For development and contributions:
8733
For building tests and Disjoint Pool:
8834
- C++ compiler with C++17 support
8935

90-
### Benchmark
36+
#### Linux
9137

92-
A simple micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
93-
In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
94-
95-
### Windows
96-
97-
Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
38+
Executable and binaries will be in **build/bin**
9839

9940
```bash
10041
$ mkdir build
10142
$ cd build
102-
$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
43+
$ cmake {path_to_source_dir}
44+
$ make
10345
```
10446

105-
### Linux
47+
#### Windows
10648

107-
Executable and binaries will be in **build/bin**
49+
Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
10850

10951
```bash
11052
$ mkdir build
11153
$ cd build
112-
$ cmake {path_to_source_dir}
113-
$ make
54+
$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
11455
```
11556

116-
### Sanitizers
57+
#### Benchmark
58+
59+
A simple micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
60+
In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
61+
62+
#### Sanitizers
11763

11864
List of sanitizers available on Linux:
11965
- AddressSanitizer
@@ -128,24 +74,7 @@ List of sanitizers available on Windows:
12874

12975
Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
13076

131-
## Contributions
132-
133-
All code has to be formatted using clang-format. To check the formatting do:
134-
135-
```bash
136-
$ mkdir build
137-
$ cd build
138-
$ cmake {path_to_source_dir} -DUMF_FORMAT_CODE_STYLE=ON
139-
$ make clang-format-check
140-
```
141-
142-
Additionally, to apply code formatting do:
143-
144-
```bash
145-
$ make clang-format-apply
146-
```
147-
148-
### CMake standard options
77+
#### CMake standard options
14978

15079
List of options provided by CMake:
15180

@@ -165,3 +94,90 @@ List of options provided by CMake:
16594
| USE_UBSAN | Enable UndefinedBehaviorSanitizer checks | ON/OFF | OFF |
16695
| USE_TSAN | Enable ThreadSanitizer checks | ON/OFF | OFF |
16796
| USE_MSAN | Enable MemorySanitizer checks | ON/OFF | OFF |
97+
98+
### Usage
99+
100+
TODO: Change links to point to oneapi-src
101+
102+
For a quick introduction to UMF usage, see [Example usage](https://patkamin.github.io/unified-memory-framework/example-usage.html),
103+
which includes the code of the basic [example](https://github.com/patkamin/unified-memory-framework/blob/main/examples/basic/basic.c).
104+
105+
## Architecture: memory pools and providers
106+
107+
A UMF memory pool is a combination of a pool allocator and a memory provider. A memory provider is responsible for coarse-grained memory allocations and management of memory pages, while the pool allocator controls memory pooling and handles fine-grained memory allocations.
108+
109+
Pool allocator can leverage existing allocators (e.g. jemalloc or tbbmalloc) or be written from scratch.
110+
111+
UMF comes with predefined pool allocators (see include/pool) and providers (see include/provider). UMF can also work with user-defined pools and providers that implement a specific interface (see include/umf/memory_pool_ops.h and include/umf/memory_provider_ops.h).
112+
113+
More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
114+
115+
### Memory providers
116+
117+
#### OS memory provider (Linux-only yet)
118+
119+
A memory provider that provides memory from an operating system.
120+
121+
##### Requirements
122+
123+
1) Linux OS
124+
2) The `UMF_BUILD_OS_MEMORY_PROVIDER` option turned `ON` (by default)
125+
3) Required packages:
126+
- libhwloc-dev
127+
4) Required packages for tests:
128+
- libnuma-dev
129+
130+
### Memory pool managers
131+
132+
#### proxy_pool (part of libumf)
133+
134+
This memory pool is distributed as part of libumf. It forwards all requests to the underlying
135+
memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions
136+
are not supported by the proxy pool.
137+
138+
#### libumf_pool_disjoint
139+
140+
TODO: Add a description
141+
142+
##### Requirements
143+
144+
To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be turned `ON`.
145+
146+
#### libumf_pool_jemalloc (Linux-only)
147+
148+
libumf_pool_jemalloc is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory pool manager built as a separate static library.
149+
The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
150+
151+
##### Requirements
152+
153+
1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
154+
2) Required packages:
155+
- libjemalloc-dev
156+
157+
#### libumf_pool_scalable (Linux-only)
158+
159+
libumf_pool_scalable is a [oneTBB](https://github.com/oneapi-src/oneTBB)-based memory pool manager built as a separate static library.
160+
The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this library.
161+
162+
##### Requirements
163+
164+
1) The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option turned `ON`
165+
2) Required packages:
166+
- libtbb-dev (libraries: libtbbmalloc.so.2)
167+
168+
## Contributions
169+
170+
All code has to be formatted using clang-format. To check the formatting do:
171+
172+
```bash
173+
$ mkdir build
174+
$ cd build
175+
$ cmake {path_to_source_dir} -DUMF_FORMAT_CODE_STYLE=ON
176+
$ make clang-format-check
177+
```
178+
179+
Additionally, to apply code formatting do:
180+
181+
```bash
182+
$ make clang-format-apply
183+
```

0 commit comments

Comments
 (0)