HAG (exec-hag) is a Rust library for budgeted native hardware resources and
experimental GPU execution. It provides allocation ownership, checked memory
accounting and bounded command submission. Model loading, numerical operators
and inference policy belong to applications above HAG.
The current transport uses Linux DRM render nodes and AMDGPU directly. It requires no Vulkan, SPIR-V, Mesa, ROCm or libdrm userspace runtime. The portable accounting API has no dependencies when default features are used.
Native Linux discovery and memory management are implemented. An opt-in fixed
shader probe and a reusable synchronous compute queue have historical hardware
qualification on AMD device 0x1586, physical GC 11.5.1. Selected downstream
inference fixtures also passed, including bounded Qwen3-0.6B Q8_0 execution.
Those results cover the recorded programs, checkpoints and requests; they do
not establish general GPU, model, concurrency or performance support. See the
qualification summary.
implementation_status() reports compiled functionality, without probing the
machine. Its native_compute field remains false, and
require_native_compute() returns a typed error. Experimental queue access is
separate from general backend readiness. HAG never silently selects CPU or
another GPU backend after a refusal.
| Cargo feature | API |
|---|---|
| Default: none | Shared memory budgets and implementation status |
linux-drm |
Linux AMDGPU discovery, queries, budgeted GEM allocation and checked host access |
native-probe |
Explicit fixed-shader submission/completion proof; includes linux-drm |
native-compute |
Trusted-program library and reusable serial queue; includes native-probe |
capi |
C ABI over the experimental queue; includes native-compute |
The queue owns three guarded data slots, immutable shader storage and a reusable command buffer. Its admission limits are 32 programs, 32 KiB of shader storage and 4 GiB minus 4 KiB per logical data slot. These are checked API bounds, not guarantees of memory availability or hardware qualification at every size.
Use Rust 1.85 or newer. From a sibling application, a local dependency can be declared as:
[dependencies]
exec-hag = { path = "../exec-hag" }Portable accounting requires no GPU:
use exec_hag::budget::MemoryBudget;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let budget = MemoryBudget::new(1024);
let reservation = budget.reserve(256)?;
assert_eq!(budget.current_bytes(), 256);
drop(reservation);
assert_eq!(budget.current_bytes(), 0);
Ok(())
}A reservation accounts for bytes; it does not allocate physical memory.
MemoryBudget::new(0) has zero capacity. Use MemoryBudget::unlimited() only
when unlimited accounting is intended. Enable linux-drm for Linux device APIs;
AmdGpuDevice::discover_report() reports discovery and rejection diagnostics
without allocating GPU buffers. See development setup
and the compute contract before enabling execution.
On Linux, build the shared and static libraries with:
cargo build --locked --release --features capiInclude include/exec_hag.h and link libexec_hag.so or
libexec_hag.a from Cargo's release output. The API exposes an opaque queue,
checked byte copies, synchronous dispatch and explicit close. The caller must
supply audited native shader code and serialize access to each handle. C
budget_bytes = 0 means unlimited, unlike Rust's MemoryBudget::new(0).
The C ownership and error contract applies
in addition to the trusted shader requirements.
Ordinary tests are hardware-free and model-free:
cargo test --locked --all-featuresRead development setup for the full check matrix and native probe instructions for separately supervised hardware work. GPU execution is never part of ordinary tests or discovery.
Allocations reserve their page-rounded charge before kernel allocation. Handles and mappings remain owned; host accesses are bounds checked. An uncertain submission or cleanup retains ownership and budget charges rather than allowing unsafe reuse. A timeout or process exit does not guarantee cancellation of GPU work. Experimental shader APIs accept trusted, audited code only.
The backend roadmap describes remaining qualification
gates. Exact inference defines the downstream numerical
and measurement contract. The archived C implementation in legacy/ is retained
for reference and is not built by Cargo.
See CONTRIBUTING.md, CONTRIBUTORS.md and
SECURITY.md. Cargo's 0.1.0 tracks API compatibility; VERSION
tracks the repository's rolling revision independently.
Use the publication checklist before sharing a source snapshot, research evidence, or binary package.
HAG is licensed under MIT. Third-party notices and exceptions are documented in thirdparty.md.
HAG is built by Execute Software and its community. See CONTRIBUTORS.md for the core team and contributor credits.
Contributions, reproducible bug reports, and documentation improvements are welcome. To support development financially, visit Ko-fi.
For enterprise licensing and support, contact admin@executesoftware.com.