ompd_rc_t ompd_initialize(
ompd_word_t api_version,
const ompd_callbacks_t *callbacks
);
The OMPD library must be initialized exactly once after it is loaded, and finalized exactly once before it is unloaded. Per OpenMP process or core file initialization and finalization are also required.
Once loaded, the tool can determine the version of the OMPD API that the library supports by calling ompd_get_api_version (see Section 5.5.1.2). If the tool supports the version that ompd_get_api_version returns, the tool starts the initialization by calling ompd_initialize (see Section 5.5.1.1) using the version of the OMPD API that the library supports. If the tool does not support the version that ompd_get_api_version returns, it may attempt to call ompd_initialize with a different version.
Summary The ompd_initialize function initializes the OMPD library.
Description A tool that uses OMPD calls ompd_initialize to initialize each OMPD library that it loads. More than one library may be present in a third-party tool, such as a debugger, because the tool may control multiple devices, which may use different runtime systems that require different OMPD libraries. This initialization must be performed exactly once before the tool can begin to operate on an OpenMP process or core file.
Description of Arguments The api_version argument is the OMPD API version that the tool requests to use. The tool may call ompd_get_api_version to obtain the latest OMPD API version that the OMPD library supports.
The tool provides the OMPD library with a set of callback functions in the callbacks input argument which enables the OMPD library to allocate and to deallocate memory in the tool’s address space, to lookup the sizes of basic primitive types in the device, to lookup symbols in the device, and to read and to write memory in the device.
Description of Return Codes This routine must return any of the general return codes listed at the beginning of Section 5.5 or any of the following return codes:
Summary The ompd_get_api_version function returns the OMPD API version.
Description The tool may call the ompd_get_api_version function to obtain the latest OMPD API version number of the OMPD library. The OMPD API version number is equal to the value of the _OPENMP macro defined in the associated OpenMP implementation, if the C preprocessor is supported. If the associated OpenMP implementation compiles Fortran codes without the use of a C preprocessor, the OMPD API version number is equal to the value of the Fortran integer parameter openmp_version.
Description of Arguments The latest version number is returned into the location to which the version argument points.
Description of Return Codes This routine must return any of the general return codes listed at the beginning of Section 5.5.
Summary The ompd_get_version_string function returns a descriptive string for the OMPD library version.
Description The tool may call this function to obtain a pointer to a descriptive version string of the OMPD library vendor, implementation, internal version, date, or any other information that may be useful to a tool user or vendor. An implementation should provide a different string for every change to its source code or build that could be visible to the interface user.
Description of Arguments A pointer to a descriptive version string is placed into the location to which the string output argument points. The OMPD library owns the string that the OMPD library returns; the tool must not modify or release this string. The string remains valid for as long as the library is loaded. The ompd_get_version_string function may be called before ompd_initialize (see Section 5.5.1.1). Accordingly, the OMPD library must not use heap or stack memory for the string.
The signatures of ompd_get_api_version (see Section 5.5.1.2) and ompd_get_version_string are guaranteed not to change in future versions of the API. In contrast, the type definitions and prototypes in the rest of the API do not carry the same guarantee. Therefore a tool that uses OMPD should check the version of the API of the loaded OMPD library before it calls any other function of the API.
Description of Return Codes This routine must return any of the general return codes listed at the beginning of Section 5.5.
Summary When the tool is finished with the OMPD library it should call ompd_finalize before it unloads the library.
Description The call to ompd_finalize must be the last OMPD call that the tool makes before it unloads the library. This call allows the OMPD library to free any resources that it may be holding.
The OMPD library may implement a finalizer section, which executes as the library is unloaded and therefore after the call to ompd_finalize. During finalization, the OMPD library may use the callbacks that the tool provided earlier during the call to ompd_initialize.
Description of Return Codes This routine must return any of the general return codes listed at the beginning of Section 5.5 or the following return code: