\pagebreak
\section{OMPT Start}
\label{sec:ompt_start}

There are three steps an OpenMP implementation takes to activate a tool.
This section explains how the tool and an OpenMP implementation interact to accomplish tool activation.

\index{OMPT interface!activating}
\index{OMPT interface!ompt_start_tool routine@\kcode{ompt_start_tool} routine}
\index{routines!ompt_start_tool@\kcode{ompt_start_tool}}
\index{ompt_start_tool routine@\kcode{ompt_start_tool} routine}
Step 1. \emph{Determine Whether to Initialize}
\begin{adjustwidth}{2.5em}{0pt}
A tool is activated by the OMPT interface when it returns a non-\bcode{NULL} pointer to an \kcode{ompt_start_tool_result_t} structure on a call to \kcode{ompt_start_tool} by the OpenMP implementation.
There are three ways that a tool can provide a definition of \kcode{ompt_start_tool} to an OpenMP implementation:
(1) Statically linking the tool's definition of \kcode{ompt_start_tool} into an OpenMP application.
(2) Introducing a dynamically linked library that includes the tool's definition of
\kcode{ompt_start_tool} into the application's address space.
(3) Providing the name of a dynamically linked library appropriate for the architecture
and operating system used by the application in the \plc{tool-libraries-var} ICV.
\end{adjustwidth}

Step 2. \emph{Initializing a First-Party tool}
\begin{adjustwidth}{2.5em}{0pt}
If a tool-provided implementation of \kcode{ompt_start_tool} returns a non-\bcode{NULL} pointer
to an \kcode{ompt_start_tool_result_t} structure, the OpenMP implementation will invoke
the tool initializer specified in this structure prior to the occurrence of any OpenMP event.
\end{adjustwidth}


\index{OMPT interface!ompt_set_callback routine@\kcode{ompt_set_callback} routine}
\index{routines!ompt_set_callback@\kcode{ompt_set_callback}}
\index{ompt_set_callback routine@\kcode{ompt_set_callback} routine}
Step 3. \emph{Monitoring Activity on the Host}
\begin{adjustwidth}{2.5em}{0pt}
To monitor execution of an OpenMP program on the host device, a tool's initializer
must register to receive notification of events that occur as an OpenMP program executes.
A tool can register callbacks for OpenMP events using the runtime entry point known
as \kcode{ompt_set_callback}, which has the following possible return codes: \hfill \break
 \kcode{ompt_set_error},
 \kcode{ompt_set_never},
 \kcode{ompt_set_impossible},
 \kcode{ompt_set_sometimes},
 \kcode{ompt_set_sometimes_paired},
 \kcode{ompt_set_always}.

If the \kcode{ompt_set_callback} runtime entry point is called outside a tool's initializer,
registration of supported callbacks may fail with a return code of \kcode{ompt_set_error}.
All callbacks registered with \kcode{ompt_set_callback} or returned by \kcode{ompt_get_callback}
use the dummy type signature \kcode{ompt_callback_t}. While this is a compromise, it is
better than providing unique runtime entry points with precise type signatures
to set and get the callback for each unique runtime entry point type signature.
\end{adjustwidth}

----------------

To use the OMPT interface a tool must provide a globally-visible implementation
of the \kcode{ompt_start_tool} function.
The function returns a pointer to an \kcode{ompt_start_tool_result_t} structure 
that contains callback pointers for tool initialization and finalization as well 
as a data word, \ucode{tool_data}, that is to be passed by reference to these callbacks.
A \bcode{NULL} return indicates the tool will not use the OMPT interface.
The runtime execution of \kcode{ompt_start_tool} is triggered by the first OpenMP 
directive or OpenMP API routine call.


In the example below, the user-provided \kcode{ompt_start_tool} function
performs a check to make sure the runtime OpenMP version that OMPT supports 
(provided by the \ucode{omp_version} argument) is identical to the 
OpenMP implementation (compile-time) version.
Also, a \bcode{NULL} is returned to indicate that the OMPT interface is not
used (no callbacks and tool data are specified). 

\emph{Note}: The \plc{omp-tools.h} file is included.

\cexample[5.0]{ompt_start}{1}