Merge pull request #26 from NotAShelf/auto-turbo

feature: dynamic CPU turbo management

Author: NotAShelf

Cargo.toml

@@ -1,7 +1,10 @@
 [package]
 name = "superfreq"
+description = "Modern CPU frequency and power management utility for Linux"
 version = "0.2.0"
 edition = "2024"
+authors = ["NotAShelf <[email protected]>"]
+rust-version = "1.85"
 
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }

README.md

@@ -20,9 +20,9 @@ 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
+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,
+features are omitted, and it is _not_ a drop-in replacement for auto-cpufreq,
 but most common usecases are already implemented.
 
 ## Features
@@ -31,6 +31,8 @@ but most common usecases are already implemented.
   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
@@ -150,6 +152,15 @@ variable.
 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)
@@ -166,6 +177,14 @@ max_freq_mhz = 3500
 [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"
@@ -209,6 +228,45 @@ 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**<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>Superfreq 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`, 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
@@ -268,14 +326,16 @@ While reporting issues, please attach the results from `superfreq debug`.
 Contributions to Superfreq are always welcome! Whether it's bug reports, feature
 requests, or code contributions, please feel free to contribute.
 
-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.
+> [!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.80 or later is required.
+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
@@ -285,9 +345,9 @@ nix develop
 ```
 
 Non-Nix users may get the appropriate Cargo and Rust versions from their package
-manager.
+manager, or using something like Rustup.
 
-### Formatting
+### 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.

src/config/types.rs

@@ -50,7 +50,10 @@ pub struct ProfileConfig {
     pub min_freq_mhz: Option<u32>,
     pub max_freq_mhz: Option<u32>,
     pub platform_profile: Option<String>,
-    pub turbo_auto_settings: Option<TurboAutoSettings>,
+    #[serde(default)]
+    pub turbo_auto_settings: TurboAutoSettings,
+    #[serde(default)]
+    pub enable_auto_turbo: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub battery_charge_thresholds: Option<BatteryChargeThresholds>,
 }
@@ -65,7 +68,8 @@ impl Default for ProfileConfig {
             min_freq_mhz: None,     // no override
             max_freq_mhz: None,     // no override
             platform_profile: None, // no override
-            turbo_auto_settings: Some(TurboAutoSettings::default()),
+            turbo_auto_settings: TurboAutoSettings::default(),
+            enable_auto_turbo: default_enable_auto_turbo(),
             battery_charge_thresholds: None,
         }
     }
@@ -124,6 +128,9 @@ pub struct ProfileConfigToml {
     pub min_freq_mhz: Option<u32>,
     pub max_freq_mhz: Option<u32>,
     pub platform_profile: Option<String>,
+    pub turbo_auto_settings: Option<TurboAutoSettings>,
+    #[serde(default = "default_enable_auto_turbo")]
+    pub enable_auto_turbo: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub battery_charge_thresholds: Option<BatteryChargeThresholds>,
 }
@@ -151,6 +158,8 @@ impl Default for ProfileConfigToml {
             min_freq_mhz: None,
             max_freq_mhz: None,
             platform_profile: None,
+            turbo_auto_settings: None,
+            enable_auto_turbo: default_enable_auto_turbo(),
             battery_charge_thresholds: None,
         }
     }
@@ -164,12 +173,18 @@ pub struct TurboAutoSettings {
     pub load_threshold_low: f32,
     #[serde(default = "default_temp_threshold_high")]
     pub temp_threshold_high: f32,
+    /// Initial turbo boost state when no previous state exists.
+    /// Set to `true` to start with turbo enabled, `false` to start with turbo disabled.
+    /// This is only used at first launch or after a reset.
+    #[serde(default = "default_initial_turbo_state")]
+    pub initial_turbo_state: bool,
 }
 
 // Default thresholds for Auto turbo mode
 pub const DEFAULT_LOAD_THRESHOLD_HIGH: f32 = 70.0; // enable turbo if load is above this
 pub const DEFAULT_LOAD_THRESHOLD_LOW: f32 = 30.0; // disable turbo if load is below this
 pub const DEFAULT_TEMP_THRESHOLD_HIGH: f32 = 75.0; // disable turbo if temperature is above this
+pub const DEFAULT_INITIAL_TURBO_STATE: bool = false; // by default, start with turbo disabled
 
 const fn default_load_threshold_high() -> f32 {
     DEFAULT_LOAD_THRESHOLD_HIGH
@@ -180,13 +195,17 @@ const fn default_load_threshold_low() -> f32 {
 const fn default_temp_threshold_high() -> f32 {
     DEFAULT_TEMP_THRESHOLD_HIGH
 }
+const fn default_initial_turbo_state() -> bool {
+    DEFAULT_INITIAL_TURBO_STATE
+}
 
 impl Default for TurboAutoSettings {
     fn default() -> Self {
         Self {
             load_threshold_high: DEFAULT_LOAD_THRESHOLD_HIGH,
             load_threshold_low: DEFAULT_LOAD_THRESHOLD_LOW,
             temp_threshold_high: DEFAULT_TEMP_THRESHOLD_HIGH,
+            initial_turbo_state: DEFAULT_INITIAL_TURBO_STATE,
         }
     }
 }
@@ -208,7 +227,8 @@ impl From<ProfileConfigToml> for ProfileConfig {
             min_freq_mhz: toml_config.min_freq_mhz,
             max_freq_mhz: toml_config.max_freq_mhz,
             platform_profile: toml_config.platform_profile,
-            turbo_auto_settings: Some(TurboAutoSettings::default()),
+            turbo_auto_settings: toml_config.turbo_auto_settings.unwrap_or_default(),
+            enable_auto_turbo: toml_config.enable_auto_turbo,
             battery_charge_thresholds: toml_config.battery_charge_thresholds,
         }
     }
@@ -282,6 +302,10 @@ const fn default_stats_file_path() -> Option<String> {
     None
 }
 
+const fn default_enable_auto_turbo() -> bool {
+    true
+}
+
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct DaemonConfigToml {
     #[serde(default = "default_poll_interval_sec")]

src/cpu.rs

@@ -1,6 +1,7 @@
 use crate::core::{GovernorOverrideMode, TurboSetting};
 use crate::util::error::ControlError;
 use core::str;
+use log::debug;
 use std::{fs, io, path::Path, string::ToString};
 
 pub type Result<T, E = ControlError> = std::result::Result<T, E>;
@@ -216,12 +217,19 @@ pub fn set_turbo(setting: TurboSetting) -> Result<()> {
     let value_pstate = match setting {
         TurboSetting::Always => "0", // no_turbo = 0 means turbo is enabled
         TurboSetting::Never => "1",  // no_turbo = 1 means turbo is disabled
-        TurboSetting::Auto => return Err(ControlError::InvalidValueError("Turbo Auto cannot be directly set via intel_pstate/no_turbo or cpufreq/boost. System default.".to_string())),
+        // Auto mode is handled at the engine level, not directly at the sysfs level
+        TurboSetting::Auto => {
+            debug!("Turbo Auto mode is managed by engine logic based on system conditions");
+            return Ok(());
+        }
     };
     let value_boost = match setting {
         TurboSetting::Always => "1", // boost = 1 means turbo is enabled
         TurboSetting::Never => "0",  // boost = 0 means turbo is disabled
-        TurboSetting::Auto => return Err(ControlError::InvalidValueError("Turbo Auto cannot be directly set via intel_pstate/no_turbo or cpufreq/boost. System default.".to_string())),
+        TurboSetting::Auto => {
+            debug!("Turbo Auto mode is managed by engine logic based on system conditions");
+            return Ok(());
+        }
     };
 
     // AMD specific paths