README.md
1# OMPT-Multiplexing
2The OMPT-Multiplexing header file allows a tool to load a second tool to
3overcome the restriction of the OpenMP to only load one tool at a time.
4The header file can also be used to load more than two tools using a cascade
5of tools that include the header file. OMPT-Multiplexing takes care of the
6multiplexing of OMPT callbacks, data pointers and runtime entry functions.
7
8Examples can be found under ./tests
9
10## Prerequisits
11- LLVM/OpenMP runtime with OMPT (https://github.com/OpenMPToolsInterface/LLVM-openmp)
12- LLVM-lit
13
14### Getting LLVM-lit
15Either build llvm and find lit+FileCheck in build directory of llvm or install using `pip`:
16```
17 $ pip install --upgrade --user pip
18 $ export PATH=$HOME/.local/bin:$PATH
19 $ export PYTHONPATH=$HOME/.local/lib/python3.*/site-packages/
20 $ pip install --user lit
21```
22
23## How to test
24```
25 $ make check-ompt-multiplex
26```
27
28## How to compile and use your OpenMP tools
29Code of first tool must include the following with the convention, that the environment variable containing the path to the client tool is the tool name with the suffix "_TOOL_LIBRARIES":
30```
31#define CLIENT_TOOL_LIBRARIES_VAR "EXAMPLE_TOOL_LIBRARIES"
32#include <ompt-multiplex.h>
33```
34Note that functions and variables with prefix "ompt_multiplex" are reserved by the tool
35
36
37To use both tools execute the following:
38```
39 $ clang -fopenmp -o program.exe
40 $ OMP_TOOL_LIBRARIES=/path/to/first/tool.so EXAMPLE_TOOL_LBRARIES=/path/to/second/tool.so ./program.exe
41```
42Note that EXAMPLE_TOOL_LIBRARIES may also contain a list of paths to tools which will be tried to load in order (similar to lists in OMP_TOOL_LIBRARIES).
43
44## Advanced usage
45To reduce the amount of memory allocations, the user can define macros before including the ompt-multiplex.h file, that specify custom data access handlers:
46
47```
48#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_THREAD_DATA get_client_thread_data
49#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_PARALLEL_DATA get_client_parallel_data
50#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_TASK_DATA get_client_task_data
51```
52
53This will reverse the calling order of the current tool and its client. In order to avoid this, one can specify a custom delete handler as well:
54
55```
56#define OMPT_MULTIPLEX_CUSTOM_DELETE_THREAD_DATA delete_thread_data
57#define OMPT_MULTIPLEX_CUSTOM_DELETE_PARALLEL_DATA delete_parallel_data
58#define OMPT_MULTIPLEX_CUSTOM_DELETE_TASK_DATA delete_task_data
59```
60
61