edgefirst-hal

EdgeFirst Hardware Abstraction Layer — a unified Rust library for edge AI inference pipelines.

This is the umbrella crate that re-exports the core EdgeFirst HAL components:

edgefirst-tensor — Zero-copy tensor memory management (DMA, SHM, PBO, system memory)
edgefirst-image — Hardware-accelerated image processing and format conversion
edgefirst-decoder — ML model output decoding (YOLOv5/v8/v11/v26, ModelPack)
edgefirst-tracker — Multi-object tracking (ByteTrack)

Features

Zero-copy memory management with DMA-BUF, POSIX shared memory, and PBO support
Hardware-accelerated image processing via OpenGL, G2D (NXP i.MX), and optimized CPU
Efficient ML post-processing for object detection and segmentation models
Int8 GPU shaders for direct signed int8 output without CPU post-processing
Cross-platform — Linux (with hardware acceleration), macOS, and other Unix systems

Quick Start

use edgefirst_image::{load_image, ImageProcessor, ImageProcessorTrait, Rotation, Flip, Crop};
use edgefirst_tensor::{PixelFormat, DType};

// Load a source image
let bytes = std::fs::read("image.jpg")?;
let input = load_image(&bytes, Some(PixelFormat::Rgb), None)?;

// Create an image processor (auto-selects best backend)
let mut processor = ImageProcessor::new()?;

// Allocate a GPU-optimal output buffer — always use create_image() for
// destinations passed to convert(). This selects the best memory type
// (DMA-buf, PBO, or system memory) for zero-copy GPU paths.
let mut output = processor.create_image(640, 640, PixelFormat::Rgb, DType::U8, None)?;

// Convert with letterbox resize
processor.convert(&input, &mut output, Rotation::None, Flip::None, Crop::default())?;

Why create_image()? Creating tensors directly with Tensor::new() or TensorDyn::image() bypasses GPU memory negotiation. The processor cannot allocate PBO-backed buffers without knowing the GL context. Use create_image() for any tensor that will be passed to convert().

Platform Support

Platform	Memory Types	Image Acceleration
Linux (NXP i.MX8/i.MX95)	DMA, SHM, PBO, Mem	OpenGL, G2D, CPU
Linux (other)	SHM, PBO, Mem	OpenGL, CPU
macOS	Mem	CPU
Other Unix	SHM, Mem	CPU

Python Bindings

This library is also available as a Python package:

pip install edgefirst-hal

See edgefirst-hal on PyPI for Python-specific documentation.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.