Superfreq

Modern, transparent and intelligent utility for CPU management on Linux.

Synopsis
Features | Usage
Contributing

What is Superfreq

Superfreq 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

# Show current system information
superfreq info

# Run as a daemon in the background
sudo superfreq daemon

# Run with verbose logging
sudo superfreq daemon --verbose

# Display comprehensive debug information
superfreq debug

CPU Governor Control

# Set CPU governor for all cores
sudo superfreq set-governor performance

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

# Force a specific governor mode persistently
sudo superfreq force-governor performance

Turbo Boost Management

# Always enable turbo boost
sudo superfreq set-turbo always

# Disable turbo boost
sudo superfreq set-turbo never

# Let Superfreq manage turbo boost based on conditions
sudo superfreq set-turbo auto

Power and Performance Settings

# Set Energy Performance Preference (EPP)
sudo superfreq set-epp performance

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

# Set ACPI platform profile
sudo superfreq set-platform-profile balanced

Frequency Control

# Set minimum CPU frequency (in MHz)
sudo superfreq set-min-freq 800

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

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

Battery Management

# Set battery charging thresholds to extend battery lifespan
sudo superfreq 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 Superfreq 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

Superfreq uses TOML configuration files. Default locations:

• /etc/xdg/superfreq/config.toml
• /etc/superfreq.toml

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

Sample Configuration

# 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/superfreq-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 Superfreq 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, Superfreq 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 Turbo is always active regardless of CPU load or temperature	Always enabled Turbo is always active regardless of CPU load or temperature
turbo = "never"	Always disabled Turbo is always disabled regardless of CPU load or temperature	Always disabled Turbo is always disabled regardless of CPU load or temperature
turbo = "auto"	Dynamically managed Superfreq enables/disables turbo based on CPU load and temperature thresholds	System default 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, Superfreq ensures that any previous turbo state restrictions are removed, allowing the hardware/kernel to manage turbo behavior according to its default algorithms.

Adaptive Polling

Superfreq 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 Superfreq 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 superfreq debug.

Contributing

Contributions to Superfreq 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

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

Superfreq is available under Mozilla Public License v2.0 for your convenience, and at our expense. Please see the license file for more details.