Symbol/size analysis: detect or prevent map-file 0x00000000 false positives (~95 KB phantom-bloat reported on FastLED#2473)

[zackees]

Summary

Map-file-based binary-size analysis is a trap: tree-shaken sections still
appear in the GNU ld map file with a real size field, but their
placement address is 0x00000000 — meaning the linker dropped them via
--gc-sections. Any analyzer that sums sizes without filtering on
address != 0x00000000 invents bloat that doesn't exist.

I just fell into exactly this trap on FastLED/FastLED#2473
(symbol audit comment)
and posted a meta-issue (FastLED/FastLED#2771) with ~95 KB of phantom
"wins" that the linker had already harvested. Caught and corrected within
the hour, but only because a reviewer pushed back ("why aren't these
tree-shaken?"). A symbol-analysis tool sanctioned by fbuild — or even just
a documented gotcha — would have caught it on the first pass.

This issue asks: does fbuild's size/symbol analysis (today or planned)
correctly filter tree-shaken sections, or does it expose the same trap to
its consumers?

The trap, concretely

Stock GNU ld --gc-sections keeps the dropped section in the map for
debugging purposes, but assigns it placement address 0x00000000. Example
from a current FastLED master build of examples/Blink/Blink.ino for
esp32s3 (PIO 6.1.19, IDF 5.4, xtensa-esp-elf-gcc 14.2.0):

 .rodata.embedded
                0x00000000    0x110f8 .../libmbedtls.a(x509_crt_bundle.S.obj)

That looks like "68 KB Mozilla CA cert bundle in the binary." It is not —
xtensa-esp32s3-elf-nm firmware.elf | grep _binary_x509_crt_bundle_start
returns nothing. The linker dropped the whole 68 KB, and the map entry is
a tombstone.

Same on this build for:

Section	Map says	Actually placed?	Reality
libmbedtls.a(x509_crt_bundle.S.obj) .rodata.embedded	69,880 B	❌ addr 0x00000000	tree-shaken
libmesh.a(mesh_parent.o) .rodata.str1.1	11,108 B	❌ addr 0x00000000	tree-shaken
libFastLED.a(third_party+.cpp.o) .rodata...huffTable	8,484 B	❌ addr 0x00000000	tree-shaken
libFastLED.a(third_party+.cpp.o) .rodata...PLM_AUDIO_SYNTHESIS_WINDOW	2,048 B	❌ addr 0x00000000	tree-shaken
libesp_common.a(esp_err_to_name.c.obj) .rodata.str1.1	6,006 B	✅ addr 0x3c0...	live

A naive map-file parser claims ~95 KB of false-positive bloat if it
sums all four "dropped" rows. The actual rodata top-10 picture is
completely different once you filter on address != 0x00000000.

What fbuild has today

fbuild --help lists build / deploy / monitor / reset / purge / daemon / show / device / mcp / clang-tidy / iwyu / test-emu / clang-query / lnk / lib-select / compile-many / ci. No size / analyze / bloat /
symbols subcommand.

fbuild#297 added build_info.json emission so downstream FastLED tooling
(ci/symbol_analysis_runner.py, ci/inspect_elf.py,
ci/compiled_size.py) can find the ELF + toolchain paths. Those tools
operate on nm/readelf output of the linked ELF and so do not have
the map-file trap by construction — they only see what is actually in the
binary.

But there is no fbuild-sanctioned path for the "what's the per-archive
contribution to rodata?" question, which is what tempts people into
map-file parsing in the first place. (The largest rodata symbols in
modern ESP32-S3 builds are anonymous merged .str1.1 string pools that
nm doesn't surface; you need the map file to attribute them to source
archives — and the map file is the trap.)

Ask

Pick one of:

A) Add fbuild size --bloat / fbuild analyze subcommand

Sanctioned, fbuild-supplied analyzer that:

1. Uses the linked ELF as ground truth for "is this in the binary".
2. For per-archive rodata attribution, parses the map file but filters
   sections placed at 0x00000000 out of the totals.
3. Cross-checks every "live" section it reports against nm/readelf on
   the ELF — anonymous string pools (.str1.*) get attributed to the
   .o file that declared them, but the size comes from the ELF's
   merged-string section, not from the map's pre-link figure.
4. Prints output that distinguishes "live in firmware.bin" (truth) from
   "section listed in .map" (intermediate state).

Optional extras:

• --top=N symbol leaderboard from ELF nm.
• Per-archive rodata/text/data split.
• --diff PRIOR.json to track size deltas across commits.
• JSON output for CI gating.

B) Document the map-file trap prominently in fbuild docs

If implementing A is out of scope, at minimum a short doc page (docs/size-analysis-gotchas.md?) with:

• The 0x00000000 filter rule.
• A vetted one-liner awk / python recipe.
• A pointer at the build_info.json contract so people know they should
  drive analysis off the ELF, not the map.

C) Sanctioned fbuild_size_helpers.py library

Drop-in Python module that ships in the fbuild distribution with vetted
implementations of the map-file filter, the per-archive grouper, and the
ELF cross-check. Then FastLED's ci/ scripts (and other downstream
consumers) can import the helpers instead of each rolling their own
awk-soup.

Why this matters now

FastLED's binary-size investigation cycle right now is:

1. User reports the binary grew.
2. Someone runs xtensa-esp32s3-elf-size -A + nm + objdump + ad-hoc
   awk over the map.
3. The audit either misses real wins or invents phantom ones (this case).
4. A reviewer catches it, the headline numbers get walked back.
5. Repeat in three months.

A 1-shot fbuild size --bloat that reliably distinguishes
"actually-linked" from "in-the-map-but-dropped" would short-circuit that
loop and stop the embarrassment of headline corrections.

Reproduction

# Build (PIO backend; fbuild backend currently hangs on cold ESP32-S3 — fbuild#117)
bash compile esp32s3 --examples Blink --platformio

MAP=.build/pio/esp32s3/.pio/build/esp32s3/firmware.map
ELF=.build/pio/esp32s3/.pio/build/esp32s3/firmware.elf

# NAIVE rodata audit — what a first-time analyzer would write:
awk '/^ \.rodata/ {section=$0; getline; size=strtonum($2); src=$3; \
     if (size>=500) print size "\t" section "\t" src }' "$MAP" \
  | sort -nr | head -10
# Output includes: x509_crt_bundle (69880), main.cpp.o (57902),
# mesh_parent (11108), ... <- WRONG, three of these are tree-shaken

# CORRECT rodata audit — filter out dropped sections:
awk '/^ \.rodata/ {section=$0; getline; addr=$1; size=strtonum($2); src=$3; \
     if (addr != "0x00000000" && size >= 500) print size "\t" section "\t" src }' "$MAP" \
  | sort -nr | head -10
# Output: main.cpp.o (57902), libesp_common (6006), ... <- mbedtls/mesh gone

# Cross-check against linked-ELF ground truth:
xtensa-esp32s3-elf-nm "$ELF" | grep _binary_x509_crt_bundle_start  # empty
xtensa-esp32s3-elf-nm "$ELF" | grep huffTable                       # empty
xtensa-esp32s3-elf-nm "$ELF" | grep PLM_AUDIO_SYNTHESIS              # empty

Related

• ESP32-S3 binary size: 657 KB on master vs 344 KB on 3.10.3 — remaining +313 KB delta breakdown FastLED#2473 — Where I got bitten by this (symbol audit
  comment,
  walked-back numbers).
• Meta: ESP32-S3 binary-size reduction — SUPERSEDED by #2773 (see comment for details) FastLED#2771 — Meta-issue with the corrected Batch 1 / Batch 2
  rollup that resulted from catching the false positives.
• fbuild#297 — build_info.json emitter (closed; the ELF-truth path
  this issue advocates for).
• fbuild#243 / Propagate eh_frame strip policy to ARM Cortex-M / Teensy / RISC-V GCC targets (follow-up to #243) #244 / docs(readme): document eh_frame strip default — deviation from PlatformIO behavior (#243 #245 follow-up) #246 — eh_frame strip work (size-policy precedent
  for fbuild-managed binary-size knobs).

[zackees]

Investigation report — pre-PR triage

I picked this up via /clud-fix to merge a fix end-to-end, but the intake
gate flagged it as a feature request with three different scopes (A, B, C)
and no chosen "definition of fixed." A PR can't be opened until we agree on
which path to land. Below is what I verified in the tree today, where the
mechanics actually live, and a recommended cut-line — so the discussion can
be about scope, not about whether the trap is real (it is) or whether fbuild
has the raw materials to address it (it does).

What fbuild has today (verified against current main)

• No size / analyze / bloat / symbols top-level subcommand. Confirmed
  in crates/fbuild-cli/src/cli/args.rs:65-389 — the subcommand enum is
  Build / Deploy / Monitor / Reset / Purge / Daemon / Show / Device / Mcp / ClangTidy / Iwyu / TestEmu / ClangQuery / Lnk / LibSelect / CompileMany / Ci.
  Your fbuild --help claim in the issue matches the source.
• Build does already expose --symbol-analysis [PATH] at
  crates/fbuild-cli/src/cli/args.rs:90-93 ("Run per-symbol memory analysis
  after building; optionally write report to PATH instead of streaming to
  console"). So fbuild already has a foothold for post-build symbol reporting
  — it just operates on the ELF via nm, not on the .map file.
• SymbolMap (crates/fbuild-core/src/lib.rs:300-383) is the existing
  analyzer: parses nm --print-size --size-sort --reverse-sort output and
  classifies symbols into Flash/RAM regions. ELF-as-ground-truth path —
  immune to the 0x00000000 trap by construction, which is exactly the
  property the issue advocates for.
• Map files are emitted by every platform's linker via
  -Wl,-Map=firmware.map (AVR crates/fbuild-build/src/avr/avr_linker.rs:111
  and the equivalent in CH32V, ESP8266, generic ARM, NRF52, Renesas, SAM,
  SiliconLabs, Teensy). So the map file is sitting on disk next to the ELF
  in every build — it's available, just not parsed anywhere in fbuild.
• No map-file parser anywhere in the workspace. No tests or examples
  consume firmware.map. The "trap" you describe is therefore not present
  in fbuild today because fbuild doesn't parse map files at all — but it
  also doesn't prevent consumers (FastLED ci/ scripts) from falling
  into the trap when they reach for the map directly.
• build_info.json (issue fbuild deficiency vs PlatformIO: no build_info.json metadata emitter (blocks downstream size/symbol tooling) #297) lives in crates/fbuild-build/src/build_info.rs:28-61
  (BuildInfo struct, emit_build_info() at line 136). It already publishes
  prog_path, cc_path, cxx_path, ar_path, objcopy_path, size_path,
  plus flags/defines/includes/libs. Adding a map_path field next to
  prog_path would be a one-line schema change with high downstream value.
• Docs convention: architecture docs live in docs/architecture/*.md
  (overview, data-flow, deploy-preemption, library-selection, portability,
  pyo3-bindings, runtime, serial). A "size analysis gotchas" page would fit
  there or as a peer doc at docs/SIZE_ANALYSIS.md.
• Diagnostic-subcommand exception is precedent for option A. Per
  crates/CLAUDE.md, clang-tidy / clang-query / iwyu / mcp / lnk / lib-select
  run in-process and intentionally bypass the daemon because they're
  read-only diagnostics. A hypothetical fbuild size / fbuild bloat
  fits that pattern cleanly — no HTTP round-trip needed.

The trap, restated to make sure I have it right

GNU ld --gc-sections keeps the dropped section row in the .map for
debugging, but writes its placement address as 0x00000000. A naive
sum-by-archive over .rodata.* rows in the map double-counts those dead
sections. ELF-side tools (nm, readelf, objdump) never see them
because the linker really did drop them, which is why
SymbolMap-via-nm is already trap-immune. The risk surface is purely
map-file analyzers. Your reproduction (x509_crt_bundle 69,880 B,
mesh_parent 11,108 B, huffTable 8,484 B, PLM_AUDIO_SYNTHESIS 2,048 B,
~95 KB total phantom-bloat) matches what I'd expect from xtensa-esp32s3-elf
14.2.0 with --gc-sections on. I have no reason to doubt the numbers.

Scope read on the three options

• Option C (fbuild_size_helpers.py) — declined as written. The repo's
  language policy (CLAUDE.md: "Python is only for CI scripts, packaging,
  hooks, and PyO3 bindings. All tests, benchmarks, and application logic
  must be written in Rust") puts a vendored Python helper module
  out-of-bounds. The PyO3 surface (fbuild-python) is locked to
  SerialMonitor / Daemon. Closest in-policy variant: ship a Rust
  library (or expose it via the existing --symbol-analysis machinery)
  that consumers shell out to via fbuild — i.e. option A in a thinner
  jacket.
• Option B (docs only) — small, well-bounded, lossy. ~1 doc page in
  docs/architecture/ or docs/SIZE_ANALYSIS.md, plus a one-line
  callout in crates/fbuild-build/src/build_info.rs near where ELF
  paths are emitted. Catches no analyzers automatically; relies on
  reviewers remembering the rule. Total work: <100 LoC of markdown.
• Option A (fbuild size / fbuild bloat) — the goal-shaped fix,
  but a real chunk of work. Concretely it's: a map-file parser
  with the address != 0x00000000 filter, an ELF cross-check that
  routes through the existing SymbolMap/nm plumbing, archive
  attribution, JSON output for CI, optionally a --diff PRIOR.json
  comparator. Realistic estimate: a new fbuild-bloat crate (or
  a module under fbuild-build/src/size/) + a Size variant on
  Commands + wiring through fbuild-cli, plus tests against
  vendored map/ELF fixtures. Probably 600–1200 LoC of Rust + tests.
  Fits the diagnostic-subcommand exception, so no daemon work.

Recommendation

Land B + a deliberately minimal slice of A in one PR; defer the
full A to a follow-up. Concretely:

1. New docs/SIZE_ANALYSIS.md with the 0x00000000 filter rule, a
   worked example using your x509_crt_bundle case, the vetted awk
   one-liner, and a pointer at build_info.json as the
   ELF-truth contract.
2. Add map_path to BuildInfo (crates/fbuild-build/src/build_info.rs)
   so downstream tooling has a single supported way to locate the map
   without duplicating fbuild's pathing logic. One field, one assignment,
   no behavior change.
3. Defer the fbuild size subcommand to a follow-up issue with a
   bounded design (map parser + filter + ELF cross-check via existing
   SymbolMap).

This makes step 7 of /clud-fix (validate the reproduction) tractable:
the doc + map_path makes it possible for someone running the issue's
exact awk snippet to land on the correct version on the first try, and
the follow-up issue is what closes the door entirely.

What I need from you before opening a PR

1. Which path? B-plus-thin-A as recommended, full A in one PR, or
   pure-B with no schema change?
2. Doc location: docs/SIZE_ANALYSIS.md (peer to ROADMAP/WHY) or
   docs/architecture/size-analysis.md (with the other architecture
   docs)? Repo convention slightly prefers the latter but the topic is
   more "guide" than "architecture."
3. If A is in scope: should the subcommand be named size, bloat,
   or analyze? size collides with the GNU size binary; bloat
   matches cargo-bloat precedent and is unambiguous.
4. Anything I'm wrong about above — particularly: is the existing
   Build --symbol-analysis flag the place this should hook in, or
   should it be a standalone subcommand from day one?

I'll wait for direction here before opening a PR. If you'd rather just
say "ship option A as one big PR," that's also fine — I just don't want
to guess the scope on a feature request with three explicit branches.