cuda-core: safe element casts require AnyBitPattern; bool is DeviceCopy by elibol · Pull Request #1516 · NVIDIA/cuda-rust

elibol · 2026-10-13T23:20:39Z

Closes #1506. First change under #1460; implements the bool decision recorded there and in #1461 and #1503.

Safe element casts previously checked size and alignment but could turn a byte containing 2 into a Rust bool. This PR rejects those casts, supports initialized bool buffers, and closes the host-side initialization, atomic-reference, kernel-argument, and pinned-alignment holes found during review and follow-up auditing.

Element validity

DeviceBuffer::cast_elem, cast_chunks, can_cast_chunks, and Tensor::reinterpret require bytemuck::AnyBitPattern on the target. Casting into bool is therefore a compile error.

bool implements DeviceCopy: valid values can be copied between host and device, and its all-zero representation is valid. DeviceCopy does not promise that every bit pattern is valid. It remains independent of DType.

The numeric DType newtypes implement Pod, and half enables its bytemuck feature, preserving numeric reinterpretation targets. cuda-core re-exports bytemuck for downstream marker implementations. Vector types in cuda-device also implement Pod, preserving cast_chunks usage.

Owned atomic-buffer conversions

wrap_elem and peel_elem use the unsafe marker DeviceRepr<Inner>. Its contract requires identical layout, valid initialized representations in both directions, no element destruction, and no additional ownership obligations. It has no methods and grants no reference conversions.

The integer and floating-point atomic macros implement DeviceRepr, not TransparentWrapper. Consequently, safe DeviceAtomicU32::wrap_ref(&u32) and the reverse peel_ref conversion are unavailable. Owned scalar buffers can still be wrapped for atomic kernel access and peeled for readback, retaining their allocation, context, and deallocation stream. Kernel accesses must obey the existing borrowing and synchronization contracts.

The marker lives in the dependency-free, no_std cuda-repr crate and is re-exported by cuda-core and cuda-device. This lets both sides share one trait without making kernel-only crates depend on the host runtime. The dependent lockfiles add this local package without changing registry or git dependencies. CI path filters include the new crate.

The atomic examples use wrap_elem/peel_elem. KernelSliceArg is not restricted to DeviceCopy, since atomic wrappers are legitimate kernel element types that cannot implement Copy.

Completed zero-initialization

DeviceBuffer::zeroed queues the zero-fill and synchronizes its stream before returning. A safe readback or launch on another stream can therefore rely on initialization having completed, including for bool. Empty allocations retain their fast path.

This makes nonempty zeroed a blocking constructor. Asynchronous initialization with automatically retained completion dependencies belongs to the subsequent runtime work; callers are not asked to repair a safe API through manual synchronization.

Host-side argument contracts and pinned alignment

KernelInputStored and KernelOutputStored now require unsafe impl. Their contracts cover truthful dtype/layout/specialization metadata, argument ABI, addressable extent, and storage/access retention through completion and graph replay. Previously an entirely safe custom binding could present Tensor<bool> storage as u8 output, so a normal byte kernel could write invalid bool values. The input counterpart could similarly mislabel arbitrary byte storage as booleans. The safe KernelInput/KernelOutput conversion traits remain available and must return stored bindings satisfying those contracts. Existing owned, borrowed, view, and mapped bindings retain their behavior.

PinnedHostBuffer reserves alignment slack, exposes an aligned interior pointer, and retains the original CUDA pointer for deallocation. It also rejects allocation sizes that exceed Rust slice/pointer-arithmetic limits. Empty and zero-sized buffers keep their aligned dangling pointers and allocation-free behavior.

Tensor alias accounting

Tensor aliases and lazy copy operations share a separate ownership token. Completion leases retain the storage itself without contributing to that token. Uniqueness therefore stays correct while a lease is being registered or destroyed: a real alias cannot become a mutable partition, and retiring a lease cannot spuriously reject a unique tensor. Access exclusion and completion retention remain enforced.

The acquisition and destruction regressions fail on the previous implementation and pass with this change. A separate test preserves ownership held by an unsubmitted copy operation.

Compatibility and validation

The new AnyBitPattern bounds are a breaking change for reinterpretation targets that do not implement that trait. Numeric targets remain supported; atomics use the owned-buffer conversions. Tuple types remain usable as buffer elements but are not reinterpretation targets. Custom stored Tile argument implementations must now explicitly uphold the documented unsafe contract.

Validated after updating this branch against main:

Full cuda-core and cuda-device tests, including GPU buffer tests, compile-fail tests for invalid bool casts and both atomic shared-reference conversions, and layout checks for all 21 scoped atomic types.
A gated-stream regression that fails without the initialization synchronization and passes with it. It inspects bytes, avoiding invalid Rust bool values in the failing case.
Owned wrapper roundtrip coverage for pointer identity, context, stream retention, and readback.
GPU runs of legacy_atomic_rmw_cas, legacy_atomic_fadd, and hashmap on an RTX 5090; all six Tile tensor reinterpretation tests.
Clippy for cuda-core/cuda-repr, cuda-device/cuda-host, and cutile; host and component formatting; cuda-core/cuda-repr rustdoc with warnings denied.
Device-only build, example lock consistency, dependency-license/SPDX/source-reference/test-matrix guards, and cargo-deny for the host, SIMT, backend, device-only, and Tile workspaces.

The Tile UI snapshot now uses the normalized external-crate path. Both UI harness tests (all 12 compile-fail cases) pass, and the CPU CI script now runs them. The version-only update to the planned v0.5.0 API boundary has landed on main in #1614; host and Tile semver checks pass. SIMT workflow branch filters now include stacked PRs targeting pull-request/<n> prerequisite mirrors.

Follow-up validation for the host-side argument and pinned-buffer fixes:

Both new compile-fail cases compiled before the fix and now fail specifically because unsafe impl is required; snapshots were reviewed and rerun without overwrite.
The pinned alignment regression failed before the fix, without constructing misaligned references. It now passes, alongside over-aligned copying, empty/ZST coverage, and allocation-size boundary tests.
Full cuda-core suite: 105 passed, 3 ignored. Selected Tile library/GPU/tensor/view suites: 168 passed, 2 ignored. Submission-lifetime suite: all 9 passed, including forgotten borrowed work and graph replay.
cuda-core and cutile Clippy with warnings denied, host/Tile formatting, and SPDX checks passed. cuda-core rustdoc with warnings denied passed. Tile documentation builds, but its stricter warnings-as-errors check reports 12 existing link warnings outside the added trait documentation.

Current follow-up validation: the complete CPU runner passes (1,408 tests, 98 intentionally ignored), including the Tile UI suites. All 25 targeted GPU buffer and pinned-host-buffer tests pass, including the cross-stream initialization regression. The branch includes the #1602 debug-source fixes and the same version metadata as #1614.

Current-main integration: Merged current main after the CuTe preview import and reconciled the dependency lockfiles and license inventory, retaining cuda-repr. CuTe library tests and doctests pass (229 tests), as do affected-package Clippy, lockfile/license guards, and dependency checks. Fresh CI is running at 93dd50704b; the preceding head had all 63 active checks passing.

DeviceBuffer::cast_elem, DeviceBuffer::cast_chunks, and Tensor::reinterpret reinterpreted device bytes as any element type of the right size and alignment, which let a u8 buffer become a DeviceBuffer<bool> or Tensor<bool> holding values other than 0 and 1 (NVIDIA#1506). The casts now require bytemuck::AnyBitPattern of their target, so bool is rejected at compile time, and bool implements DeviceCopy: a typed buffer holds valid values by construction, so bool buffers can be allocated, filled, launched, and read back like any other element type. cuda-core re-exports bytemuck, implements Pod for the DType newtypes, and enables half's bytemuck feature for f16 and bf16. The atomic wrappers in cuda-device are not Copy, so they cannot be AnyBitPattern. DeviceBuffer gains wrap_elem and peel_elem, bounded on bytemuck::TransparentWrapper, to view a scalar buffer as its atomic wrapper and back. cuda-device implements TransparentWrapper for its atomic types and Pod for its vector types, and the examples that cast into atomics use the new methods. Every example lock gains the bytemuck dependency of cuda-device. Signed-off-by: Melih Elibol <1884921+elibol@users.noreply.github.com>

copy-pr-bot · 2026-10-14T04:18:42Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

nihalpasham · 2026-10-14T13:23:25Z

So, as a first step I think the DeviceCopy / AnyBitPattern split makes sense. Under the revised contract, bool can implement DeviceCopy while remaining excluded from AnyBitPattern. Requiring AnyBitPattern on reinterpretation targets rejects cast_elem::<bool>(), preventing byte 2 from becoming a bool through that safe cast.

But we need to address two safety issues that popped up from trying to break the above setup via adversarial examples.

1. The first one is the atomic TransparentWrapper implementations expose invalid shared-reference conversions.

The intended operation is converting an owned integer buffer into an atomic buffer. But implementing TransparentWrapper also exposes safe methods on the atomic type:

use bytemuck::TransparentWrapper;

// Device code:
fn overwrite(value: &u32) {
    let atomic = DeviceAtomicU32::wrap_ref(value);
    atomic.store(7, AtomicOrdering::Relaxed);
}

The conversion aliases the same memory:

&u32 → &DeviceAtomicU32 → store(7)

The original &u32 does not permit that mutation. Matching size and alignment cannot grant that permission. The reverse conversion, peel_ref, also allows an ordinary shared reference to coexist with mutation through the atomic.

Proposed fix: remove the atomic TransparentWrapper implementations and retain wrap_elem / peel_elem using a narrower unsafe marker, provisionally named DeviceRepr<Inner>:

pub unsafe trait DeviceRepr<Inner>: Sized {}

Its documented contract would require matching layout, valid initialized representations in both directions, and no additional ownership or destruction obligations. It would provide no reference-conversion methods.

The buffer’s wrap_elem bound becomes W: DeviceRepr<T>, with the corresponding change to peel_elem. Existing atomic-buffer usage remains available:

let atomics = integers.wrap_elem::<DeviceAtomicU32>();
// Run the kernel and complete its accesses.
let integers = atomics.peel_elem::<u32>();

DeviceAtomicU32::wrap_ref(&value) becomes unavailable because the atomic no longer implements TransparentWrapper. Allocation ownership, lifetimes, and ordering must remain preserved.

nihalpasham · 2026-10-14T13:25:48Z

2. zeroed() can return before the buffer actually contains zeros.

Suppose an allocation still contains old byte 2. We request a buffer of bool, initialized to false—byte 0:

// writer and reader are independent GPU streams.
let flags = DeviceBuffer::<bool>::zeroed(&writer, 1)?;
let values = flags.to_host_vec(&reader)?;

Both calls are safe Rust. However, zeroed only queues the zero-fill on writer. This execution is possible:

Time ───────────────────────────────────────►

writer: [earlier work................][write 0]
reader:      [copy existing byte 2 to CPU]

to_host_vec waits for the copy on reader; it does not establish that writer finished initializing the allocation first. It can therefore copy byte 2 into a Rust bool, causing undefined behavior.

AnyBitPattern cannot prevent this: there is no cast to bool. The buffer was created as DeviceBuffer<bool> directly.

Proposed fix: the simplest repair is to finish initialization before safe zeroed() returns:

// After queuing the zero-fill:
stream.synchronize()?;
Ok(buf)

To preserve asynchronous initialization, retain its completion dependency and make every safe consumer honor it, including readback and kernel launches. Asking callers to synchronize in documentation does not repair the safe API.

Our GPU probe observed byte 2 throughout a 1 MiB buffer before synchronizing writer, then zeros afterward. The probe inspected u8 bytes, avoiding invalid Rust booleans.

I think the initialization-ordering code predates this PR and it only surfaced after admitting bool which exposed its invalid-value consequence.