Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Resources for developing and deploying AI models on BrainChip Akida neuromorphic
| Goal | Where to go |
| --- | --- |
| Train, convert, and evaluate a model | [Akida 1](akida1) · [Akida 2](akida2) · Akida Pico (**COMING SOON**) |
| Deploy to hardware and benchmark | Deployment (**COMING SOON**) |
| Deploy to hardware and benchmark | [Rust (no Python, no kernel module)](deployment/rust) · Python (**COMING SOON**) |
| Understand how Akida works | Concepts (**COMING SOON**) |
| New to Akida — not sure where to start | [Getting Started](#getting-started) |

Expand Down Expand Up @@ -233,6 +233,7 @@ brainchip_devhub/
│ ├── model_zoo/
│ └── notebooks/
├── deployment/ # Hardware deployment and benchmarking
│ ├── rust/ # Pure Rust deployment — no Python, no kernel module
│ ├── akida1/
│ ├── akida2/
│ └── akida_pico/
Expand Down
22 changes: 22 additions & 0 deletions deployment/rust/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
[package]
name = "akida-rust-quickstart"
version = "0.1.0"
edition = "2024"
description = "Quick-start example: deploy Akida models with pure Rust"
license = "Apache-2.0"

[dependencies]
akida-driver = { git = "https://github.com/syntheticChemistry/rustChip.git" }
akida-models = { git = "https://github.com/syntheticChemistry/rustChip.git" }

[[example]]
name = "enumerate"
path = "examples/enumerate.rs"

[[example]]
name = "parse_model"
path = "examples/parse_model.rs"

[[example]]
name = "capabilities"
path = "examples/capabilities.rs"
159 changes: 159 additions & 0 deletions deployment/rust/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
# Rust Deployment — Pure Rust Akida Driver

**No Python. No C++ SDK. No MetaTF. No kernel module required.**

Deploy trained Akida models to hardware using a pure Rust stack. Works on
any Linux kernel (5.15+). VFIO primary backend — no kernel module in the data path.

| | Python SDK | C++ Package | **Rust (this)** |
|---|---|---|---|
| Runtime deps | Python 3.10+ | libakida.so | **None** |
| Kernel module | akida_pcie.ko | akida_pcie.ko | **None (VFIO)** |
| Linux > 6.9 | ⚠️ driver rebuild | ⚠️ driver rebuild | **✅ works** |
| Binary size | ~200 MB env | ~50 MB | **~4 MB** |
| Inference latency | SDK overhead | SDK overhead | **54 µs direct** |

## Quick Start

```bash
# 1. Clone rustChip (the Rust driver)
git clone https://github.com/syntheticChemistry/rustChip.git
cd rustChip

# 2. Verify — 376 tests, ~2 seconds, no hardware required
cargo test --workspace

# 3. Build
cargo build --release

# 4. One-time VFIO setup (no root needed after this)
sudo ./scripts/bind-akida-vfio.sh

# 5. Enumerate devices
cargo run --release --bin akida -- enumerate
```

## Load and Run a Model

```rust
use akida_driver::{DeviceManager, InferenceExecutor, InferenceConfig};

fn main() -> Result<(), Box<dyn std::error::Error>> {
// Discover hardware
let mgr = DeviceManager::discover()?;
let caps = mgr.devices()[0].capabilities();
println!("Found: {:?} — {} NPs, {} MB SRAM",
caps.chip_version, caps.npu_count, caps.memory_mb);

// Load model and run inference
let model_bytes = std::fs::read("model.fbz")?;
let mut dev = mgr.open_first()?;
dev.write(&model_bytes)?;

let input = vec![0u8; 224 * 224 * 3]; // your preprocessed image
let mut output = vec![0u8; 1024];
dev.read(&mut output)?;

println!("Output: {:?}", &output[..10]);
Ok(())
}
```

## Parse Any .fbz Model

rustChip parses all models from the BrainChip model zoo — v1 and v2:

```rust
use akida_models::Model;

let model = Model::load("plant_village_mobilenetv1_0.5_224_i8_w8_a8.fbz")?;
println!("Layers: {}, Parameters: {}", model.layer_count(), model.param_count());
```

The `.fbz` format is Snappy-compressed FlatBuffers. rustChip handles the
decompression and parsing natively — no Python, no SDK.

## Backends

| Backend | Requirements | Performance | When to use |
|---------|-------------|-------------|-------------|
| **VFIO** (primary) | IOMMU enabled | Full DMA, 37 MB/s | Production (recommended) |
| **Kernel** (fallback) | akida_pcie.ko loaded | /dev/akida* R/W | Legacy systems |
| **Software** (testing) | None | CPU emulation | CI, development |

### VFIO Setup (one-time)

```bash
# Bind Akida device to vfio-pci
sudo ./scripts/bind-akida-vfio.sh

# Install udev rule for user-level access (no sudo at runtime)
sudo cp scripts/99-akida-vfio.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
```

After setup, all operations are userspace — no root required.

## Measured Performance (AKD1000, PCIe x1 Gen2)

| Metric | Value |
|--------|-------|
| Single inference | 54 µs / 18,500 Hz |
| Batch=8 | 390 µs/sample / 20,700 /s |
| DMA throughput | 37 MB/s sustained |
| Energy per inference | 1.4 µJ |
| Weight swap (`set_variable()`) | 86 µs |
| 24-hour production run | 5,978 calls, 0 errors |

## Supported Hardware

| Chip | Status | Notes |
|------|--------|-------|
| AKD1000 | ✅ Full support | PCIe x1 Gen2, validated in production |
| AKD1500 | ✅ Full support | Same Akida 1.0 IP, PCIe x2 Gen2 |
| AKD2500 | 🔲 Placeholder | Akida 2.0, TSMC 12nm, tape-out Dec 2026 |
| Akida Pico | 🔲 Placeholder | µW NPU, AXI/SPI (not PCIe) |

## Advanced: Multi-Tenancy

Run 7 independent models simultaneously on one AKD1000:

```rust
use akida_driver::tenancy::MultiTenantDevice;

let mut mt = MultiTenantDevice::new(device)?;
mt.load_at_offset("classifier.fbz", 0x0000)?; // 179 NPs
mt.load_at_offset("detector.fbz", 0x00B3)?; // 134 NPs
mt.load_at_offset("kws.fbz", 0x0139)?; // 220 NPs
// ... up to 7 programs, 814/1000 NPs used
```

## Advanced: Hybrid ESN (tanh fix)

The AKD1000's bounded ReLU breaks reservoir computing. `HybridEsn` fixes it:

```rust
use akida_driver::HybridEsn;

// Use your existing tanh-trained weights — no retraining needed
let mut esn = HybridEsn::from_weights(&w_in, &w_res, &w_out, 0.3)?;
let prediction = esn.step(&features)?; // 18,500 Hz, 1.4 µJ
```

Hardware does the matrix multiply (int4, 54 µs), host applies tanh (< 1 µs).
Full accuracy at hardware speed. No MetaTF required.

## Links

- **Source**: [syntheticChemistry/rustChip](https://github.com/syntheticChemistry/rustChip)
- **Hardware discoveries**: [BEYOND_SDK.md](https://github.com/syntheticChemistry/rustChip/blob/main/docs/BEYOND_SDK.md)
- **Integration guide**: [INTEGRATION_GUIDE.md](https://github.com/syntheticChemistry/rustChip/blob/main/specs/INTEGRATION_GUIDE.md)
- **PR to BrainChip**: [akida_dw_edma #20](https://github.com/Brainchip-Inc/akida_dw_edma/pull/20)

## License

rustChip is AGPL-3.0-or-later. This deployment guide is CC-BY-SA 4.0.

A permissive license exception is available to BrainChip and any NPU vendor
willing to engage on reciprocal terms. Contact: ecoPrimal@pm.me
(Kevin Mok, ORCID 0009-0004-2141-0321).
39 changes: 39 additions & 0 deletions deployment/rust/examples/capabilities.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
//! Display chip capabilities from the silicon model.
//!
//! No hardware required — reads from the compiled-in chip spec.
//!
//! ```bash
//! cargo run --example capabilities
//! ```

use akida_driver::pcie_ids::{self, ChipVariant};

fn main() {
println!("🧠 Akida Chip Family — Silicon Model\n");

let variants = [
("AKD1000", ChipVariant::Akd1000),
("AKD1500", ChipVariant::Akd1500),
("AKD2500", ChipVariant::Akd2500),
("Pico", ChipVariant::Pico),
];

for (name, variant) in &variants {
println!("{name}:");
println!(" Generation: {:?}", variant.generation());
println!(" NP count: {}", variant.np_count());
println!(" SRAM: {} MB", variant.sram_mb());
println!(" Local RAM: {} KB", variant.local_ram_kb());
println!(" PCIe lanes: {}{}", variant.pcie_lanes(),
if !variant.is_pcie() { " (not PCIe — AXI/SPI)" } else { "" });
println!(" Weight bits: {:?}", variant.weight_bits());
println!(" Max clock: {} MHz", variant.max_clock_mhz());
println!(" Production: {}", if variant.is_production() { "✅" } else { "🔲 pre-silicon" });
println!();
}

println!("Vendor ID: 0x{:04X}", pcie_ids::BRAINCHIP_VENDOR_ID);
println!("lspci: {}", pcie_ids::lspci_filter());
println!("\nAll device IDs: {:?}", pcie_ids::ALL_DEVICE_IDS);
println!("Future IDs: {:?}", pcie_ids::ALL_DEVICE_IDS);
}
53 changes: 53 additions & 0 deletions deployment/rust/examples/enumerate.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
//! Enumerate all Akida devices on the system.
//!
//! No hardware required — this will report "no devices found" gracefully
//! if no AKD1000/AKD1500 is present.
//!
//! ```bash
//! cargo run --example enumerate
//! ```

fn main() {
println!("🧠 Akida Device Enumeration — Pure Rust\n");

#[cfg(target_os = "linux")]
{
match akida_driver::DeviceManager::discover() {
Ok(mgr) => {
let devices = mgr.devices();
if devices.is_empty() {
println!("No Akida devices found.");
println!("\nTo use VFIO backend:");
println!(" 1. Ensure IOMMU is enabled (intel_iommu=on or amd_iommu=on)");
println!(" 2. Run: sudo ./scripts/bind-akida-vfio.sh");
println!("\nTo use kernel backend:");
println!(" 1. Load the module: sudo insmod akida-pcie.ko");
return;
}

println!("Found {} device(s):\n", devices.len());
for (i, dev) in devices.iter().enumerate() {
let caps = dev.capabilities();
println!("Device {i}:");
println!(" Chip: {:?}", caps.chip_version);
println!(" NPs: {}", caps.npu_count);
println!(" SRAM: {} MB", caps.memory_mb);
println!(" PCIe: Gen{} x{}", caps.pcie.generation, caps.pcie.lanes);
println!();
}
}
Err(e) => {
println!("Discovery failed: {e}");
println!("\nThis is expected if no Akida hardware is present.");
println!("The software backend works without hardware — see parse_model example.");
}
}
}

#[cfg(not(target_os = "linux"))]
{
println!("Hardware discovery requires Linux (VFIO/sysfs).");
println!("The software backend and model parser work on any platform.");
println!("\nTry: cargo run --example parse_model -- path/to/model.fbz");
}
}
55 changes: 55 additions & 0 deletions deployment/rust/examples/parse_model.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
//! Parse any .fbz model file from BrainChip's model zoo.
//!
//! Works on any platform — no hardware required.
//!
//! ```bash
//! # Download a model from Brainchip-Inc/models:
//! # git lfs pull --include="vision/classification/mobilenetv1/**/*.fbz"
//!
//! cargo run --example parse_model -- path/to/model.fbz
//! ```

fn main() {
println!("🧠 Akida Model Parser — Pure Rust\n");

let args: Vec<String> = std::env::args().collect();
if args.len() < 2 {
println!("Usage: cargo run --example parse_model -- <path-to-model.fbz>");
println!();
println!("Download models from: https://github.com/Brainchip-Inc/models");
println!(" git clone https://github.com/Brainchip-Inc/models.git");
println!(" cd models && git lfs pull --include=\"*.fbz\"");
return;
}

let path = &args[1];
println!("Loading: {path}\n");

match std::fs::read(path) {
Ok(bytes) => {
println!(" File size: {} bytes ({:.1} KB)", bytes.len(), bytes.len() as f64 / 1024.0);

// Show raw header bytes for format inspection
if bytes.len() >= 4 {
println!(" Header: [{:02x}, {:02x}, {:02x}, {:02x}]",
bytes[0], bytes[1], bytes[2], bytes[3]);
}

// The .fbz format is: [varint: uncompressed_size] [snappy_chunks] [zero_padding]
// The first bytes are a Snappy varint, NOT magic bytes.
println!(" Format: Snappy-compressed FlatBuffer (.fbz)");

// Attempt to find version string
if let Some(pos) = bytes.windows(5).position(|w| w == b"2.19.") {
let end = bytes[pos..].iter().position(|&b| b == 0).unwrap_or(10);
let version = String::from_utf8_lossy(&bytes[pos..pos + end.min(20)]);
println!(" SDK ver: {version} (at offset {pos})");
}

println!("\n✅ File loaded successfully. Use akida_models::Model::load() for full parsing.");
}
Err(e) => {
println!("❌ Failed to read {path}: {e}");
}
}
}