Skip to content

Commit 9bacb50

Browse files
[Doc] Redo web docs
especially the logging section. Fixes: #431
1 parent 129a2ad commit 9bacb50

File tree

2 files changed

+71
-49
lines changed

2 files changed

+71
-49
lines changed

README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,3 +237,8 @@ In case of Windows it requires:
237237

238238
All contributions to the UMF project are most welcome! Before submitting
239239
an issue or a Pull Request, please read [Contribution Guide](./CONTRIBUTING.md).
240+
241+
## Logging
242+
243+
To enable logging in UMF source files please follow the guide in the
244+
[web documentation](https://oneapi-src.github.io/unified-memory-framework/introduction.html#logging).

scripts/docs_config/introduction.rst

Lines changed: 66 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ growing. To address the increasing demand, memory subsystem of modern server
77
platforms is becoming heterogeneous. For example, High-Bandwidth Memory (HBM)
88
addresses throughput needs; the CXL protocol closes the capacity gap and tends
99
to improve memory utilization by memory pooling capabilities. Beyond CPU use
10-
cases, there are GPU accelerators with their own memory on board.
10+
cases, there are GPU accelerators with their own memory on board.
1111

1212
Modern heterogeneous memory platforms present a range of opportunities. At the
1313
same time, they introduce new challenges that could require software updates to
1414
fully utilize the HW features. There are two main problems that modern
1515
applications need to deal with. The first one is appropriate data placement and
1616
data migration between different types of memory. The second one is how SW
17-
should leverage different memory topologies.
17+
should leverage different memory topologies.
1818

1919
All applications can be divided into two big groups: enlightened and
2020
unenlightened. Enlightened applications explicitly manage data allocation
@@ -24,19 +24,15 @@ infrastructure. An underlying infrastructure refers not only to the OS with
2424
various memory tiering solutions to migrate memory pages between tiers, but
2525
also middleware: frameworks and libraries.
2626

27-
Please note that UMF is a Work-In-Progress! Read the disclaimer
28-
about that in the `README.md`_ file, before using our project.
29-
30-
==============
31-
Architecture
32-
==============
27+
About UMF
28+
=========
3329

3430
The Unified Memory Framework (`UMF`_) is a library for constructing allocators
3531
and memory pools. It also contains broadly useful abstractions and utilities
3632
for memory management. UMF allows users to create and manage multiple memory
3733
pools characterized by different attributes, allowing certain allocation types
3834
to be isolated from others and allocated using different hardware resources as
39-
required.
35+
required.
4036

4137
A memory pool is a combination of a pool allocator instance and a memory
4238
provider instance along with their properties and allocation policies.
@@ -50,7 +46,18 @@ providers provided by UMF or create their own.
5046

5147
The UMF library contains various pool allocators and memory providers but also
5248
allows for the integration of external ones, giving users the flexibility to
53-
either use existing solutions or provide their implementations.
49+
either use existing solutions or provide their implementations.
50+
51+
**Please note that UMF is a Work-In-Progress!** Read the disclaimer
52+
about that in the `README.md`_ file, before using our project.
53+
54+
The repository for Unified Memory Framework can be found on GitHub:
55+
56+
* `oneapi-src/unified-memory-framework <https://github.com/oneapi-src/unified-memory-framework>`_
57+
58+
==============
59+
Architecture
60+
==============
5461

5562
Memory Providers
5663
================
@@ -98,45 +105,6 @@ the :ref:`allocation API <allocation API>` as a first argument. There is also a
98105
retrieve a memory pool from an existing memory pointer that points to a memory
99106
previously allocated by UMF.
100107

101-
Logging
102-
---------------------
103-
104-
Logging in UMF is handled by logger. There are several levels of logging: *debug*, *info*, *warning*, and *error*.
105-
The level of logging determines what messages will be printed, ie. the level set to *warning* means all messages at levels *warning* and *error* will be printed.
106-
107-
By default, there is a guarantee that *error* messages are flushed immediately. One can change this behavior to flush on lower-level messages.
108-
109-
Loggers redirect messages to *stdout*, *stderr*, or a file
110-
111-
By default, only fatal messages are printed. To enable logger you have to set **UMF_LOG** environment variable which have following syntax for setting logger options:
112-
113-
"[level:debug|info|warning|error|fatal];[flush:debug|info|warning|error|fatal];[output:stdout|stderr|file,<path>];[timestamp:yes|no];[pid:yes|no]"
114-
115-
* level - a log level, meaning that only messages from this level and above are printed.
116-
Possible values, from the lowest level to the highest one: *debug*, *info*, *warning*, *error*, *fatal*
117-
* flush - a flush level, meaning that messages at this level and above are guaranteed to be flushed immediately,
118-
possible values are the same as above,
119-
* output - indicates where messages should be printed.
120-
Possible values are: *stdout*, *stderr* and *file*,
121-
when providing a *file* output option, a *<path>* is required
122-
* timestamp - add a timestamp to log message
123-
* pid - add thread and process ids to log message
124-
125-
.. note::
126-
For output to file, a path to the file has to be provided after a comma, like in the example above. The path has to exist, file will be created if not existing. Path to the file should be no longer than 255 characters long.
127-
The output parameter is required, all other logger options are optional. The defaults are set when options are not provided in the environment variable.
128-
Options have to be separated with `;`, option names and their values with `:`. Additionally, when providing *file* output, the keyword *file* and a path to a file
129-
have to be separated by `'`.
130-
131-
An example of an environment variable for setting up logger with logging level set to *info*, flush level set to *warning*, and output set to
132-
the ``out.log`` file::
133-
134-
UMF_LOG="level:info;flush:warning;output:file,out.log"
135-
136-
An example of an environment variable for setting up logger with logging level set to *warning* and output set to stdout::
137-
138-
UMF_LOGL="level:warning;output:stdout"
139-
140108
Inter-Process Communication
141109
===========================
142110

@@ -158,5 +126,54 @@ When a client requests an IPC handle for a memory allocated by UMF, UMF does the
158126
Not every memory provider can and must support IPC operations. It is up to the memory provider implementation to decide if it supports IPC operations.
159127
If the corresponding memory provider does not support IPC operations, UMF will return an error when a client requests an IPC handle for a memory object allocated by this memory provider.
160128

129+
==============
130+
Fundamentals
131+
==============
132+
133+
The following section provides fundamentals of the project. More detailed information can be found in
134+
contributing guide and detailed API pages.
135+
136+
The contribution guide can be found in the repository, in file: `CONTRIBUTING.md`_.
137+
138+
Logging
139+
============
140+
141+
Logging in UMF is handled by logger. There are several levels of logging: *debug*, *info*, *warning*, and *error*.
142+
The level of logging determines what messages will be printed, ie. the level set to *warning* means all messages at levels *warning* and *error* will be printed.
143+
144+
By default, there is a guarantee that *error* messages are flushed immediately. One can change this behavior to flush on lower-level messages.
145+
146+
Loggers redirect messages to *stdout*, *stderr*, or a file.
147+
148+
By default, only fatal messages are printed. To enable logger you have to set **UMF_LOG** environment variable which have the following syntax for setting logger options::
149+
150+
UMF_LOG="[level:debug|info|warning|error|fatal];[flush:debug|info|warning|error|fatal];[output:stdout|stderr|file,<path>];[timestamp:yes|no];[pid:yes|no]"
151+
152+
* level - a log level, meaning that only messages from this level and above are printed. Possible values, from the lowest level to the highest one: *debug*, *info*, *warning*, *error*, *fatal*.
153+
154+
* flush - a flush level, meaning that messages at this level and above are guaranteed to be flushed immediately, possible values are the same as above.
155+
156+
* output - indicates where messages should be printed. Possible values are: *stdout*, *stderr* and *file*, when providing a *file* output option, a *<path>* is required.
157+
158+
* timestamp - add a timestamp to log message.
159+
160+
* pid - add thread and process ids to log message.
161+
162+
.. note::
163+
For output to a file, a path to a file has to be provided after a comma, like in the example above. The path has to exist and should be no longer than 255 characters long. The file will be created if not existing.
164+
The output parameter is required. All other logger options are optional. The defaults are set when options are not provided in the environment variable.
165+
Options have to be separated with a semicolon (`;`), option names and their values with a colon (`:`). Additionally, when providing *file* output, the keyword *file* and a path to a file
166+
have to be separated by a comma (`,`).
167+
168+
An example of an environment variable for setting up logger with logging level set to *info*, flush level set to *warning*, and output set to
169+
the ``out.log`` file::
170+
171+
UMF_LOG="level:info;flush:warning;output:file,out.log"
172+
173+
An example of an environment variable for setting up logger with logging level set to *warning* and output set to stdout::
174+
175+
UMF_LOG="level:warning;output:stdout"
176+
161177
.. _UMF: https://github.com/oneapi-src/unified-memory-framework
178+
.. _CONTRIBUTING.md: https://github.com/oneapi-src/unified-memory-framework/blob/main/CONTRIBUTING.md
162179
.. _README.md: https://github.com/oneapi-src/unified-memory-framework/blob/main/README.md

0 commit comments

Comments
 (0)