Summary
Create a ublk-based daemon that replaces Linux kernel ZRAM with trueno-zram compression, enabling AVX-512 SIMD and CUDA GPU acceleration at the kernel block device level.
Feature Parity Checklist (vs kernel zram)
CLI Parity (zramctl)
| zramctl |
trueno-ublk |
Status |
-s, --size <size> |
create -s <size> |
✅ Implemented |
-a, --algorithm |
create -a <algo> |
✅ Implemented |
-t, --streams |
create -t <num> |
✅ Implemented |
-f, --find |
find |
✅ Implemented |
-r, --reset |
reset <dev> |
✅ Implemented |
-b, --bytes |
list --bytes |
✅ Implemented |
-n, --noheadings |
list --no-headers |
✅ Implemented |
-o, --output |
list --output |
✅ Implemented |
--output-all |
list --output-all |
✅ Implemented |
--raw |
list --raw |
✅ Implemented |
Output Columns Parity
| zramctl Column |
trueno-ublk |
Status |
| NAME |
NAME |
✅ Implemented |
| DISKSIZE |
DISKSIZE |
✅ Implemented |
| DATA |
DATA |
✅ Implemented |
| COMPR |
COMPR |
✅ Implemented |
| ALGORITHM |
ALGORITHM |
✅ Implemented |
| STREAMS |
STREAMS |
✅ Implemented |
| ZERO-PAGES |
ZERO-PAGES |
✅ Implemented |
| TOTAL |
TOTAL |
✅ Implemented |
| MEM-LIMIT |
MEM-LIMIT |
✅ Implemented |
| MEM-USED |
MEM-USED |
✅ Implemented |
| MIGRATED |
MIGRATED |
✅ Implemented |
| MOUNTPOINT |
MOUNTPOINT |
✅ Implemented |
| — |
GPU |
✅ Implemented (new) |
| — |
THROUGHPUT |
✅ Implemented (new) |
| — |
BACKEND |
✅ Implemented (new) |
| — |
ENTROPY |
✅ Implemented (new) |
Sysfs Parity (/sys/block/zramN/ → /run/trueno-ublk/ublkbN/)
| zram sysfs |
trueno-ublk |
Status |
disksize |
disksize |
✅ |
comp_algorithm |
comp_algorithm |
✅ |
max_comp_streams |
max_comp_streams |
✅ |
mm_stat |
mm_stat |
✅ Implemented |
io_stat |
io_stat |
✅ Implemented |
bd_stat |
bd_stat |
✅ Implemented |
debug_stat |
debug_stat |
✅ Implemented |
compact |
compact |
✅ Implemented |
idle |
idle |
✅ Implemented |
reset |
reset |
✅ Implemented |
mem_limit |
mem_limit |
✅ Implemented |
mem_used_max |
mem_used_max |
✅ Implemented |
backing_dev |
backing_dev |
✅ Implemented |
writeback |
writeback |
✅ Implemented |
writeback_limit |
writeback_limit |
✅ Implemented |
writeback_limit_enable |
writeback_limit_enable |
✅ Implemented |
| — |
gpu_enabled |
✅ Implemented (new) |
| — |
throughput |
✅ Implemented (new) |
| — |
entropy_stats |
✅ Implemented (new) |
| — |
batch_stats |
✅ Implemented (new) |
Audio/Video Workflow Support
Compression Reality for Media Files
| Format |
Type |
ZRAM Ratio |
Notes |
| H.264/H.265 |
Lossy video |
❌ ~1.0x |
Already entropy coded |
| AAC/MP3/Opus |
Lossy audio |
❌ ~1.0x |
Already compressed |
| VP9/AV1 |
Lossy video |
❌ ~1.0x |
Already compressed |
| PNG/FLAC |
Lossless |
❌ ~1.0x |
Already compressed |
| ProRes/DNxHR |
Production |
✅ 1.5-2x |
Light compression |
| Raw PCM |
Uncompressed |
✅ 2-4x |
24-bit audio |
| BMP/TIFF |
Uncompressed |
✅ 3-5x |
Raw pixels |
| Raw video |
Camera raw |
✅ 1.5-2x |
Bayer/sensor data |
| Decode buffers |
Intermediate |
✅ 2-3x |
Frame buffers |
Video Editing Pipeline
┌─────────────────────────────────────────────────────────────────┐
│ Video Editing Pipeline │
├─────────────────────────────────────────────────────────────────┤
│ │
│ H.264 file ──► Decode ──► RAW frames ──► Process ──► Encode │
│ ❌ │ ✅ ✅ ❌ │
│ (1.0x) │ (2-3x) (2-3x) (1.0x) │
│ ▼ │
│ [ZRAM benefits HERE] │
│ - Decoded frame buffers │
│ - Render intermediates │
│ - Timeline cache │
│ - Undo history │
│ │
└─────────────────────────────────────────────────────────────────┘
Live Streaming Pipeline
┌─────────────────────────────────────────────────────┐
│ Live Streaming Pipeline │
├─────────────────────────────────────────────────────┤
│ │
│ Camera ──► Raw frames ──► Encoder ──► Network │
│ ✅ │ ❌ │
│ (GPU batch) │ (already H.264) │
│ ▼ │
│ [ZRAM buffer pool] │
│ - 4K: 33MB/frame │
│ - 60fps = 2GB/sec raw │
│ - With ZRAM: ~800MB/sec │
│ │
└─────────────────────────────────────────────────────┘
Entropy-Aware Advantage
Incoming page ──► Entropy check ──┬──► High entropy (>7 bits)
│ Store uncompressed
│ (skip wasted CPU cycles)
│
└──► Low entropy (<6 bits)
Compress with LZ4
(3-4x ratio)
Kernel ZRAM: Wastes CPU cycles compressing incompressible H.264 data
trueno-ublk: Detects entropy, skips compression, saves CPU
Media Workflow Commands
# Check entropy of media files
trueno-ublk entropy ~/Videos/
# Example output:
# raw_footage.mov ProRes 4.2 bits/byte ✅ compressible
# final_export.mp4 H.264 7.9 bits/byte ❌ skip
# audio_master.wav PCM 24 3.1 bits/byte ✅ compressible
# podcast.mp3 MP3 7.8 bits/byte ❌ skip
# project_cache/ Mixed 5.2 bits/byte ✅ compressible
# Create ZRAM optimized for media workflows
trueno-ublk create -s 256G -a lz4 --gpu \
--entropy-skip 7.5 \ # Skip high-entropy data
--gpu-batch 1000 # Batch raw frames for GPU
# Mount for editing cache
sudo mount /dev/ublkb0 /mnt/edit-cache
# Point video editors here
export RESOLVE_CACHE_DIR=/mnt/edit-cache
export PREMIERE_CACHE=/mnt/edit-cache
export FFMPEG_TEMP=/mnt/edit-cache
Media Workload Summary
| Workload |
Benefit |
Why |
| Storing H.264/AAC files |
❌ None |
Already compressed |
| Decode frame buffers |
✅ 2-3x |
Raw pixel data |
| Edit timeline cache |
✅ 2-3x |
Intermediate frames |
| Render scratch space |
✅ 2-4x |
Uncompressed output |
| ProRes/DNxHR editing |
✅ 1.5-2x |
Light compression |
| FFmpeg build artifacts |
✅ 3-4x |
Object files, libs |
| ML model inference |
✅ 3-4x |
Weight buffers |
TUI Dashboard (trueno-ublk top)
Interactive real-time monitoring dashboard, similar to htop for ZRAM.
Usage
# Launch TUI dashboard
trueno-ublk top
# Monitor specific device
trueno-ublk top /dev/ublkb0
# Demo mode (simulated data)
trueno-ublk top --demo
Layout
┌─────────────────────────────────────────┬──────────────┐
│ Pipeline Flow Diagram │ Sparklines │
│ (Scalar / SIMD / GPU routing) │ Ratio/Thru │
├─────────────────────────────────────────┴──────────────┤
│ Trace Waterfall (DMA/Kernel spans) │
│ Batch #98 [==DMA==][====Kernel====][=DMA=] │
└────────────────────────────────────────────────────────┘
Pipeline Flow Panel
[ Incoming Pages ] (125,432 total)
║
┌─────────▼─────────┐
│ Adaptive Selector │ (Entropy: 5.2 bits)
└─────────┬─────────┘
║
╔═════════╬══════════╗
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌───────────┐
│ Scalar │ │ AVX-512│ │ GPU Batch │
│ 12.3% │ │ 45.2% │ │ 42.5% │
└────┬───┘ └────┬───┘ └─────┬─────┘
╚═════════╬══════════╝
▼
[ Compressed RAM ]
Ratio: 3.7x | 4.2 GB/s
Color coding:
- 🔴 Red: Scalar path active (high entropy, incompressible)
- 🟢 Green/Cyan: SIMD path active (normal data)
- 🟣 Magenta/Blue: GPU batch path active (large batches)
Trace Waterfall Panel
Shows DMA/Kernel overlap for GPU batches (Gantt chart style):
┌─ Trace Waterfall (renacer spans) ─────────────────────────┐
│ Time 0ms 10ms 20ms 30ms 40ms 50ms │
│ ├──────┼───────┼───────┼───────┼───────┼───────┤ │
│ │
│ Batch #98 [▓▓DMA▓▓][▓▓▓▓▓Kernel▓▓▓▓▓][▓DMA▓] │
│ Batch #99 [▓▓DMA▓▓][▓▓▓▓▓Kernel▓▓▓▓▓][▓DMA▓] │
│ Batch #100 [▓▓DMA▓▓][▓▓▓▓▓Kernel▓▓▓▓▓][▓DMA▓] │
│ │
│ Legend: [DMA H→D] [Kernel] [DMA D→H] │
└────────────────────────────────────────────────────────────┘
Keybindings
| Key |
Action |
q |
Quit |
p |
Pause/resume updates |
r |
Reset statistics |
c |
Trigger compaction |
w |
Trigger writeback |
g |
Toggle GPU panel |
e |
Show entropy histogram |
? |
Show help |
Architecture
┌─────────────────────────────────────────────────────────┐
│ Application │
│ write("/mnt/zram/...") │
└───────────────────────┬─────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ Linux Kernel │
│ /dev/ublkb0 (block device) │
└───────────────────────┬─────────────────────────────────┘
▼ io_uring (low overhead)
┌─────────────────────────────────────────────────────────┐
│ trueno-ublk daemon (Rust) │
│ ┌─────────────┐ ┌───────────┐ ┌───────────────────┐ │
│ │ AVX-512 LZ4 │ │ Entropy │ │ GPU Batch (CUDA) │ │
│ │ 4-6 GB/s │ │ Routing │ │ 50+ GB/s │ │
│ └─────────────┘ └───────────┘ └───────────────────┘ │
└───────────────────────┬─────────────────────────────────┘
▼
Compressed RAM (heap)
CLI Reference
Create Device
# Basic (like zramctl -f -s 1T -a lz4)
trueno-ublk create -s 1T -a lz4
# With GPU acceleration
trueno-ublk create -s 1T -a lz4 --gpu
# With streams (like zramctl -t)
trueno-ublk create -s 1T -a lz4 -t 48
# With memory limit
trueno-ublk create -s 1T -a lz4 --mem-limit 64G
# With backing device for writeback
trueno-ublk create -s 1T -a lz4 --backing-dev /dev/nvme0n1p4
# Media workflow optimized
trueno-ublk create -s 256G -a lz4 --gpu \
--entropy-skip 7.5 \
--gpu-batch 1000
# Full options
trueno-ublk create \
--size 1T \
--algorithm lz4 \
--streams 48 \
--gpu \
--mem-limit 64G \
--backing-dev /dev/nvme0n1p4 \
--writeback-limit 100G \
--entropy-skip 7.5
List Devices
# Basic (like zramctl)
trueno-ublk list
# With specific columns (like zramctl -o)
trueno-ublk list -o NAME,DISKSIZE,DATA,COMPR,RATIO
# All columns
trueno-ublk list --output-all
# Machine-readable
trueno-ublk list --raw --bytes --no-headers
# JSON output (extension)
trueno-ublk list --json
Device Stats
# Summary (like zramctl <device>)
trueno-ublk stat /dev/ublkb0
# mm_stat format (zram compatible)
trueno-ublk stat /dev/ublkb0 --mm-stat
# io_stat format
trueno-ublk stat /dev/ublkb0 --io-stat
# bd_stat format (backing device)
trueno-ublk stat /dev/ublkb0 --bd-stat
# All stats as JSON
trueno-ublk stat /dev/ublkb0 --json
# Entropy histogram
trueno-ublk stat /dev/ublkb0 --entropy
Entropy Analysis
# Analyze files/directories
trueno-ublk entropy ~/Videos/
trueno-ublk entropy ~/project/target/
# Output format
trueno-ublk entropy --json ~/Videos/
TUI Dashboard
# Interactive dashboard (like htop for zram)
trueno-ublk top
# Monitor specific device
trueno-ublk top /dev/ublkb0
# Demo mode with simulated data
trueno-ublk top --demo
# Report mode (non-interactive, single snapshot)
trueno-ublk top --report
Device Management
# Reset/remove (like zramctl -r)
trueno-ublk reset /dev/ublkb0
trueno-ublk reset --all
# Find free device (like zramctl -f)
trueno-ublk find
# Compact (trigger compaction)
trueno-ublk compact /dev/ublkb0
# Mark pages idle (for writeback)
trueno-ublk idle /dev/ublkb0
# Trigger writeback
trueno-ublk writeback /dev/ublkb0
trueno-ublk writeback /dev/ublkb0 --idle
trueno-ublk writeback /dev/ublkb0 --huge
Live Reconfiguration
# Change memory limit
trueno-ublk set /dev/ublkb0 --mem-limit 128G
# Enable/disable GPU
trueno-ublk set /dev/ublkb0 --gpu on
trueno-ublk set /dev/ublkb0 --gpu off
# Change entropy skip threshold
trueno-ublk set /dev/ublkb0 --entropy-skip 7.0
# Change writeback limit
trueno-ublk set /dev/ublkb0 --writeback-limit 200G
Expected Performance
| Metric |
Kernel ZRAM |
trueno-ublk (SIMD) |
trueno-ublk (GPU) |
| Throughput |
~2 GB/s |
4-6 GB/s |
50+ GB/s |
| Latency |
Low |
Low + syscall |
Low + syscall + batch |
| Ratio |
3:1 (zstd) |
3.7:1 (LZ4) |
3.7:1 (LZ4) |
| Incompressible |
Wastes CPU |
Skipped |
Skipped |
Implementation Plan
Phase 1: Core + CLI Parity ✅ COMPLETE
Phase 2: Full Feature Parity ✅ COMPLETE
Phase 3: TUI Dashboard ✅ COMPLETE
Phase 4: Entropy & Media Support ✅ COMPLETE
Phase 5: GPU Acceleration 🔄 IN PROGRESS
Phase 6: Production ⏳ PENDING
Files Implemented
bins/trueno-ublk/
├── Cargo.toml ✅ Dependencies configured
├── src/
│ ├── main.rs ✅ Entry point with command dispatch
│ ├── cli/
│ │ ├── mod.rs ✅ Full CLI definitions (clap)
│ │ ├── create.rs ✅ Create device command
│ │ ├── list.rs ✅ List with columns, JSON
│ │ ├── stat.rs ✅ Stats with mm/io/bd formats
│ │ ├── reset.rs ✅ Remove devices
│ │ ├── find.rs ✅ Find free slot
│ │ ├── compact.rs ✅ Trigger compaction
│ │ ├── idle.rs ✅ Mark pages idle
│ │ ├── writeback.rs ✅ Trigger writeback
│ │ ├── set.rs ✅ Live reconfiguration
│ │ ├── top.rs ✅ TUI launcher
│ │ └── entropy.rs ✅ File entropy analysis
│ ├── tui/
│ │ ├── mod.rs ✅ Full TUI with ratatui
│ │ └── widgets.rs ✅ Custom widgets
│ ├── daemon.rs ✅ Page store with compression
│ ├── device.rs ✅ UblkDevice abstraction
│ └── stats.rs ✅ Throughput/ratio/entropy tracking
Tests
18 unit tests passing:
cli::tests::* - Size parsing, format_size, columns
daemon::tests::* - Zero page detection, entropy calculation
device::tests::* - Device ID parsing, SIMD detection
stats::tests::* - Throughput, ratio, entropy trackers
tui::widgets::tests::* - Custom widget tests
Success Criteria
- ✅
trueno-ublk list output matches zramctl format
- ✅ mm_stat, io_stat, bd_stat compatible with kernel format
- ✅ All zramctl CLI options have equivalents
- ⏳ /run/trueno-ublk/ provides sysfs-like interface (pending)
- ✅
trueno-ublk top shows real-time pipeline/entropy stats
- ✅
trueno-ublk entropy analyzes media files
- ✅ Entropy-based skip saves CPU on compressed media
- ⏳ Throughput >= 4 GB/s with AVX-512 (pending ublk integration)
- ⏳ GPU batching for large sequential writes (pending)
- ⏳ No data corruption under stress (pending stress tests)
References
Summary
Create a ublk-based daemon that replaces Linux kernel ZRAM with trueno-zram compression, enabling AVX-512 SIMD and CUDA GPU acceleration at the kernel block device level.
Feature Parity Checklist (vs kernel zram)
CLI Parity (zramctl)
-s, --size <size>create -s <size>-a, --algorithmcreate -a <algo>-t, --streamscreate -t <num>-f, --findfind-r, --resetreset <dev>-b, --byteslist --bytes-n, --noheadingslist --no-headers-o, --outputlist --output--output-alllist --output-all--rawlist --rawOutput Columns Parity
Sysfs Parity (/sys/block/zramN/ → /run/trueno-ublk/ublkbN/)
disksizedisksizecomp_algorithmcomp_algorithmmax_comp_streamsmax_comp_streamsmm_statmm_statio_statio_statbd_statbd_statdebug_statdebug_statcompactcompactidleidleresetresetmem_limitmem_limitmem_used_maxmem_used_maxbacking_devbacking_devwritebackwritebackwriteback_limitwriteback_limitwriteback_limit_enablewriteback_limit_enablegpu_enabledthroughputentropy_statsbatch_statsAudio/Video Workflow Support
Compression Reality for Media Files
Video Editing Pipeline
Live Streaming Pipeline
Entropy-Aware Advantage
Kernel ZRAM: Wastes CPU cycles compressing incompressible H.264 data
trueno-ublk: Detects entropy, skips compression, saves CPU
Media Workflow Commands
Media Workload Summary
TUI Dashboard (trueno-ublk top)
Interactive real-time monitoring dashboard, similar to
htopfor ZRAM.Usage
Layout
Pipeline Flow Panel
Color coding:
Trace Waterfall Panel
Shows DMA/Kernel overlap for GPU batches (Gantt chart style):
Keybindings
qprcwge?Architecture
CLI Reference
Create Device
List Devices
Device Stats
Entropy Analysis
TUI Dashboard
Device Management
Live Reconfiguration
Expected Performance
Implementation Plan
Phase 1: Core + CLI Parity ✅ COMPLETE
bins/trueno-ublk/directorycreate,list,reset,findstatwith mm_stat/io_stat/bd_stat formatsPhase 2: Full Feature Parity ✅ COMPLETE
compact,idle,writeback,setPhase 3: TUI Dashboard ✅ COMPLETE
topcommand with ratatuiPhase 4: Entropy & Media Support ✅ COMPLETE
entropycommand for file analysisPhase 5: GPU Acceleration 🔄 IN PROGRESS
Phase 6: Production ⏳ PENDING
Files Implemented
Tests
18 unit tests passing:
cli::tests::*- Size parsing, format_size, columnsdaemon::tests::*- Zero page detection, entropy calculationdevice::tests::*- Device ID parsing, SIMD detectionstats::tests::*- Throughput, ratio, entropy trackerstui::widgets::tests::*- Custom widget testsSuccess Criteria
trueno-ublk listoutput matcheszramctlformattrueno-ublk topshows real-time pipeline/entropy statstrueno-ublk entropyanalyzes media filesReferences