[OpenMP] Add ompTest library to OpenMP (#147381)
Description
===========
OpenMP Tooling Interface Testing Library (ompTest) ompTest is a unit
testing framework for testing OpenMP implementations. It offers a
simple-to-use framework that allows a tester to check for OMPT events in
addition to regular unit testing code, supported by linking against
GoogleTest by default. It also facilitates writing concise tests while
bridging the semantic gap between the unit under test and the OMPT-event
testing.
Background
==========
This library has been developed to provide the means of testing OMPT
implementations with reasonable effort. Especially, asynchronous or
unordered events are supported and can be verified with ease, which may
prove to be challenging with LIT-based tests. Additionally, since the
assertions are part of the code being tested, ompTest can reference all
corresponding variables during assertion.
Basic Usage
===========
OMPT event assertions are placed before the code, which shall be tested.
These assertion can either be provided as one block or interleaved with
the test code. There are two types of asserters: (1) sequenced
"order-sensitive" and (2) set "unordered" assserters. Once the test is
being run, the corresponding events are triggered by the OpenMP runtime
and can be observed. Each of these observed events notifies asserters,
which then determine if the test should pass or fail.
Example (partial, interleaved)
==============================
```c++
int N = 100000;
int a[N];
int b[N];
OMPT_ASSERT_SEQUENCE(Target, TARGET, BEGIN, 0);
OMPT_ASSERT_SEQUENCE(TargetDataOp, ALLOC, N * sizeof(int)); // a ?
OMPT_ASSERT_SEQUENCE(TargetDataOp, H2D, N * sizeof(int), &a);
OMPT_ASSERT_SEQUENCE(TargetDataOp, ALLOC, N * sizeof(int)); // b ?
OMPT_ASSERT_SEQUENCE(TargetDataOp, H2D, N * sizeof(int), &b);
OMPT_ASSERT_SEQUENCE(TargetSubmit, 1);
OMPT_ASSERT_SEQUENCE(TargetDataOp, D2H, N * sizeof(int), nullptr, &b);
OMPT_ASSERT_SEQUENCE(TargetDataOp, D2H, N * sizeof(int), nullptr, &a);
OMPT_ASSERT_SEQUENCE(TargetDataOp, DELETE);
OMPT_ASSERT_SEQUENCE(TargetDataOp, DELETE);
OMPT_ASSERT_SEQUENCE(Target, TARGET, END, 0);
#pragma omp target parallel for
{
for (int j = 0; j < N; j++)
a[j] = b[j];
}
```
References
==========
This work has been presented at SC'24 workshops, see:
https://ieeexplore.ieee.org/document/10820689
Current State and Future Work
=============================
ompTest's development was mostly device-centric and aimed at OMPT device
callbacks and device-side tracing. Consequentially, a substantial part
of host-related events or features may not be supported in its current
state. However, we are confident that the related functionality can be
added and ompTest provides a general foundation for future OpenMP and
especially OMPT testing. This PR will allow us to upstream the
corresponding features, like OMPT device-side tracing in the future with
significantly reduced risk of introducing regressions in the process.
Build
=====
ompTest is linked against LLVM's GoogleTest by default, but can also be
built 'standalone'. Additionally, it comes with a set of unit tests,
which in turn require GoogleTest (overriding a standalone build). The
unit tests are added to the `check-openmp` target.
Use the following parameters to perform the corresponding build:
`LIBOMPTEST_BUILD_STANDALONE` (Default: ${OPENMP_STANDALONE_BUILD})
`LIBOMPTEST_BUILD_UNITTESTS` (Default: OFF)
---------
Co-authored-by: Jan-Patrick Lehr <JanPatrick.Lehr@amd.com>
Co-authored-by: Joachim <protze@rz.rwth-aachen.de>
GitOrigin-RevId: 35f01cea6551f577133200e29d160d35fa4b76f4
31 files changed
