[flang] Add the proposal document and rationale for the internal naming module that was previously added.

[schweitz]

Summary

This document describes how uniquing of internal names is done. This
name uniquing is done to support the constraints and invariants of the FIR
dialect of MLIR.

[schweitz]

review comments: minor edits to improve the text

[kiranchandramohan]

Could you comment on whether this mangling will have any effect on interfacing with C/C++? Will this have any effects on LTO. What happens if a bind name is specified?
http://web.mit.edu/tibbetts/Public/inside-c/www/mangling.html

[schweitz]

In D79089#2011949, @kiranchandramohan wrote:

Could you comment on whether this mangling will have any effect on interfacing with C/C++? Will this have any effects on LTO. What happens if a bind name is specified?
http://web.mit.edu/tibbetts/Public/inside-c/www/mangling.html

Hi Kiran,

Good questions and thanks for asking.

The hope is that this mangling will not conflict with C and C++, of course. None of the languages (C, C++, or Fortran) have a standard mangling. C reserves the underscore, double underscore, and underscore capital letter prefixes [1],[2]. A description of a common C++ name mangling scheme is [3],[your link]. It seems like the only common thing about Fortran name mangling implementations is that different vendors have their own, as can be experimented with [4].

The uniquing scheme described in this document has some similarities and differences to other mangling schemes, but it was designed to minimize collisions with those spaces.

As far as using bind C names, the plan is to just use the bind C name directly as it should never have the prefix marker "_Q", so it will be recognized as a symbol name that was not uniqued. That may or may not be sufficient depending other unknowns. (We are similarly targeting llvm intrinsic functions in our present work.) The fallback plan would be to unique the name and then relabel when lowering to LLVM.

The bidirectional ability and flexibility are key objectives. It means that it may be the case that these names are never exposed to the LLVM layer, in the object files, to the linker, etc. Since this scheme can recover the symbols from the front-end, the symbols can themselves be lowered as a conversion and in a target-dependent manner.

[1] https://stackoverflow.com/questions/39625352/why-do-some-functions-in-c-have-an-underscore-prefix
[2] http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
[3] https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangling
[4] https://fortran.godbolt.org/

[sscalpone]

Reminder, flang should follow the well-established naming conventions when creating external names for "f77" entities. There's nothing in this proposal that blocks that; this is just an fyi.

flang/documentation/BijectiveInternalNameUniquing.md

8

"goal" could be "feature" or "requirement" -- not important.

[schweitz]

s/goal/requirement/

[kiranchandramohan]

Thanks @schweitz for the detailed reply.

I have a couple more questions.
-> Isn't this necessary for the Block construct?
-> Will uniquing all names lead to lower readability of the IR? (Assuming that is what being proposed here)
-> Yeah, renaming local variables back to original names (during lowering to LLVM IR) when there is no clash seems better for readability.

[schweitz]

In D79089#2012963, @kiranchandramohan wrote:

Thanks @schweitz for the detailed reply.

I have a couple more questions.
-> Isn't this necessary for the Block construct?
-> Will uniquing all names lead to lower readability of the IR? (Assuming that is what being proposed here)
-> Yeah, renaming local variables back to original names (during lowering to LLVM IR) when there is no clash seems better for readability.

The uniquing is required in the context of the MLIR Module symbol space. (Artifacts with a process lifetime such as functions, globals, etc.) Locals need not be uniqued as they have a unique identity as ssa-values. (Their names are tracked with name attributes attached to the Op.)

[kiranchandramohan]

The uniquing is required in the context of the MLIR Module symbol space. (Artifacts with a process lifetime such as functions, globals, etc.) Locals need not be uniqued as they have a unique identity as ssa-> values. (Their names are tracked with name attributes attached to the Op.)

Thanks @schweitz. Adding the above information to the doc might be helpful.

[schweitz]

Clarify that the uniquing is for global artifacts.

[tskeith]

flang/documentation/BijectiveInternalNameUniquing.md

35

Submodules of an ancestor module have to have distinct names, so you don't need to include s1mod in the unique name for s2mod (though it doesn't hurt). So the unique name for smod2 could be just _QMmodSs2mod.

50

What about the blank common block? Is its name just _QB?

59

On line 30 it says F is the prefix. P makes more sense to me.

[schweitz]

flang/documentation/BijectiveInternalNameUniquing.md

35

True. It seemed the more cautious approach to include more information about the symbol origin.

50

Yes.

59

One (F) signifies scope and the other (P) identity.

flang/documentation/BijectiveInternalNameUniquing.md

+## Bijective Internal Name Uniquing
+
+FIR has a flat namespace.  No two objects may have the same name at
+the module level.  (These would be functions, globals, etc.)
+This necessitates some sort of encoding scheme to unique
+symbols from the front-end into FIR.
+
+Another requirement is
+to be able to reverse these unique names and recover the associated
+symbol in the symbol table.
+
+Fortran is case insensitive, which allows the compiler to convert the
+user's identifiers to all lower case.  Such a universal conversion implies
+that all upper case letters are available for use in uniquing.
+
+### Prefix `_Q`
+
+All uniqued names have the prefix sequence `_Q` to indicate the name has
+been uniqued.  (Q is chosen because it is a
+[low frequency letter](http://pi.math.cornell.edu/~mec/2003-2004/cryptography/subs/frequencies.html)
+in English.)
+
+### Scope Building
+
+Symbols can be scoped by the module, submodule, or procedure that contains
+that symbol.  After the `_Q` sigil, names are constructed from outermost to
+innermost scope as
+
+   * Module name prefixed with `M`
+   * Submodule name prefixed with `S`
+   * Procedure name prefixed with `F`
+
+Given:
+```
+    submodule (mod:s1mod) s2mod
+      ...
+      subroutine sub
+        ...
+      contains
+        function fun
+```
+
+The uniqued name of `fun` becomes:
+```
+    _QMmodSs1modSs2modFsubPfun
+```
+
+### Common blocks
+
+   * A common block name will be prefixed with `B`
+
+### Module scope global data
+
+   * A global data entity is prefixed with `E`
+   * A global entity that is constant (parameter) will be prefixed with `EC`
+
+### Procedures/Subprograms
+
+   * A procedure/subprogram is prefixed with `P`
+
+Given:
+```
+    subroutine sub
+```
+The uniqued name of `sub` becomes:
+```
+    _QPsub
+```
+
+### Derived types and related
+
+   * A derived type is prefixed with `T`
+   * If a derived type has KIND parameters, they are listed in a consistent
+     canonical order where each takes the form `Ki` and where _i_ is the
+     compile-time constant value. (All type parameters are integer.)  If _i_
+     is a negative value, the prefix `KN` will be used and _i_ will reflect
+     the magnitude of the value.
+
+Given:
+```
+    module mymodule
+      type mytype
+        integer :: member
+      end type
+      ...
+```
+The uniqued name of `mytype` becomes:
+```
+    _QMmymoduleTmytype
+```
+
+Given:
+```
+    type yourtype(k1,k2)
+      integer, kind :: k1, k2
+      real :: mem1
+      complex :: mem2
+    end type
+```
+
+The uniqued name of `yourtype` where `k1=4` and `k2=-6` (at compile-time):
+```
+    _QTyourtypeK4KN6
+```
+
+   * A derived type dispatch table is prefixed with `D`.  The dispatch table
+     for `type t` would be `_QDTt`
+   * A type descriptor instance is prefixed with `C`.  Intrinsic types can
+     be encoded with their names and kinds.  The type descriptor for the
+     type `yourtype` above would be `_QCTyourtypeK4KN6`.  The type
+     descriptor for `REAL(4)` would be `_QCrealK4`.
+
+### Compiler generated names
+
+Compiler generated names do not have to be mapped back to Fortran.  These
+names will be prefixed with `_QQ` and followed by a unique compiler
+generated identifier. There is, of course, no mapping back to a symbol
+derived from the input source in this case as no such symbol exists.