ompi: add missing man pages

This commit adds man pages for the MPI_Win_allocate and MPI_Win_allocated_shared
MPI-3 functions. The man page for MPI_Win_create has also been updated to
indicate support for the same_size and same_disp_unit info keys

Signed-off-by: Nathan Hjelm <hjelmn@lanl.gov>

ompi/mpi/man/man3/MPI_Win_allocate.3in

@@ -0,0 +1,106 @@
+.\" -*- nroff -*-
+.\" Copyright 2015      Los Alamos National Security, LLC. All rights reserved.
+.\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
+.\" Copyright 2007-2008 Sun Microsystems, Inc.
+.\" Copyright (c) 1996 Thinking Machines Corporation
+.\" $COPYRIGHT$
+.TH MPI_Win_allocate 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
+.SH NAME
+\fBMPI_Win_allocate\fP \- One-sided MPI call that allocates memory and
+returns a window object for RMA operations.
+
+.SH SYNTAX
+.ft R
+.SH C Syntax
+.nf
+#include <mpi.h>
+int MPI_Win_allocate (MPI_Aint \fIsize\fP, int \fIdisp_unit\fP, MPI_Info \fIinfo\fP,
+                      MPI_Comm \fIcomm\fP, void *\fIbaseptr\fP, MPI_Win *\fIwin\fP)
+
+.fi
+.SH Fortran Syntax
+.nf
+INCLUDE 'mpif.h'
+MPI_WIN_ALLOCATE(\fSIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR\fP)
+	INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE, BASEPTR\fP
+	INTEGER \fIDISP_UNIT, INFO, COMM, WIN, IERROR\fP
+
+.fi
+.SH INPUT PARAMETERS
+.ft R
+.TP 1i
+size
+Size of window in bytes (nonnegative integer).
+.TP 1i
+disp_unit
+Local unit size for displacements, in bytes (positive integer).
+.TP 1i
+info
+Info argument (handle).
+.TP 1i
+comm
+Communicator (handle).
+
+.SH OUTPUT PARAMETERS
+.ft R
+.TP 1i
+baseptr
+Initial address of window.
+.TP 1i
+win
+Window object returned by the call (handle).
+.TP 1i
+IERROR
+Fortran only: Error status (integer).
+
+.SH DESCRIPTION
+.ft R
+\fBMPI_Win_allocate\fP is a collective call executed by all processes
+in the group of \fIcomm\fP. On each process, it allocates memory of at
+least \fIsize\fP bytes, returns a pointer to it, and returns a window
+object that can be used by all processes in \fIcomm\fP to perform RMA
+operations. The returned memory consists of \fIsize\fP bytes local to
+each process, starting at address \fIbaseptr\fP and is associated with
+the window as if the user called \fBMPI_Win_create\fP on existing
+memory. The \fIsize\fP argument may be different at each process and
+\fIsize\fP = 0 is valid; however, a library might allocate and expose
+more memory in order to create a fast, globally symmetric
+allocation. The discussion of and rationales for \fBMPI_Alloc_mem\fP and
+\fBMPI_Free_mem\fP in MPI-3.1 \[char167] 8.2 also apply to
+\fBMPI_Win_allocate\fP; in particular, see the rationale in MPI-3.1
+\[char167] 8.2 for an explanation of the type used for \fIbaseptr\fP.
+.sp
+The displacement unit argument is provided to facilitate address
+arithmetic in RMA operations: the target displacement argument of an
+RMA operation is scaled by the factor \fIdisp_unit\fP specified by the
+target process, at window creation.
+.sp
+For supported info keys see \fBMPI_Win_create\fI.
+.sp
+
+.SH NOTES
+Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C
+syntax) \fIsizeof(type)\fP, for a window that consists of an array of
+elements of type \fItype\fP. The later choice will allow one to use
+array indices in RMA calls, and have those scaled correctly to byte
+displacements, even in a heterogeneous environment.
+.sp
+
+.SH ERRORS
+Almost all MPI routines return an error value; C routines as the value of the function and Fortran routines in the last argument.
+.sp
+Before the error value is returned, the current MPI error handler is
+called. By default, this error handler aborts the MPI job, except for
+I/O function errors. The error handler may be changed with
+MPI_Comm_set_errhandler; the predefined error handler
+MPI_ERRORS_RETURN may be used to cause error values to be
+returned. Note that MPI does not guarantee that an MPI program can
+continue past an error.
+
+.SH SEE ALSO
+.ft R
+.sp
+MPI_Alloc_mem
+MPI_Free_mem
+MPI_Win_create
+MPI_Win_allocate_shared

ompi/mpi/man/man3/MPI_Win_allocate_shared.3in

@@ -0,0 +1,130 @@
+.\" -*- nroff -*-
+.\" Copyright 2015      Los Alamos National Security, LLC. All rights reserved.
+.\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
+.\" Copyright 2007-2008 Sun Microsystems, Inc.
+.\" Copyright (c) 1996 Thinking Machines Corporation
+.\" $COPYRIGHT$
+.TH MPI_Win_allocate_shared 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
+.SH NAME
+\fBMPI_Win_allocate_shared\fP \- One-sided MPI call that allocates
+shared memory and returns a window object for RMA operations.
+
+.SH SYNTAX
+.ft R
+.SH C Syntax
+.nf
+#include <mpi.h>
+int MPI_Win_allocate_shared (MPI_Aint \fIsize\fP, int \fIdisp_unit\fP, MPI_Info \fIinfo\fP,
+                             MPI_Comm \fIcomm\fP, void *\fIbaseptr\fP, MPI_Win *\fIwin\fP)
+
+.fi
+.SH Fortran Syntax
+.nf
+INCLUDE 'mpif.h'
+MPI_WIN_ALLOCATE_SHARED(\fSIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR\fP)
+	INTEGER(KIND=MPI_ADDRESS_KIND) \fISIZE, BASEPTR\fP
+	INTEGER \fIDISP_UNIT, INFO, COMM, WIN, IERROR\fP
+
+.fi
+.SH INPUT PARAMETERS
+.ft R
+.TP 1i
+size
+Size of window in bytes (nonnegative integer).
+.TP 1i
+disp_unit
+Local unit size for displacements, in bytes (positive integer).
+.TP 1i
+info
+Info argument (handle).
+.TP 1i
+comm
+Communicator (handle).
+
+.SH OUTPUT PARAMETERS
+.ft R
+.TP 1i
+baseptr
+Initial address of window.
+.TP 1i
+win
+Window object returned by the call (handle).
+.TP 1i
+IERROR
+Fortran only: Error status (integer).
+
+.SH DESCRIPTION
+.ft R
+\fBMPI_Win_allocate_shared\fP is a collective call executed by all
+processes in the group of \fIcomm\fP. On each process, it allocates
+memory of at least \fIsize\fP bytes that is shared among all processes
+in \fIcomm\fP, and returns a pointer to the locally allocated segment
+in \fIbaseptr\fP that can be used for load/store accesses on the
+calling process. The locally allocated memory can be the target of
+load/store accesses by remote processes; the base pointers for other
+processes can be queried using the function
+\fBMPI_Win_shared_query\fP. The call also returns a window object that
+can be used by all processes in \fIcomm\fP to perform RMA
+operations. The \fIsize\fP argument may be different at each process
+and \fIsize\fP = 0 is valid. It is the user's responsibility to ensure
+that the communicator \fIcomm\fP represents a group of processes that
+can create a shared memory segment that can be accessed by all
+processes in the group. The discussions of rationales for
+\fBMPI_Alloc_mem\fP and \fBMPI_Free_mem\fP in MPI-3.1 \[char167] 8.2
+also apply to \fBMPI_Win_allocate_shared\fP; in particular, see the
+rationale in MPI-3.1 \[char167] 8.2 for an explanation of the type
+used for \fIbaseptr\fP. The allocated memory is contiguous across
+process ranks unless the info key \fIalloc_shared_noncontig\fP is
+specified. Contiguous across process ranks means that the first
+address in the memory segment of process i is consecutive with the
+last address in the memory segment of process i - 1. This may enable
+the user to calculate remote address offsets with local information
+only.
+.sp
+The following info keys are supported:
+.ft R
+.TP 1i
+alloc_shared_noncontig
+If not set to \fItrue\fP, the allocation strategy is to allocate
+contiguous memory across process ranks. This may limit the performance
+on some architectures because it does not allow the implementation to
+modify the data layout (e.g., padding to reduce access latency).
+.sp
+.TP 1i
+blocking_fence
+If set to \fItrue\fP, the osc/sm component will use \fBMPI_Barrier\FP
+for \fBMPI_Win_fence\fP. If set to \fIfalse\fP a condition variable
+and counter will be used instead. The default value is
+\fIfalse\fP. This info key is Open MPI specific.
+.sp
+.TP 1i
+For additional supported info keys see \fBMPI_Win_create\fP.
+.sp
+
+.SH NOTES
+Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C
+syntax) \fIsizeof(type)\fP, for a window that consists of an array of
+elements of type \fItype\fP. The later choice will allow one to use
+array indices in RMA calls, and have those scaled correctly to byte
+displacements, even in a heterogeneous environment.
+.sp
+
+.SH ERRORS
+Almost all MPI routines return an error value; C routines as the value
+of the function and Fortran routines in the last argument.
+.sp
+Before the error value is returned, the current MPI error handler is
+called. By default, this error handler aborts the MPI job, except for
+I/O function errors. The error handler may be changed with
+MPI_Comm_set_errhandler; the predefined error handler
+MPI_ERRORS_RETURN may be used to cause error values to be
+returned. Note that MPI does not guarantee that an MPI program can
+continue past an error.
+
+.SH SEE ALSO
+.ft R
+.sp
+MPI_Alloc_mem
+MPI_Free_mem
+MPI_Win_allocate
+MPI_Win_create

ompi/mpi/man/man3/MPI_Win_create.3in

@@ -1,4 +1,6 @@
 .\" -*- nroff -*-
+.\" Copyright 2015      Los Alamos National Security, LLC. All rights
+.\" reserved.
 .\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
 .\" Copyright 2007-2008 Sun Microsystems, Inc.
 .\" Copyright (c) 1996 Thinking Machines Corporation
@@ -96,7 +98,18 @@ operation.  If set to \fIsame_op_no_op\fP, then the implementation will
 assume that all concurrent accumulate calls to the same target address
 will use the same operation or MPI_NO_OP.  The default is \fIsame_op_no_op\fP.
 .sp
-
+.TP 1i
+same_size
+If set to \fItrue\fP, then the implementation may assume that the argument
+\fIsize\fP is identical on all processes, and that all processes have
+provided this info key with the same value.
+.sp
+.TP 1i
+same_disp_unit
+If set to \fItrue\fP, then the implementation may assume that the argument
+\fIdisp_unit\fP is identical on all processes, and that all processes have
+provided this info key with the same value.
+.sp
 .SH NOTES
 Common choices for \fIdisp_unit\fP are 1 (no scaling), and (in C syntax) \fIsizeof(type)\fP, for a window that consists of an array of elements of type \fItype\fP. The later choice will allow one to use array indices in RMA calls, and have those scaled correctly to byte displacements, even in a heterogeneous environment.
 .sp
@@ -124,5 +137,10 @@ Almost all MPI routines return an error value; C routines as the value of the fu
 Before the error value is returned, the current MPI error handler is
 called. By default, this error handler aborts the MPI job, except for I/O function errors. The error handler may be changed with MPI_Comm_set_errhandler; the predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned. Note that MPI does not guarantee that an MPI program can continue past an error.
 
-
+.SH SEE ALSO
-
+.ft R
+.sp
+MPI_Alloc_mem
+MPI_Free_mem
+MPI_Win_allocate
+MPI_Win_allocate_shared

ompi/mpi/man/man3/MPI_Win_shared_query.3in

@@ -0,0 +1,87 @@
+.\" -*- nroff -*-
+.\" Copyright 2015      Los Alamos National Security, LLC. All rights reserved.
+.\" Copyright 2010 Cisco Systems, Inc.  All rights reserved.
+.\" Copyright 2007-2008 Sun Microsystems, Inc.
+.\" Copyright (c) 1996 Thinking Machines Corporation
+.\" $COPYRIGHT$
+.TH MPI_Win_shared_query 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
+.SH NAME
+\fBMPI_Win_shared_query\fP \- Query a shared memory window
+
+.SH SYNTAX
+.ft R
+.SH C Syntax
+.nf
+#include <mpi.h>
+int MPI_Win_shared_query (MPI_Win \fIwin\fP, int \fIrank\fP, MPI_Aint *\fIsize\fP,
+                          int *\fIdisp_unit\fP, void *\fIbaseptr\fP)
+
+.fi
+.SH Fortran Syntax
+.nf
+INCLUDE 'mpif.h'
+MPI_WIN_SHARED_QUERY(WIN, RANK, SIZE, DISP_UNIT, BASEPTR, IERROR)
+        INTEGER WIN, RANK, DISP_UNIT, IERROR
+        INTEGER (KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR
+
+.fi
+.SH INPUT PARAMETERS
+.ft R
+.TP 1i
+win
+Shared memory window object (handle).
+.TP 1i
+rank
+Rank in the group of window \fIwin\fP (non-negative integer)
+or MPI_PROC_NULL.
+
+.SH OUTPUT PARAMETERS
+.ft R
+.TP 1i
+size
+Size of the window segment (non-negative integer).
+.TP 1i
+disp_unit
+Local unit size for displacements, in bytes (positive integer).
+.TP 1i
+baseptr
+Address for load/store access to window segment
+(choice).
+.TP 1i
+IERROR
+Fortran only: Error status (integer).
+
+.SH DESCRIPTION
+.ft R
+\fBMPI_Win_shared_query\fP queries the process-local address for
+remote memory segments created with MPI_Win_allocate_shared. This
+function can return different process-local addresses for the same
+physical memory on different processes. The returned memory can be
+used for load/store accesses subject to the constraints defined in
+MPI-3.1 \[char167] 11.7. This function can only be called with windows
+of flavor MPI_WIN_FLAVOR_SHARED. If the passed window is not of flavor
+MPI_WIN_FLAVOR_SHARED, the error MPI_ERR_RMA_FLAVOR is raised. When
+rank is MPI_PROC_NULL, the \fIpointer\fP, \fIdisp_unit\fP, and
+\fIsize\fP returned are the pointer, disp_unit, and size of the memory
+segment belonging the lowest rank that specified \fIsize\fP > 0. If
+all processes in the group attached to the window specified \fIsize\fP
+= 0, then the call returns \fIsize\fP = 0 and a \fIbaseptr\fP as if
+\fBMPI_Alloc_mem\fP was called with \fIsize\fP = 0.
+
+.SH ERRORS
+Almost all MPI routines return an error value; C routines as the value
+of the function and Fortran routines in the last argument.
+.sp
+Before the error value is returned, the current MPI error handler is
+called. By default, this error handler aborts the MPI job, except for
+I/O function errors. The error handler may be changed with
+MPI_Comm_set_errhandler; the predefined error handler
+MPI_ERRORS_RETURN may be used to cause error values to be
+returned. Note that MPI does not guarantee that an MPI program can
+continue past an error.
+
+.SH SEE ALSO
+.ft R
+.sp
+MPI_Alloc_mem
+MPI_Win_allocate_shared

ompi/mpi/man/man3/Makefile.extra

@@ -383,6 +383,8 @@ mpi_api_man_pages = \
         mpi/man/man3/MPI_Waitall.3 \
         mpi/man/man3/MPI_Waitany.3 \
         mpi/man/man3/MPI_Waitsome.3 \
+        mpi/man/man3/MPI_Win_allocate.3 \
+        mpi/man/man3/MPI_Win_allocate_shared.3 \
         mpi/man/man3/MPI_Win_attach.3 \
         mpi/man/man3/MPI_Win_c2f.3 \
         mpi/man/man3/MPI_Win_call_errhandler.3 \
@@ -413,6 +415,7 @@ mpi_api_man_pages = \
         mpi/man/man3/MPI_Win_set_errhandler.3 \
         mpi/man/man3/MPI_Win_set_info.3 \
         mpi/man/man3/MPI_Win_set_name.3 \
+        mpi/man/man3/MPI_Win_shared_query.3 \
         mpi/man/man3/MPI_Win_start.3 \
         mpi/man/man3/MPI_Win_sync.3 \
         mpi/man/man3/MPI_Win_test.3 \