feat(bloat): expose linker --cref back-references as referenced_by + optional graphviz .dot export #459

Problem

fbuild bloat (a.k.a. fbuild symbols) currently parses the linker map for section/symbol attribution — it tells you where a symbol is defined (archive + object + output section) and which input section a .rodata.<owner>.str1.N pool belongs to. It does not extract the linker's Cross Reference Table, even though GNU ld writes that table into the same firmware.map file we're already reading.

This shows up in real bloat audits. From FastLED#2886 (the ESP32-S3 Blink reduction plan, generated by bash bloat esp32s3 --top 25):

The n/a column is unavoidable today — fbuild has nothing to say about who pulled in a libc symbol, so the agent gives up. But the answer is literally already in the map file. From the cref table of the matching ESP32-P4 build I checked:

_vfprintf_r   libc.a(libc_a-vfprintf.o)        ← defining TU
              libc.a(libc_a-vprintf.o)         ← referencer
              libc.a(libc_a-printf.o)
              libc.a(libc_a-fprintf.o)

vprintf       libc.a(libc_a-vprintf.o)
              liblog.a(log_write.c.obj)        ← ESP-IDF logging
printf        libc.a(libc_a-printf.o)
              libmbedcrypto.a(pkcs5.c.obj, sha512.c.obj, …)
              libheap.a(tlsf.c.obj, heap_caps.c.obj)
              libconsole.a(commands.c.obj)
              libnvs_flash.a(nvs_page.cpp.obj)
              … (~25 more)
fprintf       libc.a(libc_a-fprintf.o)
              libsdmmc.a, libesp_timer.a, libesp_mm.a, libvfs.a,
              libesp_hw_support.a (sleep/intr/gpio/regdma/ldo),
              libesp_driver_gpio.a, libconsole.a(linenoise.c)

That is exactly the "why was this symbol linked?" information the bloat report should be answering, and it's two layers of indentation-aware parsing away from what we already do.

Proposal

Part 1 — referenced_by in report.json (minimum viable)

Add a parser pass over the Cross Reference Table block of the linker map. For each symbol, emit a new per-row field in the JSON:

{
  "demangled": "_vfprintf_r",
  "size": 11309,
  "archive": "libc.a",
  "object": "libc_a-vfprintf.o",
  "source": "nm",
  "referenced_by": [
    {"archive": "libc.a", "object": "libc_a-vprintf.o"},
    {"archive": "libc.a", "object": "libc_a-printf.o"},
    {"archive": "libc.a", "object": "libc_a-fprintf.o"}
  ]
}

In report.md, add a "Why was this linked?" column to the top-N table (or a follow-up table that lists top-K referencers per top symbol). For symbols with > K=5 referencers, render top-K + "(… and N more)".

Cref granularity is archive-member (.o), not symbol — that's a ld --cref characteristic, not a fbuild limitation. Documentation should call it out.

Part 2 — fbuild bloat graph subcommand for .dot export (optional follow-up)

Generate Graphviz .dot files from a target symbol, walking the back-reference graph outward. The depth/N question is where most of the design work lives:

Fixed N is the wrong knob. I worked through this in FastLED#2886 discussion — quick summary:

• N=1 is insufficient for any libc/IDF symbol. _vfprintf_r at N=1 stops at libc-internal wrappers (vprintf.o, printf.o, fprintf.o) — same archive as the target. You learn nothing actionable.
• N=1 is sufficient for any app-side symbol whose direct referencers are already outside the defining archive (e.g. FastLED ctor → main.cpp.o).
• Fixed N≥3 explodes for hub symbols. printf alone has ~25 mbedTLS referencers; expanding two more hops produces an unreadable wall.

Recommended default: adaptive termination + fan-out cap.

1. Cross-archive termination. Stop expanding a branch the first time it reaches a referencer whose archive is different from the original target's archive. Naturally surfaces the boundary where the symbol "escapes" its own library.
2. Per-node fan-out cap K (default 5). Sort referencers by their own contributed flash bytes, keep top-K, collapse the rest into a [… and N more] super-node.
3. Hard depth cap N=4 as a safety belt — if cross-archive termination hasn't fired by depth 4 you're chasing infra and the graph is unreadable.

Render aids:

• Color nodes by archive (FastLED / ESP-IDF / Arduino / libc / mbedTLS / libstdc++ / app).
• Size nodes by attributed flash bytes (size= proportional to log(bytes)).
• Collapse mode: --collapse-archive libc.a merges all libc-internal hops into a single super-node so the eye jumps straight to the non-libc edges (ESP_LOG, mbedTLS, etc.).
• Archive filter: --exclude-archive libc.a,libm.a for users who only want non-system referencers.

Proposed surface:

fbuild bloat graph <input> --symbol _vfprintf_r [--depth adaptive|N] \
                          [--fan-out K] [--collapse-archive A,B] \
                          [--exclude-archive A,B] -o vfprintf.dot

For the FastLED#2886 use case, the four newlib rows would each render a ~6-10 node graph with libc wrappers collapsed and the real upstream consumers (log_write.c.obj, tlsf.c.obj, ESP-IDF sleep/intr) as the leaves. Exactly the data needed to choose between "kill IDF logging", "drop mbedTLS self-tests", or "switch to nano-printf".

Acceptance

• report.json rows carry referenced_by: [{archive, object}, ...].
• report.md top-N table answers "why is this linked?" without n/a for libc/IDF rows.
• fbuild symbols still works when the map has no Cross Reference Table block (older ld versions or -Wl,--no-cref) — referenced_by becomes [], not an error.
• (Part 2) fbuild bloat graph --symbol <S> writes a readable .dot for both _vfprintf_r (libc, ~10 nodes after collapse) and a FastLED ctor (app, ~3-5 nodes), no manual tuning.

Related

• #434 — symbols → bloat rename (the umbrella under which this naturally lands)
• #427 — map-derived synthesis (the existing map-parse pass to extend)
• #428 — build_info.json toolchain paths
• FastLED#2886 — the motivating bloat audit, demonstrates the n/a gap

🤖 Generated with Claude Code