diff --git a/content/backmatter.tex b/content/backmatter.tex index f2b4b7904..e937c019e 100644 --- a/content/backmatter.tex +++ b/content/backmatter.tex @@ -164,9 +164,9 @@ \chapter{Undefined Behavior in OpenSHMEM}\label{sec:undefined} is undefined. \begin{longtable}{|>{\raggedright}p{0.3\textwidth}|>{\raggedright}p{0.6\textwidth}|} -\hline +\hline \textbf{Inappropriate Usage} & \textbf{Undefined Behavior}\tabularnewline -\hline +\hline \endhead Uninitialized library & If the \openshmem library is not initialized, calls to non-initializing \openshmem routines have undefined @@ -185,18 +185,18 @@ \chapter{Undefined Behavior in OpenSHMEM}\label{sec:undefined} situation in an implementation-defined way. For example, the library may report an error message saying that the \ac{PE} accessed is outside the range of accessible \acp{PE}, or may exit without a warning.\tabularnewline -\hline +\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. \tabularnewline -\hline +\hline Non-symmetric allocation of symmetric memory & The symmetric memory management routines are collectives. For example, all \acp{PE} in the program must call \FUNC{shmem\_malloc} with the same \VAR{size} argument. Program behavior after a mismatched \FUNC{shmem\_malloc} call is undefined.\tabularnewline -\hline +\hline Use of null pointers with non-zero \VAR{len} specified & In any \openshmem routine that takes a pointer and \VAR{len} describing the number of elements in that pointer, a null pointer may not be given unless the corresponding \VAR{len} is also @@ -209,7 +209,7 @@ \chapter{Undefined Behavior in OpenSHMEM}\label{sec:undefined} \item \VAR{len} is not 0, pointer is non-null: supported. \end{itemize} \tabularnewline -\hline +\hline \end{longtable} @@ -549,6 +549,15 @@ \subsection{\textit{Fortran} API}\label{subsec:deprecate-fortran} %% WARNING: Is \chapter{Changes to this Document}\label{sec:changelog} +\section{Version 1.5} +The following list describes the specific changes in \openshmem[1.4]: +\begin{itemize} +% +\item Added support for blocking put with signal functions. +\\ See Section \ref{subsec:shmem_put_signal}. +% +\end{itemize} + \section{Version 1.4} Major changes in \openshmem[1.4] include multithreading support, @@ -604,7 +613,7 @@ \section{Version 1.4} \FUNC{shmem\_global\_exit}. \\ See Section \ref{subsec:shmem_global_exit}. % -\item Clarified ordering semantics of memory ordering, point-to-point synchronization, and collective +\item Clarified ordering semantics of memory ordering, point-to-point synchronization, and collective synchronization routines. % \item Clarified deprecation overview and added deprecation rationale in Annex F. @@ -721,7 +730,7 @@ \section{Version 1.3} \FUNC{SHMEM\_SET}. \\See Sections \ref{subsec:shmem_atomic_fetch} and \ref{subsec:shmem_atomic_set} % -\item New alltoall data exchange operations, \FUNC{SHMEM\_ALLTOALL} +\item New alltoall data exchange operations, \FUNC{SHMEM\_ALLTOALL} and \FUNC{SHMEM\_ALLTOALLS}. \\See Sections \ref{subsec:shmem_alltoall} and \ref{subsec:shmem_alltoalls}. % @@ -779,7 +788,7 @@ \section{Version 1.2} \FUNC{shmem\_ptr}. \\See Section \ref{subsec:shmem_ptr}. % -\item New API to query the version and name information. +\item New API to query the version and name information. \\See Section \ref{subsec:shmem_info_get_version} and \ref{subsec:shmem_info_get_name}. % \item \openshmem library API normalization. All \Cstd symmetric memory management @@ -790,7 +799,7 @@ \section{Version 1.2} \\See Section \ref{subsec:shfree}. % \item Deprecation of \Fortran API routine \FUNC{SHMEM\_PUT}. -\\See Section \ref{subsec:shmem_put}. +\\See Section \ref{subsec:shmem_put}. % \item Clarification related to \FUNC{shmem\_wait}. \\See Section \ref{subsec:shmem_wait_until}. @@ -818,7 +827,7 @@ \section{Version 1.1} The following list describes the specific changes in \openshmem[1.1]: \begin{itemize} % -\item Clarifications of the completion semantics of memory synchronization +\item Clarifications of the completion semantics of memory synchronization interfaces. \\See Section \ref{subsec:memory_order}. % @@ -856,21 +865,21 @@ \section{Version 1.1} \\See Section \ref{subsec:library_constants} and \ref{subsec:shmem_wait_until}. % \item Added \ac{API} calls: \FUNC{shmem\_char\_p}, \FUNC{shmem\_char\_g}. -\\See Sections \ref{subsec:shmem_p} and \ref{subsec:shmem_g}. +\\See Sections \ref{subsec:shmem_p} and \ref{subsec:shmem_g}. % \item Removed \ac{API} calls: \FUNC{shmem\_char\_put}, \FUNC{shmem\_char\_get}. -\\See Sections \ref{subsec:shmem_put} and \ref{subsec:shmem_get}. +\\See Sections \ref{subsec:shmem_put} and \ref{subsec:shmem_get}. % \item The usage of \CTYPE{ptrdiff\_t}, \CTYPE{size\_t}, and \CTYPE{int} in the interface signature was made consistent with the description. \\See Sections \ref{subsec:coll}, \ref{subsec:shmem_iput}, and \ref{subsec:shmem_iget}. % \item Revised \FUNC{shmem\_barrier} example. -\\See Section \ref{subsec:shmem_barrier}. +\\See Section \ref{subsec:shmem_barrier}. % \item Clarification of the initial value of \VAR{pSync} work arrays for -\FUNC{shmem\_barrier}.\\ See Section \ref{subsec:shmem_barrier}. +\FUNC{shmem\_barrier}.\\ See Section \ref{subsec:shmem_barrier}. % \item Clarification of the expected behavior when multiple \FUNC{start\_pes} calls are encountered. @@ -891,26 +900,26 @@ \section{Version 1.1} \ref{subsec:shmem_atomic_fetch_add}. % \item Clarification of the expected behavior on program \OPR{exit}. -\\See Section \ref{subsec:execution_model}, Execution Model. +\\See Section \ref{subsec:execution_model}, Execution Model. % \item More detailed description for the progress of \openshmem operations provided. -\\See Section \ref{subsec:progress}. +\\See Section \ref{subsec:progress}. % \item Clarification of naming convention for non-standard interfaces and their inclusion in \HEADER{shmemx.h}. -\\See Section \ref{subsec:bindings}. +\\See Section \ref{subsec:bindings}. % \item Various fixes to \openshmem code examples across the Specification to -include appropriate header files. +include appropriate header files. % \item Removing requirement that implementations should detect size mismatch and return error information for \FUNC{shmalloc} and ensuring consistent language. -\\See Sections \ref{subsec:shfree} and Annex \ref{sec:undefined}. +\\See Sections \ref{subsec:shfree} and Annex \ref{sec:undefined}. % \item \Fortran programming fixes for examples.\\ See Sections -\ref{subsec:shmem_reductions} and \ref{subsec:shmem_wait_until}. +\ref{subsec:shmem_reductions} and \ref{subsec:shmem_wait_until}. % \item Clarifications of the reuse \VAR{pSync} and \VAR{pWork} across collectives. @@ -918,7 +927,7 @@ \section{Version 1.1} \ref{subsec:shmem_collect} and \ref{subsec:shmem_reductions}. % \item Name changes for UV and ICE for \ac{SGI} systems. -\\See Annex \ref{sec:openshmem_history}. +\\See Annex \ref{sec:openshmem_history}. % \end{itemize} diff --git a/content/p2p_sync_intro.tex b/content/p2p_sync_intro.tex index 8855716ab..11cf4474b 100644 --- a/content/p2p_sync_intro.tex +++ b/content/p2p_sync_intro.tex @@ -3,8 +3,9 @@ object. The point-to-point synchronization routines can be used to portably ensure that memory access operations observe remote updates in the order enforced by -the initiator \ac{PE} using the \FUNC{shmem\_fence} and \FUNC{shmem\_quiet} -routines. +the initiator \ac{PE} using the put-with-signal(refer +section~\ref{subsec:shmem_put_signal}, \FUNC{shmem\_fence} and +\FUNC{shmem\_quiet} routines. Where appropriate compiler support is available, \openshmem provides type-generic point-to-point synchronization interfaces via \Cstd[11] generic diff --git a/content/shmem_put_signal.tex b/content/shmem_put_signal.tex new file mode 100644 index 000000000..f4e6bb992 --- /dev/null +++ b/content/shmem_put_signal.tex @@ -0,0 +1,87 @@ +\apisummary{ + 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 setting a remote flag to signal completion. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_put\_signal}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_put\_signal}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, 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}\_put\_signal}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put\_signal}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, 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\_put\FuncParam{SIZE}\_signal}@(void *dest, const void *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}\_signal}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +\end{CsynopsisCol} +where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. + +\begin{CsynopsisCol} +void @\FuncDecl{shmem\_putmem\_signal}@(void *dest, const void *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_putmem\_signal}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *restrict sig_addr, uint64_t signal, int pe); +\end{CsynopsisCol} + +\begin{apiarguments} + \apiargument{IN}{ctx}{The context on which to perform the operation. + When this argument is not provided, the operation is performed on + \CONST{SHMEM\_CTX\_DEFAULT}.} + \apiargument{OUT}{dest}{Data object to be updated on the remote \ac{PE}. This + data object must be remotely accessible.} + \apiargument{IN}{source}{Data object containing the data to be copied.} + \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} + arrays. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd.} + \apiargument{OUT}{sig\_addr}{Data object to be updated on the remote + \ac{PE} as the signal. This signal data object must be + remotely accessible.} + \apiargument{IN}{signal}{Unsigned 64-bit value that is assigned to the + remote \VAR{sig\_addr} signal data object.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} +\end{apiarguments} + +\apidescription{ + The routines return after the data has been copied out of the \source{} + array on the local \ac{PE}. The delivery of \signal{} flag on the remote + \ac{PE} indicates the delivery of its corresponding \dest{} data words + into the data object on the remote \ac{PE}. +} + +\apireturnvalues{ + None. +} + +\apinotes{ + The \VAR{dest} and \VAR{sig\_addr} data objects must both be remotely + accessible. The \VAR{sig\_addr} and \VAR{dest} could be of different kinds, + for example, one could be a global/static \Cstd variable and the other could + be allocated on the symmetric heap. + + The restrict qualifier in \VAR{sig\_addr} expects the data object to be + distinct from \VAR{dest} and \VAR{source} data objects. + + The delivery of \signal{} flag on the remote \ac{PE} indicates only the + delivery of its corresponding \dest{} data words into the data object on + the remote \ac{PE}. Without a memory-ordering operation, there is no implied + ordering between the delivery of the signal word of a put-with-signal + routine and another data transfer. For example, the delivery of the signal + word in a sequence consisting of a put routine followed by a put-with-signal + routine does not imply delivery of the put routine's data. +} + +\begin{apiexamples} + +\apicexample + { The following example shows a simple ring-based broadcast operation using + \FUNC{shmem\_put\_signal}:} + {./example_code/shmem_put_signal_example.c} + {} +\end{apiexamples} + +\end{apidefinition} diff --git a/content/shmem_put_signal_nbi.tex b/content/shmem_put_signal_nbi.tex new file mode 100644 index 000000000..a82304db7 --- /dev/null +++ b/content/shmem_put_signal_nbi.tex @@ -0,0 +1,81 @@ +\color{Green} +\apisummary{ + The nonblocking 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 setting a remote flag to signal completion. +} + +\begin{apidefinition} + +\begin{C11synopsis} +void @\FuncDecl{shmem\_put\_signal\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_put\_signal\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, 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}\_put\_signal\_nbi}@(TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_\FuncParam{TYPENAME}\_put\_signal\_nbi}@(shmem_ctx_t ctx, TYPE *dest, const TYPE *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, 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\_put\FuncParam{SIZE}\_signal\_nbi}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_put\FuncParam{SIZE}\_signal\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +\end{CsynopsisCol} +where \SIZE{} is one of \CONST{8, 16, 32, 64, 128}. + +\begin{CsynopsisCol} +void @\FuncDecl{shmem\_putmem\_signal\_nbi}@(void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +void @\FuncDecl{shmem\_ctx\_putmem\_signal\_nbi}@(shmem_ctx_t ctx, void *dest, const void *source, size_t nelems, uint64_t *sig_addr, uint64_t signal, int pe); +\end{CsynopsisCol} + +\begin{apiarguments} + \apiargument{IN}{ctx}{The context on which to perform the operation. + When this argument is not provided, the operation is performed on + \CONST{SHMEM\_CTX\_DEFAULT}.} + \apiargument{OUT}{dest}{Data object to be updated on the remote \ac{PE}. This + data object must be remotely accessible.} + \apiargument{IN}{source}{Data object containing the data to be copied.} + \apiargument{IN}{nelems}{Number of elements in the \VAR{dest} and \VAR{source} + arrays. \VAR{nelems} must be of type \VAR{size\_t} for \Cstd.} + \apiargument{OUT}{sig\_addr}{Data object to be updated on the remote + \ac{PE} as the signal. This signal data object must be + remotely accessible.} + \apiargument{IN}{signal}{Unsigned 64-bit value that is assigned to the + remote \VAR{sig\_addr} signal data object.} + \apiargument{IN}{pe}{\ac{PE} number of the remote \ac{PE}.} +\end{apiarguments} + +\apidescription{ + The routines return after posting the operation. The operation is considered + complete after the subsequent call to \FUNC{shmem\_quiet}. At the completion + of \FUNC{shmem\_quiet}, the data has been copied out of the \source{} + array on the local \ac{PE} and delivered into the \dest{} array on the + destination \ac{PE}. The delivery of \signal{} flag on the remote + \ac{PE} indicates the delivery of its corresponding \dest{} data words + into the data object on the remote \ac{PE}. +} + +\apireturnvalues{ + None. +} + +\apinotes{ + The \VAR{dest} and \VAR{sig\_addr} data objects must both be remotely + accessible. The \VAR{sig\_addr} and \VAR{dest} could be of different kinds, + for example, one could be a global/static \Cstd variable and the other could + be allocated on the symmetric heap. + + The delivery of \signal{} flag on the remote \ac{PE} indicates only the + delivery of its corresponding \dest{} data words into the data object on + the remote \ac{PE}. Without a memory-ordering operation, there is no implied + ordering between the delivery of the signal word of a nonblocking + put-with-signal routine and another data transfer. For example, the delivery + of the signal word in a sequence consisting of a put routine followed by a + nonblocking put-with-signal routine does not imply delivery of the put + routine's data. +} + +\end{apidefinition} +\color{Black} diff --git a/example_code/shmem_put_signal_example.c b/example_code/shmem_put_signal_example.c new file mode 100644 index 000000000..cd10da1f9 --- /dev/null +++ b/example_code/shmem_put_signal_example.c @@ -0,0 +1,42 @@ +#include +#include +#include + +int main(void) +{ + int i, err_count = 0; + + shmem_init(); + + size_t size = (2<<10); + int me = shmem_my_pe(); + int n = shmem_n_pes(); + int pe = (me + 1)%n; + uint64_t* message = malloc(size * sizeof(uint64_t)); + uint64_t* data = shmem_malloc(size * sizeof(uint64_t)); + static uint64_t sig_addr = 0; + + for (i = 0; i < size; i++) { + message[i] = me; + data[i] = 0; + } + shmem_barrier_all(); + + if (me != 0) { + shmem_uint64_wait_until(&sig_addr, SHMEM_CMP_EQ, 1); + } + + shmem_putmem_signal(data, message, size*sizeof(uint64_t), + &sig_addr, 1, pe); + + if (me == 0) { + shmem_uint64_wait_until(&sig_addr, SHMEM_CMP_EQ, 1); + printf("BCAST with put with signal is complete\n"); + } + + free(message); + shmem_free(data); + + shmem_finalize(); + return 0; +} diff --git a/main_spec.tex b/main_spec.tex index 6c2c46596..00ab44f32 100644 --- a/main_spec.tex +++ b/main_spec.tex @@ -156,6 +156,9 @@ \subsubsection{\textbf{SHMEM\_P}}\label{subsec:shmem_p} \subsubsection{\textbf{SHMEM\_IPUT}}\label{subsec:shmem_iput} \input{content/shmem_iput.tex} +\subsubsection{\textbf{SHMEM\_PUT\_SIGNAL}}\label{subsec:shmem_put_signal} +\input{content/shmem_put_signal.tex} + \subsubsection{\textbf{SHMEM\_GET}}\label{subsec:shmem_get} \input{content/shmem_get.tex} @@ -171,6 +174,9 @@ \subsection{Non-blocking Remote Memory Access Routines}\label{sec:rma_nbi} \subsubsection{\textbf{SHMEM\_PUT\_NBI}}\label{subsec:shmem_put_nbi} \input{content/shmem_put_nbi.tex} +\subsubsection{\textbf{SHMEM\_PUT\_SIGNAL\_NBI}}\label{subsec:shmem_put_signal_nbi} +\input{content/shmem_put_signal_nbi.tex} + \subsubsection{\textbf{SHMEM\_GET\_NBI}}\label{subsec:shmem_get_nbi} \input{content/shmem_get_nbi.tex} diff --git a/utils/defs.tex b/utils/defs.tex index 75c75bc85..915d26424 100644 --- a/utils/defs.tex +++ b/utils/defs.tex @@ -7,8 +7,8 @@ \hyphenation{Open-SHMEM} -\renewcommand{\chaptername}{Chapter} -\renewcommand{\appendixname}{Annex} +\renewcommand{\chaptername}{Chapter} +\renewcommand{\appendixname}{Annex} % Place some penalty for doing the break % The penalty for a ``\gb'' should be greater than a \hyphenpenalty. @@ -17,15 +17,15 @@ \penalty10000} % This macro enables that all "_" (underscore) characters in the pfd -% file are searchable, and that cut&paste will copy the "_" as underscore. +% file are searchable, and that cut&paste will copy the "_" as underscore. % Without the following macro, the \_ is treated in searches and cut&paste -% as a " " (space character). -% This macro does not modify the behavior of _ in math or in verbatim +% as a " " (space character). +% This macro does not modify the behavior of _ in math or in verbatim % environments. In verbatim environments, the "_" is always treated % as a searchable character. % -\DeclareRobustCommand{\_}{\texttt{\char`\_}} -% +\DeclareRobustCommand{\_}{\texttt{\char`\_}} +% \def\colorswapnt{\colorlet{saved}{.}\color{ForestGreen}} \def\colorswapot{\colorlet{saved}{.}\color{red}} @@ -57,6 +57,7 @@ \newcommand{\source}{\textit{source}} \newcommand{\dest}{\textit{dest}} +\newcommand{\signal}{\textit{signal}} \newcommand{\PUT}{\textit{Put}} \newcommand{\GET}{\textit{Get}} \newcommand{\OPR}[1]{\textit{#1}} @@ -184,11 +185,11 @@ % % \makeatletter -\def\section{\@startsection {section}{1}{\z@}{-3.5ex plus -1ex minus +\def\section{\@startsection {section}{1}{\z@}{-3.5ex plus -1ex minus -.2ex}{2.3ex plus .2ex}{\Large\sf}} -\def\subsection{\@startsection{subsection}{2}{\z@}{-3.25ex plus -1ex minus +\def\subsection{\@startsection{subsection}{2}{\z@}{-3.25ex plus -1ex minus -.2ex}{1.5ex plus .2ex}{\large\sf}} -\def\subsubsection{\@startsection{subsubsection}{3}{\z@}{-3.25ex plus +\def\subsubsection{\@startsection{subsubsection}{3}{\z@}{-3.25ex plus -1ex minus -.2ex}{1.5ex plus .2ex}{\normalsize\sf\bf}} \def\paragraph{\@startsection {paragraph}{4}{\z@}{3.25ex plus 1ex minus .2ex} {-1em}{\normalsize\sf\bf}} % Indent after \paragraph @@ -207,12 +208,12 @@ breakatwhitespace=true, % sets if automatic breaks should only happen at whitespace basicstyle=\ttfamily\footnotesize, breaklines=true, % sets automatic line breaking - extendedchars=true, % lets you use non-ASCII characters; for 8-bits + extendedchars=true, % lets you use non-ASCII characters; for 8-bits % encodings only, does not work with UTF-8 - keepspaces=true, % keeps spaces in text, useful for keeping indentation of code + keepspaces=true, % keeps spaces in text, useful for keeping indentation of code % (possibly needs columns=flexible) morekeywords={*,...}, % if you want to add more keywords to the set - showspaces=false, % show spaces everywhere adding particular underscores; + showspaces=false, % show spaces everywhere adding particular underscores; % it overrides 'showstringspaces' showstringspaces=false, % underline spaces within strings only showtabs=false, % show tabs within strings adding particular underscores @@ -224,16 +225,16 @@ basicstyle=\ttfamily\footnotesize, breaklines=true, % sets automatic line breaking escapeinside={\%*}{*)}, % if you want to add LaTeX within your code - extendedchars=true, % lets you use non-ASCII characters; for 8-bits + extendedchars=true, % lets you use non-ASCII characters; for 8-bits % encodings only, does not work with UTF-8 keepspaces=true, % keeps spaces in text, useful for keeping % indentation of code (possibly needs columns=flexible) morekeywords={*,...}, % if you want to add more keywords to the set - showspaces=false, % show spaces everywhere adding particular underscores; + showspaces=false, % show spaces everywhere adding particular underscores; % it overrides 'showstringspaces' showstringspaces=false, % underline spaces within strings only showtabs=false, % show tabs within strings adding particular underscores - backgroundcolor=\color{gray}, + backgroundcolor=\color{gray}, } } @@ -386,7 +387,7 @@ \newenvironment{apidefinition}{ \begin{description} -\item[SYNOPSIS] \hfill \\ \\ +\item[SYNOPSIS] \hfill \\ \\ \vspace{-2em} } { @@ -402,33 +403,36 @@ aboveskip=0pt, belowskip=0pt}}{} \lstnewenvironment{C11synopsis} -{ - \textbf{C11:} +{ + \textbf{C11:} \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt, escapechar=@, - morekeywords={size_t, ptrdiff_t, TYPE, _Noreturn, shmem_ctx_t}, + morekeywords={size_t, ptrdiff_t, TYPE, _Noreturn, shmem_ctx_t, + uint64_t, restrict}, aboveskip=0pt, belowskip=0pt}}{} \lstnewenvironment{CsynopsisCol} -{ +{ \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt, escapechar=@, - morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t}, + morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t, + uint64_t, restrict}, aboveskip=0pt, belowskip=0pt}}{} \lstnewenvironment{Csynopsis} -{ - \textbf{C/C++:} +{ + \textbf{C/C++:} \lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt, escapechar=@, - morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t}, + morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t, + uint64_t, restrict}, aboveskip=0pt, belowskip=0pt}}{} \lstnewenvironment{CsynopsisST} -{ - \textbf{C/C++:} - \color{red} +{ + \textbf{C/C++:} + \color{red} {\lstset{language={C}, backgroundcolor=\color{gray}, lineskip=2pt, escapechar=@, morekeywords={size_t, ptrdiff_t, TYPE, TYPENAME, SIZE, shmem_ctx_t}, @@ -447,11 +451,11 @@ \newenvironment{apiarguments}{ \newcommand{\apiargument}[3]{ \begin{tabular}{p{2cm} p{2cm} p{10cm}} -\textbf{##1} & \textit{##2} & {##3} \\ +\textbf{##1} & \textit{##2} & {##3} \\ \end{tabular} } \hfill -\item[DESCRIPTION] \hfill +\item[DESCRIPTION] \hfill \begin{description} \item[Arguments] \hfill \\ @@ -464,7 +468,7 @@ \newcommand{\apidescription}[1]{ \begin{description} \vspace{-1em} -\item[API description] \hfill \\ +\item[API description] \hfill \\ \begin{sloppypar} #1 \end{sloppypar} @@ -478,10 +482,10 @@ \hline \tabularnewline \end{tabular}\\ #4 -} +} \newcommand{\apireturnvalues}[1]{ -\hfill +\hfill \item[Return Values] \hfill \\ #1 \\ @@ -514,7 +518,8 @@ ##1 \lstinputlisting[language={C}, tabsize=2, basicstyle=\ttfamily\footnotesize, - morekeywords={size_t, ptrdiff_t, shmem_ctx_t}]{##2} + morekeywords={size_t, ptrdiff_t, shmem_ctx_t, + uint64_t, restrict}]{##2} ##3 } \newcommand{\apifexample}[3]{ ##1