xps-thermal-bench(8)

NAME

xps-thermal-bench - Scientific, power-aware thermal optimizer for Dell XPS laptops

SYNOPSIS

xps-thermal-bench [OPTIONS]

DESCRIPTION

xps-thermal-bench is a professional diagnostic utility that automates the generation and deployment of optimized i8kmon(1) and throttled configurations. It uses scientific thermal resistance modeling and real-world throughput benchmarks to find the perfect balance between performance and acoustics for your specific hardware unit.

Key Scientific Features:

• Environmental Calibration: Samples your natural ambient idle temperature at startup to anchor fan curves correctly for your specific session (TTY vs. Desktop).
• Thermal Resistance (R_{\theta}) Modeling: Calculates the exact cooling efficiency (C/W) of your heatsink to determine sustainable power limits.
• Thermal Inertia Tracking: Measures how fast your laptop sheds heat to dynamically tune fan hysteresis, preventing the high-pitched "RPM hunting" common in thin-and-light chassis.
• Silicon Knee Detection: Identifies your CPU's unique throttling point by monitoring frequency stability jitter during load.
• Interactive Deployment: One-key installation of generated profiles directly to the system with automatic service restarts.

WORKFLOW

1. System Audit: The tool validates your kernel modules (dell_smm), power state (AC is required for accuracy), and interfering services.
2. Calibration: Captures your current environmental thermal floor.
3. Benchmarking: Runs a matrix of loads (25%–100%) against every fan tier.
4. Optimization: Calculates Quiet, Balanced, and Performance profiles using the gathered telemetry.
5. Installation: Press 'i' in the TUI to deploy your favorite profile and restart services immediately.

OPTIONS

-b, --baseline-temp CELSIUS Target temperature for the cooling phase between tests. Default: 50.

-c, --critical-temp CELSIUS Safety ceiling at which a test is aborted. Default: 95.

-C, --i8kmon-conf PATH Override the path to the i8kmon configuration. (Default: Auto-discovered via systemd).

-T, --throttled-conf PATH Override the path to the throttled configuration. (Default: Auto-discovered via systemd).

-e, --export-dir DIR Directory to write generated configurations and backups.

-f, --history-file PATH Path to the JSON telemetry database. Default: thermal_history.json.

-q, --quick Fast-track mode (skips intermediate 50% and 75% load tiers).

-s, --stressor STRESSOR stress-ng workload type (e.g., matrixprod, avx, cpu, fft). Default: matrixprod.

--no-tui Disables the interactive terminal UI for a structured stdout log.

--skip-checks Bypasses the system audit. Use only if you know your hardware is compatible.

--reprocess [HISTORY_JSON] Generates new profiles and power limits from existing data without hardware tests.

KEYBINDS (TUI Mode)

TAB Cycle between Quiet, Balanced, and Performance profile previews. i Install the currently selected profile to the system and restart services. q Quit and restore original system state (governors, frequencies, services).

SAFETY & CLEANUP

The tool is designed to be "interruption-safe." Even if the program panics or is killed via Ctrl+C, it utilizes the Rust Drop trait to ensure:

• Original CPU scaling governors are restored.
• CPU frequency limits are unlocked.
• Background power management services (like auto-cpufreq or tlp) are restarted.

SETUP

Prerequisites

• Kernel: dell_smm_hwmon must be loaded.
• Power: AC adapter must be connected.
• Dependencies: stress-ng, i8kmon, and throttled.

Installation

cargo build --release
sudo ./target/release/xps-thermal-bench

SEE ALSO

i8kmon(1), throttled(8), stress-ng(1)