Voice/AI · voice

Portal NPU Runtime — Hexagon DSP FastRPC

Safe Rust wrappers around the Qualcomm Hexagon CDSP FastRPC kernel interface. Provides DMA-BUF allocation and remote DSP invocation for voice, LLM, and other NPU consumers.

portal-npu-runtimev0.2.0voice

1.4K

Lines of Code

Tests

Files

Architecture

Four modules: device (NpuDevice — handle to FastRPC CDSP domain), error (NpuError, NpuResult), fastrpc_ffi (raw kernel FFI bindings — device paths, ioctl constants, domain IDs), shell_verify (verify_shell_binary — validates DSP shell .so before loading). The FastRpcSession type owns two file descriptors (meta_fd, rpc_fd), the domain ID, a shell_loaded flag (mutex), and an ioctl_lock (mutex for serializing kernel calls). The llm submodule (feature-gated) provides LLM-specific DSP operations.

Overview

portal-npu-runtime provides the low-level NPU abstraction layer that all QNN/DSP consumers in Portal build on. It wraps the Qualcomm FastRPC kernel interface (/dev/fastrpc-cdsp-secure) with safe Rust types, handling DMA-BUF memory allocation (page-aligned, max 256MB per allocation), remote DSP domain invocation (CDSP_SECURE_DEVICE = domain 3), and shell binary verification for DSP code loading. The FastRpcSession type manages the kernel session lifecycle with proper ioctl serialization (mutex-guarded to avoid FastRPC race conditions). The crate also includes fastrpc_ffi with raw FFI bindings to the kernel interface constants and structures.

Key Types

FastRpcSessionFastRPC session on Hexagon CDSP — owns meta_fd and rpc_fd, manages DMA-BUF allocation and DSP invocation. Domain 3 = CDSP_SECURE_DEVICE.

NpuDeviceHandle to the NPU device — wraps FastRpcSession for higher-level DMA and invocation operations.

NpuErrorError type — FastRpc kernel errors, DMA allocation failures, shell verification failures, device open errors.

verify_shell_binary()Validates a DSP shell .so binary before loading — checks magic bytes, section headers, entry point.

Modules

device

NpuDevice — higher-level NPU operations wrapping FastRpcSession: DMA allocation, buffer mapping, DSP invocation.

fastrpc_ffi

Raw FFI bindings to FastRPC kernel interface — device paths (/dev/fastrpc-cdsp-secure), ioctl constants, domain IDs (CDSP_SECURE_DEVICE = 3).

shell_verify

Shell binary verification — validates DSP .so files before loading to prevent crashes from malformed code.

llm

LLM-specific DSP operations (feature-gated) — manages the Qwen3 model context on Hexagon.

Data Flow

portal-voiced/portal-llmd → NpuDevice → FastRpcSession → /dev/fastrpc-cdsp-secure → kernel FastRPC → Hexagon CDSP → QNN model execution

Dependencies

External (6)

thiserror workspacetracing workspacelibc 0.2sha2 0.10ed25519-dalek 2hex 0.4

Platform-specific: Qualcomm X Elite only. Depends on libc for fd management. Constants: PAGE_SIZE=4096, MAX_DMA_ALLOC=256MB. Enforces # Safety sections on all pub unsafe fn.