Home

ZenTune

ZenTune is an open-source hardware management utility for AMD Ryzen mobile processors (APUs) and desktop processors on Linux and macOS Hackintosh systems. It exposes platform power limits (STAPM, Fast, Slow, PPT), thermal limits, voltage regulator current limits (TDC, EDC), clock targets, and Curve Optimizer offsets directly from user space without firmware modifications.

The application runs a terminal user interface built on Textual and communicates with a privileged background daemon via local ZeroMQ inter-process communication. Hardware access is handled through the zenmaster library, which interacts directly with AMD SMU mailboxes, kernel power profile interfaces, and discrete GPU drivers.

---

Hardware and Platform Support

Target Component	Architecture / Model	Support Level	Implementation Notes
AMD Ryzen Mobile (APUs)	Zen 1 through Zen 5+	Supported	STAPM, Fast/Slow boost, skin temperature, VRM currents, Curve Optimizer
AMD Ryzen Desktop CPUs	AM4 / AM5 platforms	Supported	PPT, TDC, EDC, PBO scalar, per-core Curve Optimizer, static clock/VID
Framework Laptop 13	Ryzen 7040 / Ryzen AI 300	Dedicated Presets	DMI-matched platform power tables
Framework Laptop 16	Ryzen 7040 (iGPU or RX 7700S dGPU)	Dedicated Presets	Discrete presets for APU-only and discrete graphics configurations
NVIDIA Discrete GPUs	Pascal through Ada Lovelace	Supported	Clock cap, core/memory offsets via NVML, and Watt-to-mW power limit management
Intel Processors	All models	Unsupported	Hardware initialization issues a warning and disables preset application

Operating System Requirements

• Linux: Kernel 5.10 or newer. Python 3.10+. Privilege elevation operates via systemd run0 (using system Polkit authentication) or standard sudo. Direct PCI access is used by default when Secure Boot is disabled; systems with Secure Boot active require the ryzen_smu kernel driver.
• macOS: Hackintosh systems with AMD processors running macOS 12 Monterey or newer. Requires DirectHW.kext loaded into the kernel for SMU mailbox tuning and physical memory access for raw PM table inspection via CLI (zenmaster --sensors), or the kext-free IOPCIBridge fallback configured with boot argument debug=0x144 (tuning supported). TUI Home tab live sensor graphing and Adaptive Mode are Linux-only.

---

Core Capabilities

• Premade Power Profiles: Four tuned operating tiers per CPU family: Eco, Balanced, Performance, and Extreme.
• Custom Preset Editor: Fine-grained configuration of up to 65 parameters on APUs and 34 on desktop processors, including power limits, thermal ceilings, clock pairs, VRM limits, and per-core Curve Optimizer offsets.
• System Platform Integration: Direct coordination with power-profiles-daemon (ppd), TuneD, and ACPI sysfs fallback (platform_profile), along with ASUS notebook WMI profiles (throttle_thermal_policy), dGPU Eco switches, CPU Energy Performance Preference (EPP), and CPU Turbo Boost.
• NVIDIA GPU Tuning: Software power limits, frequency-adjusted voltage caps, and core/memory offsets using modern NVML _ClockOffset calls with fallback to legacy driver APIs.
• Adaptive Workload Mode: Dynamic state machine that continuously samples temperature and CPU load to dynamically modulate power ceilings, Curve Optimizer margins, and iGPU boost frequencies within user-defined boundaries (Linux only).
• Automations & Event Handlers: Event-driven profile switching based on AC power transitions (battery charge and discharge) and system resume events, featuring anti-flap protection and a 5.0-second post-suspend settling delay.
• Preset Backup & Restore: Unified JSON serialization supporting atomic export and non-destructive merge imports of custom and adaptive profiles (~/zentune_backup.json, format version 1).
• Telemetry Dashboard: Real-time graphing of CPU temperatures, power consumption, core frequencies, and utilization via textual-plotext (Linux only; Home tab renders as quick navigation menu on macOS).

---

Interface Navigation & Keyboard Controls

ZenTune provides keyboard shortcuts and mouse navigation across all functional screens:

Key Binding	Screen / Action	Function
h	Home (home)	Real-time system monitoring dashboard with temperature, power, clock, and usage graphs (Linux; navigation menu on macOS).
1	Premade (power)	One-click power profile switching (Eco, Balanced, Performance, Extreme).
2	Custom (custom)	Parameter editor for creating, saving, applying, and duplicating custom tuning profiles.
3	Adaptive (adaptive)	Dynamic load-reactive tuning engine configuration and execution (Linux only).
4	Auto (automations)	Event-driven automation slot configuration (Battery Charge, Discharge, Resume).
5	Info (hardware)	Processor signature, family codename, architecture, and board identification data.
6	Status (status)	Daemon operational state, active loop counters, and raw SMU response logs.
7	Settings (settings)	Daemon service administration, privilege tool selection, themes, and configuration resets.
?	About (about)	Application version, build identifier, repository links, and runtime paths.
escape	Tabs (focus_tabs)	Returns keyboard focus to the main tab header navigation strip.
q	Quit (quit)	Closes the terminal interface while leaving background daemon loops running.

---

Documentation Index

• Linux Installation: Package installation, virtual environment setup, driver prerequisites (ryzen_smu), and privilege escalation options (run0 and sudo).
• macOS Installation: Setup procedures on AMD Hackintosh systems, DirectHW installation, and debug=0x144 IOPCIBridge fallback configuration.
• Linux Troubleshooting: Resolution steps for daemon connectivity errors, Polkit permissions, TLP profile conflicts, and Secure Boot constraints.
• macOS Troubleshooting: Guidance for SIP configuration, kernel extension approval, log tailing, and launchd service management.
• Premade Presets: Operational characteristics of built-in power tiers, family detection logic, and Framework Laptop profiles.
• Custom Presets: Comprehensive parameter reference covering thermal ceilings, power boundaries, clock clamp pairs, and Curve Optimizer encoding.
• Adaptive Mode: Dynamic workload algorithms, warm-up ramping steps, iGPU overdrive parameters, and safety thresholds.
• Automations: Event-driven monitor behavior, power-state transition handling, and post-suspend settling delays.
• Configuration: Complete reference for config.ini sections ([User], [Settings], [Automations], [Adaptive], [Info]), clamping ranges, and daemon options.
• Developer Documentation: Architectural manual covering the ZeroMQ two-process model, platformctl.py priority cascades, SMU mailboxes, and backup serialization.