update docs + agents
This commit is contained in:
82
README.md
82
README.md
@@ -1,33 +1,61 @@
|
||||
# 🔥 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. You will need a recent Rust toolchain and common build utilities.
|
||||
`ember-tune` is a standard Cargo project.
|
||||
|
||||
**Prerequisites:**
|
||||
- `rustup`
|
||||
- `build-essential` (or equivalent for your distribution)
|
||||
- `build-essential`
|
||||
- `libudev-dev`
|
||||
- `stress-ng` (Required for benchmarking)
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
# 1. Clone and Build
|
||||
git clone https://gitea.com/narl/ember-tune.git
|
||||
cd ember-tune
|
||||
|
||||
# 2. Build the release binary
|
||||
cargo build --release
|
||||
|
||||
# 3. Run the test suite (safe, uses a virtual environment)
|
||||
# This requires no special permissions and does not touch your hardware.
|
||||
# 2. Run the safe test suite
|
||||
cargo test
|
||||
```
|
||||
|
||||
**Running:**
|
||||
Due to its direct hardware access, `ember-tune` requires root privileges.
|
||||
|
||||
```bash
|
||||
# Run a full benchmark and generate optimized configs
|
||||
# Run a full benchmark
|
||||
sudo ./target/release/ember-tune
|
||||
|
||||
# Run a mock benchmark for UI/logic testing
|
||||
# Run a mock benchmark for UI testing
|
||||
sudo ./target/release/ember-tune --mock
|
||||
```
|
||||
|
||||
@@ -35,48 +63,24 @@ sudo ./target/release/ember-tune --mock
|
||||
|
||||
## 🤝 Contributing Quirk Data (`hardware_db.toml`)
|
||||
|
||||
**This is the most impactful way to contribute.** `ember-tune`'s strength comes from its `assets/hardware_db.toml`, which encodes community knowledge about how to manage specific laptops. If your hardware isn't working perfectly, you can likely fix it by adding a new entry here.
|
||||
**This is the most impactful way to contribute.** If your hardware isn't working perfectly, add a new entry to `assets/hardware_db.toml`.
|
||||
|
||||
The database is composed of four key sections: `conflicts`, `ecosystems`, `quirks`, and `discovery`.
|
||||
|
||||
### A. Reporting a Service Conflict
|
||||
If a background service on your system interferes with `ember-tune`, add it to `[[conflicts]]`.
|
||||
|
||||
**Example:** Adding `laptop-mode-tools`.
|
||||
### 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" # Orchestrator will stop/start this service
|
||||
fix_action = "SuspendService"
|
||||
help_text = "laptop-mode-tools can override power-related sysfs settings."
|
||||
```
|
||||
|
||||
### B. Adding a New Hardware Ecosystem
|
||||
If your laptop manufacturer (e.g., Razer) has a unique fan control tool or ACPI platform profile path, define it in `[ecosystems]`.
|
||||
|
||||
**Example:** A hypothetical "Razer" ecosystem.
|
||||
```toml
|
||||
[ecosystems.razer]
|
||||
vendor_regex = "Razer"
|
||||
# Path to the sysfs node that controls performance profiles
|
||||
profiles_path = "/sys/bus/platform/drivers/razer_acpi/power_mode"
|
||||
# Map human-readable names to the values the driver expects
|
||||
policy_map = { Balanced = 0, Boost = 1, Silent = 2 }
|
||||
```
|
||||
|
||||
### C. Defining a Model-Specific Quirk
|
||||
If a specific laptop model has a bug (like a stuck sensor or incorrect fan reporting), define a `[[quirks]]` entry.
|
||||
|
||||
**Example:** A laptop whose fans report 0 RPM even when spinning.
|
||||
### 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."
|
||||
# The 'action' tells the SAL to use a different method for fan detection.
|
||||
action = "UseThermalVelocityFallback"
|
||||
```
|
||||
|
||||
After adding your changes, run the test suite and then submit a Pull Request!
|
||||
|
||||
Reference in New Issue
Block a user