Add !retain metadata to retain global values under linker garbage collection

[MaskRay]

Summary

!retain may be attached to a function/global variable definition.
Its section will be marked as a linker GC root.

On ELF platforms, we set the SHF_GNU_RETAIN flag.

We don't restrict the feature to ELFOSABI_GNU and ELFOSABI_FREEBSD for
now. See the rationale in D95749.

The integrated assembler has supported SHF_GNU_RETAIN since D95730.
GNU as>=2.36 supports section flag 'R'.
We don't need to worry about GNU ld support because older GNU ld just ignores
the unknown SHF_GNU_RETAIN.

On COFF platforms, we add /INCLUDE: linker options similar to how we currently
handle llvm.used (99f479abcf2c9b36daad04eb91cd0aafa659bb1d). Retaining local
linkage symbols is not representable due to the limitation.

[phosek]

Have you considered using llvm.used instead of introducing new metadata type? __attribute__((used)) is lowered to llvm.used so this should be equivalent.

[MaskRay]

In D96837#2567702, @phosek wrote:

Have you considered using llvm.used instead of introducing new metadata type? __attribute__((used)) is lowered to llvm.used so this should be equivalent.

I have considered it. It is true that clang places __attribute__((used)) definitions in llvm.uses, but it adds a bunch of other stuff (I am reading the call sites of addUsedGlobal to figure out what I may have missed in D96838).
Second, I am concerned that the separate section semantics (copied from GCC) may not be desired for some llvm.uses use cases.

[MaskRay]

Please see the updated description of D96838. In GCC, 'used' no longer have the special semantics. 'used' and 'retain are entirely orthogonal for ELF.

[phosek]

LGTM

llvm/docs/LangRef.rst

6562–6563

Would it be possible to expand this sentence a bit? I'm not quite sure what you mean by "loosing linker GC precision".

llvm/test/CodeGen/X86/elf-retain.ll

2

Can you include top-level comment describing the purpose of this test?

[MaskRay]

improve doc

[MaskRay]

Support COFF

[rnk]

llvm/docs/LangRef.rst

6572

I think this is fine for now, but we should investigate the other implementation strategy (non-comdat unique sections) in the future to lift this limitation. What you've done here has parity with llvm.used, so we don't need to improve on that right now.

llvm/test/CodeGen/X86/coff-retain.ll

5

Maybe start by looking for the .drectve section to establish context for the CHECKs

[MaskRay]

@rnk I posted https://lists.llvm.org/pipermail/llvm-dev/2021-February/148760.html . This patch implements approach 2. If we do approach 1 (has support from @compnerd and @dblaikie), we don't need this metadata. What do you think of the tradeoff?

[rnk]

In D96837#2585874, @MaskRay wrote:

@rnk I posted https://lists.llvm.org/pipermail/llvm-dev/2021-February/148760.html . This patch implements approach 2. If we do approach 1 (has support from @compnerd and @dblaikie), we don't need this metadata. What do you think of the tradeoff?

Proposal 1 of just keeping llvm.used and changing the semantics of the source level attribute seems fine to me as well.

llvm/docs/LangRef.rst

 
 .. code-block:: text
 
     $a = comdat any
     @a = global i32 1, comdat $a
     @b = internal global i32 2, comdat $a, section "abc", !associated !0
     !0 = !{i32* @a}
 
+'``retain``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata, when attached to a global object definition, indicates that
+the global object needs to be retained under linker garbage collection.
+
+This metadata only has effects on COFF and ELF targets.
+
+On ELF targets, a separate section with the ``SHF_GNU_RETAIN`` flag is created.
+
+If an explicit section is specified, the separate section will have the
+specified name, but different from the selected section when the metadata is
+absent. I.e. if two global objects have the same explicit section but only
+one has the ``retain`` metadata, there will be two sections of the same name,
+one with the ``SHF_GNU_RETAIN`` flag.
+
+On COFF targets, this metadata only works for non-local linkage global objects.
+
+Example:
+
+.. code-block:: llvm
+
+    @a = global i32 1, !retain !{}
+    @b = constant i32 2, !retain !{}
+
+    define void @f() !retain !{} {
+      ...
+    }
 
 '``prof``' Metadata
 ^^^^^^^^^^^^^^^^^^^
 
 The ``prof`` metadata is used to record profile data in the IR.
 The first operand of the metadata node indicates the profile metadata
 type. There are currently 3 types:
 :ref:`branch_weights<prof_node_branch_weights>`,

llvm/include/llvm/IR/FixedMetadataKinds.def

 LLVM_FIXED_MD_KIND(MD_callees, "callees", 23)
 LLVM_FIXED_MD_KIND(MD_irr_loop, "irr_loop", 24)
 LLVM_FIXED_MD_KIND(MD_access_group, "llvm.access.group", 25)
 LLVM_FIXED_MD_KIND(MD_callback, "callback", 26)
 LLVM_FIXED_MD_KIND(MD_preserve_access_index, "llvm.preserve.access.index", 27)
 LLVM_FIXED_MD_KIND(MD_vcall_visibility, "vcall_visibility", 28)
 LLVM_FIXED_MD_KIND(MD_noundef, "noundef", 29)
 LLVM_FIXED_MD_KIND(MD_annotation, "annotation", 30)
+LLVM_FIXED_MD_KIND(MD_retain, "retain", 31)

llvm/lib/CodeGen/TargetLoweringObjectFileImpl.cpp

MCSection *TargetLoweringObjectFileELF::getExplicitSectionGlobal(
   }
 
   unsigned EntrySize = getEntrySizeForKind(Kind);
 
   // A section can have at most one associated section. Put each global with
   // MD_associated in a unique section.
   unsigned UniqueID = MCContext::GenericSectionID;
   const MCSymbolELF *LinkedToSym = getLinkedToSymbol(GO, TM);
-  if (GO->getMetadata(LLVMContext::MD_associated)) {
+  const bool Associated = GO->getMetadata(LLVMContext::MD_associated);
+  const bool Retain = GO->getMetadata(LLVMContext::MD_retain);
+  if (Associated || Retain) {
     UniqueID = NextUniqueID++;
+    if (Associated)
       Flags |= ELF::SHF_LINK_ORDER;
+    if (Retain && (getContext().getAsmInfo()->useIntegratedAssembler() ||
+                   getContext().getAsmInfo()->binutilsIsAtLeast(2, 36)))
+      Flags |= ELF::SHF_GNU_RETAIN;
   } else {
     if (getContext().getAsmInfo()->useIntegratedAssembler() ||
         getContext().getAsmInfo()->binutilsIsAtLeast(2, 35)) {
       // Symbols must be placed into sections with compatible entry
       // sizes. Generate unique sections for symbols that have not
       // been assigned to compatible sections.
       if (Flags & ELF::SHF_MERGE) {
         auto maybeID = getContext().getELFUniqueIDForEntsize(SectionName, Flags,
static MCSection *selectELFSectionForGlobal(
     MCContext &Ctx, const GlobalObject *GO, SectionKind Kind, Mangler &Mang,
     const TargetMachine &TM, bool EmitUniqueSection,  unsigned Flags,
     unsigned *NextUniqueID) {
   const MCSymbolELF *LinkedToSym = getLinkedToSymbol(GO, TM);
   if (LinkedToSym) {
     EmitUniqueSection = true;
     Flags |= ELF::SHF_LINK_ORDER;
   }
+  if (GO->getMetadata(LLVMContext::MD_retain) &&
+      (Ctx.getAsmInfo()->useIntegratedAssembler() ||
+       Ctx.getAsmInfo()->binutilsIsAtLeast(2, 36))) {
+    EmitUniqueSection = true;
+    Flags |= ELF::SHF_GNU_RETAIN;
+  }
 
   MCSectionELF *Section = selectELFSectionForGlobal(
       Ctx, GO, Kind, Mang, TM, EmitUniqueSection, Flags,
       NextUniqueID, LinkedToSym);
   assert(Section->getLinkedToSymbol() == LinkedToSym);
   return Section;
 }
 
for (const GlobalValue &GV : M.global_values()) {
     OS.flush();
     if (!Flags.empty()) {
       Streamer.SwitchSection(getDrectveSection());
       Streamer.emitBytes(Flags);
     }
     Flags.clear();
   }
 
+  // Emit /INCLUDE: flags for each non-local-linkage global value with the
+  // !retain metadata.
+  raw_string_ostream OS(Flags);
+  auto EmitLinkerFlags = [&](const GlobalValue &GV) {
+    emitLinkerFlagsForUsedCOFF(OS, &GV, getTargetTriple(), getMangler());
+    OS.flush();
+    if (!Flags.empty()) {
+      Streamer.SwitchSection(getDrectveSection());
+      Streamer.emitBytes(Flags);
+    }
+    Flags.clear();
+  };
+
+  for (const GlobalValue &GV : M.global_values())
+    if (auto *GO = dyn_cast<GlobalObject>(&GV))
+      if (!GV.hasLocalLinkage() && GO->hasMetadata(LLVMContext::MD_retain))
+        EmitLinkerFlags(GV);
+
   // Emit /INCLUDE: flags for each used global as necessary.
   if (const auto *LU = M.getNamedGlobal("llvm.used")) {
     assert(LU->hasInitializer() && "expected llvm.used to have an initializer");
     assert(isa<ArrayType>(LU->getValueType()) &&
            "expected llvm.used to be an array type");
     if (const auto *A = cast<ConstantArray>(LU->getInitializer())) {
       for (const Value *Op : A->operands()) {
         const auto *GV = cast<GlobalValue>(Op->stripPointerCasts());
         // Global symbols with internal or private linkage are not visible to
         // the linker, and thus would cause an error when the linker tried to
         // preserve the symbol due to the `/include:` directive.
         if (GV->hasLocalLinkage())
           continue;
 
-        raw_string_ostream OS(Flags);
-        emitLinkerFlagsForUsedCOFF(OS, GV, getTargetTriple(), getMangler());
-        OS.flush();
-
-        if (!Flags.empty()) {
-          Streamer.SwitchSection(getDrectveSection());
-          Streamer.emitBytes(Flags);
-        }
-        Flags.clear();
+        EmitLinkerFlags(*GV);
       }
     }
   }
 }
 
 void TargetLoweringObjectFileCOFF::Initialize(MCContext &Ctx,
                                               const TargetMachine &TM) {
   TargetLoweringObjectFile::Initialize(Ctx, TM);

llvm/test/CodeGen/X86/coff-retain.ll

+;; Add /INCLUDE: linker options for non-local-linkage global values with the
+;; !retain metadata.
+; RUN: llc -mtriple=x86_64-windows-msvc < %s | FileCheck %s
+
+; CHECK:      .ascii " /INCLUDE:fa"
+; CHECK-NEXT: .ascii " /INCLUDE:fb"
+; CHECK-NEXT: .ascii " /INCLUDE:ga"
+; CHECK-NEXT: .ascii " /INCLUDE:gb"
+; CHECK-NEXT: .ascii " /INCLUDE:ge"
+; CHECK-NOT:  .ascii
+
+define dso_local void @fa() !retain !{} {
+entry:
+  ret void
+}
+define weak_odr dso_local void @fb() !retain !{} {
+entry:
+  ret void
+}
+define internal void @fc() !retain !{} {
+entry:
+  ret void
+}
+
+@ga = global i32 0, !retain !{}
+@gb = weak global i32 0, !retain !{}
+@gc = internal global i32 0, !retain !{}
+@gd = private global i32 0, !retain !{}
+@ge = constant i32 3, !retain !{}
+
+;; Aliases do not get /INCLUDE:. This is to be consistent with ELF.
+@aa = alias i32, i32* @gc
+@ab = internal alias i32, i32* @gc

llvm/test/CodeGen/X86/elf-retain.ll

+;; Place a global object with !retain in a separate section with the SHF_GNU_RETAIN flag.
+; RUN: llc -mtriple=x86_64 < %s | FileCheck %s
+; RUN: llc -mtriple=x86_64 -data-sections=1 < %s | FileCheck %s
+; RUN: llc -mtriple=x86_64 -no-integrated-as -binutils-version=2.36 < %s | FileCheck %s
+; RUN: llc -mtriple=x86_64 -no-integrated-as -binutils-version=2.35 < %s | FileCheck %s --check-prefix=OLDGAS
+
+; RUN: llc -mtriple=x86_64 -data-sections=1 -unique-section-names=0 < %s | FileCheck %s --check-prefix=NOUNIQUE
+
+; CHECK:    .section .text.fa,"axR",@progbits{{$}}
+; OLDGAS-NOT: .section .text
+; NOUNIQUE: .section .text,"axR",@progbits,unique,1
+define dso_local void @fa() !retain !{} {
+entry:
+  ret void
+}
+
+; CHECK:    .section .text.fb,"axR",@progbits{{$}}
+; NOUNIQUE: .section .text,"axR",@progbits,unique,2
+define internal void @fb() !retain !{} {
+entry:
+  ret void
+}
+
+;; Explicit section.
+; CHECK:    .section ccc,"axR",@progbits,unique,1
+; OLDGAS:   .section ccc,"ax",@progbits,unique,1
+; NOUNIQUE: .section ccc,"axR",@progbits,unique,3
+define dso_local void @fc() section "ccc" !retain !{} {
+entry:
+  ret void
+}
+
+; CHECK:    .section .bss.ga,"awR",@nobits{{$}}
+; OLDGAS:   .bss{{$}}
+; NOUNIQUE: .section .bss,"awR",@nobits,unique,4
+@ga = global i32 0, !retain !{}
+
+; CHECK:    .section .data.gb,"awR",@progbits{{$}}
+; OLDGAS:   .data{{$}}
+; NOUNIQUE: .section .data,"awR",@progbits,unique,5
+@gb = internal global i32 2, !retain !{}
+
+; CHECK:    .section .rodata.gc,"aR",@progbits{{$}}
+; OLDGAS:   .section .rodata,"a",@progbits{{$}}
+; NOUNIQUE: .section .rodata,"aR",@progbits,unique,6
+@gc = constant i32 3, !retain !{}
+
+;; Explicit section.
+; CHECK:    .section ddd,"awR",@progbits,unique,2
+; OLDGAS:   .section ddd,"aw",@progbits,unique,2
+; NOUNIQUE: .section ddd,"awR",@progbits,unique,7
+@gd = global i32 1, section "ddd", !retain !{}
+
+;; Used together with !associated.
+; CHECK:    .section .data.ge,"awoR",@progbits,gc
+; OLDGAS:   .section .data.ge,"awo",@progbits,gc
+; NOUNIQUE: .section .data,"awoR",@progbits,gc,unique,8
+@ge = global i32 1, !associated !0, !retain !{}
+
+!0 = !{i32* @gc}