[LangRef] Clarify !associated

[MaskRay]

Summary

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).

[MaskRay]

Ping:)

[eugenis]

llvm/docs/LangRef.rst

6855

It sounds like the linker error is only a symptom, and the real reason is that !associated as well as SHF_LINK_ORDER can not express many-to-one relationship, right? Because ideally we would want to keep metadata alive as long as any inline location is alive, too.

[MaskRay]

llvm/docs/LangRef.rst

6855

the real reason is that !associated as well as SHF_LINK_ORDER can not express many-to-one relationship, right?

Exactly. Shall I rephrase this to make it clearer? (Do you a particular suggestion?)

[eugenis]

llvm/docs/LangRef.rst

6855

Yeah, it would be good to expand this with the underlying reason for the limitation.
Something about how !associated metadata can not be used to describe multiple users of the variable because ELF only allows one linked section per section.

[MaskRay]

improve wording

[eugenis]

LGTM, thanks!

[MaskRay]

fix typo

[morehouse]

llvm/docs/LangRef.rst

6852

I thought it was SHF_LINK_ORDER.

[MaskRay]

llvm/docs/LangRef.rst

6852

Thanks for spotting this! Fixed in d833543dd52cfb126f4c6d765166e42da217b72a

llvm/docs/LangRef.rst

 '``type``' Metadata
 ^^^^^^^^^^^^^^^^^^^
 
 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.
+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 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.
+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.
 
 Example:
 
 .. code-block:: text
 
     $a = comdat any