Build with Maven

August 27, 2026 · View on GitHub

Title

JDK 25 LTS Ubuntu 26.04 License: MIT Arch: ARM64 Arch: ARM32 Arch: X86_64 API: FFM/Panama Interface: Linux CDEV

Java UIO 2 is the next-generation evolution of the Java UIO project, rebuilt from the ground up to leverage the Foreign Function & Memory API (FFM). By moving beyond traditional JNI, Java UIO 2 achieves unprecedented performance and hardware-level accuracy for Linux Userspace IO. Engineered for JDK 25, it provides a cutting-edge cross-platform solution for modern embedded systems.

🚀 The New Standard

This project adheres to rigorous development standards to ensure production-grade reliability and performance:

  • Modern Java: Full utilization of modern Java and the latest FFM features.
  • Zero Allocation: Frame-based operations (like color display rendering via abstract device abstractions) use pre-allocated buffers to eliminate GC pressure during high-speed I/O.
  • Clean Architecture: No native loaders in device classes. Native loading is handled exclusively at the application (demo) level, keeping core logic decoupled and lean, with strict adherence to javadoc, var, and final standards.
  • Complete Documentation: 100% Javadoc coverage for all public APIs.

🏗️ Architectural Contrast: Why Java UIO 2?

FeaturePi4J (v4.0+)diozero (v1.4+)Java UIO 2
ModelProvider-Centric. Relies on a plugin architecture to map hardware.Device-Centric. Uses a "Factory" abstraction to wrap pins in objects.Kernel-Direct. Treats the Linux Kernel ABI as the only provider.
FFM IntegrationPlugin Level. FFM is an optional provider module.JNI Core. Primarily utilizes JNI/JNA for native access.Native FFM. Built specifically for Project Panama as the core engine.
32-Bit / Legacy ARMDropped. No longer supports arm32 (Pi4J v3+ targets 64-bit architectures).Stagnant / Legacy. Works on older 32-bit targets, but library development has slowed significantly.Universal 32/64-bit. Runs natively across modern 64-bit and legacy 32-bit Linux kernels without distinction.
Board SupportBoard-specific definitions/configs often required.Broad, but requires factory logic or native maps for each SoC.Universal. If it runs a standard Linux kernel, it works instantly.
GraphicsCommunity-ported Java drivers.High-level/basic shape support.Abstracted Color Displays for flexible hardware output. Full C-performance for color displays.
PortabilityHeavyweight (Core + Provider + Config).Lightweight core, but SoC-specific factories.Ultra-Lightweight. Zero-dependency bridge to Linux interfaces.

1. Universal Kernel-Standardized I/O

Most libraries require a "Provider" or specific plugin for every new board. Java UIO 2 bypasses this middleman. By targeting the Standard Linux Kernel ABI (Character Devices and UIO), any board running a modern kernel is supported immediately. The Kernel is the only "Provider" you need.

2. Deep Graphics with Abstract Color Displays

While other libraries stop at "Blinky," Java UIO 2 provides a professional-grade graphics stack. By abstracting display hardware and utilizing high-performance memory segments via FFM, you gain access to optimized drawing routines at near-native speeds.

3. Hardware-Accurate Native Sizing

A major weakness in traditional libraries is their reliance on manual JNI headers. Java UIO 2 uses a Native Sizer during the build process (via QEMU emulation). This guarantees that MemoryLayout offsets are byte-perfect for the target CPU architecture (ARM64, ARM32, or x86_64), preventing alignment traps and crashes.

🛠️ Performance Benchmark (Pine64 ARM64)

In raw performance testing on the Pine A64 (Cortex-A53), the FFM implementation demonstrated a massive leap over established JNI methods:

OperationHawtJNI (Legacy)Java UIO 2 (FFM)Improvement
GPIO Writes~292k ops/sec~561k ops/sec+91.5%
GPIO Reads~400k ops/sec~582k ops/sec+45.5%

Note: Benchmarks were performed on single-core execution. With FFM, the Java-to-Native bridge is no longer the bottleneck; the performance limit is now defined by the Linux Kernel's ioctl latency.

🌍 Architecture Support Matrix (JDK 25)

ArchitectureJNI (Java UIO)FFM (Java UIO 2)
ARM32 (v7)✅ Supported✅ Recommended
ARM64 (v8)✅ Supported✅ Recommended
X86_64✅ Supported✅ Recommended

📦 Project Depth

This repository contains more than just a library; it includes exhaustive demos demonstrating real-world complexity:

  • Color Displays: Full-color graphics, custom fonts, and buffer rotations using abstract display classes.
  • Game Logic: Arcade-style scrollers showcasing memory-efficient movement controllers and zero-allocation rendering loops.
  • Native Demos: Direct ports of JNI demos to the modern FFM era.

ARM32 Support & Modern FFM (Back to the Future)

While modern JDK releases on ARM32 face architectural performance constraints (such as restricted register counts and limited 64-bit JIT optimizations), this project bridges the gap by bringing Project Panama's Foreign Function & Memory (FFM) API to 32-bit ARM hardware. By leveraging FFM bindings over legacy JNI, developers can efficiently interface with native libraries like c-periphery on older hardware, keeping legacy platforms viable and performant.

🏗️ Building Custom ARM32 JDK 25 with FFM

For target ARM32 boards (such as NanoPi or Raspberry Pi running 32-bit environments), Java 25 requires a custom JDK build with Foreign Function & Memory (FFM) API support and proper layout handling.

  1. Run the custom JDK build script located in ~/javauio2/scripts/jdk25-arm32.sh before executing install-java.sh.
  2. Ensure the resulting openjdk-25-jdk_arm32-server-release-neon.tar.gz archive is present in your home directory (~/) prior to running the installer.

Download and Build

# Download project
sudo apt install git
cd ~/
git clone --depth 1 https://github.com/sgjava/javauio2.git

# Setup and Install
cd ~/javauio2/scripts
./jdk25-arm32.sh # ARM32 only (ensure tar.gz is in ~)
./install-java.sh
./setup-permissions.sh # ARM only
sudo reboot

# Build with Maven
cd ~/javauio2
mvn clean install # X86_64 default
# Use -P arm64 (aarch64) or -P arm32 (armhf) for profiles