Skip to content

README.md

Latest commit

 

History

History
335 lines (238 loc) · 12.5 KB

README.md

File metadata and controls

335 lines (238 loc) · 12.5 KB
Raw

ZenMaster

PyPI Python License Platform

Overview

ZenMaster adjusts power management settings for AMD Ryzen CPUs and APUs on Linux and Windows. It uses the same CLI as RyzenAdj, so your existing commands and presets keep working, but you install it with pip and never need a compiler. Set power limits, temperature limits, VRM currents, clocks, voltages and Curve Optimizer offsets without touching the BIOS.

pip install zenmaster

Reasons to use it over RyzenAdj:

  • Installs with pip — no cmake, libpci, or building from source
  • Same --name=value syntax, so scripts and presets carry over unchanged
  • Uses PawnIO on Windows instead of WinRing0, which has known CVEs
  • --help lists only the arguments your CPU supports, not every possible option
  • --table shows a labeled sensor table; --json makes the output scriptable
  • --reapply=N keeps your settings applied so other software can't undo them
  • Works as a Python library — import zenmaster — on both Linux and Windows
  • No mandatory third-party dependencies on either platform

Documentation

Full documentation lives in the Wiki:

Page What's in it
Installation Linux and Windows setup, ryzen_smu and PawnIO
CLI Usage Every option, examples, JSON output
Tuning Arguments Full argument reference with units
PM Table and Monitoring --table / --dump-table
Library API Embedding ZenMaster in Python
Architecture Internals, SMU protocol, opcode tables
Troubleshooting Fixes for the common problems
FAQ Short answers

Compatibility

Platform Status
Linux, Python 3.10+, root Supported — ryzen_smu module or PCI direct access
Windows, Python 3.10+, Administrator Supported — PawnIO driver
Intel Not supported

Note

On Linux, PCI direct access works on most systems without any kernel module. ryzen_smu is only required when Secure Boot is enabled, because kernel lockdown blocks raw PCI access. Install ryzen_smu ≥ 0.1.7 and enroll the signing key in that case.

Warning

This tool writes directly to the CPU's System Management Unit. Wrong values can cause instability, throttling, or a hard lock. Use at your own risk.

How it compares to RyzenAdj

ZenMaster keeps RyzenAdj's argument names and SMU opcode semantics, so it is a drop-in replacement for most use cases, while removing the build step and the WinRing0 driver.

RyzenAdj ZenMaster
Install Build from source (cmake, pkg-config, libpci) pip install zenmaster
Language C Pure Python 3.10+
Windows driver WinRing0 ⚠️ PawnIO ✅
--help Static — lists every argument Dynamic — only your CPU's arguments
Output Plain text Plain text or --json
PM table Raw float dump Labeled fields with units (--table)
Use as a library Link the C libryzenadj / shell out import zenmaster
Build dependencies cmake, make, libpci None
Focus "Ryzen Mobile Processors" Ryzen mobile and desktop

On WinRing0

RyzenAdj's Windows backend uses WinRing0 (OlsApi / OpenLibSys), a driver with well-documented vulnerabilities (CVE-2020-14979, CVE-2021-41285). It grants any unprivileged process full read/write access to physical memory, PCI config space, and I/O ports, and several AV vendors flag it outright.

ZenMaster uses PawnIO instead — a purpose-built, Microsoft-signed kernel driver that exposes a narrow IOCTL interface. No raw physical-memory access, no known CVEs.

Installation

Linux

pip install zenmaster

Requires root, and either the ryzen_smu kernel module or PCI direct access (used automatically when available).

Install ryzen_smu (only needed when Secure Boot is on):

git clone https://github.com/amkillam/ryzen_smu
cd ryzen_smu && make && sudo make install
sudo modprobe ryzen_smu

Apply a preset:

sudo zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

Re-apply every 30 seconds:

sudo zenmaster --stapm-limit=15000 --reapply=30

Windows

  1. Install PawnIO and reboot.
  2. Open an Administrator terminal.
pip install zenmaster
zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

CLI

zenmaster [OPTIONS] [TUNING ARGS...]
Option Description
--help Show the tuning arguments supported by your CPU
--info Detected CPU name, family, socket, active backend, and driver status
--table Live PM table with labeled values
--sensors Key live sensors only — temp, load, power, clocks (compact; structured under --json)
--dump-table Raw PM table floats with hex offsets
--json Machine-readable JSON output
--reapply=N Re-apply settings every N seconds
--version Show the installed version and check PyPI for a newer release

Tuning arguments use the same --name=value form as RyzenAdj. Arguments that take no value (--enable-oc, --power-saving, --get-*, …) are passed as bare flags. The --get-* query commands print the value the SMU returns:

$ sudo zenmaster --get-pbo-scalar
get-pbo-scalar [RSMU 0x6D] -> OK = 42 (0x0000002A)

Check what your CPU supports:

$ zenmaster --help

ZenMaster — Ryzen Power Management Tool

Usage: zenmaster [OPTIONS] [TUNING ARGS...]

Tuning arguments for AMD Ryzen 9 7950X (Raphael, AM5_V1):

  Power limits:
    --stapm-limit=<mW>                 Sustained Power Limit — STAPM LIMIT
    --fast-limit=<mW>                  Actual Power Limit — PPT LIMIT FAST
    --slow-limit=<mW>                  Average Power Limit — PPT LIMIT SLOW
    ...

Live PM table (APU / mobile):

$ sudo zenmaster --table

PM Table Version: 0x00450005
+-------------------------+-----------+------------------------+
| STAPM LIMIT             |    15.000 | stapm-limit            |
| STAPM VALUE             |    12.441 |                        |
| PPT LIMIT FAST          |    20.000 | fast-limit             |
| THM LIMIT CORE          |    90.000 | tctl-temp              |
| THM VALUE CORE          |    67.125 |                        |
+-------------------------+-----------+------------------------+

Compact live sensors — --sensors (add --json for a structured object a monitoring script can read directly):

$ sudo zenmaster --sensors
CPU Temp    :     64.0 °C
CPU Load    :     38.5 %
Socket Power:     41.2 W
iGPU Clock  :   2400.0 MHz
Mem Clock   :   2400.0 MHz

Library usage

ZenMaster is built to be embedded in tuning utilities, dashboards, and automation tools — including from non-Python apps via the --json CLI.

import zenmaster
from zenmaster import detect, apply, smu

print(zenmaster.__version__)

info = detect()
print(info.name, info.family)

try:
    backend = smu.init()
    print(backend)
except RuntimeError as e:
    print(f"SMU unavailable: {e}")
    raise SystemExit(1)

results, rejected = apply("--stapm-limit=15000 --tctl-temp=90", info.family)
for r in results:
    print(r["arg"], smu.status_name(r["status"]))

apply("--enable-oc", info.family)

if smu.pm_table_supported(info.family):
    data = smu.read_pm_table(info.family)
    ver  = smu.read_pm_table_version(info.family)

smu.send_mp1(info.family, 0x05, 15000)
smu.send_rsmu(info.family, 0x31, 90)

Backend readiness and live sensors (0.4.0):

from zenmaster import smu

smu.ensure_backend()           # init(), but returns the backend str or None — never raises
smu.unavailable_reason()       # None if usable, else a ready-to-show "why not" message
smu.module_status()            # driver verdict: .ok / .version / .min_version / .reason

s = smu.read_pm_sensors(info.family)   # read + decode the PM table → PmSensors | None
if s:
    print(s.tctl_temp, s.cclk_busy, s.socket_power, s.gfx_clk)

These work the same on Linux and Windows, and are re-exported at the top level (from zenmaster import module_status, read_pm_sensors, ...) so apps never import from zenmaster.linux.

Look up supported args for a CPU (no privileges needed):

from zenmaster import runner

print(runner.get_supported_args("Renoir"))
print(runner.lookup("Renoir", "stapm-limit"))
print(runner.is_flag_arg("enable-oc"))
print(runner.is_flag_arg("stapm-limit"))

Runnable examples live in examples/:

  • demo.py — a tour of detection, apply, queries, and raw SMU access.
  • monitor_pmtable.py — live PM-table dump (ported from RyzenAdj's get_table_values).
  • reapply_loop.py — hold a preset against drift via read_pm_sensors + apply (ported from RyzenAdj's get_fast_limit loop).

For integrators:

  • The package ships type hints (py.typed) — your type checker sees the full API.
  • smu.init() raises BackendUnavailable on failure; SMU calls before init raise SMUNotInitialized. Both subclass ZenMasterError, which subclasses RuntimeError, so you can catch as narrowly or broadly as you like.
  • apply() returns list[ApplyResult] — each result is a dict with the stable keys arg, value, mailbox, opcode, status, error, returned. error is None on success; returned holds the value from a get-* query.
  • SMU status codes are smu.SmuStatus (an IntEnum); smu.status_name(code) gives a label.
from zenmaster import smu, BackendUnavailable

try:
    smu.init()
except BackendUnavailable as e:
    ...  # no driver / not root / Secure Boot — message explains which

Install with dev dependencies:

pip install "zenmaster[dev]"
pytest

Updating

ZenMaster updates through pip:

pip install -U zenmaster

To check whether a newer release is on PyPI without updating:

zenmaster --version

From code, zenmaster.check_update() returns the newer version string, or None if you are current.

Supported CPUs

Covers first-gen Ryzen (Summit Ridge / Zen 1) through Ryzen 9000 and Strix Halo. Run zenmaster --info to confirm detection and socket mapping.

PM table support (--table): Raven Ridge, Picasso, Dali, Pollock, Renoir, Lucienne, Cezanne/Barcelo, Van Gogh (Steam Deck), Mendocino, Rembrandt, Phoenix Point, Hawk Point, Strix Point, Krackan Point, Strix Halo. On Linux it reads through the ryzen_smu module when loaded, otherwise over PCI direct (/dev/mem, subject to kernel CONFIG_STRICT_DEVMEM).

Requirements

Linux Windows
Python 3.10+ 3.10+
Privileges root Administrator
Driver ryzen_smu module or PCI direct PawnIO
Extra deps None None

Acknowledgments

Project Contribution
RyzenAdj Canonical argument names and SMU opcode semantics
UXTU4Linux SMU opcode tables and Linux backend reference
Universal x86 Tuning Utility Windows PawnIO path and CPU detection approach
ryzen_smu Linux kernel module for SMU access
PawnIO Modern signed Windows kernel driver