Cyan Skillfish GPU Governor

Adaptive GPU governor for the AMD Cyan Skillfish APU.

It continuously tracks GPU load, maintains a target frequency, and adjusts GPU frequency when the deviation is large enough. It also supports burst behavior for sustained load and optional thermal throttling.

This version can set frequency/voltage using either:

• the SMU API (thanks to bc250collective)
• kernel sysfs controls

What It Does

• Samples GPU load and computes a moving target frequency.
• Applies frequency changes only when meaningful (unless burst mode forces faster response).
• Optionally throttles with temperature limits.
• Optionally exposes a D-Bus interface to toggle a high-performance mode.

Usage

cyan-skillfish-governor-smu [-v|--verbose] [CONFIG]

• CONFIG is an optional TOML path.
• If CONFIG is omitted, internal defaults are used.

Installation

Prebuilt/community packaging references:

• AUR: https://aur.archlinux.org/packages/cyan-skillfish-governor-smu
• COPR (Fedora/Bazzite): https://copr.fedorainfracloud.org/coprs/filippor/bazzite/
• ARCHIVE: https://github.com/filippor/cyan-skillfish-governor/releases

Bazzite

Bazzite can consume the same COPR package source. On mutable setups, use the Fedora steps below.

On rpm-ostree based setups, layer the package and reboot:

sudo rpm-ostree install cyan-skillfish-governor-smu
systemctl reboot

Configuration file location:

/etc/cyan-skillfish-governor-smu/config.toml

Fedora

Enable the COPR repository and install:

sudo dnf copr enable filippor/bazzite
sudo dnf install cyan-skillfish-governor-smu

Configuration file location:

/etc/cyan-skillfish-governor-smu/config.toml

Arch

Install from AUR package cyan-skillfish-governor-smu with your preferred AUR helper:

paru -S cyan-skillfish-governor-smu

Configuration file location:

/etc/cyan-skillfish-governor-smu/config.toml

Generic Linux

If your distribution is not listed above, you can install from a release archive.

1. Download the latest release archive from GitHub Releases.

2. Extract and enter the directory:

tar -xf cyan-skillfish-governor-*.tar.gz
cd cyan-skillfish-governor-*

3. Make sure the binary is available in the extracted directory (for example by using a release archive that already contains cyan-skillfish-governor-smu, or by building it with cargo build --release).

4. Run the installer script:

chmod +x scripts/install.sh
sudo ./scripts/install.sh

Installed configuration location:

/etc/cyan-skillfish-governor-smu/config.toml

Build from sources

Clone the repository (smu branch), then build:

git clone --branch smu https://github.com/filippor/cyan-skillfish-governor.git
cd cyan-skillfish-governor

Build the binary with:

cargo build --release

Then use the binary at:

./target/release/cyan-skillfish-governor-smu

For a manual run test with an explicit config file:

./target/release/cyan-skillfish-governor-smu ./config.toml

General recommendation:

Before enabling at boot, test one manual start and check logs:

systemctl start cyan-skillfish-governor-smu

After that, run a real GPU workload (for example a benchmark or a game) for a few minutes and re-check service logs to confirm expected behavior under load. check log

systemctl status cyan-skillfish-governor-smu
sudo journalctl -u cyan-skillfish-governor-smu -n 100 --no-pager

If everything looks good, then enable it:

systemctl enable cyan-skillfish-governor-smu

after configuration change restart the service with

systemctl restart cyan-skillfish-governor-smu

Configuration

Top-level keys:

• gpu-usage (also accepts legacy gpu_usage)

  • fix-metrics (bool, default: true): enable GPU usage metrics patching.
  • method ("busy-flag" or "process", default: "busy-flag"): how load is sampled proces is more CPU intensive scan all process that use GPU.
  • flush-every (integer, default: 10): flush patched metrics every N update cycles.

• gpu

  • set-method ("smu" or "kernel", default: "smu"): backend used to apply frequency/voltage.

• dbus

  • enabled (bool, default: false): enable D-Bus performance-mode service.

• frequency-range (optional)

  • min (optional integer, MHz): initial minimum frequency limit. Default: hardware minimum.
  • max (optional integer, MHz): initial maximum frequency limit. Default: hardware maximum.
  • Both can be omitted for full range. Can be overridden at runtime via D-Bus.

• timing

  • intervals (microseconds)
    • sample (default: 2000): sampling period. Used by gpu-usage.method = "busy-flag".
    • adjust (default: sample * 10): control-loop period.
  • burst-samples (optional integer 1..=64, default: disabled): number of consecutive busy samples needed to enter burst mode.
    • 0, negative, out-of-range, or missing value disables burst mode.
  • down-events (integer, default: 10): number of low-load events (below load-target.lower) required before stepping down.
  • ramp-rates (MHz/ms)
    • normal (default: 1.0): normal ramp rate.
    • burst (default: 200 * normal): burst ramp rate. Must be greater than normal.

• frequency-thresholds

  • adjust (MHz, default: 10): minimum proposed frequency delta required to apply a non-burst change.

• load-target (fraction)

  • upper (default: 0.95): load above which target frequency increases.
  • lower (default: upper - 0.15): load below which target frequency decreases.

• temperature (degrees C)

  • throttling (optional integer 0..=110, default when missing: 85): above this temperature, max allowed frequency is reduced.
  • throttling_recovery (optional): below this temperature, max frequency is restored.
    • Must be at least 1 and strictly less than throttling.
    • Missing value keeps recovery disabled.

• safe-points

  • Array of { frequency, voltage } tables.
  • frequency in MHz, voltage in mV.
  • Must be non-empty when provided.
  • For increasing frequency, voltage must not decrease.
  • If missing entirely, conservative built-in defaults are used.

Example Configuration

Use default-config.toml as a baseline profile.

Performance Mode Script

The configuration option dbus.enabled must be set to true.

Performance mode:

• Sets frequency to max by default,
• Reduces load-check overhead (and skips load calculation entirely when gpu-usage.fix-metrics is disabled),
• Keeps thermal throttling active.

The script communicates with the governor via D-Bus (see D-Bus Interface section).

Prerequisites:

• Governor service must be running and D-Bus enabled.
• busctl (preferred) or dbus-send available on the system.

Script modes

1. Toggle and set frequency:

cyan-skillfish-performance-mode --on
cyan-skillfish-performance-mode --fixed-frequency 1200
cyan-skillfish-performance-mode --range 500 1500
cyan-skillfish-performance-mode --off
cyan-skillfish-performance-mode --status

2. Wrap a command (auto-enable then auto-disable on exit):

cyan-skillfish-performance-mode mangohud %command%
cyan-skillfish-performance-mode --fixed-frequency 1200 mangohud %command%
cyan-skillfish-performance-mode --range 700 1500 some-game

3. Steam launch option example:

cyan-skillfish-performance-mode %command%
cyan-skillfish-performance-mode --fixed-frequency 1200 %command%

If needed, you can pass -- before the wrapped command:

cyan-skillfish-performance-mode --fixed-frequency 1200 -- mangohud %command%

In wrapper mode, the script installs a cleanup trap, so performance mode is disabled when the wrapped process exits (including Ctrl+C / TERM paths handled by the script).

D-Bus Interface Complete Reference

D-Bus service exposed when dbus.enabled = true:

• Service: com.cyan.SkillFishGovernor
• Object: /com/cyan/SkillFishGovernor
• Interface: com.cyan.SkillFishGovernor.PerformanceMode

Methods

• Enable() — Enable performance mode (max frequency, reduced load overhead)
• Disable() — Disable performance mode (return to adaptive frequency control)
• SetFixedFrequency(frequency: u32) — Set fixed frequency in MHz (enables performance mode)
• SetRange(min: u32, max: u32) — Set frequency range limits (MHz). Use 0 for no limit:
  • SetRange(0, 1500) — cap to 1500 MHz
  • SetRange(500, 0) — floor to 500 MHz
  • SetRange(500, 1500) — set both limits
  • SetRange(0, 0) — clear all limits (full range)
  • Thermal throttling still applies regardless of range

Properties

• Enabled (bool, read/write) — Get or set performance mode enabled state

Examples

# Using busctl (preferred)
busctl --system call com.cyan.SkillFishGovernor /com/cyan/SkillFishGovernor com.cyan.SkillFishGovernor.PerformanceMode Enable
busctl --system call com.cyan.SkillFishGovernor /com/cyan/SkillFishGovernor com.cyan.SkillFishGovernor.PerformanceMode SetFixedFrequency u 1200
busctl --system call com.cyan.SkillFishGovernor /com/cyan/SkillFishGovernor com.cyan.SkillFishGovernor.PerformanceMode SetRange uu 500 1500
busctl --system call com.cyan.SkillFishGovernor /com/cyan/SkillFishGovernor com.cyan.SkillFishGovernor.PerformanceMode Disable

# Using dbus-send (if busctl unavailable)
dbus-send --system --dest=com.cyan.SkillFishGovernor /com/cyan/SkillFishGovernor com.cyan.SkillFishGovernor.PerformanceMode.SetRange uint32:500 uint32:1500

Troubleshooting

If the service does not behave as expected, run the governor directly with verbose logging and an explicit config path:

sudo cyan-skillfish-governor-smu --verbose /etc/cyan-skillfish-governor-smu/config.toml

If you are running from a local build tree instead of the installed binary:

./target/release/cyan-skillfish-governor-smu --verbose ./config.toml

This helps isolate whether issues come from systemd startup or from configuration/runtime behavior.