88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
# 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
|
||
```bash
|
||
cargo build --release
|
||
sudo ./target/release/xps-thermal-bench
|
||
```
|
||
|
||
## SEE ALSO
|
||
**i8kmon(1)**, **throttled(8)**, **stress-ng(1)**
|