|
| 1 | +C and Fortran Bindings |
| 2 | +====================== |
| 3 | + |
| 4 | +The C and Fortran (mpi_f08) bindings are generated from Python code in |
| 5 | +``ompi/mpi/bindings``. The C code is generated based on a template file for |
| 6 | +each function, with a header and a body containing error-checking and |
| 7 | +conversion code; the mpi_f08 Fortran bindings are generated from a single |
| 8 | +file ``ompi/mpi/fortran/use-mpi-f08/interface.in``. |
| 9 | + |
| 10 | +The Python code depends on special prototype lines used with both the C and |
| 11 | +Fortran bindings. These "prototypes" are designed to be easy to parse and use |
| 12 | +specific type constants that can be mapped directly to the expanded |
| 13 | +language-specific code, error-handling, and conversion code. |
| 14 | + |
| 15 | +C Bindings |
| 16 | +---------- |
| 17 | + |
| 18 | +This will walk through adding (or converting) a plain-C binding into a |
| 19 | +templated version controlled by the script. |
| 20 | + |
| 21 | +As an example, for ``MPI_Send`` you might have a C file that looks something |
| 22 | +like this: |
| 23 | + |
| 24 | +.. code-block:: c |
| 25 | +
|
| 26 | + #include "ompi_config.h" |
| 27 | + ...other includes... |
| 28 | +
|
| 29 | + int MPI_Send(const void *buf, int count, MPI_Datatype datatype, int dest, |
| 30 | + int tag, MPI_Comm comm) |
| 31 | + { |
| 32 | + ...internal checks... |
| 33 | + return internal_mpi_send(buf, count, datatype, dest, tag, comm); |
| 34 | + } |
| 35 | +
|
| 36 | +To convert this to a template, you will have to first ensure that only a single |
| 37 | +function is defined in the file, removing or abstracting out static functions, |
| 38 | +and separating multiple definitions, such as ``MPI_Send`` and ``MPI_Isend``, |
| 39 | +into different files. The template should also not include any macro-processing |
| 40 | +that attempts to change the name of the function or parameter types; this code |
| 41 | +should be generated by the script, or abstracted into header files that can |
| 42 | +work easily with multiple functions. |
| 43 | + |
| 44 | +At this point, the template should look like the example above, with a "header" |
| 45 | +section, with simple includes or macros, maybe a static global, and the |
| 46 | +function defintion and nothing else. |
| 47 | + |
| 48 | +The next step is to convert the signature line into the prototype format that |
| 49 | +the script expects. For ``MPI_Send``, this should look something like this: |
| 50 | + |
| 51 | +.. code-block:: c |
| 52 | +
|
| 53 | + PROTOTYPE ERROR_CLASS send(BUFFER buf, COUNT count, DATATYPE type, RANK dest, |
| 54 | + TAG tag, COMM comm) |
| 55 | +
|
| 56 | +Notice how the function name is changed, the ``MPI_`` prefix removed and the |
| 57 | +rest converted to lowercase, and also how each parameter is simplified into a |
| 58 | +``TYPE name`` format, where the ``TYPE`` conforms to an allowed list in |
| 59 | +``ompi/mpi/bindings/ompi_bindings/c_type.py``. For newer functions and types, |
| 60 | +you may have to extend the ``c_type.py`` file with a new class showing how to |
| 61 | +handle the type. |
| 62 | + |
| 63 | +The final step is to update ``Makefile.am``, adding the template name, in this |
| 64 | +case ``send.c.in``, to the ``prototype_sources`` variable, and the generated |
| 65 | +file name, ``generated_send.c``, to ``interface_profile_sources``. The |
| 66 | +generated file name must be of the form ``generated_${basename}.c``, where |
| 67 | +``${basename}`` is the name of the template file stripped of all extensions. |
| 68 | + |
| 69 | +Fortran Bindings |
| 70 | +---------------- |
| 71 | + |
| 72 | +To add a new Fortran binding, or update an existing one, one will need to |
| 73 | +modify the ``ompi/mpi/fortran/use-mpi-f08/interface.json`` file; this JSON file |
| 74 | +contains a list of prototype objects, including information about their name |
| 75 | +and each parameter passed. Below is an example for ``MPI_Waitall``: |
| 76 | + |
| 77 | +.. code-block:: |
| 78 | +
|
| 79 | + { |
| 80 | + "name": "waitall", |
| 81 | + "parameters": [ |
| 82 | + { |
| 83 | + "type": "SHORTCUT_COUNT", |
| 84 | + "name": "count" |
| 85 | + }, |
| 86 | + { |
| 87 | + "type": "REQUEST_ARRAY", |
| 88 | + "name": "array_of_requests", |
| 89 | + "dep_params": { |
| 90 | + "count": "count" |
| 91 | + } |
| 92 | + }, |
| 93 | + { |
| 94 | + "type": "STATUS_ARRAY", |
| 95 | + "name": "array_of_statuses", |
| 96 | + "dep_params": { |
| 97 | + "count": "count" |
| 98 | + } |
| 99 | + } |
| 100 | + ] |
| 101 | + } |
| 102 | +
|
| 103 | +This object includes two properties: the ``name`` property holding the |
| 104 | +subroutine name, converted to lowercase and the ``mpi_`` prefix removed; and |
| 105 | +the ``parameters`` property describing all parameters, their types and |
| 106 | +dependencies. Some parameters may depend on other types and this is listed in |
| 107 | +the ``dep_params`` field. An example of this can be seen with |
| 108 | +``array_of_requests`` above, in which ``dep_params`` holds a key-value pair |
| 109 | +``"count": "count"``, where the key ``count`` corresponds to a key required by |
| 110 | +the ``REQUEST_ARRAY`` type and the value ``count`` to the name of another |
| 111 | +parameter. These parameter dependencies are specific to the types used and are |
| 112 | +validated by the binding scripts. |
| 113 | + |
| 114 | +The Fortran binding code not only generates Fortran, but also additional |
| 115 | +wrapping C code that calls into the C bindings, making conversions and checking |
| 116 | +for Fortran-specific error conditions as necessary. The following files will be |
| 117 | +generated by the script: |
| 118 | + |
| 119 | +* ``ompi/mpi/fortran/use-mpi-f08/api_f08_generated.F90`` |
| 120 | +* ``ompi/mpi/fortran/use-mpi-f08/base/api_f08_generated.c`` |
| 121 | +* ``ompi/mpi/fortran/use-mpi-f08/base/api_f08_ts_generated.c`` |
| 122 | +* ``ompi/mpi/fortran/use-mpi-f08/mod/mpi-f08-interfaces-generated.h`` |
| 123 | + |
| 124 | +The Fortran file ``api_f08_generated.F90`` contains all the internal subroutine |
| 125 | +definitions, each of which makes a call into corresponding C functions. Two |
| 126 | +different C files are generated: ``api_f08_ts_generated.c`` contains support |
| 127 | +for compilers with TS 29113 support, allowing the use of ``CFI_cdesc_t`` types |
| 128 | +(see `Fortran 2018`_ for more details); and ``api_f08_generated.c`` for |
| 129 | +compilers without TS 29113 support. The internal subroutine names are mapped to |
| 130 | +the external interface, including multiple interfaces for the bigcount version |
| 131 | +of functions, in ``mpi-f08-interfaces-generated.h``. |
| 132 | + |
| 133 | +.. _Fortran 2018: https://fortranwiki.org/fortran/show/Fortran+2018 |
| 134 | + |
| 135 | +If a new type needs to be added, then one will need to extend |
| 136 | +``fortran_type.py`` in ``ompi/mpi/bindings/ompi_bindings`` with an additional |
| 137 | +type class specifying how to handle the type in the above generated files, |
| 138 | +including any required key-value attributes for more complicated types. New |
| 139 | +types use a ``Type`` base class with functions that can be implemented by |
| 140 | +derived classes, each returning expanded Fortran or C code. |
| 141 | + |
| 142 | +Other Considerations |
| 143 | +-------------------- |
| 144 | + |
| 145 | +Keep in mind that the generated files will not be deleted with a ``make clean`` |
| 146 | +or ``make distclean``; instead use ``make maintainer-clean`` to delete those. |
0 commit comments