From 2d2f9a086cb23acffc0349387d19ee8d1f00a7a5 Mon Sep 17 00:00:00 2001 From: James Dinan Date: Thu, 23 Jul 2020 12:07:37 -0400 Subject: [PATCH 1/6] Minor improvements to shmem_iget/iput text Signed-off-by: James Dinan --- content/shmem_iget.tex | 16 +++++++++------- content/shmem_iput.tex | 22 +++++++++------------- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/content/shmem_iget.tex b/content/shmem_iget.tex index ef9165153..c36e798b7 100644 --- a/content/shmem_iget.tex +++ b/content/shmem_iget.tex @@ -1,5 +1,5 @@ \apisummary{ - Copies strided data from a specified \ac{PE}. + Copies strided data blocks from a specified \ac{PE}. } \begin{apidefinition} @@ -31,18 +31,20 @@ \apiargument{IN}{source}{Symmetric address of the source array data object. The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} - array. The stride is scaled by the element size of the \dest{} array. - A value of \CONST{1} indicates contiguous data.} - \apiargument{IN}{sst}{The stride between consecutive elements of the - \source{} array. The stride is scaled by the element size of the \source{} - array. A value of \CONST{1} indicates contiguous data.} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \dest{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} + array. The stride must be greater than or equal to \CONST{1} and is + 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}.} \end{apiarguments} \apidescription{ - The \FUNC{iget} routines provide a method for copying strided data elements from + The \FUNC{shmem\_iget} routines provide a method for copying strided data elements from a symmetric array from a specified remote \ac{PE} to strided locations on a local array. The routines return when the data has been copied into the local \VAR{dest} array. diff --git a/content/shmem_iput.tex b/content/shmem_iput.tex index 499e21d73..16006b00d 100644 --- a/content/shmem_iput.tex +++ b/content/shmem_iput.tex @@ -31,22 +31,23 @@ \apiargument{IN}{source}{Local address of the array containing the data to be copied. The type of \source{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} - array. The stride is scaled by the element size of the \dest{} array. A - value of \CONST{1} indicates contiguous data.} - \apiargument{IN}{sst}{The stride between consecutive elements of the - \source{} array. The stride is scaled by the element size of the \source{} - array. A value of \CONST{1} indicates contiguous data.} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \dest{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} + array. The stride must be greater than or equal to \CONST{1} and is + 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}.} \end{apiarguments} \apidescription{ - The \FUNC{iput} routines provide a method for copying strided data + The \FUNC{shmem\_iput} routines provide a method for copying strided data elements (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}. Both strides, \VAR{dst} and \VAR{sst}, must be - greater than or equal to \CONST{1}. The routines return when the data has + 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 necessarily before the data has been delivered to the remote data object. } @@ -55,11 +56,6 @@ None. } -\apinotes{ - See Section \ref{subsec:memory_model} for a definition of the term - remotely accessible. -} - \begin{apiexamples} \apicexample From 16bbfd76c48061c375d2e6fb09300a81a31d66d9 Mon Sep 17 00:00:00 2001 From: James Dinan Date: Thu, 23 Jul 2020 12:07:59 -0400 Subject: [PATCH 2/6] Add shmem_ibget/ibput routines Signed-off-by: James Dinan --- content/shmem_ibget.tex | 59 +++++++++++++++++++++++++++++++++++++++ content/shmem_ibput.tex | 62 +++++++++++++++++++++++++++++++++++++++++ main_spec.tex | 6 ++++ 3 files changed, 127 insertions(+) create mode 100644 content/shmem_ibget.tex create mode 100644 content/shmem_ibput.tex diff --git a/content/shmem_ibget.tex b/content/shmem_ibget.tex new file mode 100644 index 000000000..fd5afea80 --- /dev/null +++ b/content/shmem_ibget.tex @@ -0,0 +1,59 @@ +\apisummary{ + Copies blocks of strided data from a specified \ac{PE}. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_ibget}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ibget}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{C11synopsis} +where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. + +\begin{Csynopsis} +void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_ibget}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_ibget}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{Csynopsis} +where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. + +\begin{CsynopsisCol} +void @\FuncDecl{shmem\_ibget\FuncParam{SIZE}}@(void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ctx\_ibget\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{CsynopsisCol} +where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. + +\begin{apiarguments} + \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. + When this argument is not provided, the operation is performed on + the default context.} + \apiargument{OUT}{dest}{Local address of the array to be updated. + The type of \dest{} should match that implied in the SYNOPSIS section.} + \apiargument{IN}{source}{Symmetric address of the source array data object. + The type of \source{} should match that implied in the SYNOPSIS section.} + \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \dest{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \source{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{bsize}{Number of elements per block in the \dest{} and \source{} + arrays.} + \apiargument{IN}{nblocks}{Number of blocks in the \dest{} and \source{} + arrays.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} +\end{apiarguments} + +\apidescription{ + The \FUNC{shmem\_ibget} routines provide a method for copying strided data blocks from + a symmetric array from a specified remote \ac{PE} to strided locations on a + local array. The routines return when the data has been copied into the local + \VAR{dest} array. +} + +\apireturnvalues{ + None. +} + +\end{apidefinition} diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex new file mode 100644 index 000000000..35130787a --- /dev/null +++ b/content/shmem_ibput.tex @@ -0,0 +1,62 @@ +\apisummary{ + Copies strided data blocks to a specified \ac{PE}. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_ibput}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ibput}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{C11synopsis} +where \TYPE{} is one of the standard \ac{RMA} types specified by Table \ref{stdrmatypes}. + +\begin{Csynopsis} +void @\FuncDecl{shmem\_\FuncParam{TYPENAME}\_ibput}@(TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_ibput}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{Csynopsis} +where \TYPE{} is one of the standard \ac{RMA} types and has a corresponding \TYPENAME{} specified by Table \ref{stdrmatypes}. + +\begin{CsynopsisCol} +void @\FuncDecl{shmem\_ibput\FuncParam{SIZE}}@(void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +void @\FuncDecl{shmem\_ctx\_ibput\FuncParam{SIZE}}@(shmem_ctx_t ctx, void *dest, const void *source, ptrdiff_t dst, ptrdiff_t sst, size_t bsize, size_t nblocks, int pe); +\end{CsynopsisCol} +where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. + +\begin{apiarguments} + \apiargument{IN}{ctx}{A context handle specifying the context on which to perform the operation. + When this argument is not provided, the operation is performed on + the default context.} + \apiargument{OUT}{dest}{Symmetric address of the destination array data object. + The type of \dest{} should match that implied in the SYNOPSIS section.} + \apiargument{IN}{source}{Local address of the array containing the data to be copied. + The type of \source{} should match that implied in the SYNOPSIS section.} + \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \dest{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} + array. The stride must be greater than or equal to \CONST{1} and is + scaled by the element size of the \source{} array. A value of \CONST{1} + indicates contiguous data.} + \apiargument{IN}{bsize}{Number of elements per block in the \dest{} and \source{} + arrays.} + \apiargument{IN}{nblocks}{Number of blocks in the \dest{} and \source{} + arrays.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} +\end{apiarguments} + + +\apidescription{ + The \FUNC{shmem\_ibput} routines provide a method for copying strided data + elements (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 + necessarily before the data has been delivered to the remote data object. +} + +\apireturnvalues{ + None. +} + +\end{apidefinition} diff --git a/main_spec.tex b/main_spec.tex index d9e914215..f1b68cbaa 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -171,6 +171,9 @@ \subsubsubsection{\textbf{SHMEM\_P}}\label{subsec:shmem_p} \subsubsubsection{\textbf{SHMEM\_IPUT}}\label{subsec:shmem_iput} \input{content/shmem_iput.tex} +\subsubsubsection{\textbf{SHMEM\_IBPUT}}\label{subsec:shmem_ibput} +\input{content/shmem_ibput.tex} + \subsubsubsection{\textbf{SHMEM\_GET}}\label{subsec:shmem_get} \input{content/shmem_get.tex} @@ -180,6 +183,9 @@ \subsubsubsection{\textbf{SHMEM\_G}}\label{subsec:shmem_g} \subsubsubsection{\textbf{SHMEM\_IGET}}\label{subsec:shmem_iget} \input{content/shmem_iget.tex} +\subsubsubsection{\textbf{SHMEM\_IBGET}}\label{subsec:shmem_ibget} +\input{content/shmem_ibget.tex} + \subsubsection{Nonblocking Remote Memory Access Routines}\label{subsec:rma_nbi} \subsubsubsection{\textbf{SHMEM\_PUT\_NBI}}\label{subsec:shmem_put_nbi} From 0d78753cb887cb8edcc5fa0412bbfcc7a8cd9b4a Mon Sep 17 00:00:00 2001 From: James Dinan Date: Mon, 14 Nov 2022 10:52:32 -0500 Subject: [PATCH 3/6] Update content/shmem_iget.tex --- content/shmem_iget.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shmem_iget.tex b/content/shmem_iget.tex index c36e798b7..858715719 100644 --- a/content/shmem_iget.tex +++ b/content/shmem_iget.tex @@ -1,5 +1,5 @@ \apisummary{ - Copies strided data blocks from a specified \ac{PE}. + Copies strided data from a specified \ac{PE}. } \begin{apidefinition} From 8017f57701c3e40c5e2d230115097819a790f267 Mon Sep 17 00:00:00 2001 From: James Dinan Date: Fri, 28 Jul 2023 15:01:57 -0400 Subject: [PATCH 4/6] Clarifications from July 28, 2023 reading --- content/shmem_ibget.tex | 16 ++++++++-------- content/shmem_ibput.tex | 18 +++++++++--------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/content/shmem_ibget.tex b/content/shmem_ibget.tex index fd5afea80..8f47f75cc 100644 --- a/content/shmem_ibget.tex +++ b/content/shmem_ibget.tex @@ -30,18 +30,18 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{source}{Symmetric address of the source array data object. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} - array. The stride must be greater than or equal to \CONST{1} and is - scaled by the element size of the \dest{} array. A value of \CONST{1} + \apiargument{IN}{dst}{The stride between consecutive blocks of the \dest{} + array. The stride must be greater than or equal to \VAR{bsize} and is + scaled by the element size of the \dest{} array. A value of \VAR{bsize} indicates contiguous data.} - \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} - array. The stride must be greater than or equal to \CONST{1} and is - scaled by the element size of the \source{} array. A value of \CONST{1} + \apiargument{IN}{sst}{The stride between consecutive blocks of the \source{} + array. The stride must be greater than or equal to \VAR{bsize} and is + scaled by the element size of the \source{} array. A value of \VAR{bsize} indicates contiguous data.} \apiargument{IN}{bsize}{Number of elements per block in the \dest{} and \source{} arrays.} - \apiargument{IN}{nblocks}{Number of blocks in the \dest{} and \source{} - 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}.} \end{apiarguments} diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex index 35130787a..e448d6c88 100644 --- a/content/shmem_ibput.tex +++ b/content/shmem_ibput.tex @@ -30,25 +30,25 @@ The type of \dest{} should match that implied in the SYNOPSIS section.} \apiargument{IN}{source}{Local address of the array containing the data to be copied. The type of \source{} should match that implied in the SYNOPSIS section.} - \apiargument{IN}{dst}{The stride between consecutive elements of the \dest{} - array. The stride must be greater than or equal to \CONST{1} and is - scaled by the element size of the \dest{} array. A value of \CONST{1} + \apiargument{IN}{dst}{The stride between consecutive blocks of the \dest{} + array. The stride must be greater than or equal to \VAR{bsize} and is + scaled by the element size of the \dest{} array. A value of \VAR{bsize} indicates contiguous data.} - \apiargument{IN}{sst}{The stride between consecutive elements of the \source{} - array. The stride must be greater than or equal to \CONST{1} and is - scaled by the element size of the \source{} array. A value of \CONST{1} + \apiargument{IN}{sst}{The stride between consecutive blocks of the \source{} + array. The stride must be greater than or equal to \VAR{bsize} and is + scaled by the element size of the \source{} array. A value of \VAR{bsize} indicates contiguous data.} \apiargument{IN}{bsize}{Number of elements per block in the \dest{} and \source{} arrays.} - \apiargument{IN}{nblocks}{Number of blocks in the \dest{} and \source{} - 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}.} \end{apiarguments} \apidescription{ The \FUNC{shmem\_ibput} routines provide a method for copying strided data - elements (specified by \VAR{sst}) of an array from a \source{} array on the + blocks (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 5714500b808c27058c5dd93066aa0460711d3055 Mon Sep 17 00:00:00 2001 From: James Dinan Date: Fri, 8 Sep 2023 17:31:22 -0400 Subject: [PATCH 5/6] Add ibput and ibget API notes Signed-off-by: James Dinan --- content/shmem_ibget.tex | 6 ++++++ content/shmem_ibput.tex | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/content/shmem_ibget.tex b/content/shmem_ibget.tex index 8f47f75cc..4deacf0fb 100644 --- a/content/shmem_ibget.tex +++ b/content/shmem_ibget.tex @@ -56,4 +56,10 @@ None. } +\apinotes{ + The \FUNC{shmem\_ibget} API provides a more general purpose interleaved + transfer API than \FUNC{shmem\_iget}. Calling \FUNC{shmem\_ibget} with a + block size of 1 is equivalent to the \FUNC{shmem\_iget} API. +} + \end{apidefinition} diff --git a/content/shmem_ibput.tex b/content/shmem_ibput.tex index e448d6c88..2c9498546 100644 --- a/content/shmem_ibput.tex +++ b/content/shmem_ibput.tex @@ -59,4 +59,10 @@ None. } +\apinotes{ + The \FUNC{shmem\_ibput} API provides a more general purpose interleaved + transfer API than \FUNC{shmem\_iput}. Calling \FUNC{shmem\_ibput} with a + block size of 1 is equivalent to the \FUNC{shmem\_iput} API. +} + \end{apidefinition} From a1784a9f6267c1f3e82423fa0be65e497cf8c7de Mon Sep 17 00:00:00 2001 From: James Dinan Date: Fri, 8 Sep 2023 17:39:43 -0400 Subject: [PATCH 6/6] Add changelog entry Signed-off-by: James Dinan --- content/backmatter.tex | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/backmatter.tex b/content/backmatter.tex index 10191168b..1bba92bda 100644 --- a/content/backmatter.tex +++ b/content/backmatter.tex @@ -653,6 +653,17 @@ \subsection{Table~\ref{p2psynctypes}: point-to-point synchronization types} \chapter{Changes to this Document}\label{sec:changelog} +\section{Version 1.6} +Major changes in \openshmem[1.6] include \dots + +\begin{itemize} +% +\item Added interleaved block transfer APIs \FUNC{shmem\_ibget} and + \FUNC{shmem\_ibput}. +\ChangelogRef{subsec:shmem_ibput, subsec:shmem_ibget}% +% +\end{itemize} + \section{Version 1.5} Major changes in \openshmem[1.5] include the addition of new team-based collective functions, \OPR{put-with-signal} functions, nonblocking \ac{AMO}