87 lines
3.8 KiB
Markdown
87 lines
3.8 KiB
Markdown
# 🔥 ember-tune
|
|
```text
|
|
__________ ____ ______ ____ ______ __ __ _ __ ______
|
|
/ ____/ |/ // __ )/ ____// __ \ /_ __/ / / / // | / // ____/
|
|
/ __/ / /|_/ // __ / __/ / /_/ / / / / / / // |/ // __/
|
|
/ /___ / / / // /_/ / /___ / _, _/ / / / /_/ // /| // /___
|
|
/_____//_/ /_//_____/_____//_/ |_| /_/ \____//_/ |_//_____/
|
|
|
|
>>> Physically-grounded thermal & power optimization for Linux <<<
|
|
```
|
|
|
|
> ### **Find your hardware's "Physical Sweet Spot" through automated trial-by-fire.**
|
|
|
|
`ember-tune` is a scientifically-driven hardware optimizer that replaces guesswork and manual tuning with a rigorous, automated engineering workflow. It determines the unique thermal properties of your specific laptop—including its Thermal Resistance (Rθ) and "Silicon Knee"—to generate optimal configurations for common Linux tuning daemons.
|
|
|
|
## ✨ Features
|
|
|
|
- **Automated Physical Benchmarking:** Measures real-world thermal performance under load to find the true "sweet spot" where performance-per-watt is maximized before thermal saturation causes diminishing returns.
|
|
- **Heuristic Hardware Discovery:** Utilizes a data-driven Hardware Abstraction Layer (SAL) that probes your system and automatically adapts to its unique quirks, drivers, and sensor paths.
|
|
- **Non-Destructive Configuration:** Safely merges new, optimized power limits into your existing `throttled.conf`, preserving manual undervolt settings and comments.
|
|
- **Universal Safeguard Architecture (USA):** Includes a high-frequency concurrent watchdog and RAII state restoration to guarantee your system is never left in a dangerous state.
|
|
- **Real-time TUI Dashboard:** A `ratatui`-based terminal interface provides high-resolution telemetry throughout the benchmark.
|
|
|
|
## 🔬 How it Works: The Architecture
|
|
|
|
`ember-tune` is built on a decoupled, multi-threaded architecture to ensure the UI is always responsive and that hardware state is managed safely.
|
|
|
|
1. **The Heuristic Engine:** On startup, the engine probes your system's DMI, `sysfs`, and active services. It compares these "facts" against the `hardware_db.toml` to select the correct System Abstraction Layer (SAL).
|
|
2. **The Orchestrator (Backend Thread):** This is the state machine that executes the benchmark. It communicates with hardware *only* through the SAL traits.
|
|
3. **The TUI (Main Thread):** The `ratatui` dashboard renders `TelemetryState` snapshots received from the orchestrator via an MPSC channel.
|
|
4. **The Watchdog (Safety Thread):** A high-priority thread that polls safety sensors every 100ms to trigger an atomic `EmergencyAbort` if failure conditions are met.
|
|
|
|
## ⚙️ Development Setup
|
|
|
|
`ember-tune` is a standard Cargo project.
|
|
|
|
**Prerequisites:**
|
|
- `rustup`
|
|
- `build-essential`
|
|
- `libudev-dev`
|
|
- `stress-ng` (Required for benchmarking)
|
|
|
|
```bash
|
|
# 1. Clone and Build
|
|
git clone https://gitea.com/narl/ember-tune.git
|
|
cd ember-tune
|
|
cargo build --release
|
|
|
|
# 2. Run the safe test suite
|
|
cargo test
|
|
```
|
|
|
|
**Running:**
|
|
```bash
|
|
# Run a full benchmark
|
|
sudo ./target/release/ember-tune
|
|
|
|
# Run a mock benchmark for UI testing
|
|
sudo ./target/release/ember-tune --mock
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing Quirk Data (`hardware_db.toml`)
|
|
|
|
**This is the most impactful way to contribute.** If your hardware isn't working perfectly, add a new entry to `assets/hardware_db.toml`.
|
|
|
|
### Example: Adding a Service Conflict
|
|
```toml
|
|
[[conflicts]]
|
|
id = "laptop_mode_conflict"
|
|
services = ["laptop-mode.service"]
|
|
contention = "Multiple - I/O schedulers, Power limits"
|
|
severity = "Medium"
|
|
fix_action = "SuspendService"
|
|
help_text = "laptop-mode-tools can override power-related sysfs settings."
|
|
```
|
|
|
|
### Example: Defining a Model-Specific Quirk
|
|
```toml
|
|
[[quirks]]
|
|
model_regex = "HP Envy 15-ep.*"
|
|
id = "hp_fan_stuck_sensor"
|
|
issue = "Fan sensor reports 0 RPM when active."
|
|
action = "UseThermalVelocityFallback"
|
|
```
|