superfreq/README.md

<h1 id="header" align="center">
  Watt
</h1>

<div align="center">
  Modern, transparent and intelligent utility for CPU management on Linux.
</div>

<div align="center">
  <br/>
  <a href="#what-is-watt">Synopsis</a><br/>
  <a href="#features">Features</a> | <a href="#usage">Usage</a><br/>
  <a href="#contributing">Contributing</a>
  <br/>
</div>

## What is Watt

Watt is a modern CPU frequency and power management utility for Linux systems.
It provides intelligent control of CPU governors, frequencies, and power-saving
features, helping optimize both performance and battery life.

It is greatly inspired by auto-cpufreq, but rewritten from ground up to provide
a smoother experience with a more efficient and more correct codebase. Some
features are omitted, and it is _not_ a drop-in replacement for auto-cpufreq,
but most common usecases are already implemented.

## Features

- **Real-time CPU Management**: Monitor and control CPU governors, frequencies,
  and turbo boost
- **Intelligent Power Management**: Different profiles for AC and battery
  operation
- **Dynamic Turbo Boost Control**: Automatically enables/disables turbo based on
  CPU load and temperature
- **Fine-tuned Controls**: Adjust energy performance preferences, biases, and
  frequency limits
- **Per-core Control**: Apply settings globally or to specific CPU cores
- **Battery Management**: Monitor battery status and power consumption
- **System Load Tracking**: Track system load and make intelligent decisions
- **Daemon Mode**: Run in background with adaptive polling to minimize overhead
- **Conflict Detection**: Identifies and warns about conflicts with other power
  management tools

## Usage

### Basic Commands

```bash
# Show current system information
watt info

# Run as a daemon in the background
sudo watt daemon

# Run with verbose logging
sudo watt daemon --verbose

# Display comprehensive debug information
watt debug
```

### CPU Governor Control

```bash
# Set CPU governor for all cores
sudo watt set-governor performance

# Set CPU governor for a specific core
sudo watt set-governor powersave --core-id 0

# Force a specific governor mode persistently
sudo watt force-governor performance
```

### Turbo Boost Management

```bash
# Always enable turbo boost
sudo watt set-turbo always

# Disable turbo boost
sudo watt set-turbo never

# Let Watt manage turbo boost based on conditions
sudo watt set-turbo auto
```

### Power and Performance Settings

```bash
# Set Energy Performance Preference (EPP)
sudo watt set-epp performance

# Set Energy Performance Bias (EPB)
sudo watt set-epb 4

# Set ACPI platform profile
sudo watt set-platform-profile balanced
```

### Frequency Control

```bash
# Set minimum CPU frequency (in MHz)
sudo watt set-min-freq 800

# Set maximum CPU frequency (in MHz)
sudo watt set-max-freq 3000

# Set per-core frequency limits
sudo watt set-min-freq 1200 --core-id 0
sudo watt set-max-freq 2800 --core-id 1
```

### Battery Management

```bash
# Set battery charging thresholds to extend battery lifespan
sudo watt set-battery-thresholds 40 80  # Start charging at 40%, stop at 80%
```

Battery charging thresholds help extend battery longevity by preventing constant
charging to 100%. Different laptop vendors implement this feature differently,
but Watt attempts to support multiple vendor implementations including:

- Lenovo ThinkPad/IdeaPad (Standard implementation)
- ASUS laptops
- Huawei laptops
- Other devices using the standard Linux power_supply API

Note that battery management is sensitive, and that your mileage may vary.
Please open an issue if your vendor is not supported, but patches would help
more than issue reports, as supporting hardware _needs_ hardware.

## Configuration

Watt uses TOML configuration files. Default locations:

- `/etc/xdg/watt/config.toml`
- `/etc/watt.toml`

You can also specify a custom path by setting the `WATT_CONFIG` environment
variable.

### Sample Configuration

```toml
# Settings for when connected to a power source
[charger]
# CPU governor to use
governor = "performance"
# Turbo boost setting: "always", "auto", or "never"
turbo = "auto"
# Enable or disable automatic turbo management (when turbo = "auto")
enable_auto_turbo = true
# Custom thresholds for auto turbo management
turbo_auto_settings = {
    load_threshold_high = 70.0,
    load_threshold_low = 30.0,
    temp_threshold_high = 75.0,
    initial_turbo_state = false,  # whether turbo should be initially enabled (false = disabled)
}
# Energy Performance Preference
epp = "performance"
# Energy Performance Bias (0-15 scale or named value)
epb = "balance_performance"
# Platform profile (if supported)
platform_profile = "performance"
# Min/max frequency in MHz (optional)
min_freq_mhz = 800
max_freq_mhz = 3500
# Optional: Profile-specific battery charge thresholds (overrides global setting)
# battery_charge_thresholds = [40, 80]  # Start at 40%, stop at 80%

# Settings for when on battery power
[battery]
governor = "powersave"
turbo = "auto"
# More conservative auto turbo settings on battery
enable_auto_turbo = true
turbo_auto_settings = {
    load_threshold_high = 80.0,
    load_threshold_low = 40.0,
    temp_threshold_high = 70.0,
    initial_turbo_state = false,  # start with turbo disabled on battery for power savings
}
epp = "power"
epb = "balance_power"
platform_profile = "low-power"
min_freq_mhz = 800
max_freq_mhz = 2500
# Optional: Profile-specific battery charge thresholds (overrides global setting)
# battery_charge_thresholds = [60, 80]  # Start at 60%, stop at 80% (more conservative)

# Global battery charging thresholds (applied to both profiles unless overridden)
# Start charging at 40%, stop at 80% - extends battery lifespan
# NOTE: Profile-specific thresholds (in [charger] or [battery] sections)
# take precedence over this global setting
battery_charge_thresholds = [40, 80]

# Daemon configuration
[daemon]
# Base polling interval in seconds
poll_interval_sec = 5
# Enable adaptive polling that changes with system state
adaptive_interval = true
# Minimum polling interval for adaptive polling (seconds)
min_poll_interval_sec = 1
# Maximum polling interval for adaptive polling (seconds)
max_poll_interval_sec = 30
# Double the polling interval when on battery to save power
throttle_on_battery = true
# Logging level: Error, Warning, Info, Debug
log_level = "Info"
# Optional stats file path
stats_file_path = "/var/run/watt-stats"

# Optional: List of power supplies to ignore
[power_supply_ignore_list]
mouse_battery = "hid-12:34:56:78:90:ab-battery"
# Add other devices to ignore here
```

## Advanced Features

Those are the more advanced features of Watt that some users might be more
inclined to use than others. If you have a use-case that is not covered, please
create an issue.

### Dynamic Turbo Boost Management

When using `turbo = "auto"` with `enable_auto_turbo = true`, Watt dynamically
controls CPU turbo boost based on:

- **CPU Load Thresholds**: Enables turbo when load exceeds `load_threshold_high`
  (default 70%), disables when below `load_threshold_low` (default 30%)
- **Temperature Protection**: Automatically disables turbo when CPU temperature
  exceeds `temp_threshold_high` (default 75°C)
- **Hysteresis Control**: Prevents rapid toggling by maintaining previous state
  when load is between thresholds
- **Configurable Initial State**: Sets the initial turbo state via
  `initial_turbo_state` (default: disabled) before system load data is available
- **Profile-Specific Settings**: Configure different thresholds for battery vs.
  AC power

This feature optimizes performance and power consumption by providing maximum
performance for demanding tasks while conserving energy during light workloads.

> [!TIP]
> You can disable this logic with `enable_auto_turbo = false` to let the system
> handle turbo boost natively when `turbo = "auto"`.

#### Turbo Boost Behavior Table

The table below explains how different combinations of `turbo` and
`enable_auto_turbo` settings affect CPU turbo behavior:

| Setting            | `enable_auto_turbo = true`                                                                          | `enable_auto_turbo = false`                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `turbo = "always"` | **Always enabled**<br>Turbo is always active regardless of CPU load or temperature                  | **Always enabled**<br>Turbo is always active regardless of CPU load or temperature                           |
| `turbo = "never"`  | **Always disabled**<br>Turbo is always disabled regardless of CPU load or temperature               | **Always disabled**<br>Turbo is always disabled regardless of CPU load or temperature                        |
| `turbo = "auto"`   | **Dynamically managed**<br>Watt enables/disables turbo based on CPU load and temperature thresholds | **System default**<br>Turbo is reset to system's default enabled state and is managed by the hardware/kernel |

> [!NOTE]
> When `turbo = "auto"` and `enable_auto_turbo = false`, Watt ensures that any
> previous turbo state restrictions are removed, allowing the hardware/kernel to
> manage turbo behavior according to its default algorithms.

### Adaptive Polling

Watt includes a "sophisticated" (euphemism for complicated) adaptive polling
system to try and maximize power efficiency

- **Battery Discharge Analysis** - Automatically adjusts polling frequency based
  on the battery discharge rate, reducing system activity when battery is
  draining quickly
- **System Activity Pattern Recognition** - Monitors CPU usage and temperature
  patterns to identify system stability
- **Dynamic Interval Calculation** - Uses multiple factors to determine optimal
  polling intervals - up to 3x longer on battery with minimal user impact
- **Idle Detection** - Significantly reduces polling frequency during extended
  idle periods to minimize power consumption
- **Gradual Transition** - Smooth transitions between polling rates to avoid
  performance spikes
- **Progressive Back-off** - Implements logarithmic back-off during idle periods
  (1min -> 1.5x, 2min -> 2x, 4min -> 3x, 8min -> 4x, 16min -> 5x)
- **Battery Discharge Protection** - Includes safeguards against measurement
  noise to prevent erratic polling behavior

When enabled, this intelligent polling system provides substantial power savings
over conventional fixed-interval approaches, especially during low-activity or
idle periods, while maintaining responsiveness when needed.

### Power Supply Filtering

Configure Watt to ignore certain power supplies (like peripheral batteries) that
might interfere with power state detection.

## Troubleshooting

### Permission Issues

Most CPU management commands require root privileges. If you see permission
errors, try running with `sudo`.

### Feature Compatibility

Not all features are available on all hardware:

- Turbo boost control requires CPU support for Intel/AMD boost features
- EPP/EPB settings require CPU driver support
- Platform profiles require ACPI platform profile support in your hardware

### Common Problems

1. **Settings not applying**: Check for conflicts with other power management
   tools
2. **CPU frequencies fluctuating**: May be due to thermal throttling
3. **Missing CPU information**: Verify kernel module support for your CPU

While reporting issues, please attach the results from `watt debug`.

## Contributing

Contributions to Watt are always welcome! Whether it's bug reports, feature
requests, or code contributions, please feel free to contribute.

> [!NOTE]
> If you are looking to reimplement features from auto-cpufreq, please consider
> opening an issue first and let us know what you have in mind. Certain features
> (such as the system tray) are deliberately ignored, and might not be desired
> in the codebase as they stand. Please discuss those features with us first :)

### Setup

You will need Cargo and Rust installed on your system. Rust 1.85 or later is
required.

A `.envrc` is provided, and it's usage is encouraged for Nix users.
Alternatively, you may use Nix for a reproducible developer environment

```bash
nix develop
```

Non-Nix users may get the appropriate Cargo and Rust versions from their package
manager, or using something like Rustup.

### Formatting & Lints

Please make sure to run _at least_ `cargo fmt` inside the repository to make
sure all of your code is properly formatted. For Nix code, please use Alejandra.

Clippy lints are not _required_ as of now, but a good rule of thumb to run them
before committing to catch possible code smell early.

## License

Watt is available under [Mozilla Public License v2.0](LICENSE) for your
convenience, and at our expense. Please see the license file for more details.