xps 13 3980

README.md

@@ -0,0 +1,87 @@
+# 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)**