docs: Minor updates to MPIX man pages

Add some formulaic text to the MPIX man pages:

* Indicated that these functions are only present if the corresponding
  extenion was built
* Described the available preprocessor macros
* Added a link to the Open MPI Extensions section
* Fixed string errors in the example code
* Used proper #if conditionals in the example
* Added a See Also section

Signed-off-by: Jeff Squyres <[email protected]>

Author: jsquyres

docs/features/extensions.rst

@@ -1,3 +1,5 @@
+.. _ompi-features-extentions-label:
+
 Open MPI extensions
 ===================
 

docs/man-openmpi/man3/MPIX_Query_cuda_support.3.rst

@@ -6,7 +6,7 @@ MPIX_Query_cuda_support
 
 .. include_body
 
-**MPIX_Query_cuda_support** - Returns 1 if there is CUDA aware support
+**MPIX_Query_cuda_support** - Returns 1 if there is CUDA-aware support
 and 0 if there is not.
 
 
@@ -40,33 +40,58 @@ There is no C++ binding for this function.
 DESCRIPTION
 -----------
 
-This routine return 1 if MPI library is build with CUDA and runtime
-supports CUDA buffers. This routine must be called after MPI is
-initialized by a call to :ref:`MPI_Init` or :ref:`MPI_Init_thread`.
+This function is part of an :ref:`Open MPI extension
+<ompi-features-extentions-label>`; it is not part of standard MPI.
+
+This routine returns 1 if both the MPI library was built with the
+NVIDIA CUDA library and the runtime supports CUDA buffers.  Otherwise,
+it returns 0.  This routine must be called after MPI is initialized,
+e.g., by a call to :ref:`MPI_Init(3) <MPI_Init>` or
+:ref:`MPI_Init_thread(3) <MPI_Init_thread>`.
+
+Including the Open MPI-specific file ``<mpi-ext.h>`` will define the C
+preprocessor macro ``OMPI_HAVE_MPI_EXT`` to ``1``.  Otherwise, it will
+be undefined.  This macro can be used by applications as a sentinel to
+know whether ``<mpi-ext.h>`` has been included or not.
+
+The Open MPI CUDA extension is built by default (regardless of whether
+or not Open MPI was built with CUDA support), but *could* have been
+disabled by an administrative action.  It is therefore safest for
+applications to check that the preprocessor macro
+``OMPI_HAVE_MPI_EXT_CUDA`` is defined and is set to 1 to know whether
+the ``MPIX_Query_CUDA_support()`` function is available.  Checking for
+this macro also protects the use of this function when compiling the
+application with older versions of Open MPI or other MPI
+implementations that do not have this function.
 
 
 Examples
 ^^^^^^^^
 
-::
-
+.. code-block:: c
 
    #include <stdio.h>
-   #include "mpi.h"
-
-   #include "mpi-ext.h" /* Needed for CUDA-aware check */
+   #include <mpi.h>
+   #include <mpi-ext.h> /* Needed for CUDA-aware check */
 
    int main(int argc, char *argv[])
    {
-
        MPI_Init(&argc, &argv);
 
-       if (MPIX_Query_cuda_support()) {
-           printf("This MPI library has CUDA-aware support.);
+       bool happy = false;
+   #if defined(OMPI_HAVE_MPI_EXT_CUDA) && OMPI_HAVE_MPI_EXT_CUDA
+       happy = (bool) MPIX_Query_cuda_support();
+   #endif
+
+       if (happy) {
+           printf("This Open MPI installation has CUDA-aware support.\n");
        } else {
-           printf("This MPI library does not have CUDA-aware support.);
+           printf("This Open MPI installation does not have CUDA-aware support.\n");
        }
-       MPI_Finalize();
 
+       MPI_Finalize();
        return 0;
    }
+
+.. seealso::
+   :ref:`MPIX_Query_rocm_support`

docs/man-openmpi/man3/MPIX_Query_rocm_support.3.rst

@@ -6,7 +6,7 @@ MPIX_Query_rocm_support
 
 .. include_body
 
-**MPIX_Query_rocm_support** - Returns 1 if there is AMD ROCm aware support
+**MPIX_Query_rocm_support** - Returns 1 if there is AMD ROCm-aware support
 and 0 if there is not.
 
 
@@ -40,33 +40,58 @@ There is no C++ binding for this function.
 DESCRIPTION
 -----------
 
-This routine return 1 if MPI library is build with ROCm and runtime
-supports ROCm buffers. This routine must be called after MPI is
-initialized by a call to :ref:`MPI_Init` or :ref:`MPI_Init_thread`.
+This function is part of an :ref:`Open MPI extension
+<ompi-features-extentions-label>`; it is not part of standard MPI.
+
+This routine returns 1 if both the MPI library was built with the AMD
+ROCm library and the runtime supports ROCm buffers.  Otherwise, it
+returns 0.  This routine must be called after MPI is initialized,
+e.g., by a call to :ref:`MPI_Init(3) <MPI_Init>` or
+:ref:`MPI_Init_thread(3) <MPI_Init_thread>`.
+
+Including the Open MPI-specific file ``<mpi-ext.h>`` will define the C
+preprocessor macro ``OMPI_HAVE_MPI_EXT`` to ``1``.  Otherwise, it will
+be undefined.  This macro can be used by applications as a sentinel to
+know whether ``<mpi-ext.h>`` has been included or not.
+
+The Open MPI ROCm extension is built by default (regardless of whether
+or not Open MPI was built with ROCm support), but *could* have been
+disabled by an administrative action.  It is therefore safest for
+applications to check that the preprocessor macro
+``OMPI_HAVE_MPI_EXT_ROCM`` is defined and is set to 1 to know whether
+the ``MPIX_Query_rocm_support()`` function is available.  Checking for
+this macro also protects the use of this function when compiling the
+application with older versions of Open MPI or other MPI
+implementations that do not have this function.
 
 
 Examples
 ^^^^^^^^
 
-::
-
+.. code-block:: c
 
    #include <stdio.h>
-   #include "mpi.h"
-
-   #include "mpi-ext.h" /* Needed for ROCm-aware check */
+   #include <mpi.h>
+   #include <mpi-ext.h> /* Needed for ROCm-aware check */
 
    int main(int argc, char *argv[])
    {
-
        MPI_Init(&argc, &argv);
 
-       if (MPIX_Query_rocm_support()) {
-           printf("This MPI library has ROCm-aware support.);
+       bool happy = false;
+   #if defined(OMPI_HAVE_MPI_EXT_ROCM) && OMPI_HAVE_MPI_EXT_ROCM
+       happy = (bool) MPIX_Query_rocm_support();
+   #endif
+
+       if (happy) {
+           printf("This Open MPI installation has ROCm-aware support.\n");
        } else {
-           printf("This MPI library does not have ROCm-aware support.);
+           printf("This Open MPI installation does not have ROCm-aware support.\n");
        }
-       MPI_Finalize();
 
+       MPI_Finalize();
        return 0;
    }
+
+.. seealso::
+   :ref:`MPIX_Query_cuda_support`