Merge remote-tracking branch 'BKP/v1.6/section/profiler' into tmp

content/profiling_interface.tex

@@ -1,74 +1,74 @@
-The objective of the \openshmem profiling interface is to ensure an 
-easy and flexible usage model for profiling (and other similar) 
-tool developers to interface their codes into \openshmem 
-implementations on different platforms. Since \openshmem is a 
-machine-independent standard with different implementations, it is 
-unreasonable to expect that the authors and developers of profiling 
-tools for \openshmem will have access to the source code that 
-implements \openshmem on any particular machine. It is, therefore,  
-necessary to provide a mechanism by which the implementors of such 
-tools can collect whatever performance information they wish 
+The objective of the \openshmem profiling interface is to ensure an
+easy and flexible usage model for profiling (and other similar)
+tool developers to interface their code into \openshmem
+implementations on different platforms. Since \openshmem is a
+machine-independent standard with different implementations, it is
+unreasonable to expect that the authors and developers of profiling
+tools for \openshmem will have access to the source code that
+implements \openshmem on any particular machine. It is, therefore,
+necessary to provide a mechanism by which the implementers of such
+tools can collect whatever performance information they wish
 \emph{without} access to the underlying implementation.
 
-The \openshmem profiling interface places the following requirements 
-on implementations. 
+The \openshmem profiling interface places the following requirements
+on implementations.
 
 \begin{enumerate}
-\item An \openshmem implementation must provide a mechanism through 
-which all of the \openshmem defined functions may be accessible 
-with a name shift. This requires an alternate 
-entry point name, with the prefix \FUNC{pshmem\_} for each 
-\openshmem function. For \openshmem inlined functions (e.g., macros), 
-it is also required that the \FUNC{pshmem\_} version is supplied 
-although it is not possible to replace the \FUNC{shmem\_} version 
+\item An \openshmem implementation must provide a mechanism through
+which all of the \openshmem defined functions may be accessible
+with a name shift. This requires an alternate
+entry point name, with the prefix \FUNC{pshmem\_} for each
+\openshmem function. For \openshmem inlined functions (e.g., macros),
+it is also required that the \FUNC{pshmem\_} version is supplied
+although it is not possible to replace the \FUNC{shmem\_} version
 with a user-defined version at link time.
-\item It must be ensured that the \openshmem functions that are not 
-replaced as above, may still be linked into an executable image 
-without causing name clashes. 
-\item Documentation of the implementation of different language 
-bindings of the \openshmem interface must indicate if they 
-are layered on top of each other. Using this documentation,   
-developers can determine whether they need to implement the 
-profile interface for each binding or not. For example, it must 
-be noted that the \openshmem \Cstd[11] type-generic interfaces for 
+\item It must be ensured that the \openshmem functions that are not
+replaced as above, may still be linked into an executable image
+without causing name clashes.
+\item Documentation of the implementation of different language
+bindings of the \openshmem interface must indicate if they
+are layered on top of each other. Using this documentation,
+developers can determine whether they need to implement the
+profile interface for each binding or not. For example, it must
+be noted that the \openshmem \Cstd[11] type-generic interfaces for
 different \ac{RMA} and \ac{AMO} operations cannot have any equivalent
-\FUNC{pshmem\_} interfaces because the \Cstd[11] type-generic 
+\FUNC{pshmem\_} interfaces because the \Cstd[11] type-generic
 interfaces are implemented as macros.
-\item In the case where the implementation of different \ac{API}  
-feature sets is implemented through a layered approach using 
-``wrapper'' functions, the wrapper functions must be kept separate 
-from the rest of the library. This requirement allows the developers 
-to extract these functions from the original \openshmem library 
-and add them into the profiling library without bringing along any 
+\item In the case where the implementation of different \ac{API}
+feature sets is implemented through a layered approach using
+``wrapper'' functions, the wrapper functions must be kept separate
+from the rest of the library. This requirement allows the developers
+to extract these functions from the original \openshmem library
+and add them into the profiling library without bringing along any
 other code.
-\item A no-op routine, \FUNC{shmem\_pcontrol}, must be provided 
+\item A no-op routine, \FUNC{shmem\_pcontrol}, must be provided
 in the \openshmem library.
-\item It must be ensured that any \openshmem types or constants that are 
+\item It must be ensured that any \openshmem types or constants that are
 needed by the \FUNC{pshmem\_} interfaces are defined in \HEADER{pshmem.h}.
 \end{enumerate}
 
-Provided that an \openshmem implementation meets these requirements, 
-it is possible for the implementor of the profiling system 
-to intercept the \openshmem calls that are made by the user 
-program. The information required can be collected before and after 
-calling the underlying \openshmem implementation through the name 
-shifted entry points. 
+Provided that an \openshmem implementation meets these requirements,
+it is possible for the implementer of the profiling system
+to intercept the \openshmem calls that are made by the user
+program. The information required can be collected before and after
+calling the underlying \openshmem implementation through the name
+shifted entry points.
 
 \subsection{Control of Profiling}
 \label{sec:pshmem_control_profile}
-Any user code must be able to control the profiler dynamically 
-during runtime. Generally, this capability is used for the 
+Any user code must be able to control the profiler dynamically
+during runtime. Generally, this capability is used for the
 purposes of
 
 \begin{itemize}
-\item Enabling and disabling of profiling based on the current 
+\item Enabling and disabling of profiling based on the current
 state of the execution and calculation,
 \item Flushing of the trace buffers at noncritical execution
 regions,
 \item Adding user events to a trace file.
 \end{itemize}
 
-These functionalities can be achieved through the usage of 
+These functionalities can be achieved through the usage of
 \FUNC{shmem\_pcontrol}.
 
 \subsubsection{\textbf{SHMEM\_PCONTROL}}\label{subsec:shmem_pcontrol}
@@ -133,7 +133,7 @@ \subsection{Limitations}
 
 \subsubsection{Multiple Counting}
 \label{sec:pshmem_multiple_count}
-Since some functions in \openshmem library may be implemented
+Since some functions in the \openshmem library may be implemented
 using more basic \openshmem functions, it is possible for these basic
 profiling functions to be called from within an \openshmem function
 that was originally called from a profiling routine. For example,

content/shmem_pcontrol.tex

@@ -15,7 +15,7 @@
 \end{apiarguments}
 
 \apidescription{
-  \FUNC{shmem\_pcontrol} sets the profiling level and any other  
+  \FUNC{shmem\_pcontrol} sets the profiling level and any other
   library defined effects through additional arguments. \openshmem libraries
   make no use of this routine and simply return immediately to the user code.
 }
@@ -25,26 +25,26 @@
 }
 
 \apinotes{
-  Since \openshmem has no control of the implementation of the profiling code, 
-  it is impossible to precisely specify the semantics that will be provided by 
-  calls to \FUNC{shmem\_pcontrol}. This vagueness extends to the number of 
-  arguments to the function and their datatypes. However, to provide some 
-  level of portability of user codes to different profiling libraries, the 
+  Since \openshmem has no control of the implementation of the profiling code,
+  it is impossible to precisely specify the semantics that will be provided by
+  calls to \FUNC{shmem\_pcontrol}. This vagueness extends to the number of
+  arguments to the function and their datatypes. However, to provide some
+  level of portability of user code to different profiling libraries, the
   following \VAR{level} values are recommended.
 
   \begin{itemize}
   \item \texttt{level <= 0} Profiling is disabled.
   \item \texttt{level == 1} Profiling is enabled at the default level of detail.
-  \item \texttt{level == 2} Profiling is enabled and profile buffers are 
+  \item \texttt{level == 2} Profiling is enabled and profile buffers are
   flushed if available.
-  \item \texttt{level > 2} Profiling is enabled with profile library defined 
+  \item \texttt{level > 2} Profiling is enabled with profile library defined
   effects and additional arguments.
   \end{itemize}
 
-  The default state after \FUNC{shmem\_init} is recommended to have profiling 
+  The default state after \FUNC{shmem\_init} is recommended to have profiling
   enabled at the default level of detail (\texttt{level == 1}). This allows users
-  to link with a profiling library and to obtain profile output without 
-  having to modify the user-level source code. 
+  to link with a profiling library and to obtain profile output without
+  having to modify the user-level source code.
 }
 
 \end{apidefinition}