| OPENMP API Specification: Version 5.0 November 2018

5  OMPD Interface

This chapter describes OMPD, which is an interface for third-party tools. Third-party tools exist in separate processes from the OpenMP program. To provide OMPD support, an OpenMP implementation must provide an OMPD library to be loaded by the third-party tool. An OpenMP implementation does not need to maintain any extra information to support OMPD inquiries from third-party tools unless it is explicitly instructed to do so.

OMPD allows third-party tools such as a debuggers to inspect the OpenMP state of a live program or core file in an implementation-agnostic manner. That is, a tool that uses OMPD should work with any conforming OpenMP implementation. An OpenMP implementor provides a library for OMPD that a third-party tool can dynamically load. Using the interface exported by the OMPD library, the external tool can inspect the OpenMP state of a program. In order to satisfy requests from the third-party tool, the OMPD library may need to read data from, or to find the addresses of symbols in the OpenMP program. The OMPD library provides this functionality through a callback interface that the third-party tool must instantiate for the OMPD library.

To use OMPD, the third-party tool loads the OMPD library. The OMPD library exports the API that is defined throughout this section and that the tool uses to determine OpenMP information about the OpenMP program. The OMPD library must look up the symbols and read data out of the program. It does not perform these operations directly, but instead it uses the callback interface that the tool exports to cause the tool to perform them.

The OMPD architecture insulates tools from the internal structure of the OpenMP runtime while the OMPD library is insulated from the details of how to access the OpenMP program. This decoupled design allows for flexibility in how the OpenMP program and tool are deployed, so that, for example, the tool and the OpenMP program are not required to execute on the same machine.

Generally the tool does not interact directly with the OpenMP runtime and, instead, interacts with it through the OMPD library. However, a few cases require the tool to access the OpenMP runtime directly. These cases fall into two broad categories. The first is during initialization, where the tool must look up symbols and read variables in the OpenMP runtime in order to identify the OMPD library that it should use, which is discussed in Section 5.2.2 on page 1490 and Section 5.2.3 on page 1491. The second category relates to arranging for the tool to be notified when certain events occur during the execution of the OpenMP program. For this purpose, the OpenMP implementation must define certain symbols in the runtime code, as is discussed in Section 5.6 on page 1628. Each of these symbols corresponds to an event type. The runtime must ensure that control passes through the appropriate named location when events occur. If the tool requires notification of an event, it can plant a breakpoint at the matching location. The location can, but may not, be a function. It can, for example, simply be a label. However, the names of the locations must have external C linkage.

 5.1  OMPD Interfaces Definitions
 5.2  Activating an OMPD Tool
  5.2.1  Enabling the Runtime for OMPD
  5.2.2  ompd_dll_locations
  5.2.3  ompd_dll_locations_valid
 5.3  OMPD Data Types
  5.3.1  Size Type
  5.3.2  Wait ID Type
  5.3.3  Basic Value Types
  5.3.4  Address Type
  5.3.5  Frame Information Type
  5.3.6  System Device Identifiers
  5.3.7  Native Thread Identifiers
  5.3.8  OMPD Handle Types
  5.3.9  OMPD Scope Types
  5.3.10  ICV ID Type
  5.3.11  Tool Context Types
  5.3.12  Return Code Types
  5.3.13  Primitive Type Sizes
 5.4  OMPD Tool Callback Interface
  5.4.1  Memory Management of OMPD Library
  5.4.2  Context Management and Navigation
  5.4.3  Accessing Memory in the OpenMP Program or Runtime
  5.4.4  Data Format Conversion: ompd_callback_device_host_fn_t
  5.4.5  Output: ompd_callback_print_string_fn_t
  5.4.6  The Callback Interface
 5.5  OMPD Tool Interface Routines
  5.5.1  Per OMPD Library Initialization and Finalization
  5.5.2  Per OpenMP Process Initialization and Finalization
  5.5.3  Thread and Signal Safety
  5.5.4  Address Space Information
  5.5.5  Thread Handles
  5.5.6  Parallel Region Handles
  5.5.7  Task Handles
  5.5.8  Display Control Variables
  5.5.9  Accessing Scope-Specific Information
 5.6  Runtime Entry Points for OMPD
  5.6.1  Beginning Parallel Regions
  5.6.2  Ending Parallel Regions
  5.6.3  Beginning Task Regions
  5.6.4  Ending Task Regions
  5.6.5  Beginning OpenMP Threads
  5.6.6  Ending OpenMP Threads
  5.6.7  Initializing OpenMP Devices
  5.6.8  Finalizing OpenMP Devices