diff --git a/content/backmatter.tex b/content/backmatter.tex index 498bbf4b..bc7013ff 100644 --- a/content/backmatter.tex +++ b/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 diff --git a/content/interoperability.tex b/content/interoperability.tex index bb9ed5a1..7347ee87 100644 --- a/content/interoperability.tex +++ b/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.