Skip to content

docs(design): host-access sync contract, reset-epoch frees, pinning, dst-form accumulation policy - #139

Merged
dndungu merged 1 commit into
mainfrom
docs/bug11-closeout
Jun 12, 2026
Merged

docs(design): host-access sync contract, reset-epoch frees, pinning, dst-form accumulation policy#139
dndungu merged 1 commit into
mainfrom
docs/bug11-closeout

Conversation

@dndungu

Copy link
Copy Markdown
Contributor

Summary

Documentation close-out for the gpu-training-hardening plan (zerfoo plan T5.3). docs/design.md gains the contracts shipped across #129-#138, stated in general terms:

  • Host-Access Synchronization (new section under tensor/): host reads/writes of device memory are stream-ordered via per-device registered sync hooks (tensor.RegisterHostAccessSync); the GPU engine registers a capture-guarded stream.Synchronize() and unregisters on Close (fix: stream-order GPUStorage host access (Bug 11, Wolf batch-3 gradient NaN) #137).
  • Arena Reset (expanded): pinning (ADR 006 — refcounted Pin/Unpin, reset floor, MarkStepBoundary) and reset epochs — pool-backed storage captures its epoch at allocation (gpuapi.EpochMemPool), frees route through FreeAtEpoch which atomically drops cross-epoch frees, so GC-finalizer-driven frees are safe across Reset by construction (fix: arena frees are reset-epoch guarded -- stale GC-finalizer frees dropped (Bug 11 residual) #138).
  • dst-form accumulation policy (Engine[T] section): a supplied dst keeps its storage identity — ops never re-home it onto a pool allocation — making dst-form accumulation safe for persistent tensors.
  • Graph[T]: documents the Engine() accessor and the save-for-backward lifetime contract (ADR 006).

docs/devlog.md gains the dated entry for the end-to-end GB10 validation of #137/#138 (two consecutive clean f32 training runs, zero NaN, accuracy within 0.05pp of the CPU baseline).

Docs-only change.

…dst-form accumulation policy
design.md documents the contracts shipped for the GPU training
hardening plan in general terms:
- Host-Access Synchronization: host reads/writes of device memory are
stream-ordered via per-device registered sync hooks
(tensor.RegisterHostAccessSync); the GPU engine registers a
capture-guarded stream.Synchronize() (#137).
- Arena Reset: pinning (ADR 006 reset floor / MarkStepBoundary) and
reset epochs -- FreeAtEpoch drops cross-epoch frees, making
GC-finalizer-driven frees safe across Reset (#138).
- Engine dst-form accumulation policy: results write into dst's
existing storage, never re-homed to the arena.
- Graph features: Engine() accessor and the save-for-backward
lifetime contract (ADR 006).
devlog: end-to-end GB10 validation entry for #137/#138 (two clean
runs, zero NaN, accuracy within 0.05pp of the CPU baseline).
@dndungu
dndungu merged commit ebf0008 into mainJun 12, 2026
1 check passed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@dndungu