Add documentation on C/Fortran binding code

Signed-off-by: Jake Tronge <jtronge@lanl.gov>

Author: jtronge

docs/developers/bindings.rst

@@ -0,0 +1,114 @@
+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``.
+
+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
+specific type constants that can be mapped directly to the expanded
+language-specific code, error-handling, and conversion code.
+
+C Bindings
+----------
+
+This will walk through adding (or converting) a plain-C binding into a
+templated version controlled by the script.
+
+As an example, for ``MPI_Send`` you might have a C file that looks something
+like this:
+
+.. code-block:: c
+
+    #include "ompi_config.h"
+    ...other includes...
+
+    int MPI_Send(const void *buf, int count, MPI_Datatype datatype, int dest,
+                 int tag, MPI_Comm comm)
+    {
+        ...internal checks...
+        return internal_mpi_send(buf, count, datatype, dest, tag, comm);
+    }
+
+To convert this to a template, you will have to first ensure that only a single
+function is defined in the file, removing or abstracting out static functions,
+and separating multiple definitions, such as ``MPI_Send`` and ``MPI_Isend``,
+into different files. The template should also not include any macro-processing
+that attempts to change the name of the function or parameter types; this code
+should be generated by the script, or abstracted into header files that can
+work easily with multiple functions.
+
+At this point, the template should look like the example above, with a "header"
+section, with simple includes or macros, maybe a static global, and the
+function defintion and nothing else.
+
+The next step is to convert the signature line into the prototype format that
+the script expects. For ``MPI_Send``, this should look something like this:
+
+.. code-block:: c
+
+    PROTOTYPE ERROR_CLASS send(BUFFER buf, COUNT count, DATATYPE type, RANK dest,
+                               TAG tag, COMM comm)
+
+Notice how the function name is changed, the ``MPI_`` prefix removed and the
+rest converted to lowercase, and also how each parameter is simplified into a
+``TYPE name`` format, where the ``TYPE`` conforms to an allowed list in
+``ompi/mpi/bindings/ompi_bindings/c_type.py``. For newer functions and types,
+you may have to extend the ``c_type.py`` file with a new class showing how to
+handle the type.
+
+The final step is to update ``Makefile.am``, adding the template name, in this
+case ``send.c.in``, to the ``prototype_sources`` variable, and the generated
+file name, ``generated_send.c``, to ``interface_profile_sources``. The
+generated file name must be of the form ``generated_${basename}.c``, where
+``${basename}`` is the name of the template file stripped of all extensions.
+
+Fortran Bindings
+----------------
+
+Adding a new Fortran binding may be as simple as adding an additional prototype
+to ``ompi/mpi/fortran/use-mpi-f08/interface.in``, as long as all the required
+types are already supported by the binding code. Below is an example prototype
+for ``MPI_Waitall``:
+
+.. code-block::
+
+    .waitall(SHORTCUT_COUNT count, REQUEST_ARRAY array_of_requests[count=count],
+             STATUS_ARRAY array_of_statuses[count=count])
+
+First, notice that the function name is listed with the ``MPI_`` prefix removed
+and in all lowercase along with a ``.`` before the name---this makes it easier
+to delimit prototypes across multiple lines. Parameters are listed in a
+simplified ``TYPE NAME`` form, with an optional ``[key=value;...]`` attribute
+coming after if required for the specific type. This key-value attribute is
+used to specify dependencies betwen parameters, where the key is validated by
+the type and the value must be the name of another parameter.
+
+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:
+
+* ``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;
+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``.
+
+If a new type needs to be added, then one will need to extend
+``fortran_type.py`` in ``ompi/mpi/bindings/ompi_bindings`` with an additional
+type class specifying how to handle the type in the above generated files,
+including any required key-value attributes for more complicated types. New
+types use a ``Type`` base class with functions that can be implemented by
+derived classes, each returning expanded Fortran or C code.

docs/developers/index.rst

@@ -22,3 +22,4 @@ probably don't need to read this section.
    gnu-autotools
    sphinx
    rst-for-markdown-expats.rst
+   bindings