# rktop - Rockchip System Monitor
A high-performance system monitoring tool specifically designed for Rockchip SoC devices (RK3588, RK3399, etc.), written in Rust using the Ratatui TUI framework.
## Features
### Hardware Monitoring
- **CPU**: Per-core usage, frequencies, time breakdown (user/system/iowait/idle)
- **GPU (Mali)**: Utilization percentage and frequency
- **NPU**: Per-core load and frequency
- **RGA**: Graphics accelerator scheduler load (shows all RGA cores)
- **Memory**: RAM, Swap, and ZRAM usage with detailed statistics
- **Temperatures**: All thermal sensors (CPU, GPU, NPU, etc.)
- **Network & Disk I/O**: Real-time transfer rates per adapter
### Process Information
- **Interactive Sorting**: Sort by CPU, Memory, PID, or Name (ascending/descending)
- **Detailed Metrics**: PID, User, Nice level, CPU core affinity, Runtime, CPU%, Memory%
- **Dynamic Display**: Shows as many processes as fit in the terminal
### System Statistics
- System uptime and load average
- CPU governor and frequency ranges (per cluster)
- Running and blocked process counts
- Context switches, interrupts, and softirqs per second
- External TCP connection count
### Driver & Runtime Versions
- NPU kernel driver version
- RGA kernel driver version
- RKNN Runtime library version
- RKLLM Runtime library version
## Performance
Optimized for minimal CPU overhead:
- **<1% CPU usage** during normal operation
- Cached static information (versions, hardware availability)
- UID-to-username caching (eliminates process spawns)
- Throttled refresh rates (1s/2s/3s/5s for different data types)
- Efficient hardware detection (checks availability once at startup)
## Installation
### Prerequisites
- Rockchip SoC-based device (RK3588, RK3399, etc.)
- Linux with sysfs and debugfs mounted
- Rust toolchain (for installing from crates.io or building from source)
### Install from crates.io
The easiest way to install rktop is via cargo:
```bash
cargo install rktop
```
This will download, compile, and install the latest version from [crates.io](https://crates.io/crates/rktop).
### Building from Source
```bash
# Clone the repository
git clone https://github.com/ajokela/rktop.git
cd rktop
# Build release binary
cargo build --release
# Binary will be at target/release/rktop
```
### Installing System-Wide
```bash
# If installed via cargo
# Binary is already in ~/.cargo/bin/ (ensure it's in your PATH)
# If built from source, copy to system path
sudo cp target/release/rktop /usr/local/bin/
sudo chmod +x /usr/local/bin/rktop
```
## Usage
### Basic Usage
```bash
# Run with root privileges (required for debugfs access)
sudo rktop
```
### Keyboard Controls
| `q`, `Q`, `Esc` | Quit |
| `c` | Toggle CPU sort (ascending/descending) |
| `m` | Toggle Memory sort (ascending/descending) |
| `p` | Toggle PID sort (ascending/descending) |
| `n` | Toggle Name sort (ascending/descending) |
### Running Without Root (Optional)
You can grant specific capabilities to avoid requiring root:
```bash
# Grant file read and process trace capabilities
sudo setcap cap_dac_read_search,cap_sys_ptrace=eip /usr/local/bin/rktop
# Now you can run without sudo
rktop
```
**Note**: Capabilities are removed if the binary is modified. Re-run `setcap` after updates.
## Display Panels
### CPU Panel
- Per-core usage bars with frequency
- CPU time breakdown (User, System, IOWait, Idle percentages)
- Frequency ranges for each CPU cluster (big.LITTLE)
- Running and blocked process counts
- Context switches, interrupts, and softirqs per second
### Memory Panel
- RAM usage (used + cached / total)
- Swap usage
- ZRAM usage with compression ratio
- Detailed breakdown (Total, Free, Used, Cache, Shared)
### GPU Panel (if available)
- Mali GPU utilization percentage
- Current GPU frequency
### NPU Panel (if available)
- Per-core NPU load (0-2 cores typical)
- NPU frequency
### RGA Panel (if available)
- Per-scheduler load for all RGA cores
- RK3588 example: rga3_0, rga3_1, rga2_2
### System Info Panel
- Board name and SoC model
- NPU driver version
- RGA driver version
- RKNN Runtime version
- RKLLM Runtime version
### Stats Panel
- System uptime
- Load average (1/5/15 min)
- CPU governor
- Total process count
- External TCP connections
### I/O Panel
- Disk read/write rates
- Network RX/TX rates (total)
- Per-adapter network rates
### Temperature Panel
- All thermal sensors
- Real-time temperature readings
### Process Panel
- **PID** - Process ID
- **User** - Username
- **NI** - Nice level (priority)
- **C** - Current CPU core (0-7)
- **Time** - Process runtime (MM:SS or HH:MM:SS)
- **Name** - Process name
- **CPU%** - CPU usage
- **Mem%** - Memory usage
## Architecture
### Multi-Module Design
- **src/main.rs** - Main application, TUI rendering, event loop, state management
- **src/hardware.rs** - Rockchip-specific hardware detection and monitoring
- **src/sysinfo_ext.rs** - Extended system information (processes, ZRAM, TCP stats)
### Key Design Patterns
**Caching for Performance**
- Static information cached at startup (board name, versions, hardware availability)
- Hardware availability checks prevent unnecessary sysfs reads every frame
- UID-to-username mapping cached to eliminate process spawns
**Throttled Refresh Intervals**
- CPU/Memory: 1 second
- Network/Disk I/O: 2 seconds
- Processes: 3 seconds
- Stats (uptime, load, governor, TCP): 5 seconds
**Graceful Hardware Detection**
- Functions return `Option<T>` or empty values when hardware unavailable
- UI panels conditionally render based on cached availability checks
- Works on non-Rockchip systems (shows basic CPU/memory/process info)
## Rockchip-Specific Features
### Supported SoCs
- RK3588 (tested on Orange Pi 5 Max)
- RK3399
- Other Rockchip SoCs with Mali GPU, NPU, and/or RGA
### Hardware Interfaces
The tool reads from Rockchip-specific kernel interfaces:
**Debugfs** (requires root or capabilities):
- `/sys/kernel/debug/mali0/` - GPU utilization
- `/sys/kernel/debug/rknpu/` - NPU load and version
- `/sys/kernel/debug/rkrga/` - RGA load and version
**Sysfs** (standard access):
- `/sys/devices/platform/fb000000.gpu-panthor/devfreq/` - GPU frequency
- `/sys/class/devfreq/fdab0000.npu/` - NPU frequency
- `/sys/devices/system/cpu/cpu*/cpufreq/` - CPU frequencies
**Device Tree**:
- `/proc/device-tree/model` - Board name and SoC detection
### RK3588 Specifics
**CPU Clusters**:
- CPU 0-3: Big cores (typically 1800-2400 MHz)
- CPU 4-7: LITTLE cores (408-2256 MHz)
**RGA Cores**:
- 3 schedulers total: 2× RGA3 + 1× RGA2
- Displayed as: rga3_0, rga3_1, rga2_2
**NPU Cores**:
- 3 cores (Core 0, Core 1, Core 2)
- Each with independent load monitoring
## Troubleshooting
### "Root permissions required" error
The tool needs access to debugfs. Either:
1. Run with `sudo rktop`
2. Grant capabilities: `sudo setcap cap_dac_read_search,cap_sys_ptrace=eip /usr/local/bin/rktop`
### GPU/NPU/RGA shows "not available"
- Ensure debugfs is mounted: `mount | grep debugfs`
- Check kernel drivers are loaded: `lsmod | grep -E "mali|npu|rga"`
- Some boards may not have all accelerators
### Version detection fails
- Ensure runtime libraries are installed in `/usr/lib/`
- Library paths may vary by distribution
- Parses binary ELF files directly to extract versions
### High CPU usage
- Normal usage should be <1% CPU
- If higher, check `strace` output: `sudo strace -c -p $(pgrep rktop)`
- Verify caching is working (no excessive file opens)
## Dependencies
**Rust Crates**:
- `ratatui` (0.28) - Terminal UI framework
- `crossterm` (0.28) - Terminal manipulation and event handling
- `sysinfo` (0.32) - System and process information
- `regex` (1.11) - Regular expression parsing for hardware data
- `anyhow` (1.0) - Error handling
- `nix` (0.29) - Unix system calls (for root check)
**System Requirements**:
- Linux kernel with sysfs and debugfs support
- For full features: Mali GPU, NPU, and RGA drivers loaded
## Performance Notes
From profiling with `strace -c`:
- Zero subprocess spawns during normal operation (after startup)
- Minimal file I/O through aggressive caching
- <1% CPU usage on RK3588 (Orange Pi 5 Max)
## Technical Details
### Process Monitoring
- Reads `/proc/[pid]/stat` for nice level and CPU core affinity
- Uses sysinfo crate for CPU/memory usage
- Implements global UID-to-username cache (Mutex-wrapped HashMap)
- Reduces process spawns from 260+/sec to 0-2/sec
### CPU Statistics
- Parses `/proc/stat` for context switches, interrupts, softirqs
- Calculates per-second rates from deltas
- Computes CPU time percentages (user/system/iowait/idle)
### Network Monitoring
- Per-adapter RX/TX rate calculation
- Refreshed every 2 seconds to reduce file I/O
- Shows both aggregate and per-adapter statistics
### Temperature Sensors
- Reads from `/sys/class/thermal/thermal_zone*/`
- Also checks `/sys/class/hwmon/` for additional sensors
- Filters out duplicate thermal zones
## Known Limitations
- **Rockchip-specific**: Some features only work on Rockchip SoCs
- **Debugfs access**: Requires root or capabilities for full functionality
- **Library versions**: Library paths may vary by distribution
- **No NPU process mapping**: Cannot show which process uses which NPU core (kernel limitation)
## Related Projects
- **[yarktop](https://github.com/emapco/yarktop)** - Python-based predecessor
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Credits
Developed for Rockchip SBC enthusiasts who want detailed hardware monitoring with minimal overhead.