From cc976e7e05f66fcd3bea8ba063cde6853059ab2c Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Wed, 12 Oct 2022 16:01:50 -0400 Subject: [PATCH] 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 --- docs/features/extensions.rst | 2 + .../man3/MPIX_Query_cuda_support.3.rst | 53 ++++++++++++++----- .../man3/MPIX_Query_rocm_support.3.rst | 53 ++++++++++++++----- 3 files changed, 80 insertions(+), 28 deletions(-) diff --git a/docs/features/extensions.rst b/docs/features/extensions.rst index 93bad8c42f8..592d56e7687 100644 --- a/docs/features/extensions.rst +++ b/docs/features/extensions.rst @@ -1,3 +1,5 @@ +.. _ompi-features-extentions-label: + Open MPI extensions =================== diff --git a/docs/man-openmpi/man3/MPIX_Query_cuda_support.3.rst b/docs/man-openmpi/man3/MPIX_Query_cuda_support.3.rst index de3ab156cd8..a957660a01d 100644 --- a/docs/man-openmpi/man3/MPIX_Query_cuda_support.3.rst +++ b/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 +`; 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) ` or +:ref:`MPI_Init_thread(3) `. + +Including the Open MPI-specific file ```` 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 ```` 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 - #include "mpi.h" - - #include "mpi-ext.h" /* Needed for CUDA-aware check */ + #include + #include /* 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` diff --git a/docs/man-openmpi/man3/MPIX_Query_rocm_support.3.rst b/docs/man-openmpi/man3/MPIX_Query_rocm_support.3.rst index 80150620ca4..a8396504d8c 100644 --- a/docs/man-openmpi/man3/MPIX_Query_rocm_support.3.rst +++ b/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 +`; 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) ` or +:ref:`MPI_Init_thread(3) `. + +Including the Open MPI-specific file ```` 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 ```` 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 - #include "mpi.h" - - #include "mpi-ext.h" /* Needed for ROCm-aware check */ + #include + #include /* 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`