[PATCH] D104933: [LangRef] Clarify !associated

[Fangrui Song via Phabricator via llvm-commits]

MaskRay created this revision.
MaskRay added reviewers: eugenis, morehouse, pcc, vitalybuka.
Herald added a subscriber: jdoerfert.
MaskRay requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

Notably, if !associated is used to reference a function, the function
cannot reference the metadata, e.g. -fstack-size-section usage is fine,
but -fsanitize-coverage= used to have a linker GC problem (fixed by D97430 <https://reviews.llvm.org/D97430>).


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D104933

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -6824,17 +6824,27 @@
 '``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
+This metadata 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 may also:
+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.
+
+If the metadata references a function, the function should not reference
+the metadata: the function may be inlined into other functions, leading
+to more references to the metadata. If the metadata is retained while
+the function is discarded, this will trigger a linker error.
+
+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.354556.patch
Type: text/x-patch
Size: 1693 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210625/07585ad0/attachment.bin>