From fe7a36e3fb6bf1965a94a97f2d231572a2fc281f Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 13 Nov 2024 15:12:55 -0800
Subject: [PATCH 01/11] [lld][ELF] Add --why-live flag (inspired by Mach-O)

This prints the stack of reasons that symbols that match the given
glob(s) survived GC. It has no effect unless section GC occurs.

A symbol may be live intrisically, because referenced by another symbol
or section, or because part of a live section. Sections have similar
reasons.

This implementation does not require -ffunction-sections or
-fdata-sections to produce readable results, althought it does tend to
work better (as does GC).
---
 lld/ELF/Config.h        |   1 +
 lld/ELF/Driver.cpp      |   9 +++
 lld/ELF/MarkLive.cpp    | 125 +++++++++++++++++++++++++++++++++----
 lld/ELF/Options.td      |   6 ++
 lld/test/ELF/why-live.s | 132 ++++++++++++++++++++++++++++++++++++++++
 5 files changed, 260 insertions(+), 13 deletions(-)
 create mode 100644 lld/test/ELF/why-live.s

diff --git a/lld/ELF/Config.h b/lld/ELF/Config.h
index e07c7dd4ca1b6..03b3cd4771f49 100644
--- a/lld/ELF/Config.h
+++ b/lld/ELF/Config.h
@@ -226,6 +226,7 @@ struct Config {
   llvm::StringRef thinLTOCacheDir;
   llvm::StringRef thinLTOIndexOnlyArg;
   llvm::StringRef whyExtract;
+  llvm::SmallVector<llvm::GlobPattern, 0> whyLive;
   llvm::StringRef cmseInputLib;
   llvm::StringRef cmseOutputLib;
   ReportPolicy zBtiReport = ReportPolicy::None;
diff --git a/lld/ELF/Driver.cpp b/lld/ELF/Driver.cpp
index 3e7e05746483a..4555a85a4d216 100644
--- a/lld/ELF/Driver.cpp
+++ b/lld/ELF/Driver.cpp
@@ -1545,6 +1545,15 @@ static void readConfigs(Ctx &ctx, opt::InputArgList &args) {
   ctx.arg.warnSymbolOrdering =
       args.hasFlag(OPT_warn_symbol_ordering, OPT_no_warn_symbol_ordering, true);
   ctx.arg.whyExtract = args.getLastArgValue(OPT_why_extract);
+  for (opt::Arg *arg : args.filtered(OPT_why_live)) {
+    StringRef value(arg->getValue());
+    if (Expected<GlobPattern> pat = GlobPattern::create(arg->getValue())) {
+      ctx.arg.whyLive.emplace_back(std::move(*pat));
+    } else {
+      ErrAlways(ctx) << arg->getSpelling() << ": " << pat.takeError();
+      continue;
+    }
+  }
   ctx.arg.zCombreloc = getZFlag(args, "combreloc", "nocombreloc", true);
   ctx.arg.zCopyreloc = getZFlag(args, "copyreloc", "nocopyreloc", true);
   ctx.arg.zForceBti = hasZOption(args, "force-bti");
diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index b6c22884d9176..8e9e385bc26dc 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -29,9 +29,11 @@
 #include "Target.h"
 #include "lld/Common/CommonLinkerContext.h"
 #include "lld/Common/Strings.h"
+#include "llvm/ADT/DenseMapInfoVariant.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/Object/ELF.h"
 #include "llvm/Support/TimeProfiler.h"
+#include <variant>
 #include <vector>
 
 using namespace llvm;
@@ -42,6 +44,10 @@ using namespace lld;
 using namespace lld::elf;
 
 namespace {
+
+// Something that can be the most proximate reason that something else is alive.
+typedef std::variant<InputSectionBase *, Symbol *> LiveReason;
+
 template <class ELFT> class MarkLive {
 public:
   MarkLive(Ctx &ctx, unsigned partition) : ctx(ctx), partition(partition) {}
@@ -50,7 +56,10 @@ template <class ELFT> class MarkLive {
   void moveToMain();
 
 private:
-  void enqueue(InputSectionBase *sec, uint64_t offset);
+  void enqueue(InputSectionBase *sec, uint64_t offset = 0,
+               Symbol *sym = nullptr,
+               std::optional<LiveReason> reason = std::nullopt);
+  void printWhyLive(Symbol *s) const;
   void markSymbol(Symbol *sym);
   void mark();
 
@@ -70,6 +79,12 @@ template <class ELFT> class MarkLive {
   // There are normally few input sections whose names are valid C
   // identifiers, so we just store a SmallVector instead of a multimap.
   DenseMap<StringRef, SmallVector<InputSectionBase *, 0>> cNamedSections;
+
+  // The most proximate reason that something is live. If something doesn't have
+  // a recorded reason, it is either dead, intrinsically live, or an
+  // unreferenced symbol in a live section. (These cases are trivially
+  // detectable and need not be stored.)
+  DenseMap<LiveReason, LiveReason> whyLive;
 };
 } // namespace
 
@@ -101,6 +116,12 @@ void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
   Symbol &sym = sec.file->getRelocTargetSym(rel);
   sym.used = true;
 
+  LiveReason reason;
+  if (!ctx.arg.whyLive.empty()) {
+    Defined *reasonSym = sec.getEnclosingSymbol(rel.r_offset);
+    reason = reasonSym ? LiveReason(reasonSym) : LiveReason(&sec);
+  }
+
   if (auto *d = dyn_cast<Defined>(&sym)) {
     auto *relSec = dyn_cast_or_null<InputSectionBase>(d->section);
     if (!relSec)
@@ -119,17 +140,29 @@ void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
     // group/SHF_LINK_ORDER rules (b) if the associated text section should be
     // discarded, marking the LSDA will unnecessarily retain the text section.
     if (!(fromFDE && ((relSec->flags & (SHF_EXECINSTR | SHF_LINK_ORDER)) ||
-                      relSec->nextInSectionGroup)))
-      enqueue(relSec, offset);
+                      relSec->nextInSectionGroup))) {
+      Symbol *canonicalSym = d;
+      if (!ctx.arg.whyLive.empty() && d->isSection()) {
+        if (Symbol *s = relSec->getEnclosingSymbol(offset))
+          canonicalSym = s;
+        else
+          canonicalSym = nullptr;
+      }
+      enqueue(relSec, offset, canonicalSym, reason);
+    }
     return;
   }
 
-  if (auto *ss = dyn_cast<SharedSymbol>(&sym))
-    if (!ss->isWeak())
+  if (auto *ss = dyn_cast<SharedSymbol>(&sym)) {
+    if (!ss->isWeak()) {
       cast<SharedFile>(ss->file)->isNeeded = true;
+      if (!ctx.arg.whyLive.empty())
+        whyLive.try_emplace(&sym, reason);
+    }
+  }
 
   for (InputSectionBase *sec : cNamedSections.lookup(sym.getName()))
-    enqueue(sec, 0);
+    enqueue(sec, 0, nullptr, reason);
 }
 
 // The .eh_frame section is an unfortunate special case.
@@ -187,7 +220,8 @@ static bool isReserved(InputSectionBase *sec) {
 }
 
 template <class ELFT>
-void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset) {
+void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset,
+                             Symbol *sym, std::optional<LiveReason> reason) {
   // Usually, a whole section is marked as live or dead, but in mergeable
   // (splittable) sections, each piece of data has independent liveness bit.
   // So we explicitly tell it which offset is in use.
@@ -201,15 +235,71 @@ void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset) {
     return;
   sec->partition = sec->partition ? 1 : partition;
 
+  if (!ctx.arg.whyLive.empty() && reason) {
+    if (sym) {
+      // If a specific symbol is referenced, that makes it alive. It may in turn
+      // make its section alive.
+      whyLive.try_emplace(sym, *reason);
+      whyLive.try_emplace(sec, sym);
+    } else {
+      // Otherwise, the reference generically makes the section live.
+      whyLive.try_emplace(sec, *reason);
+    }
+  }
+
   // Add input section to the queue.
   if (InputSection *s = dyn_cast<InputSection>(sec))
     queue.push_back(s);
 }
 
+// Print the stack of reasons that the given symbol is live.
+template <class ELFT> void MarkLive<ELFT>::printWhyLive(Symbol *s) const {
+  // Skip dead symbols. A symbol is dead if it belongs to a dead section.
+  if (auto *d = dyn_cast<Defined>(s)) {
+    auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
+    if (reason && !reason->isLive())
+      return;
+  }
+
+  auto msg = Msg(ctx);
+  msg << "live symbol: " << toStr(ctx, *s);
+
+  LiveReason cur = s;
+  while (true) {
+    auto it = whyLive.find(cur);
+    // If there is a specific reason this object is live...
+    if (it != whyLive.end()) {
+      cur = it->second;
+    } else {
+      // This object is live, but it has no tracked reason. It is either
+      // intrinsically live or an unreferenced symbol in a live section. Return
+      // in the first case.
+      if (!std::holds_alternative<Symbol *>(cur))
+        return;
+      auto *d = dyn_cast<Defined>(std::get<Symbol *>(cur));
+      if (!d)
+        return;
+      auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
+      if (!reason)
+        return;
+      cur = LiveReason{reason};
+    }
+
+    msg << "\n>>> kept live by ";
+    if (std::holds_alternative<Symbol *>(cur)) {
+      auto *s = std::get<Symbol *>(cur);
+      msg << toStr(ctx, *s);
+    } else {
+      auto *s = std::get<InputSectionBase *>(cur);
+      msg << toStr(ctx, s);
+    }
+  }
+}
+
 template <class ELFT> void MarkLive<ELFT>::markSymbol(Symbol *sym) {
   if (auto *d = dyn_cast_or_null<Defined>(sym))
     if (auto *isec = dyn_cast_or_null<InputSectionBase>(d->section))
-      enqueue(isec, d->value);
+      enqueue(isec, d->value, sym);
 }
 
 // This is the main function of the garbage collector.
@@ -256,7 +346,7 @@ template <class ELFT> void MarkLive<ELFT>::run() {
   }
   for (InputSectionBase *sec : ctx.inputSections) {
     if (sec->flags & SHF_GNU_RETAIN) {
-      enqueue(sec, 0);
+      enqueue(sec, 0, nullptr, std::nullopt);
       continue;
     }
     if (sec->flags & SHF_LINK_ORDER)
@@ -295,7 +385,7 @@ template <class ELFT> void MarkLive<ELFT>::run() {
     // Preserve special sections and those which are specified in linker
     // script KEEP command.
     if (isReserved(sec) || ctx.script->shouldKeep(sec)) {
-      enqueue(sec, 0);
+      enqueue(sec);
     } else if ((!ctx.arg.zStartStopGC || sec->name.starts_with("__libc_")) &&
                isValidCIdentifier(sec->name)) {
       // As a workaround for glibc libc.a before 2.34
@@ -323,11 +413,20 @@ template <class ELFT> void MarkLive<ELFT>::mark() {
       resolveReloc(sec, rel, false);
 
     for (InputSectionBase *isec : sec.dependentSections)
-      enqueue(isec, 0);
+      enqueue(isec, 0, nullptr, &sec);
 
     // Mark the next group member.
     if (sec.nextInSectionGroup)
-      enqueue(sec.nextInSectionGroup, 0);
+      enqueue(sec.nextInSectionGroup, 0, nullptr, &sec);
+  }
+
+  if (!ctx.arg.whyLive.empty()) {
+    for (Symbol *sym : ctx.symtab->getSymbols()) {
+      if (llvm::any_of(ctx.arg.whyLive, [sym](const llvm::GlobPattern &pat) {
+            return pat.match(sym->getName());
+          }))
+        printWhyLive(sym);
+    }
   }
 }
 
@@ -353,7 +452,7 @@ template <class ELFT> void MarkLive<ELFT>::moveToMain() {
       continue;
     if (ctx.symtab->find(("__start_" + sec->name).str()) ||
         ctx.symtab->find(("__stop_" + sec->name).str()))
-      enqueue(sec, 0);
+      enqueue(sec);
   }
 
   mark();
diff --git a/lld/ELF/Options.td b/lld/ELF/Options.td
index b3b12a0646875..feb24edc6f43a 100644
--- a/lld/ELF/Options.td
+++ b/lld/ELF/Options.td
@@ -572,6 +572,12 @@ defm wrap : Eq<"wrap", "Redirect symbol references to __wrap_symbol and "
                        "__real_symbol references to symbol">,
             MetaVarName<"<symbol>">;
 
+defm why_live
+    : EEq<"why-live",
+          "Report a chain of references preventing garbage collection for "
+          "each symbol matching <glob>">,
+      MetaVarName<"<glob>">;
+
 def z: JoinedOrSeparate<["-"], "z">, MetaVarName<"<option>">,
   HelpText<"Linker option extensions">;
 
diff --git a/lld/test/ELF/why-live.s b/lld/test/ELF/why-live.s
new file mode 100644
index 0000000000000..12d373cd78d28
--- /dev/null
+++ b/lld/test/ELF/why-live.s
@@ -0,0 +1,132 @@
+# REQUIRES: x86
+
+# RUN: llvm-mc -n -filetype=obj -triple=x86_64 %s -o %t.o
+# RUN: echo -e ".globl test_shared\n .section .test_shared,\"ax\",@progbits\n test_shared: jmp test_shared" |\
+# RUN:   llvm-mc -n -filetype=obj -triple=x86_64 -o %t.shared.o
+# RUN: ld.lld -shared %t.shared.o -o %t.so
+
+## Simple live section
+.globl _start
+.section ._start,"ax",@progbits
+_start:
+jmp test_simple
+jmp .Llocal
+jmp .Llocal_within_symbol
+jmp test_shared
+.size _start, .-_start
+
+.globl test_simple
+.section .test_simple,"ax",@progbits
+test_simple:
+jmp test_simple
+jmp test_from_unsized
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_simple | FileCheck %s --check-prefix=SIMPLE
+
+# SIMPLE:      live symbol: test_simple
+# SIMPLE-NEXT: >>> kept live by _start
+
+## Live only by being a member of .test_simple
+.globl test_incidental
+test_incidental:
+jmp test_incidental
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_incidental | FileCheck %s --check-prefix=INCIDENTAL
+
+# INCIDENTAL:      live symbol: test_incidental
+# INCIDENTAL-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
+# INCIDENTAL-NEXT: >>> kept live by test_simple
+# INCIDENTAL-NEXT: >>> kept live by _start
+
+## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
+.globl test_from_unsized
+.section .test_from_unsized,"ax",@progbits
+test_from_unsized:
+jmp test_from_unsized
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_from_unsized | FileCheck %s --check-prefix=FROM-UNSIZED
+
+# FROM-UNSIZED:      live symbol: test_from_unsized
+# FROM-UNSIZED-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
+# FROM-UNSIZED-NEXT: >>> kept live by test_simple
+# FROM-UNSIZED-NEXT: >>> kept live by _start
+
+## Symbols in dead sections are dead and not reported.
+.globl test_dead
+.section .test_dead,"ax",@progbits
+test_dead:
+jmp test_dead
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_dead | count 0
+
+## Undefined symbols are considered live, since they are not in dead sections.
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_undef -u test_undef | FileCheck %s --check-prefix=UNDEFINED
+
+# UNDEFINED:     live symbol: test_undef
+# UNDEFINED-NOT: >>>
+
+## Defined symbols without input section parents are live.
+.globl test_absolute
+test_absolute = 1234
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_absolute | FileCheck %s --check-prefix=ABSOLUTE
+
+# ABSOLUTE:     live symbol: test_absolute
+# ABSOLUTE-NOT: >>>
+
+## Retained sections are intrinsically live, and they make contained symbols live.
+.globl test_retained
+.section .test_retained,"axR",@progbits
+test_retained:
+jmp test_retained
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_retained | FileCheck %s --check-prefix=RETAINED
+
+# RETAINED:      live symbol: test_retained
+# RETAINED-NEXT: >>> kept live by {{.*}}:(.test_retained)
+
+## Relocs that reference offsets from sections (e.g., from local symbols) are considered to point to the section if no enclosing symbol exists.
+
+.globl test_section_offset
+.section .test_section_offset,"ax",@progbits
+test_section_offset:
+jmp test_section_offset
+.Llocal:
+jmp test_section_offset
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
+
+# SECTION-OFFSET:        live symbol: test_section_offset
+# SECTION-OFFSET-NEXT:   >>> kept live by {{.*}}:(.test_section_offset)
+# SECTION-OFFSET-NEXT:   >>> kept live by _start
+
+## Relocs that reference offsets from sections (e.g., from local symbols) are considered to point to the enclosing symbol if one exists.
+
+.globl test_section_offset_within_symbol
+.section .test_section_offset_within_symbol,"ax",@progbits
+test_section_offset_within_symbol:
+jmp test_section_offset_within_symbol
+.Llocal_within_symbol:
+jmp test_section_offset_within_symbol
+.size test_section_offset_within_symbol, .-test_section_offset_within_symbol
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
+
+# SECTION-OFFSET-WITHIN-SYMBOL:        live symbol: test_section_offset_within_symbol
+# SECTION-OFFSET-WITHIN-SYMBOL-NEXT:   >>> kept live by _start
+
+## Shared symbols
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_shared | FileCheck %s --check-prefix=SHARED
+
+# SHARED:      live symbol: test_shared
+# SHARED-NEXT: >>> kept live by _start
+
+## Globs match multiple cases. Multiple --why-live flags union.
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_s* | FileCheck %s --check-prefix=MULTIPLE
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_simple --why-live=test_shared | FileCheck %s --check-prefix=MULTIPLE
+
+# MULTIPLE-DAG: live symbol: test_simple
+# MULTIPLE-DAG: live symbol: test_shared

From 54bbe200eb724d049272f90338c422065cc2f899 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Fri, 7 Mar 2025 10:32:58 -0800
Subject: [PATCH 02/11] Resolve performance issue by templating MarkLive on
 --why-live

---
 lld/ELF/MarkLive.cpp | 77 +++++++++++++++++++++++++-------------------
 1 file changed, 43 insertions(+), 34 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 8e9e385bc26dc..b5fdf0db62cbc 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -48,18 +48,18 @@ namespace {
 // Something that can be the most proximate reason that something else is alive.
 typedef std::variant<InputSectionBase *, Symbol *> LiveReason;
 
-template <class ELFT> class MarkLive {
+template <class ELFT, bool TrackWhyLive> class MarkLive {
 public:
   MarkLive(Ctx &ctx, unsigned partition) : ctx(ctx), partition(partition) {}
 
   void run();
   void moveToMain();
+  void printWhyLive(Symbol *s) const;
 
 private:
   void enqueue(InputSectionBase *sec, uint64_t offset = 0,
                Symbol *sym = nullptr,
                std::optional<LiveReason> reason = std::nullopt);
-  void printWhyLive(Symbol *s) const;
   void markSymbol(Symbol *sym);
   void mark();
 
@@ -108,16 +108,16 @@ static uint64_t getAddend(Ctx &, InputSectionBase &sec,
   return rel.r_addend;
 }
 
-template <class ELFT>
+template <class ELFT, bool TrackWhyLive>
 template <class RelTy>
-void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
-                                  bool fromFDE) {
+void MarkLive<ELFT, TrackWhyLive>::resolveReloc(InputSectionBase &sec,
+                                                RelTy &rel, bool fromFDE) {
   // If a symbol is referenced in a live section, it is used.
   Symbol &sym = sec.file->getRelocTargetSym(rel);
   sym.used = true;
 
-  LiveReason reason;
-  if (!ctx.arg.whyLive.empty()) {
+  std::optional<LiveReason> reason;
+  if (TrackWhyLive) {
     Defined *reasonSym = sec.getEnclosingSymbol(rel.r_offset);
     reason = reasonSym ? LiveReason(reasonSym) : LiveReason(&sec);
   }
@@ -142,7 +142,7 @@ void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
     if (!(fromFDE && ((relSec->flags & (SHF_EXECINSTR | SHF_LINK_ORDER)) ||
                       relSec->nextInSectionGroup))) {
       Symbol *canonicalSym = d;
-      if (!ctx.arg.whyLive.empty() && d->isSection()) {
+      if (TrackWhyLive && d->isSection()) {
         if (Symbol *s = relSec->getEnclosingSymbol(offset))
           canonicalSym = s;
         else
@@ -156,8 +156,8 @@ void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
   if (auto *ss = dyn_cast<SharedSymbol>(&sym)) {
     if (!ss->isWeak()) {
       cast<SharedFile>(ss->file)->isNeeded = true;
-      if (!ctx.arg.whyLive.empty())
-        whyLive.try_emplace(&sym, reason);
+      if (TrackWhyLive)
+        whyLive.try_emplace(&sym, *reason);
     }
   }
 
@@ -179,10 +179,10 @@ void MarkLive<ELFT>::resolveReloc(InputSectionBase &sec, RelTy &rel,
 // A possible improvement would be to fully process .eh_frame in the middle of
 // the gc pass. With that we would be able to also gc some sections holding
 // LSDAs and personality functions if we found that they were unused.
-template <class ELFT>
+template <class ELFT, bool TrackWhyLive>
 template <class RelTy>
-void MarkLive<ELFT>::scanEhFrameSection(EhInputSection &eh,
-                                        ArrayRef<RelTy> rels) {
+void MarkLive<ELFT, TrackWhyLive>::scanEhFrameSection(EhInputSection &eh,
+                                                      ArrayRef<RelTy> rels) {
   for (const EhSectionPiece &cie : eh.cies)
     if (cie.firstRelocation != unsigned(-1))
       resolveReloc(eh, rels[cie.firstRelocation], false);
@@ -219,9 +219,10 @@ static bool isReserved(InputSectionBase *sec) {
   }
 }
 
-template <class ELFT>
-void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset,
-                             Symbol *sym, std::optional<LiveReason> reason) {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::enqueue(InputSectionBase *sec,
+                                           uint64_t offset, Symbol *sym,
+                                           std::optional<LiveReason> reason) {
   // Usually, a whole section is marked as live or dead, but in mergeable
   // (splittable) sections, each piece of data has independent liveness bit.
   // So we explicitly tell it which offset is in use.
@@ -235,7 +236,7 @@ void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset,
     return;
   sec->partition = sec->partition ? 1 : partition;
 
-  if (!ctx.arg.whyLive.empty() && reason) {
+  if (TrackWhyLive && reason) {
     if (sym) {
       // If a specific symbol is referenced, that makes it alive. It may in turn
       // make its section alive.
@@ -253,7 +254,8 @@ void MarkLive<ELFT>::enqueue(InputSectionBase *sec, uint64_t offset,
 }
 
 // Print the stack of reasons that the given symbol is live.
-template <class ELFT> void MarkLive<ELFT>::printWhyLive(Symbol *s) const {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
   // Skip dead symbols. A symbol is dead if it belongs to a dead section.
   if (auto *d = dyn_cast<Defined>(s)) {
     auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
@@ -296,7 +298,8 @@ template <class ELFT> void MarkLive<ELFT>::printWhyLive(Symbol *s) const {
   }
 }
 
-template <class ELFT> void MarkLive<ELFT>::markSymbol(Symbol *sym) {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::markSymbol(Symbol *sym) {
   if (auto *d = dyn_cast_or_null<Defined>(sym))
     if (auto *isec = dyn_cast_or_null<InputSectionBase>(d->section))
       enqueue(isec, d->value, sym);
@@ -305,7 +308,8 @@ template <class ELFT> void MarkLive<ELFT>::markSymbol(Symbol *sym) {
 // This is the main function of the garbage collector.
 // Starting from GC-root sections, this function visits all reachable
 // sections to set their "Live" bits.
-template <class ELFT> void MarkLive<ELFT>::run() {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::run() {
   // Add GC root symbols.
 
   // Preserve externally-visible symbols if the symbols defined by this
@@ -346,7 +350,7 @@ template <class ELFT> void MarkLive<ELFT>::run() {
   }
   for (InputSectionBase *sec : ctx.inputSections) {
     if (sec->flags & SHF_GNU_RETAIN) {
-      enqueue(sec, 0, nullptr, std::nullopt);
+      enqueue(sec);
       continue;
     }
     if (sec->flags & SHF_LINK_ORDER)
@@ -397,9 +401,19 @@ template <class ELFT> void MarkLive<ELFT>::run() {
   }
 
   mark();
+
+  if (TrackWhyLive) {
+    for (Symbol *sym : ctx.symtab->getSymbols()) {
+      if (llvm::any_of(ctx.arg.whyLive, [sym](const llvm::GlobPattern &pat) {
+            return pat.match(sym->getName());
+          }))
+        printWhyLive(sym);
+    }
+  }
 }
 
-template <class ELFT> void MarkLive<ELFT>::mark() {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::mark() {
   // Mark all reachable sections.
   while (!queue.empty()) {
     InputSectionBase &sec = *queue.pop_back_val();
@@ -419,15 +433,6 @@ template <class ELFT> void MarkLive<ELFT>::mark() {
     if (sec.nextInSectionGroup)
       enqueue(sec.nextInSectionGroup, 0, nullptr, &sec);
   }
-
-  if (!ctx.arg.whyLive.empty()) {
-    for (Symbol *sym : ctx.symtab->getSymbols()) {
-      if (llvm::any_of(ctx.arg.whyLive, [sym](const llvm::GlobPattern &pat) {
-            return pat.match(sym->getName());
-          }))
-        printWhyLive(sym);
-    }
-  }
 }
 
 // Move the sections for some symbols to the main partition, specifically ifuncs
@@ -439,7 +444,8 @@ template <class ELFT> void MarkLive<ELFT>::mark() {
 // We also need to move sections whose names are C identifiers that are referred
 // to from __start_/__stop_ symbols because there will only be one set of
 // symbols for the whole program.
-template <class ELFT> void MarkLive<ELFT>::moveToMain() {
+template <class ELFT, bool TrackWhyLive>
+void MarkLive<ELFT, TrackWhyLive>::moveToMain() {
   for (ELFFileBase *file : ctx.objectFiles)
     for (Symbol *s : file->getSymbols())
       if (auto *d = dyn_cast<Defined>(s))
@@ -478,13 +484,16 @@ template <class ELFT> void elf::markLive(Ctx &ctx) {
 
   // Follow the graph to mark all live sections.
   for (unsigned i = 1, e = ctx.partitions.size(); i <= e; ++i)
-    MarkLive<ELFT>(ctx, i).run();
+    if (ctx.arg.whyLive.empty())
+      MarkLive<ELFT, false>(ctx, i).run();
+    else
+      MarkLive<ELFT, true>(ctx, i).run();
 
   // If we have multiple partitions, some sections need to live in the main
   // partition even if they were allocated to a loadable partition. Move them
   // there now.
   if (ctx.partitions.size() != 1)
-    MarkLive<ELFT>(ctx, 1).moveToMain();
+    MarkLive<ELFT, false>(ctx, 1).moveToMain();
 
   // Report garbage-collected sections.
   if (ctx.arg.printGcSections)

From ce1ccc8e690dbc47f0b8f29adc892645b363247d Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <mysterymath@gmail.com>
Date: Sat, 8 Mar 2025 10:03:47 -0800
Subject: [PATCH 03/11] Handle local symbols etc.

- Explicitly track when explicitly live
  - This prevents e.g. _start from being reported live as part of .start.
- Use quad for more control over reloc offsets
---
 lld/ELF/MarkLive.cpp    | 61 +++++++++++++++++++++++++----------------
 lld/test/ELF/why-live.s | 43 +++++++++++++++++++++--------
 2 files changed, 70 insertions(+), 34 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index b5fdf0db62cbc..16a30ed08c8bc 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -80,11 +80,11 @@ template <class ELFT, bool TrackWhyLive> class MarkLive {
   // identifiers, so we just store a SmallVector instead of a multimap.
   DenseMap<StringRef, SmallVector<InputSectionBase *, 0>> cNamedSections;
 
-  // The most proximate reason that something is live. If something doesn't have
-  // a recorded reason, it is either dead, intrinsically live, or an
-  // unreferenced symbol in a live section. (These cases are trivially
-  // detectable and need not be stored.)
-  DenseMap<LiveReason, LiveReason> whyLive;
+  // The most proximate reason that something is live. A nullopt means
+  // "intrinsically live". If something doesn't have a recorded reason, it is
+  // either dead or an unreferenced symbol in a live section. (These cases are
+  // trivially detectable and need not be stored.)
+  DenseMap<LiveReason, std::optional<LiveReason>> whyLive;
 };
 } // namespace
 
@@ -157,7 +157,7 @@ void MarkLive<ELFT, TrackWhyLive>::resolveReloc(InputSectionBase &sec,
     if (!ss->isWeak()) {
       cast<SharedFile>(ss->file)->isNeeded = true;
       if (TrackWhyLive)
-        whyLive.try_emplace(&sym, *reason);
+        whyLive.try_emplace(&sym, reason);
     }
   }
 
@@ -236,15 +236,15 @@ void MarkLive<ELFT, TrackWhyLive>::enqueue(InputSectionBase *sec,
     return;
   sec->partition = sec->partition ? 1 : partition;
 
-  if (TrackWhyLive && reason) {
+  if (TrackWhyLive) {
     if (sym) {
       // If a specific symbol is referenced, that makes it alive. It may in turn
       // make its section alive.
-      whyLive.try_emplace(sym, *reason);
+      whyLive.try_emplace(sym, reason);
       whyLive.try_emplace(sec, sym);
     } else {
       // Otherwise, the reference generically makes the section live.
-      whyLive.try_emplace(sec, *reason);
+      whyLive.try_emplace(sec, reason);
     }
   }
 
@@ -264,11 +264,20 @@ void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
   }
 
   auto msg = Msg(ctx);
-  msg << "live symbol: " << toStr(ctx, *s);
 
-  LiveReason cur = s;
+  const auto printSymbol = [&](Symbol *s) {
+    if (s->isLocal())
+      msg << s->file << ":(" << toStr(ctx, *s) << ')';
+    else
+      msg << toStr(ctx, *s);
+  };
+
+  msg << "live symbol: ";
+  printSymbol(s);
+
+  std::optional<LiveReason> cur = s;
   while (true) {
-    auto it = whyLive.find(cur);
+    auto it = whyLive.find(*cur);
     // If there is a specific reason this object is live...
     if (it != whyLive.end()) {
       cur = it->second;
@@ -276,9 +285,9 @@ void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
       // This object is live, but it has no tracked reason. It is either
       // intrinsically live or an unreferenced symbol in a live section. Return
       // in the first case.
-      if (!std::holds_alternative<Symbol *>(cur))
+      if (!std::holds_alternative<Symbol *>(*cur))
         return;
-      auto *d = dyn_cast<Defined>(std::get<Symbol *>(cur));
+      auto *d = dyn_cast<Defined>(std::get<Symbol *>(*cur));
       if (!d)
         return;
       auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
@@ -286,15 +295,14 @@ void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
         return;
       cur = LiveReason{reason};
     }
+    if (!cur)
+      break;
 
     msg << "\n>>> kept live by ";
-    if (std::holds_alternative<Symbol *>(cur)) {
-      auto *s = std::get<Symbol *>(cur);
-      msg << toStr(ctx, *s);
-    } else {
-      auto *s = std::get<InputSectionBase *>(cur);
-      msg << toStr(ctx, s);
-    }
+    if (std::holds_alternative<Symbol *>(*cur))
+      printSymbol(std::get<Symbol *>(*cur));
+    else
+      msg << toStr(ctx, std::get<InputSectionBase *>(*cur));
   }
 }
 
@@ -403,12 +411,19 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
   mark();
 
   if (TrackWhyLive) {
-    for (Symbol *sym : ctx.symtab->getSymbols()) {
+    const auto handleSym = [&](Symbol *sym) {
       if (llvm::any_of(ctx.arg.whyLive, [sym](const llvm::GlobPattern &pat) {
             return pat.match(sym->getName());
           }))
         printWhyLive(sym);
-    }
+    };
+
+    for (Symbol *sym : ctx.symtab->getSymbols())
+      handleSym(sym);
+    for (ELFFileBase *file : ctx.objectFiles)
+      for (Symbol *sym : file->getSymbols())
+        if (sym->isLocal())
+          handleSym(sym);
   }
 }
 
diff --git a/lld/test/ELF/why-live.s b/lld/test/ELF/why-live.s
index 12d373cd78d28..0cb2d80c57515 100644
--- a/lld/test/ELF/why-live.s
+++ b/lld/test/ELF/why-live.s
@@ -10,9 +10,10 @@
 .section ._start,"ax",@progbits
 _start:
 jmp test_simple
-jmp .Llocal
-jmp .Llocal_within_symbol
+.quad .Lanonymous
+.quad .Lanonymous_within_symbol
 jmp test_shared
+.quad test_local
 .size _start, .-_start
 
 .globl test_simple
@@ -25,6 +26,7 @@ jmp test_from_unsized
 
 # SIMPLE:      live symbol: test_simple
 # SIMPLE-NEXT: >>> kept live by _start
+# SIMPLE-NOT:  >>>
 
 ## Live only by being a member of .test_simple
 .globl test_incidental
@@ -37,6 +39,7 @@ jmp test_incidental
 # INCIDENTAL-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
 # INCIDENTAL-NEXT: >>> kept live by test_simple
 # INCIDENTAL-NEXT: >>> kept live by _start
+# INCIDENTAL-NOT:  >>>
 
 ## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
 .globl test_from_unsized
@@ -50,6 +53,7 @@ jmp test_from_unsized
 # FROM-UNSIZED-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
 # FROM-UNSIZED-NEXT: >>> kept live by test_simple
 # FROM-UNSIZED-NEXT: >>> kept live by _start
+# FROM-UNSIZED-NOT:  >>>
 
 ## Symbols in dead sections are dead and not reported.
 .globl test_dead
@@ -85,36 +89,52 @@ jmp test_retained
 
 # RETAINED:      live symbol: test_retained
 # RETAINED-NEXT: >>> kept live by {{.*}}:(.test_retained)
+# RETAINED-NOT:  >>>
 
-## Relocs that reference offsets from sections (e.g., from local symbols) are considered to point to the section if no enclosing symbol exists.
+## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the section if no enclosing symbol exists.
 
 .globl test_section_offset
 .section .test_section_offset,"ax",@progbits
 test_section_offset:
 jmp test_section_offset
-.Llocal:
+.Lanonymous:
 jmp test_section_offset
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
 
-# SECTION-OFFSET:        live symbol: test_section_offset
-# SECTION-OFFSET-NEXT:   >>> kept live by {{.*}}:(.test_section_offset)
-# SECTION-OFFSET-NEXT:   >>> kept live by _start
+# SECTION-OFFSET:      live symbol: test_section_offset
+# SECTION-OFFSET-NEXT: >>> kept live by {{.*}}:(.test_section_offset)
+# SECTION-OFFSET-NEXT: >>> kept live by _start
+# SECTION-OFFSET-NOT:  >>>
 
-## Relocs that reference offsets from sections (e.g., from local symbols) are considered to point to the enclosing symbol if one exists.
+## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the enclosing symbol if one exists.
 
 .globl test_section_offset_within_symbol
 .section .test_section_offset_within_symbol,"ax",@progbits
 test_section_offset_within_symbol:
 jmp test_section_offset_within_symbol
-.Llocal_within_symbol:
+.Lanonymous_within_symbol:
 jmp test_section_offset_within_symbol
 .size test_section_offset_within_symbol, .-test_section_offset_within_symbol
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
 
-# SECTION-OFFSET-WITHIN-SYMBOL:        live symbol: test_section_offset_within_symbol
-# SECTION-OFFSET-WITHIN-SYMBOL-NEXT:   >>> kept live by _start
+# SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: test_section_offset_within_symbol
+# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> kept live by _start
+# SECTION-OFFSET-WITHIN-SYMBOL-NOT:  >>>
+
+## Local symbols can be queried just like global symbols.
+
+.section .test_local,"ax",@progbits
+test_local:
+jmp test_local
+.size test_local, .-test_local
+
+# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_local | FileCheck %s --check-prefix=LOCAL
+
+# LOCAL:      live symbol: {{.*}}:(test_local)
+# LOCAL-NEXT: >>> kept live by _start
+# LOCAL-NOT:  >>>
 
 ## Shared symbols
 
@@ -122,6 +142,7 @@ jmp test_section_offset_within_symbol
 
 # SHARED:      live symbol: test_shared
 # SHARED-NEXT: >>> kept live by _start
+# SHARED-NOT:  >>>
 
 ## Globs match multiple cases. Multiple --why-live flags union.
 

From dc3a9ca4efdb444f557e322d2a40bbcf81ca27e4 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 12 Mar 2025 14:49:58 -0700
Subject: [PATCH 04/11] Address various review comments

- Prefer "using"
- Defer lookup of sec+offset liveness reasons to printing time
- Indent instructions
- Avoid unnecessary toStr()
- Provide description strings to print with liveness reasons
---
 lld/ELF/MarkLive.cpp    | 141 +++++++++++++++++++++++-----------------
 lld/test/ELF/why-live.s |  62 +++++++++---------
 2 files changed, 111 insertions(+), 92 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 16a30ed08c8bc..96593e2fb1151 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -45,8 +45,16 @@ using namespace lld::elf;
 
 namespace {
 
-// Something that can be the most proximate reason that something else is alive.
-typedef std::variant<InputSectionBase *, Symbol *> LiveReason;
+using SecOffset = std::pair<InputSectionBase*, unsigned>;
+
+// Something that can have an independent reason for being live.
+using LiveObject = std::variant<InputSectionBase *, Symbol *, SecOffset>;
+
+// The most proximate reason that an object is live.
+struct LiveReason {
+  std::optional<LiveObject> obj;
+  StringRef desc;
+};
 
 template <class ELFT, bool TrackWhyLive> class MarkLive {
 public:
@@ -57,10 +65,9 @@ template <class ELFT, bool TrackWhyLive> class MarkLive {
   void printWhyLive(Symbol *s) const;
 
 private:
-  void enqueue(InputSectionBase *sec, uint64_t offset = 0,
-               Symbol *sym = nullptr,
-               std::optional<LiveReason> reason = std::nullopt);
-  void markSymbol(Symbol *sym);
+  void enqueue(InputSectionBase *sec, uint64_t offset, Symbol *sym,
+               LiveReason reason);
+  void markSymbol(Symbol *sym, StringRef reason);
   void mark();
 
   template <class RelTy>
@@ -80,11 +87,8 @@ template <class ELFT, bool TrackWhyLive> class MarkLive {
   // identifiers, so we just store a SmallVector instead of a multimap.
   DenseMap<StringRef, SmallVector<InputSectionBase *, 0>> cNamedSections;
 
-  // The most proximate reason that something is live. A nullopt means
-  // "intrinsically live". If something doesn't have a recorded reason, it is
-  // either dead or an unreferenced symbol in a live section. (These cases are
-  // trivially detectable and need not be stored.)
-  DenseMap<LiveReason, std::optional<LiveReason>> whyLive;
+  // The most proximate reason that something is live.
+  DenseMap<LiveObject, LiveReason> whyLive;
 };
 } // namespace
 
@@ -116,11 +120,9 @@ void MarkLive<ELFT, TrackWhyLive>::resolveReloc(InputSectionBase &sec,
   Symbol &sym = sec.file->getRelocTargetSym(rel);
   sym.used = true;
 
-  std::optional<LiveReason> reason;
-  if (TrackWhyLive) {
-    Defined *reasonSym = sec.getEnclosingSymbol(rel.r_offset);
-    reason = reasonSym ? LiveReason(reasonSym) : LiveReason(&sec);
-  }
+  LiveReason reason;
+  if (TrackWhyLive)
+    reason = {SecOffset(&sec, rel.r_offset), "referenced by"};
 
   if (auto *d = dyn_cast<Defined>(&sym)) {
     auto *relSec = dyn_cast_or_null<InputSectionBase>(d->section);
@@ -222,7 +224,7 @@ static bool isReserved(InputSectionBase *sec) {
 template <class ELFT, bool TrackWhyLive>
 void MarkLive<ELFT, TrackWhyLive>::enqueue(InputSectionBase *sec,
                                            uint64_t offset, Symbol *sym,
-                                           std::optional<LiveReason> reason) {
+                                           LiveReason reason) {
   // Usually, a whole section is marked as live or dead, but in mergeable
   // (splittable) sections, each piece of data has independent liveness bit.
   // So we explicitly tell it which offset is in use.
@@ -241,7 +243,7 @@ void MarkLive<ELFT, TrackWhyLive>::enqueue(InputSectionBase *sec,
       // If a specific symbol is referenced, that makes it alive. It may in turn
       // make its section alive.
       whyLive.try_emplace(sym, reason);
-      whyLive.try_emplace(sec, sym);
+      whyLive.try_emplace(sec, LiveReason{sym, "contained live symbol"});
     } else {
       // Otherwise, the reference generically makes the section live.
       whyLive.try_emplace(sec, reason);
@@ -258,8 +260,8 @@ template <class ELFT, bool TrackWhyLive>
 void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
   // Skip dead symbols. A symbol is dead if it belongs to a dead section.
   if (auto *d = dyn_cast<Defined>(s)) {
-    auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
-    if (reason && !reason->isLive())
+    auto *sec = dyn_cast_or_null<InputSectionBase>(d->section);
+    if (sec && !sec->isLive())
       return;
   }
 
@@ -267,50 +269,64 @@ void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
 
   const auto printSymbol = [&](Symbol *s) {
     if (s->isLocal())
-      msg << s->file << ":(" << toStr(ctx, *s) << ')';
+      msg << s->file << ":(" << s << ')';
     else
-      msg << toStr(ctx, *s);
+      msg << s;
   };
 
   msg << "live symbol: ";
   printSymbol(s);
 
-  std::optional<LiveReason> cur = s;
+  LiveObject cur = s;
   while (true) {
-    auto it = whyLive.find(*cur);
+    auto it = whyLive.find(cur);
+    LiveReason reason;
     // If there is a specific reason this object is live...
     if (it != whyLive.end()) {
-      cur = it->second;
+      reason = it->second;
     } else {
-      // This object is live, but it has no tracked reason. It is either
-      // intrinsically live or an unreferenced symbol in a live section. Return
-      // in the first case.
-      if (!std::holds_alternative<Symbol *>(*cur))
-        return;
-      auto *d = dyn_cast<Defined>(std::get<Symbol *>(*cur));
-      if (!d)
-        return;
-      auto *reason = dyn_cast_or_null<InputSectionBase>(d->section);
-      if (!reason)
-        return;
-      cur = LiveReason{reason};
+      // This object is live, but it has no tracked reason. It must be an
+      // unreferenced symbol in a live section or a symbol with no section.
+      const auto getParentSec = [&]() -> InputSectionBase * {
+        auto *d = dyn_cast<Defined>(std::get<Symbol *>(cur));
+        if (!d)
+          return nullptr;
+        return dyn_cast_or_null<InputSectionBase>(d->section);
+      };
+      InputSectionBase *sec = getParentSec();
+      reason = sec ? LiveReason{sec, "in live section"}
+                   : LiveReason{std::nullopt, "no section"};
     }
-    if (!cur)
-      break;
 
-    msg << "\n>>> kept live by ";
-    if (std::holds_alternative<Symbol *>(*cur))
-      printSymbol(std::get<Symbol *>(*cur));
-    else
-      msg << toStr(ctx, std::get<InputSectionBase *>(*cur));
+    if (reason.obj) {
+      msg << "\n>>> " << reason.desc << ": ";
+      // The reason may not yet have been resolved to a symbol; do so now.
+      if (std::holds_alternative<SecOffset>(*reason.obj)) {
+        const auto &so = std::get<SecOffset>(*reason.obj);
+        InputSectionBase *sec = so.first;
+        Defined *sym = sec->getEnclosingSymbol(so.second);
+        cur = sym ? LiveObject(sym) : LiveObject(sec);
+      } else {
+        cur = *reason.obj;
+      }
+
+      if (std::holds_alternative<Symbol *>(cur))
+        printSymbol(std::get<Symbol *>(cur));
+      else
+        msg << std::get<InputSectionBase *>(cur);
+    }
+    if (!reason.obj) {
+      msg << " (" << reason.desc << ')';
+      break;
+    }
   }
 }
 
 template <class ELFT, bool TrackWhyLive>
-void MarkLive<ELFT, TrackWhyLive>::markSymbol(Symbol *sym) {
+void MarkLive<ELFT, TrackWhyLive>::markSymbol(Symbol *sym, StringRef reason) {
   if (auto *d = dyn_cast_or_null<Defined>(sym))
     if (auto *isec = dyn_cast_or_null<InputSectionBase>(d->section))
-      enqueue(isec, d->value, sym);
+      enqueue(isec, d->value, sym, {std::nullopt, reason});
 }
 
 // This is the main function of the garbage collector.
@@ -324,7 +340,7 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
   // file can interpose other ELF file's symbols at runtime.
   for (Symbol *sym : ctx.symtab->getSymbols())
     if (sym->isExported && sym->partition == partition)
-      markSymbol(sym);
+      markSymbol(sym, "externally visible symbol; may interpose");
 
   // If this isn't the main partition, that's all that we need to preserve.
   if (partition != 1) {
@@ -332,16 +348,16 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
     return;
   }
 
-  markSymbol(ctx.symtab->find(ctx.arg.entry));
-  markSymbol(ctx.symtab->find(ctx.arg.init));
-  markSymbol(ctx.symtab->find(ctx.arg.fini));
+  markSymbol(ctx.symtab->find(ctx.arg.entry), "entry point");
+  markSymbol(ctx.symtab->find(ctx.arg.init), "initializer function");
+  markSymbol(ctx.symtab->find(ctx.arg.fini), "finalizer function");
   for (StringRef s : ctx.arg.undefined)
-    markSymbol(ctx.symtab->find(s));
+    markSymbol(ctx.symtab->find(s), "undefined command line flag");
   for (StringRef s : ctx.script->referencedSymbols)
-    markSymbol(ctx.symtab->find(s));
+    markSymbol(ctx.symtab->find(s), "referenced by linker script");
   for (auto [symName, _] : ctx.symtab->cmseSymMap) {
-    markSymbol(ctx.symtab->cmseSymMap[symName].sym);
-    markSymbol(ctx.symtab->cmseSymMap[symName].acleSeSym);
+    markSymbol(ctx.symtab->cmseSymMap[symName].sym, "ARM CMSE symbol");
+    markSymbol(ctx.symtab->cmseSymMap[symName].acleSeSym, "ARM CMSE symbol");
   }
 
   // Mark .eh_frame sections as live because there are usually no relocations
@@ -358,7 +374,7 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
   }
   for (InputSectionBase *sec : ctx.inputSections) {
     if (sec->flags & SHF_GNU_RETAIN) {
-      enqueue(sec);
+      enqueue(sec, 0, nullptr, {std::nullopt, "retained"});
       continue;
     }
     if (sec->flags & SHF_LINK_ORDER)
@@ -396,8 +412,10 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
 
     // Preserve special sections and those which are specified in linker
     // script KEEP command.
-    if (isReserved(sec) || ctx.script->shouldKeep(sec)) {
-      enqueue(sec);
+    if (isReserved(sec)) {
+      enqueue(sec, 0, nullptr, {std::nullopt, "reserved"});
+    } else if (ctx.script->shouldKeep(sec)) {
+      enqueue(sec, 0, nullptr, {std::nullopt, "KEEP in linker script"});
     } else if ((!ctx.arg.zStartStopGC || sec->name.starts_with("__libc_")) &&
                isValidCIdentifier(sec->name)) {
       // As a workaround for glibc libc.a before 2.34
@@ -442,11 +460,12 @@ void MarkLive<ELFT, TrackWhyLive>::mark() {
       resolveReloc(sec, rel, false);
 
     for (InputSectionBase *isec : sec.dependentSections)
-      enqueue(isec, 0, nullptr, &sec);
+      enqueue(isec, 0, nullptr, {&sec, "dependent section"});
 
     // Mark the next group member.
     if (sec.nextInSectionGroup)
-      enqueue(sec.nextInSectionGroup, 0, nullptr, &sec);
+      enqueue(sec.nextInSectionGroup, 0, nullptr,
+              {&sec, "next in section group"});
   }
 }
 
@@ -466,14 +485,14 @@ void MarkLive<ELFT, TrackWhyLive>::moveToMain() {
       if (auto *d = dyn_cast<Defined>(s))
         if ((d->type == STT_GNU_IFUNC || d->type == STT_TLS) && d->section &&
             d->section->isLive())
-          markSymbol(s);
+          markSymbol(s, {});
 
   for (InputSectionBase *sec : ctx.inputSections) {
     if (!sec->isLive() || !isValidCIdentifier(sec->name))
       continue;
     if (ctx.symtab->find(("__start_" + sec->name).str()) ||
         ctx.symtab->find(("__stop_" + sec->name).str()))
-      enqueue(sec);
+      enqueue(sec, 0, nullptr, {});
   }
 
   mark();
diff --git a/lld/test/ELF/why-live.s b/lld/test/ELF/why-live.s
index 0cb2d80c57515..2da66afa3f373 100644
--- a/lld/test/ELF/why-live.s
+++ b/lld/test/ELF/why-live.s
@@ -9,57 +9,57 @@
 .globl _start
 .section ._start,"ax",@progbits
 _start:
-jmp test_simple
-.quad .Lanonymous
-.quad .Lanonymous_within_symbol
-jmp test_shared
-.quad test_local
+  jmp test_simple
+  .quad .Lanonymous
+  .quad .Lanonymous_within_symbol
+  jmp test_shared
+  .quad test_local
 .size _start, .-_start
 
 .globl test_simple
 .section .test_simple,"ax",@progbits
 test_simple:
-jmp test_simple
-jmp test_from_unsized
+  jmp test_simple
+  jmp test_from_unsized
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_simple | FileCheck %s --check-prefix=SIMPLE
 
 # SIMPLE:      live symbol: test_simple
-# SIMPLE-NEXT: >>> kept live by _start
+# SIMPLE-NEXT: >>> referenced by: _start (entry point)
 # SIMPLE-NOT:  >>>
 
 ## Live only by being a member of .test_simple
 .globl test_incidental
 test_incidental:
-jmp test_incidental
+  jmp test_incidental
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_incidental | FileCheck %s --check-prefix=INCIDENTAL
 
 # INCIDENTAL:      live symbol: test_incidental
-# INCIDENTAL-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
-# INCIDENTAL-NEXT: >>> kept live by test_simple
-# INCIDENTAL-NEXT: >>> kept live by _start
+# INCIDENTAL-NEXT: >>> in live section: {{.*}}.o:(.test_simple)
+# INCIDENTAL-NEXT: >>> contained live symbol: test_simple
+# INCIDENTAL-NEXT: >>> referenced by: _start (entry point)
 # INCIDENTAL-NOT:  >>>
 
 ## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
 .globl test_from_unsized
 .section .test_from_unsized,"ax",@progbits
 test_from_unsized:
-jmp test_from_unsized
+  jmp test_from_unsized
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_from_unsized | FileCheck %s --check-prefix=FROM-UNSIZED
 
 # FROM-UNSIZED:      live symbol: test_from_unsized
-# FROM-UNSIZED-NEXT: >>> kept live by {{.*}}.o:(.test_simple)
-# FROM-UNSIZED-NEXT: >>> kept live by test_simple
-# FROM-UNSIZED-NEXT: >>> kept live by _start
+# FROM-UNSIZED-NEXT: >>> referenced by: {{.*}}.o:(.test_simple)
+# FROM-UNSIZED-NEXT: >>> contained live symbol: test_simple
+# FROM-UNSIZED-NEXT: >>> referenced by: _start (entry point)
 # FROM-UNSIZED-NOT:  >>>
 
 ## Symbols in dead sections are dead and not reported.
 .globl test_dead
 .section .test_dead,"ax",@progbits
 test_dead:
-jmp test_dead
+  jmp test_dead
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_dead | count 0
 
@@ -67,7 +67,7 @@ jmp test_dead
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_undef -u test_undef | FileCheck %s --check-prefix=UNDEFINED
 
-# UNDEFINED:     live symbol: test_undef
+# UNDEFINED:     live symbol: test_undef (no section)
 # UNDEFINED-NOT: >>>
 
 ## Defined symbols without input section parents are live.
@@ -76,19 +76,19 @@ test_absolute = 1234
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_absolute | FileCheck %s --check-prefix=ABSOLUTE
 
-# ABSOLUTE:     live symbol: test_absolute
+# ABSOLUTE:     live symbol: test_absolute (no section)
 # ABSOLUTE-NOT: >>>
 
 ## Retained sections are intrinsically live, and they make contained symbols live.
 .globl test_retained
 .section .test_retained,"axR",@progbits
 test_retained:
-jmp test_retained
+  jmp test_retained
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_retained | FileCheck %s --check-prefix=RETAINED
 
 # RETAINED:      live symbol: test_retained
-# RETAINED-NEXT: >>> kept live by {{.*}}:(.test_retained)
+# RETAINED-NEXT: >>> in live section: {{.*}}:(.test_retained) (retained)
 # RETAINED-NOT:  >>>
 
 ## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the section if no enclosing symbol exists.
@@ -96,15 +96,15 @@ jmp test_retained
 .globl test_section_offset
 .section .test_section_offset,"ax",@progbits
 test_section_offset:
-jmp test_section_offset
+  jmp test_section_offset
 .Lanonymous:
-jmp test_section_offset
+  jmp test_section_offset
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
 
 # SECTION-OFFSET:      live symbol: test_section_offset
-# SECTION-OFFSET-NEXT: >>> kept live by {{.*}}:(.test_section_offset)
-# SECTION-OFFSET-NEXT: >>> kept live by _start
+# SECTION-OFFSET-NEXT: >>> in live section: {{.*}}:(.test_section_offset)
+# SECTION-OFFSET-NEXT: >>> referenced by: _start (entry point)
 # SECTION-OFFSET-NOT:  >>>
 
 ## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the enclosing symbol if one exists.
@@ -112,28 +112,28 @@ jmp test_section_offset
 .globl test_section_offset_within_symbol
 .section .test_section_offset_within_symbol,"ax",@progbits
 test_section_offset_within_symbol:
-jmp test_section_offset_within_symbol
+  jmp test_section_offset_within_symbol
 .Lanonymous_within_symbol:
-jmp test_section_offset_within_symbol
+  jmp test_section_offset_within_symbol
 .size test_section_offset_within_symbol, .-test_section_offset_within_symbol
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
 
 # SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: test_section_offset_within_symbol
-# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> kept live by _start
+# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> referenced by: _start (entry point)
 # SECTION-OFFSET-WITHIN-SYMBOL-NOT:  >>>
 
 ## Local symbols can be queried just like global symbols.
 
 .section .test_local,"ax",@progbits
 test_local:
-jmp test_local
+  jmp test_local
 .size test_local, .-test_local
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_local | FileCheck %s --check-prefix=LOCAL
 
 # LOCAL:      live symbol: {{.*}}:(test_local)
-# LOCAL-NEXT: >>> kept live by _start
+# LOCAL-NEXT: >>> referenced by: _start (entry point)
 # LOCAL-NOT:  >>>
 
 ## Shared symbols
@@ -141,7 +141,7 @@ jmp test_local
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_shared | FileCheck %s --check-prefix=SHARED
 
 # SHARED:      live symbol: test_shared
-# SHARED-NEXT: >>> kept live by _start
+# SHARED-NEXT: >>> referenced by: _start (entry point)
 # SHARED-NOT:  >>>
 
 ## Globs match multiple cases. Multiple --why-live flags union.

From a331dda44afc20768e9b13f975a0c65992cc3587 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <mysterymath@gmail.com>
Date: Fri, 14 Mar 2025 15:23:38 -0700
Subject: [PATCH 05/11] clang-format fix

---
 lld/ELF/MarkLive.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 96593e2fb1151..219c9d4a6ce85 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -45,7 +45,7 @@ using namespace lld::elf;
 
 namespace {
 
-using SecOffset = std::pair<InputSectionBase*, unsigned>;
+using SecOffset = std::pair<InputSectionBase *, unsigned>;
 
 // Something that can have an independent reason for being live.
 using LiveObject = std::variant<InputSectionBase *, Symbol *, SecOffset>;

From 3d9c2ee557adcfe8a47cfdccf2c751017af1df6d Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 19 Mar 2025 13:59:17 -0700
Subject: [PATCH 06/11] Address review feedback

- LiveObject -> LiveItem
- nit: alive -> live
- Prefer "keeps live" to "(may) make live"
- Inline getParentSec lambda
- Always print symbol file
- reason.item guard clause
- Use /*offset=*/ and /*sym=*/ for enqueue
- Update ld.lld.1
---
 lld/ELF/MarkLive.cpp    | 85 +++++++++++++++++++----------------------
 lld/ELF/Options.td      |  8 ++--
 lld/docs/ld.lld.1       |  2 +
 lld/test/ELF/why-live.s | 42 ++++++++++----------
 4 files changed, 66 insertions(+), 71 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 219c9d4a6ce85..1742e6844c055 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -48,11 +48,11 @@ namespace {
 using SecOffset = std::pair<InputSectionBase *, unsigned>;
 
 // Something that can have an independent reason for being live.
-using LiveObject = std::variant<InputSectionBase *, Symbol *, SecOffset>;
+using LiveItem = std::variant<InputSectionBase *, Symbol *, SecOffset>;
 
-// The most proximate reason that an object is live.
+// The most proximate reason that something is live.
 struct LiveReason {
-  std::optional<LiveObject> obj;
+  std::optional<LiveItem> item;
   StringRef desc;
 };
 
@@ -88,7 +88,7 @@ template <class ELFT, bool TrackWhyLive> class MarkLive {
   DenseMap<StringRef, SmallVector<InputSectionBase *, 0>> cNamedSections;
 
   // The most proximate reason that something is live.
-  DenseMap<LiveObject, LiveReason> whyLive;
+  DenseMap<LiveItem, LiveReason> whyLive;
 };
 } // namespace
 
@@ -164,7 +164,7 @@ void MarkLive<ELFT, TrackWhyLive>::resolveReloc(InputSectionBase &sec,
   }
 
   for (InputSectionBase *sec : cNamedSections.lookup(sym.getName()))
-    enqueue(sec, 0, nullptr, reason);
+    enqueue(sec, /*offset=*/0, /*sym=*/nullptr, reason);
 }
 
 // The .eh_frame section is an unfortunate special case.
@@ -240,12 +240,12 @@ void MarkLive<ELFT, TrackWhyLive>::enqueue(InputSectionBase *sec,
 
   if (TrackWhyLive) {
     if (sym) {
-      // If a specific symbol is referenced, that makes it alive. It may in turn
-      // make its section alive.
+      // If a specific symbol is referenced, that keeps it live. The symbol then
+      // keeps its section live.
       whyLive.try_emplace(sym, reason);
       whyLive.try_emplace(sec, LiveReason{sym, "contained live symbol"});
     } else {
-      // Otherwise, the reference generically makes the section live.
+      // Otherwise, the reference generically keeps the section live.
       whyLive.try_emplace(sec, reason);
     }
   }
@@ -268,57 +268,49 @@ void MarkLive<ELFT, TrackWhyLive>::printWhyLive(Symbol *s) const {
   auto msg = Msg(ctx);
 
   const auto printSymbol = [&](Symbol *s) {
-    if (s->isLocal())
-      msg << s->file << ":(" << s << ')';
-    else
-      msg << s;
+    msg << s->file << ":(" << s << ')';
   };
 
   msg << "live symbol: ";
   printSymbol(s);
 
-  LiveObject cur = s;
+  LiveItem cur = s;
   while (true) {
     auto it = whyLive.find(cur);
     LiveReason reason;
-    // If there is a specific reason this object is live...
+    // If there is a specific reason this item is live...
     if (it != whyLive.end()) {
       reason = it->second;
     } else {
-      // This object is live, but it has no tracked reason. It must be an
+      // This item is live, but it has no tracked reason. It must be an
       // unreferenced symbol in a live section or a symbol with no section.
-      const auto getParentSec = [&]() -> InputSectionBase * {
-        auto *d = dyn_cast<Defined>(std::get<Symbol *>(cur));
-        if (!d)
-          return nullptr;
-        return dyn_cast_or_null<InputSectionBase>(d->section);
-      };
-      InputSectionBase *sec = getParentSec();
+      InputSectionBase *sec = nullptr;
+      if (auto *d = dyn_cast<Defined>(std::get<Symbol *>(cur)))
+        sec = dyn_cast_or_null<InputSectionBase>(d->section);
       reason = sec ? LiveReason{sec, "in live section"}
                    : LiveReason{std::nullopt, "no section"};
     }
 
-    if (reason.obj) {
-      msg << "\n>>> " << reason.desc << ": ";
-      // The reason may not yet have been resolved to a symbol; do so now.
-      if (std::holds_alternative<SecOffset>(*reason.obj)) {
-        const auto &so = std::get<SecOffset>(*reason.obj);
-        InputSectionBase *sec = so.first;
-        Defined *sym = sec->getEnclosingSymbol(so.second);
-        cur = sym ? LiveObject(sym) : LiveObject(sec);
-      } else {
-        cur = *reason.obj;
-      }
-
-      if (std::holds_alternative<Symbol *>(cur))
-        printSymbol(std::get<Symbol *>(cur));
-      else
-        msg << std::get<InputSectionBase *>(cur);
-    }
-    if (!reason.obj) {
+    if (!reason.item) {
       msg << " (" << reason.desc << ')';
       break;
     }
+
+    msg << "\n>>> " << reason.desc << ": ";
+    // The reason may not yet have been resolved to a symbol; do so now.
+    if (std::holds_alternative<SecOffset>(*reason.item)) {
+      const auto &so = std::get<SecOffset>(*reason.item);
+      InputSectionBase *sec = so.first;
+      Defined *sym = sec->getEnclosingSymbol(so.second);
+      cur = sym ? LiveItem(sym) : LiveItem(sec);
+    } else {
+      cur = *reason.item;
+    }
+
+    if (std::holds_alternative<Symbol *>(cur))
+      printSymbol(std::get<Symbol *>(cur));
+    else
+      msg << std::get<InputSectionBase *>(cur);
   }
 }
 
@@ -374,7 +366,7 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
   }
   for (InputSectionBase *sec : ctx.inputSections) {
     if (sec->flags & SHF_GNU_RETAIN) {
-      enqueue(sec, 0, nullptr, {std::nullopt, "retained"});
+      enqueue(sec, /*offset=*/0, /*sym=*/nullptr, {std::nullopt, "retained"});
       continue;
     }
     if (sec->flags & SHF_LINK_ORDER)
@@ -413,9 +405,10 @@ void MarkLive<ELFT, TrackWhyLive>::run() {
     // Preserve special sections and those which are specified in linker
     // script KEEP command.
     if (isReserved(sec)) {
-      enqueue(sec, 0, nullptr, {std::nullopt, "reserved"});
+      enqueue(sec, /*offset=*/0, /*sym=*/nullptr, {std::nullopt, "reserved"});
     } else if (ctx.script->shouldKeep(sec)) {
-      enqueue(sec, 0, nullptr, {std::nullopt, "KEEP in linker script"});
+      enqueue(sec, /*offset=*/0, /*sym=*/nullptr,
+              {std::nullopt, "KEEP in linker script"});
     } else if ((!ctx.arg.zStartStopGC || sec->name.starts_with("__libc_")) &&
                isValidCIdentifier(sec->name)) {
       // As a workaround for glibc libc.a before 2.34
@@ -460,11 +453,11 @@ void MarkLive<ELFT, TrackWhyLive>::mark() {
       resolveReloc(sec, rel, false);
 
     for (InputSectionBase *isec : sec.dependentSections)
-      enqueue(isec, 0, nullptr, {&sec, "dependent section"});
+      enqueue(isec, /*offset=*/0, /*sym=*/nullptr, {&sec, "dependent section"});
 
     // Mark the next group member.
     if (sec.nextInSectionGroup)
-      enqueue(sec.nextInSectionGroup, 0, nullptr,
+      enqueue(sec.nextInSectionGroup, /*offset=*/0, /*sym=*/nullptr,
               {&sec, "next in section group"});
   }
 }
@@ -492,7 +485,7 @@ void MarkLive<ELFT, TrackWhyLive>::moveToMain() {
       continue;
     if (ctx.symtab->find(("__start_" + sec->name).str()) ||
         ctx.symtab->find(("__stop_" + sec->name).str()))
-      enqueue(sec, 0, nullptr, {});
+      enqueue(sec, /*offset=*/0, /*sym=*/nullptr, /*reason=*/{});
   }
 
   mark();
diff --git a/lld/ELF/Options.td b/lld/ELF/Options.td
index feb24edc6f43a..62d8f49acde39 100644
--- a/lld/ELF/Options.td
+++ b/lld/ELF/Options.td
@@ -568,16 +568,16 @@ defm whole_archive: B<"whole-archive",
 
 def why_extract: JJ<"why-extract=">, HelpText<"Print to a file about why archive members are extracted">;
 
-defm wrap : Eq<"wrap", "Redirect symbol references to __wrap_symbol and "
-                       "__real_symbol references to symbol">,
-            MetaVarName<"<symbol>">;
-
 defm why_live
     : EEq<"why-live",
           "Report a chain of references preventing garbage collection for "
           "each symbol matching <glob>">,
       MetaVarName<"<glob>">;
 
+defm wrap : Eq<"wrap", "Redirect symbol references to __wrap_symbol and "
+                       "__real_symbol references to symbol">,
+            MetaVarName<"<symbol>">;
+
 def z: JoinedOrSeparate<["-"], "z">, MetaVarName<"<option>">,
   HelpText<"Linker option extensions">;
 
diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index b5c1816ce6e5f..953cf665f2b4f 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -755,6 +755,8 @@ Report unresolved symbols as warnings.
 Force load of all members in a static library.
 .It Fl -why-extract Ns = Ns Ar file
 Print to a file about why archive members are extracted.
+.It Fl --why-live Ns = Ns Ar glob
+Report a chain of references preventing garbage collection for each symbol matching the glob.
 .It Fl -wrap Ns = Ns Ar symbol
 Redirect
 .Ar symbol
diff --git a/lld/test/ELF/why-live.s b/lld/test/ELF/why-live.s
index 2da66afa3f373..9b709c301df74 100644
--- a/lld/test/ELF/why-live.s
+++ b/lld/test/ELF/why-live.s
@@ -24,8 +24,8 @@ test_simple:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_simple | FileCheck %s --check-prefix=SIMPLE
 
-# SIMPLE:      live symbol: test_simple
-# SIMPLE-NEXT: >>> referenced by: _start (entry point)
+# SIMPLE:      live symbol: {{.*}}.o:(test_simple)
+# SIMPLE-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # SIMPLE-NOT:  >>>
 
 ## Live only by being a member of .test_simple
@@ -35,10 +35,10 @@ test_incidental:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_incidental | FileCheck %s --check-prefix=INCIDENTAL
 
-# INCIDENTAL:      live symbol: test_incidental
+# INCIDENTAL:      live symbol: {{.*}}.o:(test_incidental)
 # INCIDENTAL-NEXT: >>> in live section: {{.*}}.o:(.test_simple)
-# INCIDENTAL-NEXT: >>> contained live symbol: test_simple
-# INCIDENTAL-NEXT: >>> referenced by: _start (entry point)
+# INCIDENTAL-NEXT: >>> contained live symbol: {{.*}}.o:(test_simple)
+# INCIDENTAL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # INCIDENTAL-NOT:  >>>
 
 ## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
@@ -49,10 +49,10 @@ test_from_unsized:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_from_unsized | FileCheck %s --check-prefix=FROM-UNSIZED
 
-# FROM-UNSIZED:      live symbol: test_from_unsized
+# FROM-UNSIZED:      live symbol: {{.*}}.o:(test_from_unsized)
 # FROM-UNSIZED-NEXT: >>> referenced by: {{.*}}.o:(.test_simple)
-# FROM-UNSIZED-NEXT: >>> contained live symbol: test_simple
-# FROM-UNSIZED-NEXT: >>> referenced by: _start (entry point)
+# FROM-UNSIZED-NEXT: >>> contained live symbol: {{.*}}.o:(test_simple)
+# FROM-UNSIZED-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # FROM-UNSIZED-NOT:  >>>
 
 ## Symbols in dead sections are dead and not reported.
@@ -67,7 +67,7 @@ test_dead:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_undef -u test_undef | FileCheck %s --check-prefix=UNDEFINED
 
-# UNDEFINED:     live symbol: test_undef (no section)
+# UNDEFINED:     live symbol: <internal>:(test_undef) (no section)
 # UNDEFINED-NOT: >>>
 
 ## Defined symbols without input section parents are live.
@@ -76,7 +76,7 @@ test_absolute = 1234
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_absolute | FileCheck %s --check-prefix=ABSOLUTE
 
-# ABSOLUTE:     live symbol: test_absolute (no section)
+# ABSOLUTE:     live symbol: {{.*}}.o:(test_absolute) (no section)
 # ABSOLUTE-NOT: >>>
 
 ## Retained sections are intrinsically live, and they make contained symbols live.
@@ -87,7 +87,7 @@ test_retained:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_retained | FileCheck %s --check-prefix=RETAINED
 
-# RETAINED:      live symbol: test_retained
+# RETAINED:      live symbol: {{.*}}.o:(test_retained)
 # RETAINED-NEXT: >>> in live section: {{.*}}:(.test_retained) (retained)
 # RETAINED-NOT:  >>>
 
@@ -102,9 +102,9 @@ test_section_offset:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
 
-# SECTION-OFFSET:      live symbol: test_section_offset
+# SECTION-OFFSET:      live symbol: {{.*}}.o:(test_section_offset)
 # SECTION-OFFSET-NEXT: >>> in live section: {{.*}}:(.test_section_offset)
-# SECTION-OFFSET-NEXT: >>> referenced by: _start (entry point)
+# SECTION-OFFSET-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # SECTION-OFFSET-NOT:  >>>
 
 ## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the enclosing symbol if one exists.
@@ -119,8 +119,8 @@ test_section_offset_within_symbol:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
 
-# SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: test_section_offset_within_symbol
-# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> referenced by: _start (entry point)
+# SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: {{.*}}.o:(test_section_offset_within_symbol)
+# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # SECTION-OFFSET-WITHIN-SYMBOL-NOT:  >>>
 
 ## Local symbols can be queried just like global symbols.
@@ -132,16 +132,16 @@ test_local:
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_local | FileCheck %s --check-prefix=LOCAL
 
-# LOCAL:      live symbol: {{.*}}:(test_local)
-# LOCAL-NEXT: >>> referenced by: _start (entry point)
+# LOCAL:      live symbol: {{.*}}.o:(test_local)
+# LOCAL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # LOCAL-NOT:  >>>
 
 ## Shared symbols
 
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_shared | FileCheck %s --check-prefix=SHARED
 
-# SHARED:      live symbol: test_shared
-# SHARED-NEXT: >>> referenced by: _start (entry point)
+# SHARED:      live symbol: {{.*}}.so:(test_shared)
+# SHARED-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
 # SHARED-NOT:  >>>
 
 ## Globs match multiple cases. Multiple --why-live flags union.
@@ -149,5 +149,5 @@ test_local:
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_s* | FileCheck %s --check-prefix=MULTIPLE
 # RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_simple --why-live=test_shared | FileCheck %s --check-prefix=MULTIPLE
 
-# MULTIPLE-DAG: live symbol: test_simple
-# MULTIPLE-DAG: live symbol: test_shared
+# MULTIPLE-DAG: live symbol: {{.*}}.o:(test_simple)
+# MULTIPLE-DAG: live symbol: {{.*}}.so:(test_shared)

From 93c58660811b8dd824aa82850c66148ca674dc80 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <mysterymath@gmail.com>
Date: Wed, 19 Mar 2025 19:46:51 -0700
Subject: [PATCH 07/11] A few nits

---
 lld/ELF/MarkLive.cpp | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 1742e6844c055..68025fd147cb4 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -453,12 +453,13 @@ void MarkLive<ELFT, TrackWhyLive>::mark() {
       resolveReloc(sec, rel, false);
 
     for (InputSectionBase *isec : sec.dependentSections)
-      enqueue(isec, /*offset=*/0, /*sym=*/nullptr, {&sec, "dependent section"});
+      enqueue(isec, /*offset=*/0, /*sym=*/nullptr,
+              {&sec, "depended on by section"});
 
     // Mark the next group member.
     if (sec.nextInSectionGroup)
       enqueue(sec.nextInSectionGroup, /*offset=*/0, /*sym=*/nullptr,
-              {&sec, "next in section group"});
+              {&sec, "in section group with"});
   }
 }
 
@@ -478,7 +479,7 @@ void MarkLive<ELFT, TrackWhyLive>::moveToMain() {
       if (auto *d = dyn_cast<Defined>(s))
         if ((d->type == STT_GNU_IFUNC || d->type == STT_TLS) && d->section &&
             d->section->isLive())
-          markSymbol(s, {});
+          markSymbol(s, /*reason=*/{});
 
   for (InputSectionBase *sec : ctx.inputSections) {
     if (!sec->isLive() || !isValidCIdentifier(sec->name))

From e5529b05e5eaaada7ad94ef76bba2e739e83b108 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <mysterymath@gmail.com>
Date: Fri, 21 Mar 2025 09:44:35 -0700
Subject: [PATCH 08/11] Address review comments

- Add comments clarifying invariants and getEnclosinSymbol rationale
- Remove extraneous "-" from ld.lld.1
- Replace "-NOT: >>>" with "-EMPTY:"
- Use split-file to simplify paths
---
 lld/ELF/MarkLive.cpp       |   9 ++-
 lld/docs/ld.lld.1          |   2 +-
 lld/test/ELF/why-live.s    | 153 -----------------------------------
 lld/test/ELF/why-live.test | 160 +++++++++++++++++++++++++++++++++++++
 4 files changed, 169 insertions(+), 155 deletions(-)
 delete mode 100644 lld/test/ELF/why-live.s
 create mode 100644 lld/test/ELF/why-live.test

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index 68025fd147cb4..e0c999490dcd2 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -87,7 +87,10 @@ template <class ELFT, bool TrackWhyLive> class MarkLive {
   // identifiers, so we just store a SmallVector instead of a multimap.
   DenseMap<StringRef, SmallVector<InputSectionBase *, 0>> cNamedSections;
 
-  // The most proximate reason that something is live.
+  // The most proximate reason that something is live. This forms a DAG between
+  // LiveItems. Acyclicality is maintained by only admitting the first
+  // discovered reason for each LiveItem; this captures the acyclic region of
+  // the liveness graph around the GC roots.
   DenseMap<LiveItem, LiveReason> whyLive;
 };
 } // namespace
@@ -145,6 +148,10 @@ void MarkLive<ELFT, TrackWhyLive>::resolveReloc(InputSectionBase &sec,
                       relSec->nextInSectionGroup))) {
       Symbol *canonicalSym = d;
       if (TrackWhyLive && d->isSection()) {
+        // This is expensive, so ideally this would be deferred until it's known
+        // whether this reference contributes to a printed whyLive chain, but
+        // that determination cannot be made without knowing the enclosing
+        // symbol.
         if (Symbol *s = relSec->getEnclosingSymbol(offset))
           canonicalSym = s;
         else
diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index 953cf665f2b4f..7b2650637cb10 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -755,7 +755,7 @@ Report unresolved symbols as warnings.
 Force load of all members in a static library.
 .It Fl -why-extract Ns = Ns Ar file
 Print to a file about why archive members are extracted.
-.It Fl --why-live Ns = Ns Ar glob
+.It Fl -why-live Ns = Ns Ar glob
 Report a chain of references preventing garbage collection for each symbol matching the glob.
 .It Fl -wrap Ns = Ns Ar symbol
 Redirect
diff --git a/lld/test/ELF/why-live.s b/lld/test/ELF/why-live.s
deleted file mode 100644
index 9b709c301df74..0000000000000
--- a/lld/test/ELF/why-live.s
+++ /dev/null
@@ -1,153 +0,0 @@
-# REQUIRES: x86
-
-# RUN: llvm-mc -n -filetype=obj -triple=x86_64 %s -o %t.o
-# RUN: echo -e ".globl test_shared\n .section .test_shared,\"ax\",@progbits\n test_shared: jmp test_shared" |\
-# RUN:   llvm-mc -n -filetype=obj -triple=x86_64 -o %t.shared.o
-# RUN: ld.lld -shared %t.shared.o -o %t.so
-
-## Simple live section
-.globl _start
-.section ._start,"ax",@progbits
-_start:
-  jmp test_simple
-  .quad .Lanonymous
-  .quad .Lanonymous_within_symbol
-  jmp test_shared
-  .quad test_local
-.size _start, .-_start
-
-.globl test_simple
-.section .test_simple,"ax",@progbits
-test_simple:
-  jmp test_simple
-  jmp test_from_unsized
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_simple | FileCheck %s --check-prefix=SIMPLE
-
-# SIMPLE:      live symbol: {{.*}}.o:(test_simple)
-# SIMPLE-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# SIMPLE-NOT:  >>>
-
-## Live only by being a member of .test_simple
-.globl test_incidental
-test_incidental:
-  jmp test_incidental
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_incidental | FileCheck %s --check-prefix=INCIDENTAL
-
-# INCIDENTAL:      live symbol: {{.*}}.o:(test_incidental)
-# INCIDENTAL-NEXT: >>> in live section: {{.*}}.o:(.test_simple)
-# INCIDENTAL-NEXT: >>> contained live symbol: {{.*}}.o:(test_simple)
-# INCIDENTAL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# INCIDENTAL-NOT:  >>>
-
-## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
-.globl test_from_unsized
-.section .test_from_unsized,"ax",@progbits
-test_from_unsized:
-  jmp test_from_unsized
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_from_unsized | FileCheck %s --check-prefix=FROM-UNSIZED
-
-# FROM-UNSIZED:      live symbol: {{.*}}.o:(test_from_unsized)
-# FROM-UNSIZED-NEXT: >>> referenced by: {{.*}}.o:(.test_simple)
-# FROM-UNSIZED-NEXT: >>> contained live symbol: {{.*}}.o:(test_simple)
-# FROM-UNSIZED-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# FROM-UNSIZED-NOT:  >>>
-
-## Symbols in dead sections are dead and not reported.
-.globl test_dead
-.section .test_dead,"ax",@progbits
-test_dead:
-  jmp test_dead
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_dead | count 0
-
-## Undefined symbols are considered live, since they are not in dead sections.
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_undef -u test_undef | FileCheck %s --check-prefix=UNDEFINED
-
-# UNDEFINED:     live symbol: <internal>:(test_undef) (no section)
-# UNDEFINED-NOT: >>>
-
-## Defined symbols without input section parents are live.
-.globl test_absolute
-test_absolute = 1234
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_absolute | FileCheck %s --check-prefix=ABSOLUTE
-
-# ABSOLUTE:     live symbol: {{.*}}.o:(test_absolute) (no section)
-# ABSOLUTE-NOT: >>>
-
-## Retained sections are intrinsically live, and they make contained symbols live.
-.globl test_retained
-.section .test_retained,"axR",@progbits
-test_retained:
-  jmp test_retained
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_retained | FileCheck %s --check-prefix=RETAINED
-
-# RETAINED:      live symbol: {{.*}}.o:(test_retained)
-# RETAINED-NEXT: >>> in live section: {{.*}}:(.test_retained) (retained)
-# RETAINED-NOT:  >>>
-
-## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the section if no enclosing symbol exists.
-
-.globl test_section_offset
-.section .test_section_offset,"ax",@progbits
-test_section_offset:
-  jmp test_section_offset
-.Lanonymous:
-  jmp test_section_offset
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
-
-# SECTION-OFFSET:      live symbol: {{.*}}.o:(test_section_offset)
-# SECTION-OFFSET-NEXT: >>> in live section: {{.*}}:(.test_section_offset)
-# SECTION-OFFSET-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# SECTION-OFFSET-NOT:  >>>
-
-## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the enclosing symbol if one exists.
-
-.globl test_section_offset_within_symbol
-.section .test_section_offset_within_symbol,"ax",@progbits
-test_section_offset_within_symbol:
-  jmp test_section_offset_within_symbol
-.Lanonymous_within_symbol:
-  jmp test_section_offset_within_symbol
-.size test_section_offset_within_symbol, .-test_section_offset_within_symbol
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
-
-# SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: {{.*}}.o:(test_section_offset_within_symbol)
-# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# SECTION-OFFSET-WITHIN-SYMBOL-NOT:  >>>
-
-## Local symbols can be queried just like global symbols.
-
-.section .test_local,"ax",@progbits
-test_local:
-  jmp test_local
-.size test_local, .-test_local
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections --why-live=test_local | FileCheck %s --check-prefix=LOCAL
-
-# LOCAL:      live symbol: {{.*}}.o:(test_local)
-# LOCAL-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# LOCAL-NOT:  >>>
-
-## Shared symbols
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_shared | FileCheck %s --check-prefix=SHARED
-
-# SHARED:      live symbol: {{.*}}.so:(test_shared)
-# SHARED-NEXT: >>> referenced by: {{.*}}.o:(_start) (entry point)
-# SHARED-NOT:  >>>
-
-## Globs match multiple cases. Multiple --why-live flags union.
-
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_s* | FileCheck %s --check-prefix=MULTIPLE
-# RUN: ld.lld %t.o %t.so -o /dev/null --gc-sections %t.so --why-live=test_simple --why-live=test_shared | FileCheck %s --check-prefix=MULTIPLE
-
-# MULTIPLE-DAG: live symbol: {{.*}}.o:(test_simple)
-# MULTIPLE-DAG: live symbol: {{.*}}.so:(test_shared)
diff --git a/lld/test/ELF/why-live.test b/lld/test/ELF/why-live.test
new file mode 100644
index 0000000000000..d91ee9d50bb51
--- /dev/null
+++ b/lld/test/ELF/why-live.test
@@ -0,0 +1,160 @@
+# REQUIRES: x86
+
+# RUN: rm -rf %t && split-file %s %t && cd %t
+# RUN: llvm-mc -n -filetype=obj -triple=x86_64 -o shared.o shared.s
+# RUN: ld.lld -shared shared.o -o a.so
+# RUN: llvm-mc -n -filetype=obj -triple=x86_64 -o a.o a.s
+
+#--- shared.s
+.globl test_shared
+.section .test_shared,"ax",@progbits
+test_shared:
+  jmp test_shared
+
+#--- a.s
+## Simple live section
+.globl _start
+.section ._start,"ax",@progbits
+_start:
+  jmp test_simple
+  .quad .Lanonymous
+  .quad .Lanonymous_within_symbol
+  jmp test_shared
+  .quad test_local
+.size _start, .-_start
+
+.globl test_simple
+.section .test_simple,"ax",@progbits
+test_simple:
+  jmp test_simple
+  jmp test_from_unsized
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_simple | FileCheck %s --check-prefix=SIMPLE
+
+# SIMPLE:      live symbol: a.o:(test_simple)
+# SIMPLE-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# SIMPLE-EMPTY:
+
+## Live only by being a member of .test_simple
+.globl test_incidental
+test_incidental:
+  jmp test_incidental
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_incidental | FileCheck %s --check-prefix=INCIDENTAL
+
+# INCIDENTAL:      live symbol: a.o:(test_incidental)
+# INCIDENTAL-NEXT: >>> in live section: a.o:(.test_simple)
+# INCIDENTAL-NEXT: >>> contained live symbol: a.o:(test_simple)
+# INCIDENTAL-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# INCIDENTAL-EMPTY:
+
+## Reached from a reference in section .test_simple directly, since test_simple is an unsized symbol.
+.globl test_from_unsized
+.section .test_from_unsized,"ax",@progbits
+test_from_unsized:
+  jmp test_from_unsized
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_from_unsized | FileCheck %s --check-prefix=FROM-UNSIZED
+
+# FROM-UNSIZED:      live symbol: a.o:(test_from_unsized)
+# FROM-UNSIZED-NEXT: >>> referenced by: a.o:(.test_simple)
+# FROM-UNSIZED-NEXT: >>> contained live symbol: a.o:(test_simple)
+# FROM-UNSIZED-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# FROM-UNSIZED-EMPTY:
+
+## Symbols in dead sections are dead and not reported.
+.globl test_dead
+.section .test_dead,"ax",@progbits
+test_dead:
+  jmp test_dead
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_dead | count 0
+
+## Undefined symbols are considered live, since they are not in dead sections.
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_undef -u test_undef | FileCheck %s --check-prefix=UNDEFINED
+
+# UNDEFINED:     live symbol: <internal>:(test_undef) (no section)
+# UNDEFINED-EMPTY:
+
+## Defined symbols without input section parents are live.
+.globl test_absolute
+test_absolute = 1234
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_absolute | FileCheck %s --check-prefix=ABSOLUTE
+
+# ABSOLUTE:     live symbol: a.o:(test_absolute) (no section)
+# ABSOLUTE-EMPTY:
+
+## Retained sections are intrinsically live, and they make contained symbols live.
+.globl test_retained
+.section .test_retained,"axR",@progbits
+test_retained:
+  jmp test_retained
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_retained | FileCheck %s --check-prefix=RETAINED
+
+# RETAINED:      live symbol: a.o:(test_retained)
+# RETAINED-NEXT: >>> in live section: a.o:(.test_retained) (retained)
+# RETAINED-EMPTY:
+
+## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the section if no enclosing symbol exists.
+
+.globl test_section_offset
+.section .test_section_offset,"ax",@progbits
+test_section_offset:
+  jmp test_section_offset
+.Lanonymous:
+  jmp test_section_offset
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_section_offset | FileCheck %s --check-prefix=SECTION-OFFSET
+
+# SECTION-OFFSET:      live symbol: a.o:(test_section_offset)
+# SECTION-OFFSET-NEXT: >>> in live section: a.o:(.test_section_offset)
+# SECTION-OFFSET-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# SECTION-OFFSET-EMPTY:
+
+## Relocs that reference offsets from sections (e.g., from anonymous symbols) are considered to point to the enclosing symbol if one exists.
+
+.globl test_section_offset_within_symbol
+.section .test_section_offset_within_symbol,"ax",@progbits
+test_section_offset_within_symbol:
+  jmp test_section_offset_within_symbol
+.Lanonymous_within_symbol:
+  jmp test_section_offset_within_symbol
+.size test_section_offset_within_symbol, .-test_section_offset_within_symbol
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=SECTION-OFFSET-WITHIN-SYMBOL
+
+# SECTION-OFFSET-WITHIN-SYMBOL:      live symbol: a.o:(test_section_offset_within_symbol)
+# SECTION-OFFSET-WITHIN-SYMBOL-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# SECTION-OFFSET-WITHIN-SYMBOL-EMPTY:
+
+## Local symbols can be queried just like global symbols.
+
+.section .test_local,"ax",@progbits
+test_local:
+  jmp test_local
+.size test_local, .-test_local
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_local | FileCheck %s --check-prefix=LOCAL
+
+# LOCAL:      live symbol: a.o:(test_local)
+# LOCAL-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# LOCAL-EMPTY:
+
+## Shared symbols
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_shared | FileCheck %s --check-prefix=SHARED
+
+# SHARED:      live symbol: a.so:(test_shared)
+# SHARED-NEXT: >>> referenced by: a.o:(_start) (entry point)
+# SHARED-EMPTY:
+
+## Globs match multiple cases. Multiple --why-live flags union.
+
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_s* | FileCheck %s --check-prefix=MULTIPLE
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_simple --why-live=test_shared | FileCheck %s --check-prefix=MULTIPLE
+
+# MULTIPLE-DAG: live symbol: a.o:(test_simple)
+# MULTIPLE-DAG: live symbol: a.so:(test_shared)

From 5701a08b8dfc03047600f72a4831842ae38443f7 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 26 Mar 2025 08:09:29 -0700
Subject: [PATCH 09/11] Address review feedback

- Delete blank line after "namespace {"
- Extend glob test to cover multiple pattern matches; add NOT
---
 lld/ELF/MarkLive.cpp       | 1 -
 lld/test/ELF/why-live.test | 9 +++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/lld/ELF/MarkLive.cpp b/lld/ELF/MarkLive.cpp
index e0c999490dcd2..afebc4464c909 100644
--- a/lld/ELF/MarkLive.cpp
+++ b/lld/ELF/MarkLive.cpp
@@ -44,7 +44,6 @@ using namespace lld;
 using namespace lld::elf;
 
 namespace {
-
 using SecOffset = std::pair<InputSectionBase *, unsigned>;
 
 // Something that can have an independent reason for being live.
diff --git a/lld/test/ELF/why-live.test b/lld/test/ELF/why-live.test
index d91ee9d50bb51..129f903b3c51b 100644
--- a/lld/test/ELF/why-live.test
+++ b/lld/test/ELF/why-live.test
@@ -153,8 +153,9 @@ test_local:
 
 ## Globs match multiple cases. Multiple --why-live flags union.
 
-# RUN: ld.lld a.o a.so --gc-sections --why-live=test_s* | FileCheck %s --check-prefix=MULTIPLE
-# RUN: ld.lld a.o a.so --gc-sections --why-live=test_simple --why-live=test_shared | FileCheck %s --check-prefix=MULTIPLE
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_se* --why-live=test_se* | FileCheck %s --check-prefix=MULTIPLE
+# RUN: ld.lld a.o a.so --gc-sections --why-live=test_section_offset --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=MULTIPLE
 
-# MULTIPLE-DAG: live symbol: a.o:(test_simple)
-# MULTIPLE-DAG: live symbol: a.so:(test_shared)
+# MULTIPLE-DAG: live symbol: a.o:(test_section_offset)
+# MULTIPLE-DAG: live symbol: a.o:(test_section_offset_within_symbol)
+# MULTIPLE-NOT: live symbol

From 59382106effff39de2b0304faaf73b89b7374317 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 26 Mar 2025 08:24:02 -0700
Subject: [PATCH 10/11] Add release note

---
 lld/docs/ReleaseNotes.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lld/docs/ReleaseNotes.rst b/lld/docs/ReleaseNotes.rst
index 431b694f7bce1..43ed6fa73589b 100644
--- a/lld/docs/ReleaseNotes.rst
+++ b/lld/docs/ReleaseNotes.rst
@@ -35,6 +35,10 @@ ELF Improvements
   not provided in the command line by the user and cannot be inferred from
   inputs.
 
+* ``--why-live=<glob>`` prints for each symbol matching ``<glob>`` a chain of
+  items that kept it live during garbage collection. This is inspired by the
+  Mach-O LLD feature of the same name.
+
 Breaking changes
 ----------------
 

From f99fb7a691e99003532b5c7530b5109b826c6653 Mon Sep 17 00:00:00 2001
From: Daniel Thornburgh <dthorn@google.com>
Date: Wed, 26 Mar 2025 09:27:20 -0700
Subject: [PATCH 11/11] Add quotes around wildcards

---
 lld/test/ELF/why-live.test | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lld/test/ELF/why-live.test b/lld/test/ELF/why-live.test
index 129f903b3c51b..d8f8cc7b6db64 100644
--- a/lld/test/ELF/why-live.test
+++ b/lld/test/ELF/why-live.test
@@ -153,7 +153,7 @@ test_local:
 
 ## Globs match multiple cases. Multiple --why-live flags union.
 
-# RUN: ld.lld a.o a.so --gc-sections --why-live=test_se* --why-live=test_se* | FileCheck %s --check-prefix=MULTIPLE
+# RUN: ld.lld a.o a.so --gc-sections --why-live="test_se*" --why-live="test_se*" | FileCheck %s --check-prefix=MULTIPLE
 # RUN: ld.lld a.o a.so --gc-sections --why-live=test_section_offset --why-live=test_section_offset_within_symbol | FileCheck %s --check-prefix=MULTIPLE
 
 # MULTIPLE-DAG: live symbol: a.o:(test_section_offset)