wasm-d8-perf

name	wasm-d8-perf
description	Use this skill to reproduce, profile, or analyze WebAssembly (Wasm) execution performance using d8 shell.

WebAssembly Performance Analysis in d8

Reproduce, profile, and analyze Wasm performance using the V8 developer shell (d8).

1. Reproduction and Establishing a Baseline

• Build Configurations:
  • CRITICAL: Always use a release build (e.g., out/x64.release/d8) for benchmarking.
  • Use optdebug (e.g., out/x64.optdebug/d8) for disassembling/debugging (preserves symbols).
• Measurement Metrics:
  • Wall time: Measure execution time (e.g., JS console.time()).
    • LLM Tip (Statistical Rigor & Warmup): Run 3-5 times; take the median/average. Ensure code runs in a loop to trigger Turboshaft tier-up (warmup) before measuring.
  • Resource/CPU: Use /usr/bin/time -v (Wall time, memory) and perf stat -d (cycles, instructions, IPC, branch misses).
    • LLM Tip (perf Fallback): If perf fails due to permissions (e.g. kernel.perf_event_paranoid), notify the user to adjust settings or switch to a PMU-enabled environment (gLinux/Cloudtop). Fall back to d8 --prof if needed.
  • GC Overhead: Use --trace-gc to trace garbage collection pauses, especially if WasmGC is used.
• Tier Isolation: Compare performance between execution tiers to understand the optimization effect.
  • Liftoff (Baseline): d8 --liftoff-only script.js
  • Turboshaft (Optimized): d8 --no-liftoff script.js
    • Note: --no-liftoff disables speculative inlining since it skips Liftoff execution and thus doesn't collect feedback.

2. Hotspot Identification

Find where time is spent, what the hottest functions, loops, blocks, or instructions are, so we focus on that:

• Linux Perf: Run ./tools/profiling/linux-perf-d8.py to get a profile with JIT symbols resolved, then analyze with perf report.
• V8 Profiler: Run d8 --prof script.js and analyze v8.log with ./tools/linux-tick-processor.
• Categorize Hotspots: Wasm user code, JS code, V8 C++ Runtime/GC/Compilation, or JS/Wasm boundary (wrappers).

3. Deep Dive Analysis

Compilation Overhead

• Identify Slow to Compile Functions: Use d8 --trace-wasm-compilation-times and d8 --turbo-stats-wasm.
• Inspect Bytecode: Build wami (tools/dev/gm.py x64.release wami) and disassemble: out/x64.release/wami --single-wat=<func_index> <path_to_wasm>

Wasm Binary Quality & Toolchain

Unoptimized Wasm binary patterns can hurt V8 compilation and execution.

• Ask the user if source code (C++/Rust) is available.
• Check for: huge functions, excessive locals, many branches, or missed static optimizations.
• Ensure binary is a release build (compiled with -O3/-Os).

Execution Performance & Optimization (Deep Dives)

Perform deep dives on hot functions:

• Turboshaft IR Traces: Run d8 --trace-turbo --trace-turbo-filter=<func_name>.
  • Context Window: To keep the context windows clean use jq programmatically:
    • List phases: jq '.phases[].name' turbo-*.json
    • Count nodes: jq '.phases[] | {name: .name, node_count: (if (.data | type) == "object" and .data.nodes then (.data.nodes | length) else 0 end)}' turbo-*.json
    • Find ops: jq '.phases[] | select(.name == "TurboshaftTypeAssertionsPhase") | select((.data | type) == "object" and .data.nodes) | .data.nodes[] | select(.title | contains("BoundsCheck"))' turbo-*.json
• Assembly Profiling: Run perf annotate -i file.perf.data.jitted --stdio to map hot instructions to bytecode.
  • Instruction Skid: Account for cycle misattribution; inspect surrounding instructions and data dependencies.
• Disassembly & Comments: Run out/x64.optdebug/d8 --print-wasm-code-function-index=<idx> --code-comments.
  • LLM Tip: Redirect disassembly output to a file (> disasm.txt) to avoid flooding the terminal.
• Optimization & Tracing Flags:
  • Inlining: --trace-wasm-inlining, --trace-turbo-inlining
  • Loop Peeling and Unrolling: Enable/disable --wasm-loop-peeling, --wasm-loop-unrolling to see an effect of those optimizations.
  • Other Optimizations: --turboshaft-trace-load-elimination, --turboshaft-trace-peeling, --turboshaft-trace-unrolling
  • Typing: --trace-wasm-typer
• Inlining & Tiering Budgets: Scalability tuning flags to adjust optimizations:
  • Tiering up earlier or later: --wasm-tiering-budget=<value>.
  • Inline more or less aggressively: --wasm-inlining-budget=<value>.
• V8 Flag Discovery: Search for context-specific flags using d8 --help | grep -i <keyword> or by looking up definitions in src/flags/flag-definitions.h and via grep. Refer to v8-commands skill for general usage.

4. Synthesis and Reporting

Provide a clear report summarizing:

1. Hottest Functions: Contribution and compilation tier (Liftoff vs Turboshaft).
2. Inlining Status: Report Wasm-to-Wasm and JS/Wasm wrapper and body inlining.
3. Wasm Input Binary Properties: Release vs debug, missed static optimizations, very large functions, or otherwise noteworthy code patterns.
4. Disassembly & Assembly Hotspots: Highlight hot instructions and map them to Wasm bytecode.
5. Turboshaft Optimization: Key phases affecting the CFG and any failed optimizations.
6. Code Skeleton: Provide a simplified snippet of the hot block/loop at the most useful level (source, bytecode, IR, or machine code).

5. Experimentation & Verification

Only proceed to this step after your initial report and explicit approval by the user.

• Ablation Studies: Toggle optimizations to measure wall-time impact (e.g. --no-wasm-loop-unrolling, --no-turboshaft-wasm-load-elimination, --no-wasm-inlining, --no-turbo-inline-js-wasm-calls).
  • LLM Tip: Present results in a Before vs. After table.
• Wasm Binary/Static Optimization: Use wasm-opt -O3 (or -Os) if available on PATH, or ask the user to rebuild with different flags.
• Hypotheses: Align on potential optimization opportunities with the user before implementing fixes.