diff --git a/.gitignore b/.gitignore index 721f3a3f6..a4d74c687 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,11 @@ main_spec.log main_spec.out main_spec.pdf main_spec.toc +language_ext.aux +language_ext.idx +language_ext.ilg +language_ext.ind +language_ext.log +language_ext.out +language_ext.pdf +language_ext.toc diff --git a/Makefile b/Makefile index 0a48e04d4..d5fb43500 100644 --- a/Makefile +++ b/Makefile @@ -1,10 +1,18 @@ TARGET = main_spec +LANG_EXT = language_ext SOURCES = $(shell find . -name '*.tex' -print) FIGURES = $(shell find figures -name '*.pdf' -print) EXAMPLES = $(shell find example_code -name '*.[c,f]*' -print) .PHONY: all -all: ${TARGET}.pdf +all: ${TARGET}.pdf ${LANG_EXT}.pdf + +${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES} + pdflatex $(LATEXOPT) ${TARGET} + makeindex ${TARGET} + pdflatex $(LATEXOPT) ${TARGET} + makeindex ${TARGET} + pdflatex $(LATEXOPT) ${TARGET} ${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES} pdflatex $(LATEXOPT) ${TARGET} @@ -15,5 +23,7 @@ ${TARGET}.pdf: ${SOURCES} ${FIGURES} ${EXAMPLES} .PHONY: clean clean: - rm -f ${TARGET}.{log,aux,ps,dvi,bbl,blg,log,idx,out,toc,pdf,out} chappage.txt + rm -f ${TARGET}.{log,aux,ps,dvi,bbl,blg,log,idx,out,toc,pdf,out} \ + ${LANG_EXT}.{log,aux,ps,dvi,bbl,blg,log,idx,out,toc,pdf,out} \ + chappage.txt diff --git a/language/coverpage.tex b/language/coverpage.tex new file mode 100644 index 000000000..cf0517478 --- /dev/null +++ b/language/coverpage.tex @@ -0,0 +1,122 @@ +\thispagestyle{empty} +\begin{center} +\textbf{\LARGE Language Binding Extensions For}\\ +\par +\end{center} + +\begin{center} +\textbf{\Huge \openshmem} +\par +\end{center} + +\begin{center} +\textbf{\LARGE Application Programming Interface}\\ +\includegraphics[scale=0.65]{figures/OpenSHMEM_Pound}\\ +\url{http://www.openshmem.org/} +\par +\end{center} + +\begin{center} +Version \insertDocVersion +\par +\end{center} + +\vspace{0.5in} +\begin{center} +\today +\end{center} + +\vspace{0.5in} + +\vfill{} + +\section*{Development by} +\begin{itemize} +\item For a current list of contributors and collaborators please see\\ + \url{http://www.openshmem.org/site/Contributors/} +\item For a current list of OpenSHMEM implementations and tools, please see\\ + \url{http://openshmem.org/site/Links#impl/} + +\end{itemize} + +\pagebreak{} + +\section*{Sponsored by} +\begin{itemize} +\item \ac{DoD}\\ + \url{http://www.defense.gov/ } +\item \ac{ORNL}\\ + \url{http://www.ornl.gov/} +\item \ac{LANL}\\ + \url{http://www.lanl.gov/} +\end{itemize} + +\section*{Current Authors and Collaborators} +\begin{itemize} +\item Matthew Baker, \ac{ORNL} +\item Swen Boehm, \ac{ORNL} +\item Aurelien Bouteiller, \ac{UTK} +\item Barbara Chapman, \ac{SBU} +\item Robert Cernohous, Cray Inc. +\item James Culhane, \ac{LANL} +\item Tony Curtis, \ac{SBU} +\item James Dinan, Intel +\item Mike Dubman, Mellanox +\item Karl Feind, \ac{HPE} +\item Manjunath Gorentla Venkata, \ac{ORNL} +\item Max Grossman, Rice University +\item Khaled Hamidouche, \ac{AMD} +\item Jeff Hammond, Intel +\item Yossi Itigin, Mellanox +\item Bryant Lam, \ac{DoD} +\item David Knaak, Cray Inc. +\item Jeff Kuehn, \ac{LANL} +\item Jens Manser, \ac{DoD} +\item Tiffany M. Mintz, \ac{ORNL} +\item David Ozog, Intel +\item Nicholas Park, \ac{DoD} +\item Steve Poole, \ac{OSSS} +\item Wendy Poole, \ac{OSSS} +\item Swaroop Pophale, \ac{ORNL} +\item Sreeram Potluri, NVIDIA +\item Howard Pritchard, \ac{LANL} +\item Naveen Ravichandrasekaran, Cray Inc. +\item Michael Raymond, \ac{HPE} +\item James Ross, \ac{ARL} +\item Pavel Shamis, ARM Inc. +\item Sameer Shende, \ac{UO} +\item Lauren Smith, \ac{DoD} + +\end{itemize} + +\section*{Alumni Authors and Collaborators} +\begin{itemize} +\item Amrita Banerjee, \ac{UH} +\item Monika ten Bruggencate, Cray Inc. +\item Eduardo D'Azevedo, \ac{ORNL} +\item Oscar Hernandez, \ac{ORNL} +\item Gregory Koenig, \ac{ORNL} +\item Graham Lopez, \ac{ORNL} +\item Ricardo Mauricio, \ac{UH} +\item Ram Nanjegowda, \ac{UH} +\item Aaron Welch, \ac{ORNL} + +\end{itemize} + +\date{\today} + +\section*{Acknowledgments} +The \openshmem specification belongs to Open Source Software Solutions, Inc. +(OSSS), a non-profit organization, under an agreement with HPE. For a current list +of Contributors and Collaborators, please see + \url{http://www.openshmem.org/site/Contributors/}. +We gratefully acknowledge support from +Oak Ridge National Laboratory's +Extreme Scale Systems Center and the continuing support of the Department of Defense.\\ +\\ +We would also like to acknowledge the contribution of the members of the +\openshmem mailing list for their ideas, discussions, suggestions, and +constructive criticism which has helped us improve this document.\\ +\\ +\openshmem[1.4] is dedicated to the memory of David Charles Knaak. David was a highly involved +colleague and contributor to the entire OpenSHMEM project. He will be missed. diff --git a/language/frontmatter.tex b/language/frontmatter.tex new file mode 100644 index 000000000..a75ab7bed --- /dev/null +++ b/language/frontmatter.tex @@ -0,0 +1,36 @@ +\hypersetup{pageanchor=true,citecolor=blue} + +% Set header/footer for opening content +\pagestyle{fancy} +\fancyhead{} +\fancyhead[LE,LO]{\insertDocVersion} +\fancyhead[CO,CE]{--- DRAFT ---} +\SetWatermarkText{DRAFT} +\SetWatermarkScale{1} +\fancyfoot[CE,CO]{\thepage} %affects page numbering for the first pages, + %except the first ToC page + +\pagenumbering{roman} %sets coverpage and toc page numbers to roman numerals + +\input{language/coverpage} + +\setcounter{tocdepth}{4} +\setcounter{secnumdepth}{4} +\tableofcontents + +\mainmatter % included for use of documenttype 'book' + +% Set header/footer for main content +\pagestyle{fancy} %replacing {headings} with {fancy} for customization +\withlinenumbers %adds line numbers to edges of normal pages +\fancyhf{} +\fancyhead[RE, LO]{\rightmark} +\fancyhead[RO, LE]{\thepage} +\renewcommand{\headrulewidth}{0pt} +\renewcommand{\thesection}{\arabic{section}} + +{ %using setlength to force standardized spacing, if needed +% this command is ended in backmatter.tex +%\setlength{\baselineskip}{3pt plus 3pt minus 3pt} + +\setlength{\parskip}{3pt} diff --git a/language/ftn08/api.tex b/language/ftn08/api.tex new file mode 100644 index 000000000..af24e8fe7 --- /dev/null +++ b/language/ftn08/api.tex @@ -0,0 +1,365 @@ +As the \Fortran[bind(C)] language bindings are implemented over the \openshmem +\Cstd language bindings, there are no semantic or functional differences in the +\Fortran[bind(C)] language binding interfaces. The following sections tabulates +the argument and standard type definition for the \Fortran[bind(C)] language +bindings with the corresponding \Cstd language bindings for semantic reference. +Refer \openshmem specification for argument definition, API description, and +explanation on the return values. +\\ +\\ +\\ +\subsubsection{Library Setup, Exit, and Query Routines} +\label{subsubsec:ftn_setup} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +SUBROUTINE shmem\_init() + +\textit{Argument Mapping}: +None. + +\textit{Return}: +None. + & +void shmem\_init(void); +\tabularnewline \hline +%% +FUNCTION shmem\_my\_pe() + +\textit{Argument Mapping}: +None. + +\textit{Return}: +INTEGER(C\_INT) :: pe\_index +& +int shmem\_my\_pe(void); +\tabularnewline \hline +%% +FUNCTION shmem\_n\_pes() + +\textit{Argument Mapping}: +None. + +\textit{Return}: +INTEGER(C\_INT) :: num\_pes +& +int shmem\_n\_pes(void); +\tabularnewline \hline +%% +SUBROUTINE shmem\_finalize() + +\textit{Argument Mapping}: +None. + +\textit{Return}: +None. +& +void shmem\_finalize(void); +\tabularnewline \hline +%% +SUBROUTINE shmem\_global\_exit(status) + +\textit{Argument Mapping}: + +INTEGER(C\_INT), INTENT(IN) :: status + +\textit{Return}: +None. +& +void shmem\_global\_exit(int status); +\tabularnewline \hline +%% +\end{longtable} + +\subsubsection{Thread Support} +\label{subsubsec:ftn_thread} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +FUNCTION shmem\_init\_thread(requested, actual) + +\textit{Argument Mapping}: + +INTEGER(C\_INT), INTENT(IN) :: requested + +TYPE(INTEGER), INTENT(OUT) :: actual + +\textit{Return}: + +INTEGER(C\_INT) :: error\_code +& +int shmem\_init\_thread(int requested, + +int *actual); +\tabularnewline \hline +%% +SUBROUTINE shmem\_query\_thread(provided) + +\textit{Argument Mapping}: + +TYPE(INTEGER), INTENT(OUT) :: provided + +\textit{Return}: +None. +& +void shmem\_query\_thread(int *provided); +\tabularnewline \hline +%% +\end{longtable} + + +\subsubsection{Memory Management Routines} +\label{subsubsec:ftn_mem_manage} + +\subsubsection{Communication Management Routines} +\label{subsubsec:ftn_comm_manage} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +FUNCTION shmem\_ctx\_create(options, ctx) + +\textit{Argument Mapping}: + +INTEGER(C\_INT), INTENT(IN) :: options + +TYPE(shmem\_ctx\_t), INTENT(OUT) :: ctx + +\textit{Return}: + +INTEGER(C\_INT) :: error\_code +& +int shmem\_ctx\_create(long options, + +shmem\_ctx\_t *ctx); +\tabularnewline \hline +%% +SUBROUTINE shmem\_ctx\_destroy(ctx) + +\textit{Argument Mapping}: + +TYPE(shmem\_ctx\_t), INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_destroy(shmem\_ctx\_t ctx); +\tabularnewline \hline +%% +\end{longtable} + + +\subsubsection{Remote Memory Access Routines} +\label{subsubsec:ftn_rma} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +SUBROUTINE shmem\_putmem(dest, src, nbytes, pe, ctx) + +\textit{Argument Mapping}: + +TYPE(*),DIMENSION(*),INTENT(OUT) :: dest + +TYPE(*),DIMENSION(*),INTENT(IN) :: src + +INTEGER(C\_SIZE\_T), INTENT(IN) :: nbytes + +INTEGER(C\_INT), INTENT(IN) :: pe + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_putmem(shmem\_ctx\_t *ctx, void *dest, const void *src, size\_t nelems, int pe); +\tabularnewline \hline +%% +SUBROUTINE shmem\_getmem(dest, src, nbytes, pe, ctx) + +\textit{Argument Mapping}: + +TYPE(*),DIMENSION(*),INTENT(OUT) :: dest + +TYPE(*),DIMENSION(*),INTENT(IN) :: src + +INTEGER(C\_SIZE\_T), INTENT(IN) :: nbytes + +INTEGER(C\_INT), INTENT(IN) :: pe + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_getmem(shmem\_ctx\_t *ctx, void *dest, const void *src, size\_t nelems, int pe); +\tabularnewline \hline +%% +\end{longtable} + + +\subsubsection{Non-blocking Remote Memory Access Routines} +\label{subsubsec:ftn_rma_nbi} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +SUBROUTINE shmem\_putmem\_nbi(dest, src, nbytes, pe, ctx) + +\textit{Argument Mapping}: + +TYPE(*),DIMENSION(*),INTENT(OUT) :: dest + +TYPE(*),DIMENSION(*),INTENT(IN) :: src + +INTEGER(C\_SIZE\_T), INTENT(IN) :: nbytes + +INTEGER(C\_INT), INTENT(IN) :: pe + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_putmem\_nbi(shmem\_ctx\_t *ctx, void *dest, const void *src, size\_t nelems, int pe); +\tabularnewline \hline +%% +SUBROUTINE shmem\_getmem\_nbi(dest, src, nbytes, pe, ctx) + +\textit{Argument Mapping}: + +TYPE(*),DIMENSION(*),INTENT(OUT) :: dest + +TYPE(*),DIMENSION(*),INTENT(IN) :: src + +INTEGER(C\_SIZE\_T), INTENT(IN) :: nbytes + +INTEGER(C\_INT), INTENT(IN) :: pe + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_getmem\_nbi(shmem\_ctx\_t *ctx, void *dest, const void *src, size\_t nelems, int pe); +\tabularnewline \hline +%% +\end{longtable} + + +\subsubsection{Atomic Memory Operations} +\label{subsubsec:ftn_amo} + +\subsubsection{Collective Routines} +\label{subsubsec:ftn_coll} + +\subsubsection{Point-To-Point Synchronization Routines} +\label{subsubsec:ftn_ptp_sync} + +\subsubsection{Memory Ordering Routines} +\label{subsubsec:ftn_mem_order} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +SUBROUTINE shmem\_quiet(ctx) + +\textit{Argument Mapping}: + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_quiet(shmem\_ctx\_t *ctx); +\tabularnewline \hline +%% +SUBROUTINE shmem\_fence(ctx) + +\textit{Argument Mapping}: + +TYPE(shmem\_ctx\_t), OPTIONAL, INTENT(IN) :: ctx + +\textit{Return}: +None. +& +void shmem\_ctx\_fence(shmem\_ctx\_t *ctx); +\tabularnewline \hline +%% +\end{longtable} + +\subsubsection{Distributed Locking Routines} +\label{subsubsec:ftn_locks} + +\begin{longtable}{|p{0.58\textwidth}|p{0.40\textwidth}|} +\hline +\textbf{\Fortran[bind(C)] Language Binding Interface} & +\textbf{\Cstd Language Binding Interface} +\tabularnewline \hline +\endhead +%% +SUBROUTINE shmem\_clear\_lock(lock) + +\textit{Argument Mapping}: + +INTEGER(C\_LONG),INTENT(IN) :: lock + +\textit{Return}: +None. +& +void shmem\_clear\_lock(long *lock); +\tabularnewline \hline +%% +SUBROUTINE shmem\_set\_lock(lock) + +\textit{Argument Mapping}: + +INTEGER(C\_LONG),INTENT(IN) :: lock + +\textit{Return}: +None. +& +void shmem\_set\_lock(long *lock); +\tabularnewline \hline +%% +FUNCTION shmem\_test\_lock(lock) + +\textit{Argument Mapping}: + +INTEGER(C\_LONG),INTENT(IN) :: ctx + +\textit{Return}: + +INTEGER(C\_INT)::status +& +int shmem\_test\_lock(long *lock); +\tabularnewline \hline +%% +\end{longtable} + diff --git a/language/ftn08/compiling_pgms.tex b/language/ftn08/compiling_pgms.tex new file mode 100644 index 000000000..e69de29bb diff --git a/language/ftn08/overview.tex b/language/ftn08/overview.tex new file mode 100644 index 000000000..f30078eb5 --- /dev/null +++ b/language/ftn08/overview.tex @@ -0,0 +1,31 @@ +\openshmem \Fortran[bind(C)] language bindings is based on \Fortran-\Cstd +interoperability feature introduced in \Fortran[2018](ISO/IEC 1539-1:2018(E)) +language standard. \Fortran[2018] defines a standard way to generate procedure, +derived-type declarations and global variables which are interoperable with +\Cstd(ISO/IEC 9899:2011). The bind(C) attribute available in the \Fortran +language enables the interoperability with \Cstd. The \openshmem +\Fortran[bind(C)] language bindings use this standard way to generate \Fortran +wrappers over the primary \Cstd language bindings provided by \openshmem. + +\begin{itemize} + \item All the \openshmem APIs specified by the \openshmem \Fortran[bind(C)] + language bindings are implemented as a wrapper interface using \Fortran + bind(C) attribute over the \Cstd language bindings specified by \openshmem + specification. + \item All available language constants, library handles, and environment + variables from the \openshmem specification are supported by \openshmem + \Fortran[bind(C)] language bindings. + \item The \Fortran[bind(C)] language bindings is defined in a module named + \textit{shmem}. The \textit{shmem} module must contain only the interfaces + and constant names defined in this specification. + \item All \openshmem extension APIs that are not part of this specification + must be defined in a separate \textit{shmemx} module. The \textit{shmemx} + module must exist, even if no extensions are provided. Any extensions shall + use the \textit{shmemx\_} prefix for all routine, variable, and constant + names. + \item \openshmem APIs in this language bindings are available either as a + subroutine or a function. \openshmem \Cstd APIs which returns a value are + wrapped as functions, while those APIs that have some arguments and perform + a specific operation without returning any values are wrapped as + subroutines. +\end{itemize} diff --git a/language/ftn08/writing_pgms.tex b/language/ftn08/writing_pgms.tex new file mode 100644 index 000000000..e69de29bb diff --git a/language/lang_ext_overview.tex b/language/lang_ext_overview.tex new file mode 100644 index 000000000..c04c5c2c3 --- /dev/null +++ b/language/lang_ext_overview.tex @@ -0,0 +1,7 @@ +\openshmem provides ISO \Cstd bindings. \Cstd bindings are the primary language +bindings provided by \openshmem specification. Implementations can claim +conformance to the specification by just providing support for the primary \Cstd +bindings. In this document, other language bindings are introduced as extensions +to the \openshmem specification. Implementations can selectively provide support +for language bindings introduced in this document and may claim conformance only +with respect to those languages. diff --git a/language_ext.tex b/language_ext.tex new file mode 100644 index 000000000..e9d902f98 --- /dev/null +++ b/language_ext.tex @@ -0,0 +1,39 @@ +\documentclass[10pt]{book} + +\input{utils/packages} + +\input{utils/defs} + +\begin{document} + +\input{language/frontmatter} + + +\section{The OpenSHMEM Effort}\label{subsec:openshmem_effort} +\input{content/the_openshmem_effort} + +\section{Language Binding Extensions Overview}\label{subsec:lang_ext_overview} +\input{language/lang_ext_overview} + +\clearpage + +\chapter{Fortran Bind(C) Interface} + +\section{Overview}\label{subsec:ftn08_overview} +\input{language/ftn08/overview.tex} + +\section{OpenSHMEM Library API}\label{subsec:ftn08_api} +\input{language/ftn08/api.tex} + +\section{Writing OpenSHMEM Programs}\label{subsec:ftn08_writing} +\input{language/ftn08/writing_pgms.tex} + +\section{Compiling and Running OpenSHMEM Programs}\label{subsec:ftn08_compiling} +\input{language/ftn08/compiling_pgms.tex} + +\clearpage +\phantomsection +\addcontentsline{toc}{chapter}{Index} +\printindex + +\end{document}