openmp/tools/multiplex/README.md

   1 # OMPT-Multiplexing
   2 The OMPT-Multiplexing header file allows a tool to load a second tool to
   3 overcome the restriction of the OpenMP to only load one tool at a time.
   4 The header file can also be used to load more than two tools using a cascade
   5 of tools that include the header file. OMPT-Multiplexing takes care of the
   6 multiplexing of OMPT callbacks, data pointers and runtime entry functions.
   7
   8 Examples 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
  15 Either 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
  29 Code 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 #define CLIENT_TOOL_VERBOSE_INIT_VAR "EXAMPLE_TOOL_VERBOSE_INIT"
  33 #include <ompt-multiplex.h>
  34 ```
  35 Alternatively, the name of the tool can be set as a prefix for both variables:
  36 ```
  37 #define OMPT_MULTIPLEX_TOOL_NAME "EXAMPLE"
  38 #include <ompt-multiplex.h>
  39 ```
  40 This define will have the same effect as to two defines above.
  41
  42 Note that functions and variables with prefix "ompt_multiplex" are reserved by the tool
  43
  44
  45 To use both tools execute the following:
  46 ```
  47  $ clang -fopenmp -o program.exe
  48  $ OMP_TOOL_LIBRARIES=/path/to/first/tool.so EXAMPLE_TOOL_LBRARIES=/path/to/second/tool.so ./program.exe
  49 ```
  50 Note 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).
  51
  52 ## Advanced usage
  53 To reduce the amount of memory allocations, the user can define macros before including the ompt-multiplex.h file, that specify custom data access handlers:
  54
  55 ```
  56 #define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_THREAD_DATA get_client_thread_data
  57 #define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_PARALLEL_DATA get_client_parallel_data
  58 #define OMPT_MULTIPLEX_CUSTOM_GET_CLIENT_TASK_DATA get_client_task_data
  59 ```
  60
  61 This 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:
  62
  63 ```
  64 #define OMPT_MULTIPLEX_CUSTOM_DELETE_THREAD_DATA delete_thread_data
  65 #define OMPT_MULTIPLEX_CUSTOM_DELETE_PARALLEL_DATA delete_parallel_data
  66 #define OMPT_MULTIPLEX_CUSTOM_DELETE_TASK_DATA delete_task_data
  67 ```
  68