From ac518923c3e21fd91c784a35054d8049c5cb21d6 Mon Sep 17 00:00:00 2001 From: Brandon Potter Date: Thu, 29 Aug 2024 09:25:14 -0500 Subject: [PATCH 1/5] profiler: remove whitespace at end of line --- content/profiling_interface.tex | 94 ++++++++++++++++----------------- content/shmem_pcontrol.tex | 22 ++++---- 2 files changed, 58 insertions(+), 58 deletions(-) diff --git a/content/profiling_interface.tex b/content/profiling_interface.tex index e50ab8d7..51a50909 100644 --- a/content/profiling_interface.tex +++ b/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 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 \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 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. \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} diff --git a/content/shmem_pcontrol.tex b/content/shmem_pcontrol.tex index a20f61e4..79abbbd7 100644 --- a/content/shmem_pcontrol.tex +++ b/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 codes 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} From 45a64caa7fcd9c146e6b9b0a18cd579d3cf51af9 Mon Sep 17 00:00:00 2001 From: Bryan Morgan <108841484+bcmIntc@users.noreply.github.com> Date: Fri, 30 Aug 2024 13:27:12 -0400 Subject: [PATCH 2/5] Update profiling_interface.tex 1/3: "code" instead of "codes" (mass noun). --- content/profiling_interface.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/profiling_interface.tex b/content/profiling_interface.tex index 51a50909..81ed2d83 100644 --- a/content/profiling_interface.tex +++ b/content/profiling_interface.tex @@ -1,6 +1,6 @@ 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 +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 From 1539658268c1b57034bf74a14a5d105bb9a81266 Mon Sep 17 00:00:00 2001 From: Bryan Morgan <108841484+bcmIntc@users.noreply.github.com> Date: Fri, 30 Aug 2024 13:31:07 -0400 Subject: [PATCH 3/5] Update shmem_pcontrol.tex 2/3: "code" instead of "codes" (mass noun). --- content/shmem_pcontrol.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shmem_pcontrol.tex b/content/shmem_pcontrol.tex index 79abbbd7..d4aac2b3 100644 --- a/content/shmem_pcontrol.tex +++ b/content/shmem_pcontrol.tex @@ -29,7 +29,7 @@ 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 + level of portability of user code to different profiling libraries, the following \VAR{level} values are recommended. \begin{itemize} From d534723e887cdd764dd43e18515d28c41ab3b17f Mon Sep 17 00:00:00 2001 From: Bryan Morgan <108841484+bcmIntc@users.noreply.github.com> Date: Fri, 30 Aug 2024 13:33:08 -0400 Subject: [PATCH 4/5] Update profiling_interface.tex Added "the" before \openshmem. --- content/profiling_interface.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/profiling_interface.tex b/content/profiling_interface.tex index 81ed2d83..401cc83e 100644 --- a/content/profiling_interface.tex +++ b/content/profiling_interface.tex @@ -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, From 98c8718ddb3cead8095e664037337de5b965db9a Mon Sep 17 00:00:00 2001 From: Brandon Potter Date: Thu, 5 Sep 2024 12:22:57 -0500 Subject: [PATCH 5/5] Spelling fix for implementer text --- content/profiling_interface.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/profiling_interface.tex b/content/profiling_interface.tex index 401cc83e..9fec4875 100644 --- a/content/profiling_interface.tex +++ b/content/profiling_interface.tex @@ -6,7 +6,7 @@ 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 +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. @@ -48,7 +48,7 @@ \end{enumerate} Provided that an \openshmem implementation meets these requirements, -it is possible for the implementor of the profiling system +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