[llvm] c34b0ab - [LangRef] Clarify !associated

[Fangrui Song via llvm-commits]

Author: Fangrui Song
Date: 2021-07-08T10:07:10-07:00
New Revision: c34b0ab589e5760b1eb82bf1f289590d351ea3c6

URL: https://github.com/llvm/llvm-project/commit/c34b0ab589e5760b1eb82bf1f289590d351ea3c6
DIFF: https://github.com/llvm/llvm-project/commit/c34b0ab589e5760b1eb82bf1f289590d351ea3c6.diff

LOG: [LangRef] Clarify !associated

Notably, a global variable with the metadata should generally not be referenced
by a function function. E.g. -fstack-size-section usage is fine, but
-fsanitize-coverage= used to have a linker GC problem (fixed by D97430).

Reviewed By: eugenis

Differential Revision: https://reviews.llvm.org/D104933

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 98a18e8d093d3..812a4c0d047bc 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -6838,17 +6838,29 @@ See :doc:`TypeMetadata`.
 '``associated``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``associated`` metadata may be attached to a global object
-declaration with a single argument that references another global object.
-
-This metadata prevents discarding of the global object in linker GC
-unless the referenced object is also discarded. The linker support for
-this feature is spotty. For best compatibility, globals carrying this
-metadata may also:
-
-- Be in a comdat with the referenced global.
-- Be in @llvm.compiler.used.
-- Have an explicit section with a name which is a valid C identifier.
+The ``associated`` metadata may be attached to a global variable definition with
+a single argument that references a global object (optionally through an alias).
+
+This metadata lowers to the ELF section flag ``SHF_LINK_INFO`` which prevents
+discarding of the global variable in linker GC unless the referenced object is
+also discarded. The linker support for this feature is spotty. For best
+compatibility, globals carrying this metadata should:
+
+- Be in ``@llvm.compiler.used``.
+- If the referenced global variable is in a comdat, be in the same comdat.
+
+``!associated`` can not express many-to-one relationship. A global variable with
+the metadata should generally not be referenced by a function: the function may
+be inlined into other functions, leading to more references to the metadata.
+Ideally we would want to keep metadata alive as long as any inline location is
+alive, but this many-to-one relationship is not representable. Moreover, if the
+metadata is retained while the function is discarded, the linker will report an
+error of a relocation referencing a discarded section.
+
+The metadata is often used with an explicit section consisting of valid C
+identifiers so that the runtime can find the metadata section with
+linker-defined encapsulation symbols ``__start_<section_name>`` and
+``__stop_<section_name>``.
 
 It does not have any effect on non-ELF targets.