Struct Device 

pub struct Device(/* private fields */);

An activated native address/execution domain, independent of any program.

Implementations

impl Device

pub unsafe fn prepare_xdna( &self, artifact: &Artifact, columns: u16, bindings: &[XdnaBinding<'_>], ) -> Result<XdnaProgram>

Load and bind a canonical XDNA image for the selected logical width.

Safety

The native executable must be trusted and obey its binding contracts.

Examples found in repository

examples/mall_probe.rs (lines 38-53)

fn main() -> Result<()> {
    let seconds: f64 = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "2".into())
        .parse()
        .map_err(|e: std::num::ParseFloatError| hrx::Error::Message(e.to_string()))?;
    if !seconds.is_finite() || !(0.01..=3600.0).contains(&seconds) {
        return Err(hrx::Error::Message("seconds must be in 0.01..=3600".into()));
    }
    let device = Device::open(Engine::Xdna, 0)?;
    let compiler = Compiler::for_target(None, device.target())?;
    println!("working_set_MiB GB/s dispatches/s");
    for mib in [1, 4, 8, 16, 32, 64] {
        let bytes = mib * 1024 * 1024;
        let artifact = compiler
            .module(include_str!("../tests/kernels/copy.xdna.loom"))
            .compile(
                &Specialization::new("copy")
                    .with_config("copy.packets", (bytes / 4096).to_string()),
            )?;
        let input = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        let output = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        input.write(0, &vec![0x5a; bytes])?;
        let program = unsafe {
            device.prepare_xdna(
                &artifact,
                1,
                &[
                    XdnaBinding {
                        buffer: &input,
                        offset: 0,
                        length: bytes,
                    },
                    XdnaBinding {
                        buffer: &output,
                        offset: 0,
                        length: bytes,
                    },
                ],
            )
        }?;
        unsafe { program.dispatch() }?.wait()?;
        let mut check = vec![0; bytes];
        output.read(0, &mut check)?;
        assert!(check.iter().all(|&b| b == 0x5a));
        let start = Instant::now();
        let mut count = 0;
        while start.elapsed() < Duration::from_secs_f64(seconds) {
            unsafe { program.dispatch() }?.wait()?;
            count += 1;
        }
        let elapsed = start.elapsed().as_secs_f64();
        println!(
            "{} {:.3} {:.1}",
            2 * mib,
            2.0 * bytes as f64 * count as f64 / elapsed / 1e9,
            count as f64 / elapsed
        );
    }
    Ok(())
}

impl Device

pub fn queue(&self) -> Result<Queue>

Create a native PM4 queue with one serialized host producer.

Examples found in repository

examples/unified_probe.rs (line 16)

fn main() -> Result<()> {
    let fabric = Fabric::resolve()?;
    let gpu = Device::open(Engine::Gpu, 0)?;
    let npu = Device::open(Engine::Xdna, 0)?;
    let buffer = fabric.allocate(1 << 20, &[gpu.clone(), npu.clone()])?;
    println!(
        "GPU address={:#x}, XDNA DMA address={:#x}",
        buffer.device_address(&gpu)?,
        buffer.device_address(&npu)?
    );
    let fill = gpu.queue()?.prepare_fill(&buffer, 0, buffer.len(), 0x5a)?;
    unsafe { fill.dispatch() }?.wait()?;
    let mut bytes = vec![0; buffer.len()];
    buffer.read(0, &mut bytes)?;
    assert!(bytes.iter().all(|&byte| byte == 0x5a));
    println!("native shared allocation: {} bytes verified", bytes.len());
    Ok(())
}

pub fn sdma_queue(&self) -> Result<Queue>

Create a native SDMA transfer queue without loading compute kernels.

impl Device

pub unsafe fn load(&self, artifact: &Artifact) -> Result<Kernel>

Load an entry from a compiler-produced artifact onto this GPU.

Safety

The executable is native code. The caller must trust its code and its declared memory/argument contract; parsing is not a sandbox.

pub unsafe fn load_sanitized( &self, artifact: &Artifact, options: &SanitizerRuntimeOptions, ) -> Result<Kernel>

Load an artifact with an owned, bounded sanitizer feedback channel. Supports address/value/operation reports and workgroup-local race checking. Address shadow covers the complete bound allocations and executable storage. Allocation starts must be 8-byte aligned; undeclared pointers stay poisoned. Preparation rejects an address span whose shadow exceeds the configured limit. Dispatch through an AQL queue, which supplies the native dispatch pointer.

Safety

The artifact must use the current compiler and its bounded shadow checks. It remains trusted native code. Use report-only instrumentation when execution must complete after a diagnostic; trap mode can fault the queue.

pub unsafe fn load_bytes(&self, bytes: &[u8], symbol: &str) -> Result<Kernel>

Load a native gfx1151 code object and select its named entry.

Safety

The native code must be trusted and obey its declared memory contract.

impl Device

pub fn aql_queue(&self, maximum_private_bytes: u32) -> Result<AqlQueue>

Create an AQL queue with fixed per-workitem scratch capacity. Zero admits kernels with no private segment. All physical scratch slots are allocated before returning; dispatch never grows the pool.

pub fn aql_queue_budgeted( &self, maximum_private_bytes: u32, budget: Option<&MemoryBudget>, ) -> Result<AqlQueue>

Create a queue whose scratch and prepared dispatch storage share a byte ceiling.

impl Device

pub fn endpoint(&self) -> &Endpoint

Passive identity retained by the activated device.

pub fn target(&self) -> &Target

Exact target for offline compilation and executable admission.

Examples found in repository

examples/mall_probe.rs (line 20)

fn main() -> Result<()> {
    let seconds: f64 = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "2".into())
        .parse()
        .map_err(|e: std::num::ParseFloatError| hrx::Error::Message(e.to_string()))?;
    if !seconds.is_finite() || !(0.01..=3600.0).contains(&seconds) {
        return Err(hrx::Error::Message("seconds must be in 0.01..=3600".into()));
    }
    let device = Device::open(Engine::Xdna, 0)?;
    let compiler = Compiler::for_target(None, device.target())?;
    println!("working_set_MiB GB/s dispatches/s");
    for mib in [1, 4, 8, 16, 32, 64] {
        let bytes = mib * 1024 * 1024;
        let artifact = compiler
            .module(include_str!("../tests/kernels/copy.xdna.loom"))
            .compile(
                &Specialization::new("copy")
                    .with_config("copy.packets", (bytes / 4096).to_string()),
            )?;
        let input = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        let output = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        input.write(0, &vec![0x5a; bytes])?;
        let program = unsafe {
            device.prepare_xdna(
                &artifact,
                1,
                &[
                    XdnaBinding {
                        buffer: &input,
                        offset: 0,
                        length: bytes,
                    },
                    XdnaBinding {
                        buffer: &output,
                        offset: 0,
                        length: bytes,
                    },
                ],
            )
        }?;
        unsafe { program.dispatch() }?.wait()?;
        let mut check = vec![0; bytes];
        output.read(0, &mut check)?;
        assert!(check.iter().all(|&b| b == 0x5a));
        let start = Instant::now();
        let mut count = 0;
        while start.elapsed() < Duration::from_secs_f64(seconds) {
            unsafe { program.dispatch() }?.wait()?;
            count += 1;
        }
        let elapsed = start.elapsed().as_secs_f64();
        println!(
            "{} {:.3} {:.1}",
            2 * mib,
            2.0 * bytes as f64 * count as f64 / elapsed / 1e9,
            count as f64 / elapsed
        );
    }
    Ok(())
}

impl Device

pub fn open(engine: Engine, index: usize) -> Result<Self>

Open a selected engine ordinal in the shared, weakly cached provider. Live buffers keep their exact device identity; the registry owns no device.

Examples found in repository

examples/unified_probe.rs (line 8)

fn main() -> Result<()> {
    let fabric = Fabric::resolve()?;
    let gpu = Device::open(Engine::Gpu, 0)?;
    let npu = Device::open(Engine::Xdna, 0)?;
    let buffer = fabric.allocate(1 << 20, &[gpu.clone(), npu.clone()])?;
    println!(
        "GPU address={:#x}, XDNA DMA address={:#x}",
        buffer.device_address(&gpu)?,
        buffer.device_address(&npu)?
    );
    let fill = gpu.queue()?.prepare_fill(&buffer, 0, buffer.len(), 0x5a)?;
    unsafe { fill.dispatch() }?.wait()?;
    let mut bytes = vec![0; buffer.len()];
    buffer.read(0, &mut bytes)?;
    assert!(bytes.iter().all(|&byte| byte == 0x5a));
    println!("native shared allocation: {} bytes verified", bytes.len());
    Ok(())
}

examples/mall_probe.rs (line 19)

fn main() -> Result<()> {
    let seconds: f64 = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "2".into())
        .parse()
        .map_err(|e: std::num::ParseFloatError| hrx::Error::Message(e.to_string()))?;
    if !seconds.is_finite() || !(0.01..=3600.0).contains(&seconds) {
        return Err(hrx::Error::Message("seconds must be in 0.01..=3600".into()));
    }
    let device = Device::open(Engine::Xdna, 0)?;
    let compiler = Compiler::for_target(None, device.target())?;
    println!("working_set_MiB GB/s dispatches/s");
    for mib in [1, 4, 8, 16, 32, 64] {
        let bytes = mib * 1024 * 1024;
        let artifact = compiler
            .module(include_str!("../tests/kernels/copy.xdna.loom"))
            .compile(
                &Specialization::new("copy")
                    .with_config("copy.packets", (bytes / 4096).to_string()),
            )?;
        let input = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        let output = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        input.write(0, &vec![0x5a; bytes])?;
        let program = unsafe {
            device.prepare_xdna(
                &artifact,
                1,
                &[
                    XdnaBinding {
                        buffer: &input,
                        offset: 0,
                        length: bytes,
                    },
                    XdnaBinding {
                        buffer: &output,
                        offset: 0,
                        length: bytes,
                    },
                ],
            )
        }?;
        unsafe { program.dispatch() }?.wait()?;
        let mut check = vec![0; bytes];
        output.read(0, &mut check)?;
        assert!(check.iter().all(|&b| b == 0x5a));
        let start = Instant::now();
        let mut count = 0;
        while start.elapsed() < Duration::from_secs_f64(seconds) {
            unsafe { program.dispatch() }?.wait()?;
            count += 1;
        }
        let elapsed = start.elapsed().as_secs_f64();
        println!(
            "{} {:.3} {:.1}",
            2 * mib,
            2.0 * bytes as f64 * count as f64 / elapsed / 1e9,
            count as f64 / elapsed
        );
    }
    Ok(())
}

pub fn open_with_lifetime( engine: Engine, index: usize, lifetime: NativeLifetime, ) -> Result<Self>

Open in an explicitly selected native ownership domain.

pub fn id(&self) -> usize

Stable identity while this device or any dependent owner is live.

pub fn fabric(&self) -> Fabric

Allocation and discovery domain retained by this device.

Examples found in repository

examples/mall_probe.rs (line 31)

fn main() -> Result<()> {
    let seconds: f64 = std::env::args()
        .nth(1)
        .unwrap_or_else(|| "2".into())
        .parse()
        .map_err(|e: std::num::ParseFloatError| hrx::Error::Message(e.to_string()))?;
    if !seconds.is_finite() || !(0.01..=3600.0).contains(&seconds) {
        return Err(hrx::Error::Message("seconds must be in 0.01..=3600".into()));
    }
    let device = Device::open(Engine::Xdna, 0)?;
    let compiler = Compiler::for_target(None, device.target())?;
    println!("working_set_MiB GB/s dispatches/s");
    for mib in [1, 4, 8, 16, 32, 64] {
        let bytes = mib * 1024 * 1024;
        let artifact = compiler
            .module(include_str!("../tests/kernels/copy.xdna.loom"))
            .compile(
                &Specialization::new("copy")
                    .with_config("copy.packets", (bytes / 4096).to_string()),
            )?;
        let input = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        let output = device
            .fabric()
            .allocate(bytes, std::slice::from_ref(&device))?;
        input.write(0, &vec![0x5a; bytes])?;
        let program = unsafe {
            device.prepare_xdna(
                &artifact,
                1,
                &[
                    XdnaBinding {
                        buffer: &input,
                        offset: 0,
                        length: bytes,
                    },
                    XdnaBinding {
                        buffer: &output,
                        offset: 0,
                        length: bytes,
                    },
                ],
            )
        }?;
        unsafe { program.dispatch() }?.wait()?;
        let mut check = vec![0; bytes];
        output.read(0, &mut check)?;
        assert!(check.iter().all(|&b| b == 0x5a));
        let start = Instant::now();
        let mut count = 0;
        while start.elapsed() < Duration::from_secs_f64(seconds) {
            unsafe { program.dispatch() }?.wait()?;
            count += 1;
        }
        let elapsed = start.elapsed().as_secs_f64();
        println!(
            "{} {:.3} {:.1}",
            2 * mib,
            2.0 * bytes as f64 * count as f64 / elapsed / 1e9,
            count as f64 / elapsed
        );
    }
    Ok(())
}

Trait Implementations

impl Clone for Device

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.