This is an archive of the discontinued LLVM Phabricator instance.

Add GNU attribute 'retain'

Authored by MaskRay on Feb 24 2021, 11:40 PM.



For ELF targets, GCC 11 will set SHF_GNU_RETAIN on the section of a
__attribute__((retain)) function/variable to prevent linker garbage
collection. (See for the linker support).

This patch adds retain functions/variables to the llvm.used list, which has
the desired linker GC semantics. Note: retain does not imply used,
so an unused function/variable can be dropped by Sema.

Before 'retain' was introduced, previous ELF solutions require inline asm or
linker tricks, e.g. asm volatile(".reloc 0, R_X86_64_NONE, target");
(architecture dependent) or define a non-local symbol in the section and use
ld -u. There was no elegant source-level solution.

With D97448, __attribute__((retain)) will set SHF_GNU_RETAIN on ELF targets.

Diff Detail

Event Timeline

MaskRay created this revision.Feb 24 2021, 11:40 PM
MaskRay requested review of this revision.Feb 24 2021, 11:40 PM
Herald added a project: Restricted Project. · View Herald TranscriptFeb 24 2021, 11:40 PM
Herald added a subscriber: cfe-commits. · View Herald Transcript
zzheng added a subscriber: zzheng.Feb 25 2021, 9:54 AM
rnk added inline comments.Feb 25 2021, 2:11 PM

I think it would be helpful to add more context here, since each linker has its own terminology to describe section GC. Here's my attempt at starting this paragraph:

Whether this attribute has any effect on the linker depends on the target and the linker. Most linkers support the feature of section garbage collection (--gc-sections), also known as "dead stripping" (ld64 -dead_strip) or discarding unreferenced sections (link.exe /OPT:REF). On COFF and Mach-O targets (Windows and Apple platforms), the `used` attribute prevents symbols from being removed by linker section GC. On ELF targets, ...

I'm not sure how to link to the docs for the various command line flags from rst, but I think it would be helpful.


The linker can discard definitions for various reasons, like comdats, weak symbols, archive semantics, etc etc. Is SHF_GNU_RETAIN specific to section GC? Can you say so if so?

MaskRay updated this revision to Diff 326513.Feb 25 2021, 2:37 PM
MaskRay marked 2 inline comments as done.

Improve documentation


Adopted. Thanks!


Thanks for spotting this confusing part. I'll add archive member selection and COMDAT group resolution.

Weak symbols are not related. Weak symbols are part of symbol resolution, that does not affect the sections backing up the symbols.

I have performed a large-scale internal test. I don't find any problem with a toolchain built with D97446/D97447/D97448.

rnk accepted this revision.Feb 26 2021, 11:52 AM

lgtm with a minor doc tweak

My reading of the discussion is that this is ready, but please wait for others if you are aware of any outstanding concerns.


The attribute does have an effect on non-ELF targets: a retained global will be added to llvm.used, if it ends up being emitted. Maybe you can say that the attribute is only necessary on ELF targets, and that there is no harm in using retain in addition to used on non-ELF targets. Using the attributes together should result in consistent behavior across platforms.

This revision is now accepted and ready to land.Feb 26 2021, 11:52 AM
MaskRay updated this revision to Diff 326766.Feb 26 2021, 12:14 PM

Improve doc as rnk suggested.

This revision was landed with ongoing or failed builds.Feb 26 2021, 4:38 PM
This revision was automatically updated to reflect the committed changes.