1==============
2LTO Visibility
3==============
4
5*LTO visibility* is a property of an entity that specifies whether it can be
6referenced from outside the current LTO unit. A *linkage unit* is a set of
7translation units linked together into an executable or DSO, and a linkage
8unit's *LTO unit* is the subset of the linkage unit that is linked together
9using link-time optimization; in the case where LTO is not being used, the
10linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit.
11
12The LTO visibility of a class is used by the compiler to determine which
13classes the whole-program devirtualization (``-fwhole-program-vtables``) and
14control flow integrity (``-fsanitize=cfi-vcall`` and ``-fsanitize=cfi-mfcall``)
15features apply to. These features use whole-program information, so they
16require the entire class hierarchy to be visible in order to work correctly.
17
18If any translation unit in the program uses either of the whole-program
19devirtualization or control flow integrity features, it is effectively an ODR
20violation to define a class with hidden LTO visibility in multiple linkage
21units. A class with public LTO visibility may be defined in multiple linkage
22units, but the tradeoff is that the whole-program devirtualization and
23control flow integrity features can only be applied to classes with hidden LTO
24visibility. A class's LTO visibility is treated as an ODR-relevant property
25of its definition, so it must be consistent between translation units.
26
27In translation units built with LTO, LTO visibility is based on the
28class's symbol visibility as expressed at the source level (i.e. the
29``__attribute__((visibility("...")))`` attribute, or the ``-fvisibility=``
30flag) or, on the Windows platform, the dllimport and dllexport attributes. When
31targeting non-Windows platforms, classes with a visibility other than hidden
32visibility receive public LTO visibility. When targeting Windows, classes
33with dllimport or dllexport attributes receive public LTO visibility. All
34other classes receive hidden LTO visibility. Classes with internal linkage
35(e.g. classes declared in unnamed namespaces) also receive hidden LTO
36visibility.
37
38During the LTO link, all classes with public LTO visibility will be refined
39to hidden LTO visibility when the ``--lto-whole-program-visibility`` lld linker
40option is applied (``-plugin-opt=whole-program-visibility`` for gold). This flag
41can be used to defer specifying whether classes have hidden LTO visibility until
42link time, to allow bitcode objects to be shared by different LTO links.
43Due to an implementation limitation, symbols associated with classes with hidden
44LTO visibility may still be exported from the binary when using this flag. It is
45unsafe to refer to these symbols, and their visibility may be relaxed to hidden
46in a future compiler release.
47
48A class defined in a translation unit built without LTO receives public
49LTO visibility regardless of its object file visibility, linkage or other
50attributes.
51
52This mechanism will produce the correct result in most cases, but there are
53two cases where it may wrongly infer hidden LTO visibility.
54
551. As a corollary of the above rules, if a linkage unit is produced from a
56   combination of LTO object files and non-LTO object files, any hidden
57   visibility class defined in both a translation unit built with LTO and
58   a translation unit built without LTO must be defined with public LTO
59   visibility in order to avoid an ODR violation.
60
612. Some ABIs provide the ability to define an abstract base class without
62   visibility attributes in multiple linkage units and have virtual calls
63   to derived classes in other linkage units work correctly. One example of
64   this is COM on Windows platforms. If the ABI allows this, any base class
65   used in this way must be defined with public LTO visibility.
66
67Classes that fall into either of these categories can be marked up with the
68``[[clang::lto_visibility_public]]`` attribute. To specifically handle the
69COM case, classes with the ``__declspec(uuid())`` attribute receive public
70LTO visibility. On Windows platforms, clang-cl's ``/MT`` and ``/MTd``
71flags statically link the program against a prebuilt standard library;
72these flags imply public LTO visibility for every class declared in the
73``std`` and ``stdext`` namespaces.
74
75Example
76=======
77
78The following example shows how LTO visibility works in practice in several
79cases involving two linkage units, ``main`` and ``dso.so``.
80
81.. code-block:: none
82
83    +-----------------------------------------------------------+  +----------------------------------------------------+
84    | main (clang++ -fvisibility=hidden):                       |  | dso.so (clang++ -fvisibility=hidden):              |
85    |                                                           |  |                                                    |
86    |  +-----------------------------------------------------+  |  |  struct __attribute__((visibility("default"))) C { |
87    |  | LTO unit (clang++ -fvisibility=hidden -flto):       |  |  |    virtual void f();                               |
88    |  |                                                     |  |  |  }                                                 |
89    |  |  struct A { ... };                                  |  |  |  void C::f() {}                                    |
90    |  |  struct [[clang::lto_visibility_public]] B { ... }; |  |  |  struct D {                                        |
91    |  |  struct __attribute__((visibility("default"))) C {  |  |  |    virtual void g() = 0;                           |
92    |  |    virtual void f();                                |  |  |  };                                                |
93    |  |  };                                                 |  |  |  struct E : D {                                    |
94    |  |  struct [[clang::lto_visibility_public]] D {        |  |  |    virtual void g() { ... }                        |
95    |  |    virtual void g() = 0;                            |  |  |  };                                                |
96    |  |  };                                                 |  |  |  __attribute__((visibility("default"))) D *mkE() { |
97    |  |                                                     |  |  |    return new E;                                   |
98    |  +-----------------------------------------------------+  |  |  }                                                 |
99    |                                                           |  |                                                    |
100    |  struct B { ... };                                        |  +----------------------------------------------------+
101    |                                                           |
102    +-----------------------------------------------------------+
103
104We will now describe the LTO visibility of each of the classes defined in
105these linkage units.
106
107Class ``A`` is not defined outside of ``main``'s LTO unit, so it can have
108hidden LTO visibility. This is inferred from the object file visibility
109specified on the command line.
110
111Class ``B`` is defined in ``main``, both inside and outside its LTO unit. The
112definition outside the LTO unit has public LTO visibility, so the definition
113inside the LTO unit must also have public LTO visibility in order to avoid
114an ODR violation.
115
116Class ``C`` is defined in both ``main`` and ``dso.so`` and therefore must
117have public LTO visibility. This is correctly inferred from the ``visibility``
118attribute.
119
120Class ``D`` is an abstract base class with a derived class ``E`` defined
121in ``dso.so``.  This is an example of the COM scenario; the definition of
122``D`` in ``main``'s LTO unit must have public LTO visibility in order to be
123compatible with the definition of ``D`` in ``dso.so``, which is observable
124by calling the function ``mkE``.
125