Merge remote-tracking branch 'kwaters4/backmatter-1.6v' into tmp

Author: jdinan

content/backmatter.tex

@@ -151,9 +151,9 @@ \chapter{Undefined Behavior in OpenSHMEM}\label{sec:undefined}
 \tabularnewline
 \hline
 Use of non-symmetric variables & Some routines require remotely accessible
-variables to perform their function.  For example, a \PUT{} to a non-symmetric variable may
-be trapped where possible and the library may abort the program.  Another
-implementation may choose to continue execution with or without a warning.
+variables to perform their function.  For example, an \openshmem libray may detect a \PUT{} to a non-symmetric variable
+and choose to abort the program.  
+However, another implementation may choose to continue execution with or without a warning.
 \tabularnewline
 \hline
 Non-symmetric allocation of symmetric memory & The symmetric memory management routines are
@@ -648,12 +648,17 @@ \subsection{Table~\ref{p2psynctypes}: point-to-point synchronization types}
 \chapter{Changes to this Document}\label{sec:changelog}
 
 \section{Version 1.6}
+\label{changelog:v1.6}
 Major changes in \openshmem[1.6] include the addition of the new
 \FUNC{shmem\_team\_ptr}, \FUNC{shmem\_ibget}, and \FUNC{shmem\_ibput}
 functions.
 
 The following list describes the specific changes in \openshmem[1.6]:
-\begin{itemize}
+\begin{enumerate}
+%
+\item Added an inclusive (\FUNC{shmem\_sum\_inscan}) and exclusive 
+(\FUNC{shmem\_sum\_exscan}) collective summation operation. 
+\ChangelogRef{subsec:shmem_scan}
 %
 \item Added support for initialization and finalization routines to be called
     multiple times, and added an initialization status query API
@@ -668,23 +673,14 @@ \section{Version 1.6}
   update a remote flag without associated data transfer of a put-with-signal operation.
 \ChangelogRef{subsec:shmem_signal_add, subsec:shmem_signal_set}%
 %
-\item Clarified that \OPR{Fence} operations only guarantee ordering for
-    operations that are performed on the same context.
-\ChangelogRef{subsec:shmem_fence}%
-%
 \item Added a team-based pointer query routine:
   \FUNC{shmem\_team\_ptr}.
 \ChangelogRef{subsec:shmem_team_ptr}%
 %
-\item Clarified that \FUNC{shmem\_team\_split\_strided} and
-    \FUNC{shmem\_team\_split\_strided} return a nonzero value when the parent
-    team compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}.
-\ChangelogRef{subsec:shmem_team_split_strided, subsec:shmem_team_split_2d}%
-%
-\item Removed \openshmem[1.5] Table 9, which was an incomplete duplicate of
-    \openshmem[1.5] Table 10, and clarified the types, names, and supporting
-    operations for team-based reductions.
-\ChangelogRef{teamreducetypes}%
+\item Clarified that the behavior of \FUNC{shmem\_team\_split\_strided} is
+    undefined when the input \VAR{start}, \VAR{stride}, and \VAR{size} arguments
+    imply a \textit{wrap-around} with respect to the parent team's \acp{PE}.
+\ChangelogRef{subsec:shmem_team_split_strided}%
 %
 \item Added the session routines, \FUNC{shmem\_ctx\_session\_start} and
     \FUNC{shmem\_ctx\_session\_stop}, which allow users to pass hints to the
@@ -703,11 +699,6 @@ \section{Version 1.6}
     the world team.
 \ChangelogRef{subsec:shmem_malloc, subsec:shmem_free, subsec:shmem_realloc,
   subsec:shmem_align, subsec:shmmallochint, subsec:shmem_calloc}%
-\item Corrected the level argument's recommended value in API notes for
-    \FUNC{shmem\_pcontrol} to indicate that the value should be greater than
-    2 to enable profiling with profile library defined effects and
-    additional arguments.
-\ChangelogRef{subsec:shmem_pcontrol}
 %
 \item Clarified that \FUNC{shmem\_team\_get\_config} returns the current
     configuration values, which may differ from the values assigned at the
@@ -722,7 +713,44 @@ \section{Version 1.6}
     stride argument is 0 or negative.
 \ChangelogRef{subsec:shmem_team_split_strided}
 %
-\end{itemize}
+\item Clarified the requirements for the source buffer before entering the
+    collective routines.
+\ChangelogRef{subsec:shmem_alltoall,subsec:shmem_broadcast,subsec:shmem_collect,subsec:shmem_reductions,subsec:shmem_scan}
+%
+\item Added a new Errata Section~\ref{sec:errata} that indicates errors or ambiguities in the
+    \openshmem specification and the version that required correction or clarification.
+\ChangelogRef{sec:errata}
+%
+\item Removed \openshmem[1.5] Table 9, which was an incomplete duplicate of
+    \openshmem[1.5] Table 10, and clarified the types, names, and supporting
+    operations for team-based reductions. \label{changelog:reduction_table}
+\ChangelogRef{teamreducetypes}%
+%
+\item Clarified that \VAR{source} and \VAR{dest} arrays must be the same
+    across \acp{PE} in \openshmem reductions \label{changelog:reduction_args}
+\ChangelogRef{subsec:shmem_reductions}
+%
+\item Clarified that \OPR{Fence} operations only guarantee ordering for
+    operations that are performed on the same context. \label{changelog:fence_ctx}
+\ChangelogRef{subsec:shmem_fence}%
+%
+\item Clarified that \FUNC{shmem\_test\_all} and \FUNC{shmem\_test\_all\_vector}
+    routines return 1 when the test set is empty. \label{changelog:test_all}
+\ChangelogRef{subsec:shmem_test_all,subsec:shmem_test_all_vector}%
+%
+\item Clarified that \FUNC{shmem\_team\_split\_strided} and
+    \FUNC{shmem\_team\_split\_strided} return a nonzero value when the parent
+        team compares equal to \LibConstRef{SHMEM\_TEAM\_INVALID}. \label{changelog:split_strided_2d}
+\ChangelogRef{subsec:shmem_team_split_strided, subsec:shmem_team_split_2d}%
+%
+\item Corrected the level argument's recommended value in API notes for
+    \FUNC{shmem\_pcontrol} to indicate that the value should be greater than
+    2 to enable profiling with profile library defined effects and
+    additional arguments. \label{changelog:pcontrol}
+\ChangelogRef{subsec:shmem_pcontrol}
+%
+
+\end{enumerate}
 
 \section{Version 1.5}
 Major changes in \openshmem[1.5] include the addition of new team-based
@@ -732,7 +760,7 @@ \section{Version 1.5}
 interface, and the removal of the entire \Fortran \ac{API}.
 
 The following list describes the specific changes in \openshmem[1.5]:
-\begin{itemize}
+\begin{enumerate}
 %
 \item Removed \FUNC{SHMEM\_CACHE}.
 \ChangelogRef{dep:shmem_cache}%
@@ -883,7 +911,7 @@ \section{Version 1.5}
 \item Clarified the atomicity guarantees of the \openshmem memory model.
 \ChangelogRef{subsec:amo_guarantees}%
 %
-\end{itemize}
+\end{enumerate}
 
 \section{Version 1.4}
 Major changes in \openshmem[1.4] include
@@ -898,7 +926,7 @@ \section{Version 1.4}
 and \Cstd[11] type-generic interfaces for point-to-point synchronization.
 
 The following list describes the specific changes in \openshmem[1.4]:
-\begin{itemize}
+\begin{enumerate}
 %
 \item New communication management \ac{API}, including \FUNC{shmem\_ctx\_create};
     \FUNC{shmem\_ctx\_destroy}; and additional \ac{RMA}, \ac{AMO}, and memory ordering
@@ -1018,7 +1046,7 @@ \section{Version 1.4}
 \item Clarified that complex-typed reductions in C are optionally supported.
 \ChangelogRef{subsec:shmem_reductions}%
 %
-\end{itemize}
+\end{enumerate}
 
 
 
@@ -1031,7 +1059,7 @@ \section{Version 1.3}
 and \Cstd[11] type-generic interfaces for \ac{RMA} and \ac{AMO} operations.
 
 The following list describes the specific changes in \openshmem[1.3]:
-\begin{itemize}
+\begin{enumerate}
 %
 \item Clarified implementation of \acp{PE} as threads.
 %
@@ -1072,7 +1100,7 @@ \section{Version 1.3}
 \item Deprecation of \FUNC{SHMEM\_CACHE}.
 \ChangelogRef{dep:shmem_cache}%
 %
-\end{itemize}
+\end{enumerate}
 
 
 
@@ -1087,7 +1115,7 @@ \section{Version 1.2}
 and clarifications to several \ac{API} descriptions.
 
 The following list describes the specific changes in \openshmem[1.2]:
-\begin{itemize}
+\begin{enumerate}
 %
 \item Added specification of \VAR{pSync} initialization for all routines that use it.
 %
@@ -1143,7 +1171,7 @@ \section{Version 1.2}
       support across versions of the \openshmem Specification.
 \ChangelogRef{sec:dep}%
 %
-\end{itemize}
+\end{enumerate}
 
 
 
@@ -1157,7 +1185,7 @@ \section{Version 1.1}
 and general readabilty and usability improvements to the document structure.
 
 The following list describes the specific changes in \openshmem[1.1]:
-\begin{itemize}
+\begin{enumerate}
 %
 \item Clarifications of the completion semantics of memory synchronization
       interfaces.
@@ -1266,6 +1294,47 @@ \section{Version 1.1}
 \item Name changes for UV and ICE for \ac{SGI} systems.
 \ChangelogRef{sec:openshmem_history}%
 %
-\end{itemize}
+\end{enumerate}
+
+\chapter{Errata}\label{sec:errata}
+
+Errors or ambiguities in the \openshmem specification may be discovered after
+publication.
+Errata, or corrections, are included in the the sections below indicating the
+version of the OpenSHMEM specification that required the correction or
+clarification.
+These corrections have been applied to all subsequent versions of the
+specification and this section serves as a historical record of the changes
+made to assist users and implementers with applying the necessary corrections.
+Errata that result in a change to the specifciation are also included in
+Annex~\ref{sec:changelog}.
+For an implementation to comply with a particular version of \openshmem, it
+must account for all errata associated with that version as indicated below.
+
+\section{Version 1.5}
+
+\begin{enumerate}
+  \item Removed \openshmem[1.5] Table 9, which was an incomplete duplicate of
+      \openshmem[1.5] Table 10, and clarified the types, names, and supporting
+      operations for team-based reductions
+        (\ref{changelog:v1.6}.\ref{changelog:reduction_table}).
+  \item Clarified that \VAR{source} and \VAR{dest} arrays must be the same
+      across \acp{PE} in \openshmem reductions
+        (\ref{changelog:v1.6}.\ref{changelog:reduction_args}).
+  \item Clarified that \OPR{Fence} operations only guarantee ordering for operations
+     that are performed on the same context
+        (\ref{changelog:v1.6}.\ref{changelog:fence_ctx}).
+  \item Clarified that \FUNC{shmem\_test\_all} and
+     \FUNC{shmem\_test\_all\_vector} routines return 1 when the test set is empty
+        (\ref{changelog:v1.6}.\ref{changelog:test_all}).
+  \item Clarified that \FUNC{shmem\_team\_split\_strided} and
+     \FUNC{shmem\_team\_split\_2d} return nonzero when the parent team is
+     \LibConstRef{SHMEM\_TEAM\_INVALID}
+        (\ref{changelog:v1.6}.\ref{changelog:split_strided_2d}).
+  \item Corrected the \VAR{level} argument's recommended value in API notes for
+     \FUNC{shmem\_pcontrol} to indicate that the value should be greater than 2 to enable
+     profiling with profile library defined effects and additional arguments
+        (\ref{changelog:v1.6}.\ref{changelog:pcontrol}).
+\end{enumerate}
 
 %end of setlength command that was started in frontmatter.tex

content/interoperability.tex

@@ -119,7 +119,7 @@ \subsection{Mapping Process Identification Numbers}
 This feature, however, may be provided by only some of the \openshmem and \ac{MPI}
 implementations (e.g., if both environments share the same underlying process
 manager) and is not portably guaranteed. A portable program should always
-use the standard functions in each model, namely, \FUNC{shmem\_team\_my\_pe} in \openshmem
+use the standard functions in each model, namely, \FUNC{shmem\_team\_my\_pe} or \FUNC{shmem\_my\_pe} in \openshmem 
 and \FUNC{MPI\_Comm\_rank} in \ac{MPI}, to query the process identification numbers
 in each communication environment and manage the mapping of identifiers in the
 program when necessary.