1e9b8ed1fSJoachim Protze# OMPT-Multiplexing 2e9b8ed1fSJoachim ProtzeThe OMPT-Multiplexing header file allows a tool to load a second tool to 3e9b8ed1fSJoachim Protzeovercome the restriction of the OpenMP to only load one tool at a time. 4e9b8ed1fSJoachim ProtzeThe header file can also be used to load more than two tools using a cascade 5e9b8ed1fSJoachim Protzeof tools that include the header file. OMPT-Multiplexing takes care of the 6e9b8ed1fSJoachim Protzemultiplexing of OMPT callbacks, data pointers and runtime entry functions. 7e9b8ed1fSJoachim Protze 8e9b8ed1fSJoachim ProtzeExamples can be found under ./tests 9e9b8ed1fSJoachim Protze 10e9b8ed1fSJoachim Protze## Prerequisits 11e9b8ed1fSJoachim Protze- LLVM/OpenMP runtime with OMPT (https://github.com/OpenMPToolsInterface/LLVM-openmp) 12e9b8ed1fSJoachim Protze- LLVM-lit 13e9b8ed1fSJoachim Protze 14e9b8ed1fSJoachim Protze### Getting LLVM-lit 15e9b8ed1fSJoachim ProtzeEither build llvm and find lit+FileCheck in build directory of llvm or install using `pip`: 16e9b8ed1fSJoachim Protze``` 17e9b8ed1fSJoachim Protze $ pip install --upgrade --user pip 18e9b8ed1fSJoachim Protze $ export PATH=$HOME/.local/bin:$PATH 19e9b8ed1fSJoachim Protze $ export PYTHONPATH=$HOME/.local/lib/python3.*/site-packages/ 20e9b8ed1fSJoachim Protze $ pip install --user lit 21e9b8ed1fSJoachim Protze``` 22e9b8ed1fSJoachim Protze 23e9b8ed1fSJoachim Protze## How to test 24e9b8ed1fSJoachim Protze``` 25e9b8ed1fSJoachim Protze $ make check-ompt-multiplex 26e9b8ed1fSJoachim Protze``` 27e9b8ed1fSJoachim Protze 28e9b8ed1fSJoachim Protze## How to compile and use your OpenMP tools 29e9b8ed1fSJoachim ProtzeCode 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": 30e9b8ed1fSJoachim Protze``` 31e9b8ed1fSJoachim Protze#define CLIENT_TOOL_LIBRARIES_VAR "EXAMPLE_TOOL_LIBRARIES" 32*820be30aSJoachim Jenke#define CLIENT_TOOL_VERBOSE_INIT_VAR "EXAMPLE_TOOL_VERBOSE_INIT" 33e9b8ed1fSJoachim Protze#include <ompt-multiplex.h> 34e9b8ed1fSJoachim Protze``` 35*820be30aSJoachim JenkeAlternatively, the name of the tool can be set as a prefix for both variables: 36*820be30aSJoachim Jenke``` 37*820be30aSJoachim Jenke#define OMPT_MULTIPLEX_TOOL_NAME "EXAMPLE" 38*820be30aSJoachim Jenke#include <ompt-multiplex.h> 39*820be30aSJoachim Jenke``` 40*820be30aSJoachim JenkeThis define will have the same effect as to two defines above. 41*820be30aSJoachim Jenke 42e9b8ed1fSJoachim ProtzeNote that functions and variables with prefix "ompt_multiplex" are reserved by the tool 43e9b8ed1fSJoachim Protze 44e9b8ed1fSJoachim Protze 45e9b8ed1fSJoachim ProtzeTo use both tools execute the following: 46e9b8ed1fSJoachim Protze``` 47e9b8ed1fSJoachim Protze $ clang -fopenmp -o program.exe 48e9b8ed1fSJoachim Protze $ OMP_TOOL_LIBRARIES=/path/to/first/tool.so EXAMPLE_TOOL_LBRARIES=/path/to/second/tool.so ./program.exe 49e9b8ed1fSJoachim Protze``` 50e9b8ed1fSJoachim ProtzeNote 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). 51e9b8ed1fSJoachim Protze 52e9b8ed1fSJoachim Protze## Advanced usage 53e9b8ed1fSJoachim ProtzeTo reduce the amount of memory allocations, the user can define macros before including the ompt-multiplex.h file, that specify custom data access handlers: 54e9b8ed1fSJoachim Protze 55e9b8ed1fSJoachim Protze``` 56e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_THREAD_DATA get_client_thread_data 57e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_PARALLEL_DATA get_client_parallel_data 58e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_TASK_DATA get_client_task_data 59e9b8ed1fSJoachim Protze``` 60e9b8ed1fSJoachim Protze 61*820be30aSJoachim JenkeThis will reverse the calling order of the current tool and its client for clean-up events. In order to avoid this, one can specify a custom delete handler as well: 62e9b8ed1fSJoachim Protze 63e9b8ed1fSJoachim Protze``` 64e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_DELETE_THREAD_DATA delete_thread_data 65e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_DELETE_PARALLEL_DATA delete_parallel_data 66e9b8ed1fSJoachim Protze#define OMPT_MULTIPLEX_CUSTOM_DELETE_TASK_DATA delete_task_data 67e9b8ed1fSJoachim Protze``` 68e9b8ed1fSJoachim Protze 69