Bigcount: Update docs and address other comments

Signed-off-by: Jake Tronge <[email protected]>

Author: jtronge

config/ompi_setup_mpi_fortran.m4

@@ -653,8 +653,6 @@ end type test_mpi_handle],
     AS_IF([test $OMPI_MIN_REQUIRED_FORTRAN_BINDINGS -gt $OMPI_BUILD_FORTRAN_BINDINGS],
           [AC_MSG_ERROR([Cannot build requested Fortran bindings, aborting])])
 
-    dnl AC_CONFIG_FILES([ompi/mpi/fortran/use-mpi-f08/bindings/mpi-f-interfaces-bind.h])
-
     # -------------------
     # mpif.h final setup
     # -------------------

docs/developers/bindings.rst

@@ -2,10 +2,10 @@ C and Fortran Bindings
 ======================
 
 The C and Fortran (mpi_f08) bindings are generated from Python code in
-``ompi/mpi/bindings``. The C code is generated based on a template file for
-each function, with a header and a body containing error-checking and
-conversion code; the mpi_f08 Fortran bindings are generated from a single
-file ``ompi/mpi/fortran/use-mpi-f08/interface.in``.
+``ompi/mpi/bindings``. Both the language bindings are generated from
+template files for each function. In the C case, each template file corresponds
+to a single generated C file, while in the Fortran case there are three major
+files generated for all functions.
 
 The Python code depends on special prototype lines used with both the C and
 Fortran bindings. These "prototypes" are designed to be easy to parse and use
@@ -69,66 +69,32 @@ generated file name must be of the form ``generated_${basename}.c``, where
 Fortran Bindings
 ----------------
 
-To add a new Fortran binding, or update an existing one, one will need to
-modify the ``ompi/mpi/fortran/use-mpi-f08/interface.json`` file; this JSON file
-contains a list of prototype objects, including information about their name
-and each parameter passed. Below is an example for ``MPI_Waitall``:
+Adding new Fortran bindings follows a similar process to the C version above.
+All new interfaces are actually based on a single C-template file following the
+same format as the C interface templates. However, the C file generated will
+use Fortran-specific arguments, including ``CFI_*`` arguments, when TS 29113 is
+enabled, ``MPI_Fint *`` arguments in other cases, and others specific to how
+the Fortran MPI types are defined. Most of these files perform Fortran-specific
+error handling, Fortran-to-C type conversion, and other necessary steps before
+calling the actually C bindings with the proper arguments.
 
-.. code-block::
-
-    {
-        "name": "waitall",
-        "parameters": [
-            {
-                "type": "SHORTCUT_COUNT",
-                "name": "count"
-            },
-            {
-                "type": "REQUEST_ARRAY",
-                "name": "array_of_requests",
-                "dep_params": {
-                    "count": "count"
-                }
-            },
-            {
-                "type": "STATUS_ARRAY",
-                "name": "array_of_statuses",
-                "dep_params": {
-                    "count": "count"
-                }
-            }
-        ]
-    }
-
-This object includes two properties: the ``name`` property holding the
-subroutine name, converted to lowercase and the ``mpi_`` prefix removed; and
-the ``parameters`` property describing all parameters, their types and
-dependencies. Some parameters may depend on other types and this is listed in
-the ``dep_params`` field. An example of this can be seen with
-``array_of_requests`` above, in which ``dep_params`` holds a key-value pair
-``"count": "count"``, where the key ``count`` corresponds to a key required by
-the ``REQUEST_ARRAY`` type and the value ``count`` to the name of another
-parameter. These parameter dependencies are specific to the types used and are
-validated by the binding scripts.
-
-The Fortran binding code not only generates Fortran, but also additional
-wrapping C code that calls into the C bindings, making conversions and checking
-for Fortran-specific error conditions as necessary. The following files will be
-generated by the script:
+These templates are used not only to generate a C backing file for the Fortran
+code, but also the Fortran interface definitions and the Fortran subroutines
+corresponding to the generated C file. These are output in three separate files:
 
 * ``ompi/mpi/fortran/use-mpi-f08/api_f08_generated.F90``
 * ``ompi/mpi/fortran/use-mpi-f08/base/api_f08_generated.c``
-* ``ompi/mpi/fortran/use-mpi-f08/base/api_f08_ts_generated.c``
 * ``ompi/mpi/fortran/use-mpi-f08/mod/mpi-f08-interfaces-generated.h``
 
 The Fortran file ``api_f08_generated.F90`` contains all the internal subroutine
-definitions, each of which makes a call into corresponding C functions. Two
-different C files are generated: ``api_f08_ts_generated.c`` contains support
-for compilers with TS 29113 support, allowing the use of ``CFI_cdesc_t`` types
-(see `Fortran 2018`_ for more details); and ``api_f08_generated.c`` for
-compilers without TS 29113 support. The internal subroutine names are mapped to
-the external interface, including multiple interfaces for the bigcount version
-of functions, in ``mpi-f08-interfaces-generated.h``.
+definitions, each of which makes a call into corresponding C functions. The
+internal subroutine names are mapped to the external interface, including
+multiple interfaces for the bigcount version of functions, in
+``mpi-f08-interfaces-generated.h``. The C file ``api_f08_generated.c``
+basically contains a concatenation of all fully expanded C templates.
+These files contain preprocessing directives to ensure they can support
+compilers with and without TS 29113 support, allowing use of
+``CFI_cdesc_t`` types when available (see `Fortran 2018`_ for more details).
 
 .. _Fortran 2018: https://fortranwiki.org/fortran/show/Fortran+2018
 

docs/developers/prerequisites.rst

@@ -47,6 +47,15 @@ build them manually, see the :ref:`how to build and install GNU
 Autotools section <developers-installing-autotools-label>` for much
 more detail.
 
+Python
+------
+
+Python >= v3.6 is required for generating the Fortran bindings, which
+is necessary if you build Open MPI from a Git clone.
+
+Python is also required for running Sphinx to generate the docs, too
+(:ref:`see below <developers-requirements-sphinx-label>`).
+
 Perl
 ----
 
@@ -88,6 +97,8 @@ MacPorts on MacOS), see `the Flex Github repository
 <https://github.com/westes/flex>`_.
 
 
+.. _developers-requirements-sphinx-label:
+
 Sphinx (and therefore Python)
 -----------------------------
 

ompi/mpi/fortran/use-mpi-f08/base/bigcount.h

@@ -1,3 +1,13 @@
+/*
+ * Copyright (c) 2024      Triad National Security, LLC. All rights
+ *                         reserved.
+ * $COPYRIGHT$
+ *
+ * Additional copyrights may follow
+ *
+ * $HEADER$
+ */
+
 /*
  * Bigcount array conversion macros for Fortran templates.
  */