ADR 0003: 32-bit ILP32 Data Model

Status

Accepted (reconstructed)

Context

WebAssembly standard MVP specifies 32-bit linear memory indexing (wasm32) using i32 addresses (docs/decisions/003-ilp32.md, commit d23afed, src/wasm/opcodes.rs). C++ data models vary across platforms (LP64 on modern 64-bit Unix, LLP64 on Windows, ILP32 on 32-bit platforms) . To target WebAssembly 32-bit linear memory, a consistent data representation is required for integers, pointers, and memory offsets (docs/decisions/003-ilp32.md, commit d23afed).

Options Considered

  • Option 1: 64-bit memory model with WebAssembly Memory64 (wasm64)
    • Pros: Aligns with 64-bit desktop conventions; larger address space.
    • Cons: Memory64 is not universally supported in browser runtimes; 64-bit pointers waste cache and linear memory in small WebAssembly workloads.
  • Option 2: 32-bit ILP32 model (wasm32)
    • Pros: Direct mapping to WebAssembly MVP standard (i32.load, i32.store, 32-bit address space); stable structure alignments across 32-bit targets; compact data structures.
    • Cons: Maximum linear memory is bounded by 4 GiB (and configured by default to 256 MiB in cppbolt).

Decision

Target the ILP32 data model (docs/decisions/003-ilp32.md, commit d23afed, src/ast/types.rs#L40-L70):

  • sizeof(int) == 4
  • sizeof(long) == 4
  • sizeof(long long) == 8
  • sizeof(pointer) == 4 (represented as Wasm i32 addresses)
  • sizeof(float) == 4 (Wasm f32)
  • sizeof(double) == 8 (Wasm f64)

Consequences

Positive

  • Memory layouts and struct alignments remain stable across native test harnesses and browser hosts (docs/decisions/003-ilp32.md, commit d23afed, src/runtime/memory_layout.rs, tests/oracle_gate.rs).
  • Direct alignment with WebAssembly linear memory instructions without pointer widening or narrowing (src/codegen/expr.rs#L120-L160, src/wasm/opcodes.rs).

Negative / Trade-offs

  • Programs assuming 64-bit long types must use long long for 64-bit integer arithmetic (src/ast/types.rs, tests/c_basics/types/long_long.cpp).