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 modern Java and the latest FFM features.
• Zero Allocation: Frame-based operations (like SSD1331 rendering) 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 at the application level, keeping core logic decoupled and lean.
• Complete Documentation: 100% Javadoc coverage for all public APIs.

---

🏗️ Architectural Contrast: Why Java UIO 2?

Feature	Pi4J (v4.0+)	diozero (v1.4+)	Java UIO 2
Model	Provider-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 Integration	Plugin 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 ARM	Dropped. 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 Support	Board-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.
Graphics	Community-ported Java drivers.	High-level/basic shape support.	Deep u8g2 Binding for nearly 200 displays. Full C-performance for SSD1331 OLEDs.
Portability	Heavyweight (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 u8g2 & SSD1331

While other libraries stop at "Blinky," Java UIO 2 provides a professional-grade graphics stack. By binding the industry-standard u8g2 library via FFM, you gain access to hundreds of fonts and 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:

Operation	HawtJNI (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)

Architecture	JNI (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:

• SSD1331 OLED: Full-color graphics, custom fonts, and buffer rotations.
• Game Logic: Atari-style Centipede clones showcasing memory-efficient movement controllers.
• 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.shbefore 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/sgoldsmith/javauio2.git](https://github.com/sgoldsmith/javauio2.git)
# Setup and Installcd~/javauio2/scripts
./jdk25-arm32.sh # ARM32 only (ensure tar.gz is in ~)
./install-java.sh
./setup-permissions.sh # ARM only
sudo reboot
# Build with Mavencd~/javauio2
mvn clean install # X86_64 default# Use -P arm64 (aarch64) or -P arm32 (armhf) for profiles