Ariels changes as in email from 06/01/2016

Author: jprotze

figures/ompd-structural-overview.docx

@@ -9,12 +9,14 @@ \section{Breakpoint Locations for Managing Parallel Regions and Tasks}
 launching parallel regions or tasks,
 %%%% OMPD provides a routine that the debugger can invoke to 
 %%%% determine where to place breakpoints. 
-the OpenMP runtime must define a number of routines in which
+the OpenMP runtime must define a number of symbols at which
 the debugger may plant breakpoints to receive notification of
 particular events.
-The runtime is expected to call these routines when these events occur
-\emph{and} data collection for OMPD is
+The runtime is expected to execute through these locations when
+these events occur \emph{and} data collection for OMPD is
 enabled (see~\S\ref{runtime-interface:sec}).
+These locations may, but do not have to, be subroutines
+(see~\S\ref{structural-overview:sec}).
 
 \paragraph{Advice to implementors} The debugger needs to be able to detect 
 the beginning of OpenMP runtime code.
@@ -72,12 +74,12 @@ \section{Breakpoint Locations for Managing Parallel Regions and Tasks}
 
 \subsection{Parallel Regions}
 
-The OpenMP runtime must call \texttt{ompd\_bp\_parallel\_begin}
-when a new parallel region is launched.
-The call should  occur after a task encounters a parallel construct,
+The OpenMP runtime must execute through
+\texttt{ompd\_bp\_parallel\_begin} when a new parallel region is launched.
+This should occur after a task encounters a parallel construct,
 but before any implicit task starts to execute the parallel
 region's work.
-The type signature for \texttt{ompd\_bp\_parallel\_begin} is:
+Conceptually, the type signature for \texttt{ompd\_bp\_parallel\_begin} is:
 \begin{quote}
 \begin{lstlisting}
 void ompd_bp_parallel_begin ( void );
@@ -103,14 +105,18 @@ \subsection{Parallel Regions}
 will be that of the task encountering the parallel construct.
 The `reenter runtime' address in the information returned by
 \refdef{\texttt{ompd\_get\_task\_frame}}{get-task-frame:def}
-will be that of the stack frame where the thread entered the OpenMP
+will be that of the stack frame where the thread called the OpenMP
 runtime to handle the parallel construct.
 The `exit runtime' address will be for the stack frame where the thread
 left the OpenMP runtime to execute the user code that encountered
 the parallel construct.
 
-When a parallel region finishes, the OpenMP runtime will call
-the \texttt{ompd\_bp\_parallel\_end} routine:
+When a parallel region finishes, the OpenMP runtime will cause
+control to flow through
+the location \texttt{ompd\_bp\_parallel\_end}.
+Conceptually, \texttt{ompd\_bp\_parallel\_end} has this type
+signature, but as with other event notification locations 
+does not need to be a function:
 \begin{quote}
 \begin{lstlisting}
 void ompd_bp_parallel_end ( void );
@@ -128,7 +134,7 @@ \subsection{Parallel Regions}
 terminating.
 The `reenter runtime' address in the frame information returned by
 \refdef{\texttt{ompd\_get\_task\_frame}}{get-task-frame:def}
-will be that for the stack frame in which the thread entered the
+will be that for the stack frame in which the thread called the
 OpenMP runtime to start the parallel construct just terminating.
 The `exit runtime' address will refer to the stack frame where the
 thread left the OpenMP runtime to execute the user code that
@@ -237,14 +243,17 @@ \subsection{Parallel Regions}
 \subsection{Task Regions}
 
 When starting a new task region, the OpenMP runtime system
-calls \texttt{ompd\_bp\_task\_begin}:
+must allow control to pass through \texttt{ompd\_bp\_task\_begin}.
+Conceptually, \texttt{ompd\_bp\_task\_end} has this type
+signature, but as with other event notification locations 
+does not need to be a function:
 \begin{quote}
 \begin{lstlisting}
 void ompd_bp_task_begin ( void );
 \end{lstlisting}
 \end{quote}
 \labeldef{bp-task-begin:def}
-The OpenMP runtime system will call this routine after the task
+The OpenMP runtime system will execute through this location after the task
 construct is encountered, but before the new explicit task starts.
 When the breakpoint is triggered the debugger can map the operating
 thread to an OpenMP handle using
@@ -256,7 +265,9 @@ \subsection{Task Regions}
 \refdef{\texttt{ompd\_get\_task\_function}}{get-task-function:def}.
 
 When a task region completes, the OpenMP runtime system
-calls the \texttt{ompd\_bp\_task\_end} function:
+executes through the location \texttt{ompd\_bp\_task\_end}.
+If it is implemented as a subroutine, \texttt{ompd\_bp\_task\_end}
+has this signature:
 \begin{quote}
 \begin{lstlisting}
 void ompd_bp_task_end ( void );
@@ -269,4 +280,4 @@ \subsection{Task Regions}
 OpenMP thread handle.
 At this point
 \refdef{\texttt{ompd\_get\_top\_task\_region}}{get-top-task-region:def}
-returns the handle for the terminating task.
+returns the handle for the terminating task.

figures/ompd-structural-overview.pdf

@@ -93,6 +93,62 @@ \subsection{Design Objectives}
 This includes support for OpenMP state, call frame,
 task and parallel region information.
 
+\subsection{Structural Overview}
+\label{structural-overview:sec}
+
+Figure~\ref{ompd-structural-overview:fig} shows how the different components
+fit together.
+The debugger loads the OMPD plugin that matches the OpenMP runtime
+being used by the target.
+The plugin exports the API defined in this document, which the debugger
+uses to get OpenMP information about the target.
+The OMPD plugin will need to look up the symbols,
+or read data out of the target.
+It does not do this directly, but instead asks the debugger to perform
+these operations for it using a callback interface exported by the debugger.
+This callback interface is also defined in this document
+(see Section~\ref{sec:ompd_data_types}).
+
+This architectural layout insulates the debugger from the details
+of the internal structure of the OpenMP runtime.
+Similarly, the OMPD plugin does not need to be concerned about
+how to access the target.
+Decoupling the plugin and debugger in this ways allows for
+great flexibility in how the target and tool are deployed,
+so that, for example, there is no requirement that debugger
+and target execute on the same machine.
+
+Generally the debugger does not interact directly with the OpenMP
+runtime in the target, and instead uses the OMPD plugin for this purpose.
+However, there are a few instances where the debugger does need
+to access the OpenMP runtime directly.
+These cases fall into two broad categories.
+The first is during initialization, where the debugger needs
+to be able to look up symbols and read variables in OpenMP runtime
+in order to identify the OPMP plugin it should use.
+This is discussed in Section~\ref{runtime-interface:sec}.
+
+The second category relates to arranging for the debugger to be notified
+when certain events occur during the execution of the OpenMP program.
+The model used for this purpose is that the OpenMP implementation
+is required to define certain symbols in the runtime code.
+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 debugger wants to get notification of an event, it can plant
+a breakpoint at the matching location.
+
+The code locations can, but do not need to, be functions.
+They can, for example, simply be labels.
+However, the names must have external \texttt{C} linkage.
+
+\begin{figure}
+  \centering
+    \includegraphics[width=6.0in,natwidth=424.8,natheight=417.6]{figures/ompd-structural-overview.pdf}
+  \caption{OMPD: Structural overview}
+\label{ompd-structural-overview:fig}
+\end{figure}
+
 
 \subsection{Design Scope}
 \label{design-scope:sec}

ompd-tr.pdf

@@ -10,6 +10,8 @@ \section{Memory Management}
 If the OMPD DLL is implemented in \texttt{C++}, memory management operators 
 like \texttt{new} and \texttt{delete} in all their variants, \emph{must all} be 
 overloaded and implemented in terms of the callbacks provided by the debugger.
+The OMPD DLL must be coded so that any of its definitions of \texttt{new} or
+\texttt{delete} do not interfere with any defined by the debugger.
 
 In some cases the OMPD DLL will need to allocate memory to
 return results to the debugger. This memory will then be `owned' by the 
@@ -27,4 +29,4 @@ \section{Memory Management}
 
 Contexts are created by the debugger and passed to the OMPD implementation.
 The OMPD DLL does not need to release contexts; instead this will be done by 
-the debugger after it releases any handles that may be referencing the contexts.
+the debugger after it releases any handles that may be referencing the contexts.

sec_breakpoints.tex

@@ -279,13 +279,15 @@ \subsection{Runtime States}
 
 The OMPD runtime states mirror those in OMPT (see Appendix~A
 of~\cite{ompt-tr2}).
+Note that there is no guarantee that the numeric values of the
+corresponding members of the enumerations are identical.
 
 \begin{quote}
 \begin{lstlisting}
 typedef enum {
   /* work states (0..15) */
   ompd_state_work_serial           = 0x00,   /* working outside parallel */
-  ompd_state_work_paralle l        = 0x01,   /* working within parallel  */
+  ompd_state_work_parallel         = 0x01,   /* working within parallel  */
   ompd_state_work_reduction        = 0x02,   /* performing a reduction   */
 
   /* idle (16..31) */
@@ -304,8 +306,9 @@ \subsection{Runtime States}
   ompd_state_wait_taskgroup        = 0x51,   /* waiting at a taskgroup   */
 
   /* mutex wait states (96..111) */
-  ompd_state_wait_lock             = 0x60,   /* waiting for lock         */
-  ompd_state_wait_nest_lock        = 0x61,   /* waiting for nest lock    */  
+  ompd_state_wait_mutex            = 0x60,   /* waiting for any mutex kind
+                                                                         */
+  ompd_state_wait_lock             = 0x61,   /* waiting for lock         */  
   ompd_state_wait_critical         = 0x62,   /* waiting for critical     */
   ompd_state_wait_atomic           = 0x63,   /* waiting for atomic       */
   ompd_state_wait_ordered          = 0x64,   /* waiting for ordered      */
@@ -596,4 +599,4 @@ \subsection{Type Signatures for Debugger Callbacks}
   const char              *string
 );
 \end{lstlisting}
-\end{quote}
+\end{quote}

sec_introduction.tex

@@ -47,18 +47,27 @@ \section{OpenMP Runtime Interface}
 by loading a 32-bit OMPD that can manage a 64-bit OpenMP runtime.
 
 The OpenMP runtime shall notify the debugger that
-\texttt{ompd\_dll\_locations} is valid by calling:
+\texttt{ompd\_dll\_locations} is valid by allowing execution
+to pass through a location identified by the symbol
+\texttt{ompd\_dll\_locations\_valid}.
+This symbol must have external, \texttt{C}, linkage.
+
+Conceptually, \texttt{ompd\_dll\_locations\_valid} has the following
+signature:
 \begin{quote}
 \begin{lstlisting}
 void ompd_dll_locations_valid ( void );
 \end{lstlisting}
 \end{quote}
 \labeldef{dll-locations-valid:def}
+However, as noted in Section~\ref{structural-overview:sec},
+the event notification location does not need to be a function,
+and can instead be a labeled location in the code.
 
 \noindent
 The debugger can receive notification of this event by planting
-a breakpoint in this routine.
-\texttt{ompd\_dll\_locations\_valid()} has \texttt{C} linkage,
+a breakpoint at this location.
+\texttt{ompd\_dll\_locations\_valid} has \texttt{C} linkage,
 and the debugger will not apply name mangling before searching
 for this routine.
 In order to support debugging, the OpenMP runtime may need to collect
@@ -68,10 +77,10 @@ \section{OpenMP Runtime Interface}
 to support OMPD debugging if:
 \begin{enumerate}
 \item
-  the environment variable \texttt{OMP\_OMPD} is set to \texttt{on}
+  the environment variable \texttt{OMP\_DEBUG} is set to \texttt{on}
 \item
   the target calls the
-  \texttt{void omp\_ompd\_enable~(~void~)}\labeldef{ompd-enable:def}
+  \texttt{void omp\_debug\_enable~(~void~)}\labeldef{ompd-enable:def}
   function defined in the OpenMP runtime.
   This function may be called by the main executable, or any of the
   shared libraries the executable loads, and may be made in an
@@ -83,7 +92,7 @@ \section{OpenMP Runtime Interface}
   \textbf{Rationale:}
   In some cases it may not be possible to control a target's
   environment.
-  \texttt{omp\_ompd\_enable} allows a target itself to turn on
+  \texttt{omp\_debug\_enable} allows a target itself to turn on
   data collection for OMPD.
   Allowing the function to be called from an initializer allows
   the call to be positioned in an otherwise empty DLL that the
@@ -99,4 +108,4 @@ \section{OpenMP Runtime Interface}
 %% available to an OMPD plugin, including the following types of information:
 %% \verb|ompt_state_t|, \verb|ompt_wait_id_t|, and \verb|ompt_frame_t|
 %% data structures.
-%% \end{comment}
+%% \end{comment}

sec_memory_mgmt.tex

@@ -14,9 +14,9 @@ \section{OpenMP Runtime Requirements}
   \refdef{\texttt{ompd\_dll\_locations}}{dll-locations:def};
 \item
   The OpenMP must define
-  \refdef{\texttt{ompd\_dll\_locations\_valid~()}}{dll-locations-valid:def}
-  and call it once \texttt{ompd\_dll\_locations} is ready to be
-  read by the debugger;
+  \refdef{\texttt{ompd\_dll\_locations\_valid}}{dll-locations-valid:def}
+  and ensure that control flows through it once
+  \texttt{ompd\_dll\_locations} is ready to be read by the debugger;
 \item
   In order to support debugging, the OpenMP may need to collect and
   maintain information about a target's execution that, perhaps for
@@ -26,18 +26,18 @@ \section{OpenMP Runtime Requirements}
   necessary to support OMPD:
   \begin{enumerate}
   \item
-    the environment variable \texttt{OMP\_OMPD} is set to \texttt{on};
+    the environment variable \texttt{OMP\_DEBUG} is set to \texttt{on};
   \item
     the \emph{target} calls
-    \refdef{\texttt{omp\_ompd\_enable~()}}{ompd-enable:def}
+    \refdef{\texttt{omp\_debug\_enable~()}}{ompd-enable:def}
 \begin{notes}
 ilaguna: should OMPD support any of the previous mechanisms or both of 
 them? From the text it's not clear.
 \end{notes}
   \end{enumerate}
 \item
-  The OpenMP must define the following routines and call them at the
-  times described in Section~\ref{breakpoint-locations:sec}:
+  The OpenMP must define the following code symbols, and execute through
+  them at the times described in Section~\ref{breakpoint-locations:sec}:
   \begin{description}
   \item [\texttt{ompd\_bp\_parallel\_begin}]
   \item [\texttt{ompd\_bp\_parallel\_end}]
@@ -93,4 +93,4 @@ \section{OpenMP Runtime Requirements}
 %% A debugger can set a breakpoint in  \verb|ompt_enable_complete|  to observe 
 %%when a tool has been enabled or disabled.
 %% \end{comment}
-\clearpage
+\clearpage

sec_ompd_interface.tex

@@ -89,3 +89,10 @@ \subsection{Thread State Inquiry Analogue}
 );
 \end{lstlisting}
 \end{quote}
+
+The states are represented by values of the enumeration type
+\refdef{\texttt{ompd\_state\_t}}{state-t:def}.
+The symbolic names of the members of \texttt{ompd\_state\_t} should
+match those of the OMPT enumeration type \texttt{omp\_state\_e}.
+However, there is no guarantee that the numeric values of the corresponding
+symbolic constants are identical.