Re: [Patch] libgomp: Add stub omp_control_tool for OMPT

Sandra Loosemore wrote:
> That should be @code{omp_pause_resource}, right?

Fixed.

And committed as Rev. r17-485-ga94fc2737d4c39

* * *

The following should be addressed - but I decided to do so
as follow up, either soon with minor tweaking or when adding
more OMPT documentation later on. Regarding:

>> +@node Tool Control Routine
>> +@section Tool Control Routine
>> +Routine that supports the use of the OpenMP tools interface (OMPT). 
...
>> +@subsection @code{omp_control_tool} -- pass commands to a tool
>> +The @code{omp_control_tool} routine can be used to pass commands to 
>> a tool. The
>> +values […] The following predefined values for
>> +@var{command} are supported by all tools:
>
> Having read this far, I'm wondering what a "tool" is; that's a 
> completely generic term.  Could we use the term "monitoring tool" 
> somewhere early on in the discussion?  And/or add a sentence that 
> describes what kind of "tools" these are?

I concur that 'tool' is rather generic. The question is how to word
it best? I have to admit that I don't like 'monitoring tool', either,
being both a bit too narrow and also rather unclear what it means.

To me, "OpenMP tools interface (OMPT)" give a much clearer hint what
it does - without stating much either.

If you have a good short proposal based on the following lengthy words,
I am happy to add it - otherwise, I am wondering whether it should be
deferred to a @section about OMPT.

* * *

OMPT (the OpenMP Tools Interface) works as follows: The user sets the the
OMP_TOOL_LIBRARIES environment variable to point to a shared library
("libMyTool.so").

The runtime dlopens that library and calls ompt_start_tool; the library
in turn registers call backs for the events it is interested in – and the
OpenMP calls those when the event happens, e.g. when entering a parallel
region.

This permits tracing in some way what the program does OpenMP wise,
usually either used directly to see the timing of the program or often
by doing some fancier tracing differently and using OMPT just to see
what code the program is actually doing to make more sense of the
generic tracing.

The OMPT proposers describe OMPT as follows:

OMPT enables performance tools to gather useful performance information 
from applications with low overhead and to map this information back to 
a user-level view of applications. OMPT provides three principal 
capabilities: (1) runtime state tracking, which enables a sampling-based 
performance tool to understand what an application thread is doing, (2) 
callbacks and inquiry functions that enable sampling-based performance 
tools to attribute application performance to complete calling contexts, 
and (3) additional callback notifications that enable construction of 
more full-featured monitoring capabilities.

And OpenMP itself describes it as:

This chapter provides an overview of OMPT, which is an interface for first-party tools. First-party
tools are linked or loaded directly into the OpenMP program. OMPT defines mechanisms to
initialize a tool, to examine thread state associated with a thread, to interpret the call stack of a
thread, to receive notification about events, to trace activity on target devices, to assess
implementation-dependent details of an OpenMP implementation (such as supported states and
mutual exclusion implementations), and to control a tool from an OpenMP program.


I am a bit unsure how to word this best, trying to be as generic as possible
without leaving the user wondering. - I think we shouldn't add more than a few
words here - but we need some section about OMPT in general elsewhere.

A simple tool doing so is, e.g., https://github.com/passlab/omptrace

Of course, the heavy suits/collections of tools can also do this,
possibly stacked on each otherlike:

* Score-P - https://www.vi-hps.org/projects/score-p/overview/overview.html
* TAU - Tuning and Analysis Utilities - https://www.cs.uoregon.edu/research/tau/docs.php
* Scalasca - https://www.scalasca.org/

Tobias