Add GNU attribute 'retain'

[MaskRay]

Summary

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 AttrDocs.td 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.

[rnk]

clang/include/clang/Basic/AttrDocs.td

74

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.

86

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]

Improve documentation

clang/include/clang/Basic/AttrDocs.td

74

Adopted. Thanks!

86

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.

[MaskRay]

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

[rnk]

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.

clang/include/clang/Basic/AttrDocs.td

98

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.

[MaskRay]

Improve doc as rnk suggested.