Skip to content

Commit 604ae59

Browse files
committed
Add GAI Tooling Notice to readme
1 parent 9d98b90 commit 604ae59

File tree

1 file changed

+34
-15
lines changed

1 file changed

+34
-15
lines changed

README.md

Lines changed: 34 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ For a quick introduction to UMF usage, please see
1818
[examples](https://oneapi-src.github.io/unified-memory-framework/examples.html)
1919
documentation, which includes the code of the
2020
[basic example](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/basic/basic.c).
21-
The are also more advanced that allocates USM memory from the
21+
The are also more advanced that allocates USM memory from the
2222
[Level Zero device](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/level_zero_shared_memory/level_zero_shared_memory.c)
2323
using the Level Zero API and UMF Level Zero memory provider and [CUDA device](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/cuda_shared_memory/cuda_shared_memory.c)
2424
using the CUDA API and UMF CUDA memory provider.
@@ -28,19 +28,23 @@ using the CUDA API and UMF CUDA memory provider.
2828
### Requirements
2929

3030
Required packages:
31+
3132
- libhwloc-dev >= 2.3.0 (Linux) / hwloc >= 2.3.0 (Windows)
3233
- C compiler
3334
- [CMake](https://cmake.org/) >= 3.14.0
3435

3536
For development and contributions:
37+
3638
- clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
3739
- cmake-format-0.6 (can be installed with `python -m pip install cmake-format==0.6.13`)
3840
- black (can be installed with `python -m pip install black==24.3.0`)
3941

4042
For building tests, multithreaded benchmarks and Disjoint Pool:
43+
4144
- C++ compiler with C++17 support
4245

4346
For Level Zero memory provider tests:
47+
4448
- Level Zero headers and libraries
4549
- compatible GPU with installed driver
4650

@@ -50,8 +54,8 @@ Executable and binaries will be in **build/bin**.
5054
The `{build_config}` can be either `Debug` or `Release`.
5155

5256
```bash
53-
$ cmake -B build -DCMAKE_BUILD_TYPE={build_config}
54-
$ cmake --build build -j $(nproc)
57+
cmake -B build -DCMAKE_BUILD_TYPE={build_config}
58+
cmake --build build -j $(nproc)
5559
```
5660

5761
### Windows
@@ -60,8 +64,8 @@ Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build
6064
The `{build_config}` can be either `Debug` or `Release`.
6165

6266
```bash
63-
$ cmake -B build -G "Visual Studio 15 2017 Win64"
64-
$ cmake --build build --config {build_config} -j $Env:NUMBER_OF_PROCESSORS
67+
cmake -B build -G "Visual Studio 15 2017 Win64"
68+
cmake --build build --config {build_config} -j $Env:NUMBER_OF_PROCESSORS
6569
```
6670

6771
### Benchmark
@@ -73,20 +77,22 @@ UMF also provides multithreaded benchmarks that can be enabled by setting both
7377
`UMF_BUILD_BENCHMARKS` and `UMF_BUILD_BENCHMARKS_MT` CMake
7478
configuration flags to `ON`. Multithreaded benchmarks require a C++ support.
7579

76-
The Scalable Pool requirements can be found in the relevant 'Memory Pool
80+
The Scalable Pool requirements can be found in the relevant 'Memory Pool
7781
managers' section below.
7882

7983
### Sanitizers
8084

8185
List of sanitizers available on Linux:
86+
8287
- AddressSanitizer
8388
- UndefinedBehaviorSanitizer
8489
- ThreadSanitizer
85-
- Is mutually exclusive with other sanitizers.
90+
- Is mutually exclusive with other sanitizers.
8691
- MemorySanitizer
87-
- Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
92+
- Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
8893

8994
List of sanitizers available on Windows:
95+
9096
- AddressSanitizer
9197

9298
Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
@@ -133,7 +139,7 @@ UMF comes with predefined pool allocators (see [`include/umf/pools`](include/umf
133139
providers that implement a specific interface (see [`include/umf/memory_pool_ops.h`](include/umf/memory_pool_ops.h)
134140
and [`include/umf/memory_provider_ops.h`](include/umf/memory_provider_ops.h)).
135141

136-
More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
142+
More detailed documentation is available here: <https://oneapi-src.github.io/unified-memory-framework/>
137143

138144
### Memory providers
139145

@@ -146,6 +152,7 @@ A memory provider that can provide memory from a given pre-allocated buffer.
146152
A memory provider that provides memory from an operating system.
147153

148154
OS memory provider supports two types of memory mappings (set by the `visibility` parameter):
155+
149156
1) private memory mapping (`UMF_MEM_MAP_PRIVATE`)
150157
2) shared memory mapping (`UMF_MEM_MAP_SHARED` - supported on Linux only yet)
151158

@@ -159,16 +166,18 @@ Permission to duplicate another process's file descriptor is governed by a ptrac
159166
the `/proc/sys/kernel/yama/ptrace_scope` interface in the following way:
160167

161168
```sh
162-
$ sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
169+
sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
163170
```
164171

165172
There are available two mechanisms for the shared memory mapping:
173+
166174
1) a named shared memory object (used if the `shm_name` parameter is not NULL) or
167175
2) an anonymous file descriptor (used if the `shm_name` parameter is NULL)
168176

169177
The `shm_name` parameter should be a null-terminated string of up to NAME_MAX (i.e., 255) characters none of which are slashes.
170178

171179
An anonymous file descriptor for the shared memory mapping will be created using:
180+
172181
1) `memfd_secret()` syscall - (if it is implemented and) if the `UMF_MEM_FD_FUNC` environment variable does not contain the "memfd_create" string or
173182
2) `memfd_create()` syscall - otherwise (and if it is implemented).
174183

@@ -178,7 +187,8 @@ IPC API on Linux requires the `PTRACE_MODE_ATTACH_REALCREDS` permission (see `pt
178187
to duplicate another process's file descriptor (see above).
179188

180189
Packages required for tests (Linux-only yet):
181-
- libnuma-dev
190+
191+
- libnuma-dev
182192

183193
#### Level Zero memory provider
184194

@@ -191,7 +201,7 @@ Permission to duplicate another process's file descriptor is governed by a ptrac
191201
the `/proc/sys/kernel/yama/ptrace_scope` interface in the following way:
192202

193203
```sh
194-
$ sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
204+
sudo bash -c "echo 0 > /proc/sys/kernel/yama/ptrace_scope"
195205
```
196206

197207
##### Requirements
@@ -266,7 +276,7 @@ To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be
266276

267277
#### Jemalloc pool
268278

269-
Jemalloc pool is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory
279+
Jemalloc pool is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory
270280
pool manager built as a separate static library: libjemalloc_pool.a on Linux and
271281
jemalloc_pool.lib on Windows.
272282
The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
@@ -275,6 +285,7 @@ The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this
275285

276286
In case of Linux OS jemalloc is built from the (fetched) sources with the following
277287
non-default options enabled:
288+
278289
- `--with-jemalloc-prefix=je_` - adds the `je_` prefix to all public APIs,
279290
- `--disable-cxx` - disables C++ integration, it will cause the `new` and the `delete`
280291
operators implementations to be omitted.
@@ -289,6 +300,7 @@ The default jemalloc package is required on Windows.
289300

290301
1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
291302
2) jemalloc is required:
303+
292304
- on Linux and MacOS: jemalloc is fetched and built from sources (a custom build),
293305
- on Windows: the default jemalloc package is required
294306

@@ -300,7 +312,8 @@ It is distributed as part of libumf. To use this pool, TBB must be installed in
300312
##### Requirements
301313

302314
Packages required for using this pool and executing tests/benchmarks (not required for build):
303-
- libtbb-dev (libtbbmalloc.so.2) on Linux or tbb (tbbmalloc.dll) on Windows
315+
316+
- libtbb-dev (libtbbmalloc.so.2) on Linux or tbb (tbbmalloc.dll) on Windows
304317

305318
### Memspaces (Linux-only)
306319

@@ -338,10 +351,11 @@ To enable this feature, the `UMF_BUILD_SHARED_LIBRARY` option needs to be turned
338351
In case of Linux it can be done without any code changes using the `LD_PRELOAD` environment variable:
339352

340353
```sh
341-
$ LD_PRELOAD=/usr/lib/libumf_proxy.so myprogram
354+
LD_PRELOAD=/usr/lib/libumf_proxy.so myprogram
342355
```
343356

344357
The memory used by the proxy memory allocator is mmap'ed:
358+
345359
1) with the `MAP_PRIVATE` flag by default or
346360
2) with the `MAP_SHARED` flag if the `UMF_PROXY` environment variable contains one of two following strings: `page.disposition=shared-shm` or `page.disposition=shared-fd`. These two options differ in a mechanism used during IPC:
347361
- `page.disposition=shared-shm` - IPC uses the named shared memory. An SHM name is generated using the `umf_proxy_lib_shm_pid_$PID` pattern, where `$PID` is the PID of the process. It creates the `/dev/shm/umf_proxy_lib_shm_pid_$PID` file.
@@ -357,6 +371,7 @@ It can be enabled by adding the `size.threshold=<value>` string to the `UMF_PROX
357371
#### Windows
358372

359373
In case of Windows it requires:
374+
360375
1) explicitly linking your program dynamically with the `umf_proxy.dll` library
361376
2) (C++ code only) including `proxy_lib_new_delete.h` in a single(!) source file in your project
362377
to override also the `new`/`delete` operations.
@@ -370,3 +385,7 @@ an issue or a Pull Request, please read [Contribution Guide](./CONTRIBUTING.md).
370385

371386
To enable logging in UMF source files please follow the guide in the
372387
[web documentation](https://oneapi-src.github.io/unified-memory-framework/introduction.html#logging).
388+
389+
## Notices
390+
391+
These contents may have been developed with support from one or more Intel-operated generative artificial intelligence solutions.

0 commit comments

Comments
 (0)