Struct View 

pub struct View<'a> { /* private fields */ }

A binding into a device allocation, borrowed from it.

The borrow keeps the buffer alive and identifies the stream allowed to use this view. Any stream on the same device may use it, ordered by the caller.

Implementations

impl<'a> View<'a>

pub fn access(self, access: Access) -> AccessView<'a>

Declare how a graph operation accesses this view.

pub fn read(self) -> AccessView<'a>

Declare read-only graph access.

pub fn write(self) -> AccessView<'a>

Declare write-only graph access.

pub fn read_write(self) -> AccessView<'a>

Declare graph access that reads and writes existing bytes.

impl<'a> View<'a>

pub fn slice(self, offset: usize, length: usize) -> Result<Self>

Borrow a region relative to this view, rejecting overflow and overruns. An empty region at the end of the view is valid.

Examples found in repository

examples/import_probe.rs (line 63)

fn main() -> Result<()> {
    let mib: usize = match std::env::args().collect::<Vec<_>>().as_slice() {
        [_] => 16,
        [_, flag, value] if flag == "--mib" => value.parse().expect("--mib expects an integer"),
        _ => {
            eprintln!("usage: import_probe [--mib N]");
            std::process::exit(2);
        }
    };
    let bytes = mib * 1024 * 1024;
    let layout = Layout::from_size_align(bytes, PAGE).expect("page-aligned layout");

    // Owned for the whole scope below; the imported buffer never frees it.
    let host = unsafe { alloc_zeroed(layout) };
    assert!(!host.is_null(), "host allocation failed");
    let result = (|| -> Result<()> {
        let mut stream = Stream::open()?;
        let buffer = match unsafe { stream.import_host(host.cast(), bytes) } {
            Ok(buffer) => buffer,
            Err(error) => {
                println!("import: UNSUPPORTED ({error})");
                return Ok(());
            }
        };
        println!("import: ok ({mib} MiB at {host:p})");

        // Prove the host pages start clear, so a match afterwards can only be the GPU.
        let before = unsafe { std::slice::from_raw_parts(host, bytes) };
        assert!(before.iter().all(|&b| b == 0), "host memory was not zeroed");

        stream.fill(buffer.binding(), PATTERN)?;
        stream.synchronize()?;

        // Read the ORIGINAL host pointer -- no download, no staging buffer.
        let after = unsafe { std::slice::from_raw_parts(host, bytes) };
        let wrong = after.iter().filter(|&&b| b != PATTERN).count();
        if wrong == 0 {
            println!("gpu fill visible on host pointer: YES (zero-copy confirmed)");
        } else {
            println!("gpu fill visible on host pointer: NO ({wrong}/{bytes} bytes unwritten)");
        }

        // A device-side read of the same buffer must also see host writes.
        let mirror = stream.allocate(bytes)?;
        unsafe { std::slice::from_raw_parts_mut(host, bytes) }.fill(0x3c);
        stream.copy(mirror.binding(), buffer.binding())?;
        let mut check = [0u8; 64];
        stream.read_blocking(mirror.binding().slice(0, check.len())?, &mut check)?;
        let coherent = check.iter().all(|&b| b == 0x3c);
        println!(
            "host write visible to device: {}",
            if coherent { "YES" } else { "NO" }
        );
        Ok(())
    })();
    unsafe { dealloc(host, layout) };
    result
}

examples/unified_probe.rs (line 202)

fn main() -> Result<()> {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let (xclbin, mib) = match args.as_slice() {
        [xclbin] => (xclbin.clone(), 4usize),
        [xclbin, flag, value] if flag == "--mib" => (
            xclbin.clone(),
            value.parse().expect("--mib expects an integer"),
        ),
        _ => {
            eprintln!("usage: unified_probe <xclbin> [--mib N]");
            std::process::exit(2);
        }
    };
    let bytes = mib * 1024 * 1024;
    let layout = Layout::from_size_align(bytes, PAGE).expect("page-aligned layout");
    let host = unsafe { alloc_zeroed(layout) };
    assert!(!host.is_null(), "host allocation failed");

    let result = (|| -> Result<()> {
        println!("host allocation: {mib} MiB at {host:p}");

        let context = match unsafe { dvxrt::Context::new(0, &xclbin) } {
            Ok(context) => context,
            Err(error) => {
                println!("npu context: UNAVAILABLE ({error})");
                return Ok(());
            }
        };
        let group = context.group_id(ARG_A).expect("group id for A");

        // 1. Can amdxdna pin pages we allocated? Reported either way -- if it can, either
        //    runtime may own the allocation; if it cannot, only the NPU's allocator may.
        match unsafe { context.import_bo(host.cast(), bytes, dvxrt::BoKind::HostOnly, group) } {
            Ok(_) => println!("npu userptr import (host-owned pages): YES"),
            Err(error) => println!("npu userptr import (host-owned pages): NO ({error})"),
        }

        // 2. The direction that matters: let the NPU's allocator own the pages -- it is the
        //    more constrained of the two -- and import its host mapping into the GPU runtime.
        let bo = context
            .alloc_bo(bytes, dvxrt::BoKind::HostOnly, group)
            .expect("allocate an NPU BO");
        let shared = bo.map().expect("map the NPU BO");
        println!("npu allocation mapped at {shared:p}");
        assert_eq!(shared as usize % PAGE, 0, "NPU mapping is not page-aligned");

        let mut stream = Stream::open()?;
        let imported = unsafe { stream.import_host(shared.cast(), bytes) };
        match &imported {
            Ok(_) => println!("gpu import of the NPU mapping: YES"),
            Err(error) => println!("gpu import of the NPU mapping: NO ({error})"),
        }

        // 3. If the shared mapping took, check that a GPU write lands in the NPU's BO.
        if let Ok(buffer) = &imported {
            stream.fill(buffer.binding(), GPU_PATTERN)?;
            stream.synchronize()?;
            bo.sync(false, bytes).expect("invalidate for device reads");
            let mut seen = vec![0u8; 4096];
            bo.read(&mut seen).expect("read through the NPU BO");
            let wrong = seen.iter().filter(|&&b| b != GPU_PATTERN).count();
            println!(
                "gpu write -> npu read: {}",
                if wrong == 0 {
                    "YES".into()
                } else {
                    format!("NO ({wrong} bytes differ)")
                }
            );
        }

        // 3b. The dma-buf route: the GPU allocates, HSA exports the allocation as a
        //     dma-buf, and XRT imports that descriptor. Neither runtime copies, and unlike
        //     the host-pointer routes above neither driver has to pin the other's pages.
        // The GPU-side import above HSA-locked these pages, so they are exportable.
        let locked = unsafe { stream.import_host(host.cast(), bytes) };
        let export = match &locked {
            Ok(buffer) => {
                stream.fill(buffer.binding(), GPU_PATTERN)?;
                stream.synchronize()?;
                export_dmabuf(host.cast(), bytes)
            }
            Err(error) => Err(format!("host pages are not GPU-resident: {error}")),
        };
        match export {
            Ok((fd, size)) => {
                println!("hsa dma-buf export of a GPU buffer: YES (fd {fd})");
                match unsafe { context.import_dmabuf(fd, size) } {
                    Ok(imported) => {
                        println!("npu import of the GPU dma-buf: YES");
                        let mut seen = vec![0u8; 4096];
                        match imported.read(&mut seen) {
                            Ok(()) => {
                                let wrong = seen.iter().filter(|&&b| b != GPU_PATTERN).count();
                                println!(
                                    "  gpu write -> npu read over dma-buf: {}",
                                    if wrong == 0 {
                                        "YES".into()
                                    } else {
                                        format!("NO ({wrong} bytes differ)")
                                    }
                                );
                            }
                            Err(error) => {
                                println!("  read through the imported BO failed: {error}")
                            }
                        }
                    }
                    Err(error) => println!("npu import of the GPU dma-buf: NO ({error})"),
                }
            }
            Err(error) => println!("hsa dma-buf export of a GPU buffer: NO ({error})"),
        }

        // 4. And the reverse: the NPU's BO writes, the GPU reads.
        if let Ok(buffer) = &imported {
            bo.write(&vec![NPU_PATTERN; bytes])
                .expect("write through the NPU BO");
            let mirror = stream.allocate(bytes)?;
            stream.copy(mirror.binding(), buffer.binding())?;
            let mut check = [0u8; 64];
            stream.read_blocking(mirror.binding().slice(0, check.len())?, &mut check)?;
            let back = check.iter().all(|&b| b == NPU_PATTERN);
            println!("npu write -> gpu read: {}", if back { "YES" } else { "NO" });
        }
        Ok(())
    })();
    unsafe { dealloc(host, layout) };
    result
}

examples/stream_bench.rs (line 60)

fn main() -> Result<()> {
    let mut stream = Stream::open()?;
    let mut metrics = BTreeMap::new();
    let samples = std::env::var("HRX_BENCH_SAMPLES")
        .ok()
        .and_then(|value| value.parse::<usize>().ok())
        .filter(|&value| value > 0)
        .unwrap_or(9);
    let (ns, _) = measure(&mut stream, samples, 50_000, |stream| {
        for _ in 0..50_000 {
            let buffer = stream.scratch(1024 * 1024)?;
            black_box(&buffer);
            stream.recycle(buffer)?;
        }
        Ok(())
    })?;
    metrics.insert("scratch_reuse_ns", ns);
    let (ns, _) = measure(&mut stream, samples, 2_000, |stream| {
        for _ in 0..2_000 {
            black_box(stream.allocate(1024 * 1024)?);
        }
        Ok(())
    })?;
    metrics.insert("allocate_drop_ns", ns);

    let bytes = 256 * 1024 * 1024;
    let chunk = vec![0x3cu8; 4 * 1024 * 1024];
    let weights = stream.allocate(bytes)?;
    let (_, ns) = measure(&mut stream, samples, 1, |stream| {
        for offset in (0..bytes).step_by(chunk.len()) {
            stream.upload(weights.binding().slice(offset, chunk.len())?, &chunk)?;
        }
        Ok(())
    })?;
    metrics.insert(
        "queued_upload_gib_s",
        bytes as f64 / (1024f64.powi(3) * ns * 1e-9),
    );
    let mut check = [0u8; 16];
    stream.read_blocking(
        weights.try_slice(bytes - check.len(), check.len())?,
        &mut check,
    )?;
    assert_eq!(check, [0x3c; 16]);
    drop(weights);

    let compiler = hrx::loom::Compiler::for_stream(None, &stream)?;
    let module = compiler.module(include_str!("../tests/kernels/euler.loom"));
    let mut spec = hrx::loom::Specialization::new("krea2_euler");
    spec.set_config("krea2.euler.grid_x", "1");
    spec.set_config("krea2.euler.grid_y", "1");
    let artifact = module.compile(&spec)?;
    // This repository owns the source; use its exact dimensions and scalar layout.
    let kernel = unsafe { stream.load_artifact(&artifact)? };
    let sample = stream.allocate(512)?;
    let velocity = stream.allocate(512)?;
    let ones: Vec<u8> = (0..256).flat_map(|_| 0x3f80u16.to_le_bytes()).collect();
    stream.upload_blocking(sample.binding(), &ones)?;
    stream.upload_blocking(velocity.binding(), &ones)?;
    let mut constants = Constants::new();
    match kernel.info().constant_byte_length {
        8 => constants.push(256u32)?,
        12 => constants.push(256u64)?,
        n => return Err(hrx::Error::Message(format!("unexpected constant size {n}"))),
    }
    constants.push(0f32)?;
    let bindings = [sample.binding(), velocity.binding()];
    let (enqueue, complete) = measure(&mut stream, samples, 2048, |stream| {
        for _ in 0..2048 {
            // The source accesses exactly the 256 bf16 elements in each buffer.
            unsafe {
                stream.dispatch(&kernel, [1; 3], [256, 1, 1], &constants, &bindings)?;
            }
        }
        Ok(())
    })?;
    metrics.insert("dispatch_enqueue_ns", enqueue);
    metrics.insert("dispatch_complete_ns", complete);

    // Use disjoint allocations in both graphs. Even an idempotent store is a
    // write: concurrent Euler dispatches cannot share their in/out buffer.
    let mut graph_buffers = Vec::new();
    for _ in 0..32 {
        let sample = stream.allocate(512)?;
        let velocity = stream.allocate(512)?;
        stream.upload(sample.binding(), &ones)?;
        stream.upload(velocity.binding(), &ones)?;
        graph_buffers.push((sample, velocity));
    }
    stream.synchronize()?;
    let mut builder = stream.graph()?;
    let mut previous = None;
    for (sample, velocity) in &graph_buffers {
        let after = previous.as_slice();
        previous = Some(unsafe {
            builder.dispatch(
                after,
                &kernel,
                [1; 3],
                [256, 1, 1],
                &constants,
                &[sample.binding(), velocity.binding()],
            )?
        });
    }
    let chained = builder.finish()?;

    // The same disjoint workloads, this time allowing concurrent scheduling.
    let mut builder = stream.graph()?;
    for (sample, velocity) in &graph_buffers {
        unsafe {
            builder.dispatch(
                &[],
                &kernel,
                [1; 3],
                [256, 1, 1],
                &constants,
                &[sample.binding(), velocity.binding()],
            )?;
        }
    }
    let independent = builder.finish()?;
    let mut graphs = [chained, independent];
    let mut enqueue = [Vec::new(), Vec::new()];
    let mut complete = [Vec::new(), Vec::new()];
    for round in 0..samples + 3 {
        for arm in if round % 2 == 0 { [0, 1] } else { [1, 0] } {
            stream.synchronize()?;
            let start = Instant::now();
            for _ in 0..256 {
                stream.launch(&mut graphs[arm])?;
            }
            let submitted = start.elapsed();
            stream.synchronize()?;
            let elapsed = start.elapsed();
            if round >= 3 {
                enqueue[arm].push(submitted.as_secs_f64() * 1e9 / 256.0);
                complete[arm].push(elapsed.as_secs_f64() * 1e9 / (256.0 * 32.0));
            }
        }
    }
    for values in enqueue.iter_mut().chain(complete.iter_mut()) {
        values.sort_by(f64::total_cmp);
    }
    let ns = complete[0][samples / 2];
    let ns_free = complete[1][samples / 2];
    metrics.insert("graph_enqueue_ns_per_replay", enqueue[0][samples / 2]);
    metrics.insert("graph_complete_ns_per_kernel", ns);
    metrics.insert("graph_independent_ns_per_kernel", ns_free);
    metrics.insert("graph_scheduling_difference_ns_per_kernel", ns - ns_free);
    for (sample, _) in &graph_buffers {
        let mut output = vec![0; 512];
        stream.read_blocking(sample.binding(), &mut output)?;
        assert_eq!(output, ones);
    }
    let mut output = vec![0; 512];
    stream.read_blocking(sample.binding(), &mut output)?;
    assert_eq!(output, ones);
    println!("{}", serde_json::to_string(&metrics)?);
    Ok(())
}

pub fn offset(self) -> usize

Byte offset from the start of the owning allocation.

pub fn owner(self) -> &'a Buffer

The buffer handle from which this view was borrowed.

pub fn len(self) -> usize

The bytes this view covers.

pub fn is_empty(self) -> bool

Whether this view covers no bytes.

Trait Implementations

impl<'a> Clone for View<'a>

fn clone(&self) -> View<'a>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Copy for View<'a>

impl<'a> Debug for View<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.