From 634db0883fc668ad6168ece0005e603161a3357c Mon Sep 17 00:00:00 2001 From: "Rahman, Md" Date: Tue, 27 Aug 2024 20:49:28 -0500 Subject: [PATCH 1/7] PR 514 content: signal set add update --- content/shmem_signal_add.tex | 6 +-- content/shmem_signal_set.tex | 6 +-- content/shmem_signal_wait_until.tex | 2 +- content/signaling.tex | 57 ++++++++++++++++++++++++++++ main_spec.tex | 59 +---------------------------- 5 files changed, 65 insertions(+), 65 deletions(-) create mode 100644 content/signaling.tex diff --git a/content/shmem_signal_add.tex b/content/shmem_signal_add.tex index 272b03a63..362fbeef8 100644 --- a/content/shmem_signal_add.tex +++ b/content/shmem_signal_add.tex @@ -5,12 +5,12 @@ \begin{apidefinition} \begin{C11synopsis} -void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_add}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{C11synopsis} \begin{Csynopsis} -void @\FuncDecl{shmem\_signal\_add}@(const uint64_t *sig_addr, uint64_t signal, int pe); -void @\FuncDecl{shmem\_ctx\_signal\_add}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_add}@(uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_add}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{Csynopsis} \begin{apiarguments} diff --git a/content/shmem_signal_set.tex b/content/shmem_signal_set.tex index 00c70345d..d0eefbfd8 100644 --- a/content/shmem_signal_set.tex +++ b/content/shmem_signal_set.tex @@ -5,12 +5,12 @@ \begin{apidefinition} \begin{C11synopsis} -void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_set}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{C11synopsis} \begin{Csynopsis} -void @\FuncDecl{shmem\_signal\_set}@(const uint64_t *sig_addr, uint64_t signal, int pe); -void @\FuncDecl{shmem\_ctx\_signal\_set}@(shmem_ctx_t ctx, const uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_signal\_set}@(uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_signal\_set}@(shmem_ctx_t ctx, uint64_t *sig_addr, uint64_t signal, int pe); \end{Csynopsis} \begin{apiarguments} diff --git a/content/shmem_signal_wait_until.tex b/content/shmem_signal_wait_until.tex index 5d93ec7f3..564c5a773 100644 --- a/content/shmem_signal_wait_until.tex +++ b/content/shmem_signal_wait_until.tex @@ -11,7 +11,7 @@ \begin{apiarguments} -\apiargument{IN}{sig\_addr}{Local address of the source signal variable.} +\apiargument{IN}{sig\_addr}{Local address of the remotely accessible source signal variable.} \apiargument{IN}{cmp}{The comparison operator that compares \VAR{sig\_addr} with \VAR{cmp\_value}.} \apiargument{IN}{cmp\_value}{The value against which the object pointed to diff --git a/content/signaling.tex b/content/signaling.tex new file mode 100644 index 000000000..bd04940b4 --- /dev/null +++ b/content/signaling.tex @@ -0,0 +1,57 @@ +This section specifies the OpenSHMEM support for \OPR{put-with-signal}, +nonblocking \OPR{put-with-signal}, and \OPR{signal-\{add, fetch, set\}} routines. The +put-with-signal routines provide a method for copying data from a contiguous +local data object to a data object on a specified \ac{PE} and subsequently +updating a remote flag to signal completion. +The signal-add and signal-set routines provide methods for updating +the signal object without the associated data transfer of a +put-with-signal operation. +The signal-fetch routine provides support for reading a local signal value. + +\openshmem \OPR{put-with-signal} and \OPR{signal-\{add, set\}} +routines specified in this section have two +variants. In one of the variants, the context handle, \VAR{ctx}, is explicitly +passed as an argument. In this variant, the operation is performed on the +specified context. If the context handle \VAR{ctx} does not correspond to a +valid context, the behavior is undefined. In the other variant, the context +handle is not explicitly passed and thus, the operations are performed on the +default context. + +\subsubsection{Atomicity Guarantees for Signaling Operations} +\label{subsec:signal_atomicity} +All signaling operations put-with-signal, nonblocking put-with-signal, and +signal-\{add, fetch, set\} are performed on a signal data object, a remotely accessible +symmetric object of type \VAR{uint64\_t}. A signal operator in the +put-with-signal routine is an \openshmem library constant that determines the +type of update to be performed as a signal on the signal data object. + +All signaling operations on the signal data object complete as if performed +atomically with respect to the following: +\begin{itemize} + \item other blocking or nonblocking variant of the put-with-signal routine + that updates the signal data object using the same signal update operator; + \item signal-add routine when the put-with-signal routine uses the + \LibConstRef{SHMEM\_SIGNAL\_ADD} signal operator; + \item signal-set routine when the put-with-signal routine uses the + \LibConstRef{SHMEM\_SIGNAL\_SET} signal operator; + \item signal-fetch routine that fetches the signal data object; and + \item any point-to-point synchronization routine that accesses the signal + data object. +\end{itemize} + +\subsubsection{Available Signal Operators} +\label{subsec:signal_operator} + +With the atomicity guarantees as described in +Section~\ref{subsec:signal_atomicity}, the following options can be used as a +signal operator. + + \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_SET}}{An update to signal data + object is an atomic set operation. It writes an unsigned 64-bit value as a + signal into the signal data object on a remote \VAR{PE} as an atomic + operation.} + + \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_ADD}}{An update to signal data + object is an atomic add operation. It adds an unsigned 64-bit value as a + signal into the signal data object on a remote \VAR{PE} as an atomic + operation.} diff --git a/main_spec.tex b/main_spec.tex index cfc3f8ae9..fe83dcb51 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -306,64 +306,7 @@ \subsubsubsection{\textbf{SHMEM\_ATOMIC\_FETCH\_XOR\_NBI}} \subsection{Signaling Operations}\label{sec:shmem_signal} -This section specifies the OpenSHMEM support for \OPR{put-with-signal}, -nonblocking \OPR{put-with-signal}, and \OPR{signal-\{add, fetch, set\}} routines. The -put-with-signal routines provide a method for copying data from a contiguous -local data object to a data object on a specified \ac{PE} and subsequently -updating a remote flag to signal completion. -The signal-add and signal-set routines provide methods for updating -the signal object without the associated data transfer of a -put-with-signal operation. -The signal-fetch routine provides support for reading a local signal value. - -\openshmem \OPR{put-with-signal} and \OPR{signal-\{add, set\}} -routines specified in this section have two -variants. In one of the variants, the context handle, \VAR{ctx}, is explicitly -passed as an argument. In this variant, the operation is performed on the -specified context. If the context handle \VAR{ctx} does not correspond to a -valid context, the behavior is undefined. In the other variant, the context -handle is not explicitly passed and thus, the operations are performed on the -default context. - -\subsubsection{Atomicity Guarantees for Signaling Operations} -\label{subsec:signal_atomicity} -All signaling operations put-with-signal, nonblocking put-with-signal, and -signal-\{add, fetch, set\} are performed on a signal data object, a remotely accessible -symmetric object of type \VAR{uint64\_t}. A signal operator in the -put-with-signal routine is an \openshmem library constant that determines the -type of update to be performed as a signal on the signal data object. - -All signaling operations on the signal data object complete as if performed -atomically with respect to the following: -\begin{itemize} - \item other blocking or nonblocking variant of the put-with-signal routine - that updates the signal data object using the same signal update operator; - \item signal-add routine when the put-with-signal routine uses the - \LibConstRef{SHMEM\_SIGNAL\_ADD} signal operator; - \item signal-set routine when the put-with-signal routine uses the - \LibConstRef{SHMEM\_SIGNAL\_SET} signal operator; - \item signal-fetch routine that fetches the signal data object; and - \item any point-to-point synchronization routine that accesses the signal - data object. -\end{itemize} - -\subsubsection{Available Signal Operators} -\label{subsec:signal_operator} - -With the atomicity guarantees as described in -Section~\ref{subsec:signal_atomicity}, the following options can be used as a -signal operator. - - \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_SET}}{An update to signal data - object is an atomic set operation. It writes an unsigned 64-bit value as a - signal into the signal data object on a remote \VAR{PE} as an atomic - operation.} - - \apitablerow{\LibConstRef{SHMEM\_SIGNAL\_ADD}}{An update to signal data - object is an atomic add operation. It adds an unsigned 64-bit value as a - signal into the signal data object on a remote \VAR{PE} as an atomic - operation.} - +\input{content/signaling.tex} \subsubsection{\textbf{SHMEM\_PUT\_SIGNAL}}\label{subsec:shmem_put_signal} \input{content/shmem_put_signal.tex} From a3b5d824d03e3f4acd99ccf592d742767922abcc Mon Sep 17 00:00:00 2001 From: "Rahman, Md" Date: Thu, 29 Aug 2024 14:51:30 -0500 Subject: [PATCH 2/7] Typo fix --- content/atomics_intro.tex | 2 +- content/rma_intro.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/atomics_intro.tex b/content/atomics_intro.tex index d803887dc..3a9ad5c6c 100644 --- a/content/atomics_intro.tex +++ b/content/atomics_intro.tex @@ -56,7 +56,7 @@ integer types defined in \HEADER{stdint.h} by \Cstd[99]~\S7.18.1.1 and \Cstd[11]~\S7.20.1.1. When the \Cstd translation environment does not provide exact-width integer types with \HEADER{stdint.h}, an -\openshmem implemementation is not required to provide support for these types. +\openshmem implementation is not required to provide support for these types. \begin{table}[h] \begin{center} diff --git a/content/rma_intro.tex b/content/rma_intro.tex index f986d6c81..e45078a86 100644 --- a/content/rma_intro.tex +++ b/content/rma_intro.tex @@ -44,7 +44,7 @@ \footnote{Formally, the \Cstd[99] specification is ISO/IEC~9899:1999(E).}% ~\S7.18.1.1 and \Cstd[11]~\S7.20.1.1. When the \Cstd translation environment does not provide exact-width integer types with \HEADER{stdint.h}, an -\openshmem implemementation is not required to provide support for these types. +\openshmem implementation is not required to provide support for these types. \begin{table}[h] \begin{center} From 46fbaa96cffdb6c272c698a7b52a583c9d481153 Mon Sep 17 00:00:00 2001 From: "Rahman, Md" Date: Thu, 29 Aug 2024 16:29:31 -0500 Subject: [PATCH 3/7] Clarified PE being relative to the team for APIs with context --- content/rma_intro.tex | 2 +- content/shmem_atomic_add.tex | 4 ++-- content/shmem_atomic_and.tex | 5 ++--- content/shmem_atomic_compare_swap.tex | 4 ++-- content/shmem_atomic_compare_swap_nbi.tex | 4 ++-- content/shmem_atomic_fetch.tex | 6 +++--- content/shmem_atomic_fetch_add.tex | 5 ++--- content/shmem_atomic_fetch_add_nbi.tex | 5 ++--- content/shmem_atomic_fetch_and.tex | 5 ++--- content/shmem_atomic_fetch_and_nbi.tex | 5 ++--- content/shmem_atomic_fetch_inc.tex | 5 ++--- content/shmem_atomic_fetch_inc_nbi.tex | 5 ++--- content/shmem_atomic_fetch_nbi.tex | 5 ++--- content/shmem_atomic_fetch_or.tex | 5 ++--- content/shmem_atomic_fetch_or_nbi.tex | 5 ++--- content/shmem_atomic_fetch_xor.tex | 5 ++--- content/shmem_atomic_fetch_xor_nbi.tex | 5 ++--- content/shmem_atomic_inc.tex | 5 ++--- content/shmem_atomic_or.tex | 5 ++--- content/shmem_atomic_set.tex | 5 ++--- content/shmem_atomic_swap.tex | 4 ++-- content/shmem_atomic_swap_nbi.tex | 4 ++-- content/shmem_atomic_xor.tex | 5 ++--- content/shmem_g.tex | 3 +++ content/shmem_get.tex | 3 ++- content/shmem_get_nbi.tex | 3 ++- content/shmem_ibget.tex | 3 ++- content/shmem_ibput.tex | 3 ++- content/shmem_iget.tex | 3 ++- content/shmem_iput.tex | 3 ++- content/shmem_p.tex | 3 ++- content/shmem_put.tex | 3 ++- content/shmem_put_nbi.tex | 3 ++- content/shmem_put_signal.tex | 3 ++- content/shmem_put_signal_nbi.tex | 3 ++- content/shmem_signal_add.tex | 5 ++--- content/shmem_signal_set.tex | 5 ++--- 37 files changed, 75 insertions(+), 79 deletions(-) diff --git a/content/rma_intro.tex b/content/rma_intro.tex index e45078a86..200966bdb 100644 --- a/content/rma_intro.tex +++ b/content/rma_intro.tex @@ -18,7 +18,7 @@ The destination \ac{PE} is specified as an integer representing the \ac{PE} number. This \ac{PE} number is relative to the team associated with the -communication context being using for the operation. If no context argument is passed to the routine, +communication context being used for the operation. If no context argument is passed to the routine, then the routine operates on the default context, which implies that the \ac{PE} number is relative to the world team. If the \ac{PE} number passed to the routine is invalid, being negative diff --git a/content/shmem_atomic_add.tex b/content/shmem_atomic_add.tex index 127374963..8a3b4f3dc 100644 --- a/content/shmem_atomic_add.tex +++ b/content/shmem_atomic_add.tex @@ -39,8 +39,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_and.tex b/content/shmem_atomic_and.tex index f82ee4bf1..5803812b1 100644 --- a/content/shmem_atomic_and.tex +++ b/content/shmem_atomic_and.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_compare_swap.tex b/content/shmem_atomic_compare_swap.tex index 85b371fa8..3763909da 100644 --- a/content/shmem_atomic_compare_swap.tex +++ b/content/shmem_atomic_compare_swap.tex @@ -45,8 +45,8 @@ type as \VAR{dest}.} \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \VAR{dest} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_compare_swap_nbi.tex b/content/shmem_atomic_compare_swap_nbi.tex index 84a90a128..a3dabaa56 100644 --- a/content/shmem_atomic_compare_swap_nbi.tex +++ b/content/shmem_atomic_compare_swap_nbi.tex @@ -35,8 +35,8 @@ \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number upon which - \VAR{dest} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch.tex b/content/shmem_atomic_fetch.tex index 3c11f2a11..3e7fab8a6 100644 --- a/content/shmem_atomic_fetch.tex +++ b/content/shmem_atomic_fetch.tex @@ -40,9 +40,9 @@ the default context.} \apiargument{IN}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number from which - \VAR{source} is to be fetched.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides + relative to the team associated with the given \VAR{ctx} when provided, or the + default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_add.tex b/content/shmem_atomic_fetch_add.tex index a07977ec9..a0e73984c 100644 --- a/content/shmem_atomic_fetch_add.tex +++ b/content/shmem_atomic_fetch_add.tex @@ -41,9 +41,8 @@ SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_add_nbi.tex b/content/shmem_atomic_fetch_add_nbi.tex index 3b9e40212..7f1007a29 100644 --- a/content/shmem_atomic_fetch_add_nbi.tex +++ b/content/shmem_atomic_fetch_add_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic fetch-and-add operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_and.tex b/content/shmem_atomic_fetch_and.tex index 0a4d78438..675449f27 100644 --- a/content/shmem_atomic_fetch_and.tex +++ b/content/shmem_atomic_fetch_and.tex @@ -27,9 +27,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_and_nbi.tex b/content/shmem_atomic_fetch_and_nbi.tex index 9959a1cc8..97b8b0c5c 100644 --- a/content/shmem_atomic_fetch_and_nbi.tex +++ b/content/shmem_atomic_fetch_and_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise AND operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_inc.tex b/content/shmem_atomic_fetch_inc.tex index 447102466..96437ac73 100644 --- a/content/shmem_atomic_fetch_inc.tex +++ b/content/shmem_atomic_fetch_inc.tex @@ -38,9 +38,8 @@ the default context.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_atomic_fetch_inc_nbi.tex b/content/shmem_atomic_fetch_inc_nbi.tex index 6cfbfb3a6..a7c17c3b7 100644 --- a/content/shmem_atomic_fetch_inc_nbi.tex +++ b/content/shmem_atomic_fetch_inc_nbi.tex @@ -28,9 +28,8 @@ The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_atomic_fetch_nbi.tex b/content/shmem_atomic_fetch_nbi.tex index 4891dc974..43fdd53be 100644 --- a/content/shmem_atomic_fetch_nbi.tex +++ b/content/shmem_atomic_fetch_nbi.tex @@ -28,9 +28,8 @@ The type of \VAR{fetch} should match that implied in the SYNOPSIS section.} \apiargument{OUT}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number from which - \VAR{source} is to be fetched.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_or.tex b/content/shmem_atomic_fetch_or.tex index 81046d8a7..0eb922bd5 100644 --- a/content/shmem_atomic_fetch_or.tex +++ b/content/shmem_atomic_fetch_or.tex @@ -27,9 +27,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_or_nbi.tex b/content/shmem_atomic_fetch_or_nbi.tex index 7a6c86684..d62fcd3ab 100644 --- a/content/shmem_atomic_fetch_or_nbi.tex +++ b/content/shmem_atomic_fetch_or_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_xor.tex b/content/shmem_atomic_fetch_xor.tex index a390500e6..fd563cb10 100644 --- a/content/shmem_atomic_fetch_xor.tex +++ b/content/shmem_atomic_fetch_xor.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_fetch_xor_nbi.tex b/content/shmem_atomic_fetch_xor_nbi.tex index 2b2cd085e..f69739c34 100644 --- a/content/shmem_atomic_fetch_xor_nbi.tex +++ b/content/shmem_atomic_fetch_xor_nbi.tex @@ -30,9 +30,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_inc.tex b/content/shmem_atomic_inc.tex index fde7e9dc4..c7cc359fb 100644 --- a/content/shmem_atomic_inc.tex +++ b/content/shmem_atomic_inc.tex @@ -38,9 +38,8 @@ the default context.} \apiargument{OUT}{dest}{Symmetric address of the destination data object. The type of \dest{} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_or.tex b/content/shmem_atomic_or.tex index 033de757f..5f00c530f 100644 --- a/content/shmem_atomic_or.tex +++ b/content/shmem_atomic_or.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise OR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_set.tex b/content/shmem_atomic_set.tex index fcea7dbc0..070e760f5 100644 --- a/content/shmem_atomic_set.tex +++ b/content/shmem_atomic_set.tex @@ -42,9 +42,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the atomic set operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} -\apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \VAR{dest} is to be updated.} - +\apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_swap.tex b/content/shmem_atomic_swap.tex index adab7bdb9..3a0a6577b 100644 --- a/content/shmem_atomic_swap.tex +++ b/content/shmem_atomic_swap.tex @@ -39,8 +39,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{ An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_swap_nbi.tex b/content/shmem_atomic_swap_nbi.tex index bfac883c2..fb619f202 100644 --- a/content/shmem_atomic_swap_nbi.tex +++ b/content/shmem_atomic_swap_nbi.tex @@ -30,8 +30,8 @@ \apiargument{IN}{value}{The value to be atomically written to the remote \ac{PE}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer that indicates the \ac{PE} number on which - \dest{} is to be updated.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_atomic_xor.tex b/content/shmem_atomic_xor.tex index d4f863ad4..65a7b6dc5 100644 --- a/content/shmem_atomic_xor.tex +++ b/content/shmem_atomic_xor.tex @@ -28,9 +28,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The operand to the bitwise XOR operation. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{An integer value for the \ac{PE} on which \VAR{dest} - is to be updated.} - + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_g.tex b/content/shmem_g.tex index 1fa6a2c98..e9412c812 100644 --- a/content/shmem_g.tex +++ b/content/shmem_g.tex @@ -23,6 +23,9 @@ \apiargument{IN}{source}{Symmetric address of the source data object. The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{pe}{The number of the remote \ac{PE} on which \VAR{source} resides.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} on which \VAR{source} resides + relative to the team associated with the given \VAR{ctx} when provided, or the + default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_get.tex b/content/shmem_get.tex index 890f83f23..2536421b1 100644 --- a/content/shmem_get.tex +++ b/content/shmem_get.tex @@ -37,7 +37,8 @@ The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays. For \FUNC{shmem\_getmem} and \FUNC{shmem\_ctx\_getmem}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_get_nbi.tex b/content/shmem_get_nbi.tex index 57adb768d..61e8261f4 100644 --- a/content/shmem_get_nbi.tex +++ b/content/shmem_get_nbi.tex @@ -39,7 +39,8 @@ \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays. For \FUNC{shmem\_getmem\_nbi} and \FUNC{shmem\_ctx\_getmem\_nbi}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_ibget.tex b/content/shmem_ibget.tex index 4deacf0fb..811f1e2d1 100644 --- a/content/shmem_ibget.tex +++ b/content/shmem_ibget.tex @@ -42,7 +42,8 @@ arrays.} \apiargument{IN}{nblocks}{Number of blocks to be copied from the \source{} array to the \dest{} array.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex index 2c9498546..695c05d98 100644 --- a/content/shmem_ibput.tex +++ b/content/shmem_ibput.tex @@ -42,7 +42,8 @@ arrays.} \apiargument{IN}{nblocks}{Number of blocks to be copied from the \source{} array to the \dest{} array.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_iget.tex b/content/shmem_iget.tex index 858715719..369d057a2 100644 --- a/content/shmem_iget.tex +++ b/content/shmem_iget.tex @@ -40,7 +40,8 @@ indicates contiguous data.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_iput.tex b/content/shmem_iput.tex index 16006b00d..a937d54e2 100644 --- a/content/shmem_iput.tex +++ b/content/shmem_iput.tex @@ -39,7 +39,8 @@ scaled by the element size of the \source{} array. A value of \CONST{1} indicates contiguous data.} \apiargument{IN}{nelems}{Number of elements in the \dest{} and \source{} arrays.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} diff --git a/content/shmem_p.tex b/content/shmem_p.tex index 71e5594b8..9f94208a2 100644 --- a/content/shmem_p.tex +++ b/content/shmem_p.tex @@ -24,7 +24,8 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{value}{The value to be transferred to \VAR{dest}. The type of \VAR{value} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{pe}{The number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put.tex b/content/shmem_put.tex index f71355a86..ce5c3c22a 100644 --- a/content/shmem_put.tex +++ b/content/shmem_put.tex @@ -38,7 +38,8 @@ The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} arrays. For \FUNC{shmem\_putmem} and \FUNC{shmem\_ctx\_putmem}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_nbi.tex b/content/shmem_put_nbi.tex index 0c42d7c8a..0f7c385d6 100644 --- a/content/shmem_put_nbi.tex +++ b/content/shmem_put_nbi.tex @@ -39,7 +39,8 @@ \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} arrays. For \FUNC{shmem\_putmem\_nbi} and \FUNC{shmem\_ctx\_putmem\_nbi}, elements are bytes.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_signal.tex b/content/shmem_put_signal.tex index 7fd33a8e9..799129345 100644 --- a/content/shmem_put_signal.tex +++ b/content/shmem_put_signal.tex @@ -48,7 +48,8 @@ remote \VAR{sig\_addr} signal data object.} \apiargument{IN}{sig\_op}{Signal operator that represents the type of update to be performed on the remote \VAR{sig\_addr} signal data object.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_put_signal_nbi.tex b/content/shmem_put_signal_nbi.tex index 3cbf36250..611d301ec 100644 --- a/content/shmem_put_signal_nbi.tex +++ b/content/shmem_put_signal_nbi.tex @@ -48,7 +48,8 @@ remote \VAR{sig\_addr} signal data object.} \apiargument{IN}{sig\_op}{Signal operator that represents the type of update to be performed on the remote \VAR{sig\_addr} signal data object.} - \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_signal_add.tex b/content/shmem_signal_add.tex index 362fbeef8..a7bb2aa38 100644 --- a/content/shmem_signal_add.tex +++ b/content/shmem_signal_add.tex @@ -27,9 +27,8 @@ Unsigned 64-bit value that is used for updating the remote \VAR{sig\_addr} signal data object. } - \apiargument{IN}{pe}{ - \ac{PE} number of the remote \ac{PE}. - } + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ diff --git a/content/shmem_signal_set.tex b/content/shmem_signal_set.tex index d0eefbfd8..b463917a3 100644 --- a/content/shmem_signal_set.tex +++ b/content/shmem_signal_set.tex @@ -27,9 +27,8 @@ Unsigned 64-bit value that is used for updating the remote \VAR{sig\_addr} signal data object. } - \apiargument{IN}{pe}{ - \ac{PE} number of the remote \ac{PE}. - } + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE} relative to the team associated + with the given \VAR{ctx} when provided, or the default context otherwise.} \end{apiarguments} \apidescription{ From fe631aea72384e98166033372ca2f2f2b501e57f Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Fri, 30 Aug 2024 07:34:53 -0400 Subject: [PATCH 4/7] different -> remote PE --- content/shmem_get.tex | 2 +- content/shmem_get_nbi.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/shmem_get.tex b/content/shmem_get.tex index 2536421b1..b34f84cf6 100644 --- a/content/shmem_get.tex +++ b/content/shmem_get.tex @@ -43,7 +43,7 @@ \apidescription{ The get routines provide a method for copying a contiguous symmetric data - object from a different \ac{PE} to a contiguous data object on the local + object from a remote \ac{PE} to a contiguous data object on the local \ac{PE}. The routines return after the data has been delivered to the \dest{} array on the local \ac{PE}. } diff --git a/content/shmem_get_nbi.tex b/content/shmem_get_nbi.tex index 61e8261f4..61bbb6987 100644 --- a/content/shmem_get_nbi.tex +++ b/content/shmem_get_nbi.tex @@ -45,7 +45,7 @@ \apidescription{ The get routines provide a method for copying a contiguous symmetric data - object from a different \ac{PE} to a contiguous data object on the local + object from a remote \ac{PE} to a contiguous data object on the local \ac{PE}. The routines return after initiating the operation. The operation is considered complete after a subsequent call to \FUNC{shmem\_quiet}. At the completion of \FUNC{shmem\_quiet}, the From 787391c8aefb9bc434df8d47d7955e16428a9680 Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Fri, 30 Aug 2024 07:35:51 -0400 Subject: [PATCH 5/7] Added 'with 'blocks of size bsize' to text --- content/shmem_ibput.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex index 695c05d98..55b2987d8 100644 --- a/content/shmem_ibput.tex +++ b/content/shmem_ibput.tex @@ -49,7 +49,7 @@ \apidescription{ The \FUNC{shmem\_ibput} routines provide a method for copying strided data - blocks (specified by \VAR{sst}) of an array from a \source{} array on the + blocks (of size \VAR{bsize}) with stride (specified by \VAR{sst}) of an array from a \source{} array on the local \ac{PE} to locations specified by stride \VAR{dst} on a \dest{} array on specified remote \ac{PE}. The routines return when the data has been copied out of the \VAR{source} array on the local \ac{PE} but not From cd6b99e2f1fb01a5ae6f1176596c71d3c1fe9cc1 Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Fri, 30 Aug 2024 07:36:28 -0400 Subject: [PATCH 6/7] Explain all the deprecated blocks since we added _atomics_ to AMO operations --- content/atomics_intro.tex | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/atomics_intro.tex b/content/atomics_intro.tex index 3a9ad5c6c..ed78ef510 100644 --- a/content/atomics_intro.tex +++ b/content/atomics_intro.tex @@ -123,3 +123,11 @@ \label{bitamotypes} \end{center} \end{table} + +Starting in \openshmem[1.4], all \ac{AMO} functions added "\_atomic\_" to the function name. There were no semantic of argument changes to the functions, simply a name change. + + + + + + From 03dfb155c06e2ac969267901f5172a9f7cd3352b Mon Sep 17 00:00:00 2001 From: Brian Smith Date: Fri, 30 Aug 2024 13:14:49 -0400 Subject: [PATCH 7/7] Tweaked deprecated atomics text per conversation with Jim. Now it's in a deprecated block for easy future removal --- content/atomics_intro.tex | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/content/atomics_intro.tex b/content/atomics_intro.tex index ed78ef510..71f2ec5e7 100644 --- a/content/atomics_intro.tex +++ b/content/atomics_intro.tex @@ -29,6 +29,13 @@ The non-fetching routines include: \FUNC{shmem\_atomic\_\{set, inc, add, and, or, xor\}[\_nbi]}. +\begin{DeprecateBlock} + +Starting in \openshmem[1.4], all \ac{AMO} functions added "\_atomic\_" to the function +name and deprecated the equivalent functions without "\_atomic\_" in the name. + +\end{DeprecateBlock} + \end{itemize} \openshmem \ac{AMO} routines specified in this section have two variants. In @@ -123,8 +130,7 @@ \label{bitamotypes} \end{center} \end{table} - -Starting in \openshmem[1.4], all \ac{AMO} functions added "\_atomic\_" to the function name. There were no semantic of argument changes to the functions, simply a name change. +]