2 files changed, 73 insertions, 0 deletions
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 5a2f98c493a..d2fe2acc7d5 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -6271,6 +6271,13 @@ enum is the smallest type which can represent all of its values::
     !0 = !{i32 1, !"short_wchar", i32 1}
     !1 = !{i32 1, !"short_enum", i32 0}
 
+LTO Post-Link Module Flags Metadata
+-----------------------------------
+
+Some optimisations are only when the entire LTO unit is present in the current
+module. This is represented by the ``LTOPostLink`` module flags metadata, which
+will be created with a value of ``1`` when LTO linking occurs.
+
 Automatic Linker Flags Named Metadata
 =====================================
 
@@ -16816,6 +16823,8 @@ Overview:
 The ``llvm.type.test`` intrinsic tests whether the given pointer is associated
 with the given type identifier.
 
+.. _type.checked.load:
+
 '``llvm.type.checked.load``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/llvm/docs/TypeMetadata.rst b/llvm/docs/TypeMetadata.rst
index 84cf05ba70f..7d0745b9279 100644
--- a/llvm/docs/TypeMetadata.rst
+++ b/llvm/docs/TypeMetadata.rst
@@ -224,3 +224,67 @@ efficiently to minimize the sizes of the underlying bitsets.
     }
 
 .. _GlobalLayoutBuilder: https://github.com/llvm/llvm-project/blob/master/llvm/include/llvm/Transforms/IPO/LowerTypeTests.h
+
+``!vcall_visibility`` Metadata
+==============================
+
+In order to allow removing unused function pointers from vtables, we need to
+know whether every virtual call which could use it is known to the compiler, or
+whether another translation unit could introduce more calls through the vtable.
+This is not the same as the linkage of the vtable, because call sites could be
+using a pointer of a more widely-visible base class. For example, consider this
+code:
+
+.. code-block:: c++
+
+  __attribute__((visibility("default")))
+  struct A {
+    virtual void f();
+  };
+
+  __attribute__((visibility("hidden")))
+  struct B : A {
+    virtual void f();
+  };
+
+With LTO, we know that all code which can see the declaration of ``B`` is
+visible to us. However, a pointer to a ``B`` could be cast to ``A*`` and passed
+to another linkage unit, which could then call ``f`` on it. This call would
+load from the vtable for ``B`` (using the object pointer), and then call
+``B::f``. This means we can't remove the function pointer from ``B``'s vtable,
+or the implementation of ``B::f``. However, if we can see all code which knows
+about any dynamic base class (which would be the case if ``B`` only inherited
+from classes with hidden visibility), then this optimisation would be valid.
+
+This concept is represented in IR by the ``!vcall_visibility`` metadata
+attached to vtable objects, with the following values:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 90
+
+   * - Value
+     - Behavior
+
+   * - 0 (or omitted)
+     - **Public**
+           Virtual function calls using this vtable could be made from external
+           code.
+
+   * - 1
+     - **Linkage Unit**
+           All virtual function calls which might use this vtable are in the
+           current LTO unit, meaning they will be in the current module once
+           LTO linking has been performed.
+
+   * - 2
+     - **Translation Unit**
+           All virtual function calls which might use this vtable are in the
+           current module.
+
+In addition, all function pointer loads from a vtable marked with the
+``!vcall_visibility`` metadata (with a non-zero value) must be done using the
+:ref:`llvm.type.checked.load <type.checked.load>` intrinsic, so that virtual
+calls sites can be correlated with the vtables which they might load from.
+Other parts of the vtable (RTTI, offset-to-top, ...) can still be accessed with
+normal loads.