maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[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
This commit is contained in:
Fangrui Song 2021-07-08 10:07:10 -07:00
parent 8cf60e61e7
commit c34b0ab589
1 changed files with 21 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
llvm/docs/LangRef.rst
View File

@ -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.
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:
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 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.