[PATCH] D104933: [LangRef] Clarify !associated

[Fangrui Song via Phabricator via llvm-commits]

MaskRay updated this revision to Diff 357073.
MaskRay added a comment.

improve wording


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D104933/new/

https://reviews.llvm.org/D104933

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -6838,17 +6838,30 @@
 '``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
+declaration 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:
+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 a comdat with the referenced global.
-- Be in @llvm.compiler.used.
-- Have an explicit section with a name which is a valid C identifier.
+- 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
+error 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.
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D104933.357073.patch
Type: text/x-patch
Size: 2149 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210707/ed7a0a95/attachment.bin>