Device Bridge Contract

This document defines the behavioral contract for the backend-specific device bridge used by the GPU worker. The bridge is the worker's boundary between host ring memory, device memory, and tinygrad-compatible views.

Allocation

alloc_device(ObjectSpec, extent) creates a device allocation suitable for the object spec and extent.
Allocation failure is reported as device allocation failure.
Allocations are tied to the current worker generation.
free_device releases an allocation after no compute or copy event depends on it.

Host To Device

host_to_device copies exactly the requested host range to the requested device range.
For synchronous copies, return means bytes are safe to release.
For asynchronous copies, completion of the copy event means bytes are safe to release.
Copy failure is reported as device copy failure.

Device To Host

device_to_host copies exactly the requested device range to the requested host range.
For synchronous copies, return means host bytes are valid.
For asynchronous copies, completion of the copy event means host bytes are valid.
Copy failure is reported as output copy failure or device copy failure.

Tinygrad View

wrap_for_tinygrad creates a tinygrad-compatible view over a device allocation.
The view matches the tensor view spec used by the role.
Invalid view shape or dtype fails the step.

Lifetime

Device allocations are not freed while compute uses them.
Device allocations are not freed while copy events use them.
Worker restart invalidates all prior device handles.
Old-generation handles are rejected.

Test Direction

Tests should use a fake backend to observe allocation, copy, completion, view, and free calls. Success tests should assert exact ranges and safe cursor-release points. Fault tests should inject allocation failure, copy failure, invalid view, and old-generation handles.

1.9 KiB Raw Blame History