Fuchsia Memory (//src/memory)

//src/memory contains Fuchsia's userspace memory monitoring, attribution, profiling, diagnostics components, shared libraries, and host analysis tools.

Directory Layout

Memory Attribution & System Monitoring

  • attribution/ — Fuchsia's modern memory attribution framework and Memory Monitor 2 (memory_monitor2):
    • monitor/ — memory_monitor2 system component collecting Zircon kernel statistics, attribution trees, memory stalls, and page refault telemetry for Inspect, Cobalt metrics, and trace recording.
    • processing/ — Rust library aggregating Principal/Resource attribution claims, Zircon VMO/mapping snapshots, and memory bucket definitions into digests and summaries.
    • server/ — Rust helper library serving fuchsia.memory.attribution.Provider for runner and component implementations (such as ELF runner, Starnix, and driver manager).
    • refaults_vmo/ — Shared-memory bitvector and counter primitives (PageRefaultCounter, AtomicBitVec) used by user pagers (Fxfs, Erofs, Starnix) to report page refaults to fuchsia.memory.attribution.PageRefaultSink.
    • testing/ — Integration test utilities for verifying component memory attribution trees.
  • buckets/ — JSON5 memory bucket definitions (buckets.json5 and subsystem-specific bucket configs) that classify processes and VMOs into named subsystems for Inspect reporting, Cobalt telemetry, and memory triage.
  • pressure_signaler/ — memory_pressure_signaler component monitoring Zircon kernel memory pressure events, serving fuchsia.memorypressure.Provider to system clients, and optionally filing critical crash reports.
  • legacy/ — Legacy C++ Memory Monitor 1 implementation, superseded by attribution/monitor/:
    • legacy/monitor/ — Legacy C++ memory_monitor component.
    • legacy/metrics/ — Legacy C++ library capturing Zircon process/VMO state and computing memory summaries, digests, and bucket matches for legacy/monitor/.

Profiling & Diagnostics Components

  • heapdump/ — Live userspace and kernel heap profiler backing ffx profile heapdump:
    • collector/ — On-device component collecting live heap snapshots from instrumented processes and serving symbolizable pprof profiles.
    • instrumentation/ — C/C++ Scudo allocator hooks and Rust bindings recording live allocations into shared VMOs.
    • kernel-collector/ — Collector exporting Zircon kernel heap profiles.
    • lib/ — Shared snapshot streaming (heapdump_snapshot) and VMO layout (heapdump_vmo) crates.
    • example/ — Example component demonstrating heapdump instrumentation.
  • sampler/ — Statistical heap profiler (memory_sampler component and instrumentation/ Poisson sampling library) recording sampled allocations and exporting pprof profiles via crash reports.
  • stacktrack/ — Live thread call-stack tracker backing ffx profile stacktrack:
    • collector/ — On-device collector snapshotting live thread stacks from instrumented processes.
    • instrumentation/ — Runtime hooks and async frame tracking recording live call stacks into shared VMOs.
    • lib/ — Shared snapshot (stacktrack_snapshot) and VMO table (stacktrack_vmo) crates.
    • example/ — Example component demonstrating stacktrack integration.
  • thrasher/ — Diagnostic component and tool for generating controlled page/memory thrashing workloads.

Shared Libraries & Allocator Utilities (lib/)

  • lib/index_table_builder/ — Deduplicating string and index table builder crate used during profile and trace serialization.
  • lib/memory_mapped_vmo/ — Safe Rust wrapper over memory-mapped Zircon VMOs shared by attribution/refaults_vmo, heapdump, and stacktrack.
  • lib/performance/ — Host Python library (memory: profile.py, resource_usage.py) used by end-to-end performance tests to capture device memory profiles and publish metrics.
  • lib/pprof/ — Rust crate constructing pprof protobuf profiles (shared by ffx profile heapdump and tools/dupefinder).
  • lib/scudo/ — C header (mallopt.h) and Rust bindings (scudo) for controlling the Scudo memory allocator (such as purging thread caches).

Host Analysis Tools & Scripts

  • tools/ — Offline host analysis scripts and Python libraries (smaps/, snapshots/, debug_json/, images_json/, multidict/, dataclasses_json_lite/, components_sql.py, mem_digest.py, mem_tree.py, treemap.py) for inspecting snapshots, computing digests, and visualizing memory usage.
    • tools/dupefinder/ — Host Rust CLI (fx dupefinder) that analyzes heapdump snapshots and heap content dumps to blame source locations allocating duplicate buffers and render HTML/JSON reports.

Testing

Run unit and integration tests across //src/memory:

fx test //src/memory:tests

Host-driven emulator E2E tests (such as dupefinder's smoke test) live under:

fx test //src/memory:host_tests

Related Directories Outside //src/memory

  • FIDL & SDK Libraries:
    • //sdk/fidl/fuchsia.memory* (fuchsia.memory, fuchsia.memory.attribution, fuchsia.memory.attribution.plugin, fuchsia.memory.debug, fuchsia.memory.heapdump.*, fuchsia.memory.inspection, fuchsia.memory.sampler, fuchsia.memory.stacktrack.*)
    • //sdk/fidl/fuchsia.memorypressure
    • //sdk/lib/heapdump_instrumentation
  • FFX Developer CLI Plugins:
    • //src/developer/ffx/plugins/profile/memory
    • //src/developer/ffx/plugins/profile/heapdump
    • //src/developer/ffx/plugins/profile/stacktrack
  • Assembly Inputs & Boot Budget Tests:
    • //bundles/assembly/bazel_inputs/src/memory
    • //src/tests/memory_budget