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,55 @@ 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.  If
+Open MPI was built with the CUDA extenion, this function is declared
+in ``mpi-ext.h``.
+
+Including the 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.
+
+If the Open MPI CUDA extension is available (and therefore the
+``MPIX_Query_cuda_support()`` function is available), the C
+preprocessor macro ``OMPI_HAVE_MPI_EXT_CUDA`` will be defined to
+``1`` in ``<mpi-ext.h>``.  Otherwise, it will be undefined.
+
+This routine return 1 if both the MPI library was built with 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>`.
 
 
 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,55 @@ 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.  If
+Open MPI was built with the ROCm extenion, this function is declared
+in ``<mpi-ext.h>``.
+
+Including the 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.
+
+If the Open MPI CUDA extension is available (and therefore the
+``MPIX_Query_rocm_support()`` function is available), the C
+preprocessor macro ``OMPI_HAVE_MPI_EXT_ROCM`` will be defined to
+``1`` in ``<mpi-ext.h>``.  Otherwise, it will be undefined.
+
+This routine return 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>`.
 
 
 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`