Skip to main content

ZenMaster

PyPI Python License Platform

Overview

ZenMaster configures power limits, thermal thresholds, VRM current limits, clocks, voltages, and Curve Optimizer offsets on AMD Zen processors via the System Management Unit (SMU). It operates across Linux, Windows, and macOS (AMD Hackintosh) without requiring BIOS configuration.

ZenMaster uses the same CLI options and argument naming conventions as RyzenAdj, serving as a drop-in replacement that installs via pip with zero compilation steps.

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

Key Capabilities

  • Broad CPU Coverage: Supports 44 AMD Zen CPU families spanning Zen 1 through Zen 5/6, including mobile APUs, desktop processors, Threadripper workstations, server EPYC platforms (via HSMP), and Hygon Dhyana.
  • Pure Python Delivery: Pure Python 3.10+ package with no C compiler, cmake, or libpci dependencies.
  • Safe Windows Driver: Uses Microsoft-signed PawnIO instead of WinRing0. PawnIO enforces restricted IOCTL dispatch and lacks arbitrary physical-memory mapping primitives.
  • Cross-Process Synchronization: Uses named system mutexes (/run/lock/access_pci.lock on Linux, Global\Access_PCI on Windows) to serialize SMN bus access across concurrent processes and daemons.
  • Hardware-Filtered CLI: zenmaster --help dynamically queries CPUID and displays only the arguments implemented for the detected CPU family.
  • Curve Optimizer Engine: --set-coper supports individual core, CCD, and CCX targeting (core:val, ccd:core:val, ccd:ccx:core:val) with 20-bit two's complement sign-magnitude encoding.
  • Telemetry and Monitoring: Parses SMU Power Management (PM) tables across 28 hardware table structures. Supports formatted table output (--table), live curses per-core monitoring (--sensors), raw binary extraction (--dump-table), and machine-readable JSON (--json).
  • Persistence Support: --reapply=N runs an integrated background reapply loop to preserve parameters against OEM thermal daemon overrides.
  • Embeddable Library: import zenmaster exports typed primitives (detect, apply, smu, read_smn, write_smn, get_ccd_count) under py.typed.

Detailed technical documentation is available in the ZenMaster Wiki.


Documentation

Page Description
Installation Setup instructions for Linux (ryzen_smu / direct PCI), Windows (PawnIO), and macOS (DirectHW / IOPCIBridge)
CLI Usage Command-line reference, query flags, JSON output, and reapply loops
Tuning Arguments Complete SMU argument index, units, opcode mappings, and Curve Optimizer syntax
PM Table and Monitoring Real-time monitoring (--sensors), PM table decoding (--table), and binary dumps
Library API Python integration, low-level SMN operations, and typed exception hierarchies
How ZenMaster Talks to the SMU SMU mailbox protocols (MP1, RSMU, HSMP), PCI config space, and OS driver layers
Architecture Subsystem design, family dispatching, opcode tables, and lock mechanisms
Troubleshooting Root causes and solutions for permission errors, driver conflicts, and rejected opcodes
FAQ Common questions on safety, persistence, hardware support, and limitations

Compatibility

Platform Privileges Driver Requirements Access Mechanism
Linux, Python 3.10+ root None (direct PCI), or ryzen_smu (>= 0.1.7) Direct PCI config via /dev/mem / /dev/port, or /sys/kernel/ryzen_smu/ sysfs
Windows, Python 3.10+ Administrator PawnIO \\.\PawnIO driver handle (IOCTL_READ_PCI_CONFIG, IOCTL_WRITE_PCI_CONFIG)
macOS (AMD Hackintosh), Python 3.10+ root DirectHW.kext, or kext-free DirectHW user-client, or IOPCIBridge Mach service (--iopci, tuning only)
Intel n/a Not supported None

Quick Start

Linux

pip install zenmaster

# Display detected processor family, CCD count, mailbox type, and supported tuning count
sudo zenmaster --info

# Apply power limits and thermal limits
sudo zenmaster --stapm-limit=15000 --fast-limit=20000 --slow-limit=18000 --tctl-temp=90

# Monitor live per-core clocks and power table telemetry
sudo zenmaster --sensors

Windows

Install PawnIO, restart the system, and execute commands from an Administrator terminal:

pip install zenmaster

zenmaster --info
zenmaster --stapm-limit=15000 --fast-limit=20000 --slow-limit=18000 --tctl-temp=90
zenmaster --table

macOS (AMD Hackintosh)

Requires DirectHW.kext for full features, or --iopci for kext-free tuning:

pip3 install zenmaster

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

# Kext-free tuning mode via IOPCIBridge
sudo zenmaster --iopci --stapm-limit=15000 --fast-limit=20000

Library Usage

ZenMaster is structured as an importable Python library with typed interfaces (py.typed).

import zenmaster
from zenmaster import detect, apply, smu, read_smn, write_smn, get_ccd_count
from zenmaster.exceptions import ZenMasterError, BackendUnavailable, SMUNotInitialized

# Detect CPU family, CPUID, CCD topology, and SMU mailbox protocol
info = detect()
print(f"Family: {info.family.name}")
print(f"Mailbox: {info.family.mailbox_type}")
print(f"Physical CCDs: {get_ccd_count()}")
print(f"Available tuning args: {len(info.family.args)}")

# Initialize the platform hardware driver
try:
    smu.init()
except BackendUnavailable as exc:
    print(f"Initialization failed: {exc}")
    raise SystemExit(1)

# Apply SMU settings
results, rejected = apply("--stapm-limit=15000 --fast-limit=20000 --tctl-temp=90", info.family)

for r in results:
    status_str = smu.status_name(r["status"])
    print(f"{r['arg']}: {status_str} (0x{r['status']:02X})")

if rejected:
    print(f"Rejected unsupported arguments: {rejected}")

# Low-level direct SMN access (synchronized via named PCI lock)
value = read_smn(0x0005A380)
print(f"SMN 0x0005A380 = 0x{value:08X}")

Library Architecture Highlights

  • Typed Exceptions: Root exception ZenMasterError (subclass of RuntimeError) with derived types BackendUnavailable, SMUNotInitialized, UnsupportedCPU, SMUTimeoutError, and PMTableError.
  • Direct SMN Operations: read_smn(address) and write_smn(address, value) expose serialized access to the System Management Network bus.
  • Hardware Introspection: detect() returns a CpuInfo object containing CPUID model, stepping, package socket, and the detected CpuFamily.
  • Top-Level Exports: 53 functions and classes exported from zenmaster, with specialized submodules available in zenmaster.sensors (alias zenmaster.table) and zenmaster.iopci (aliases zenmaster.iokit, zenmaster.iokitcore).

Technical Comparison: ZenMaster vs. RyzenAdj

Feature RyzenAdj ZenMaster v1.2.2
Installation Compilation from source (cmake, make, libpci-dev) pip install zenmaster (pure Python package)
Supported Families ~15 APU and desktop families 44 families (Zen 1 to Zen 5/6, Desktop, Mobile, Threadripper, Server EPYC via HSMP)
Windows Driver WinRing0 (OlsApi.dll) ⚠️ PawnIO (PawnIO.sys) ✅
Windows Driver Security Known vulnerabilities (CVE-2020-14979, CVE-2021-41285); unprivileged physical memory read/write Microsoft-signed, IOCTL boundary validation, zero arbitrary physical memory access
Process Synchronization None; uncoordinated concurrent PCI config space access Named cross-process mutex (/run/lock/access_pci.lock on Linux, Global\Access_PCI on Windows)
CLI --help Static output listing all arguments across all generations Dynamic; queries CPUID and displays only arguments implemented for detected CPU
Curve Optimizer Basic per-core integer pass-through Multi-token per-core/CCD targeting (--set-coper=core:val, ccd:core:val, ccd:ccx:core:val) with 20-bit encoding
Server Support None AMD EPYC 7002/7003/9004/9005 series via Host System Management Port (HSMP, 0x3B10A8C)
PM Table Telemetry Unlabeled floating-point array dump Labeled field decoder (--table), curses live monitor (--sensors), and binary export (--dump-table) across 28 structs
macOS Support Partial (DirectHW only) Full DirectHW support plus kext-free IOPCIBridge user-client fallback (--iopci)
Library Embedding Link C shared library or fork subprocess import zenmaster with full type annotations (py.typed)

Supported Processor Families

ZenMaster supports 44 AMD Zen CPU architectures spanning client, mobile, workstation, and enterprise platforms:

  • Zen 1 / Zen+: Summit Ridge, Pinnacle Ridge, Raven Ridge, Picasso
  • Zen 2: Matisse, Castle Peak (Threadripper), Rome (EPYC), Renoir, Lucienne, Van Gogh (Steam Deck), Mendocino
  • Zen 3 / Zen 3+: Vermeer, Chagall (Threadripper), Milan (EPYC), Cezanne, Barcelo, Rembrandt, Rembrandt+, Dragon Crest
  • Zen 4 / Zen 4c: Raphael, Genoa / Bergamo (EPYC), Storm Peak (Threadripper), Phoenix, Phoenix 2, Hawk Point, Dragon Range
  • Zen 5 / Zen 5c / Zen 6: Granite Ridge, Turin (EPYC), Strix Point, Strix Halo, Fire Range, Krackan Point, Medusa, Olympic Ridge
  • Hygon Dhyana: Chinese x86 Zen 1 derivative architecture

Run zenmaster --info to determine the detected family, mailbox architecture, CCD configuration, and PM table version of your system.


Updating

pip install -U zenmaster

To check PyPI for a newer release without upgrading:

zenmaster --version

Programmatic version checks can be executed via zenmaster.check_update().


Acknowledgments

Project Contribution
RyzenAdj Originating project for AMD SMU parameter naming and opcode semantics
Universal x86 Tuning Utility SMU opcode references, PawnIO driver integration architecture, and family detection patterns
ZenTune Reference Linux backend implementation, hardware detection matrices, and sysfs interfaces
ryzen_smu Linux kernel driver module for out-of-tree SMU mailbox communication
PawnIO Modern Microsoft-signed Windows kernel driver interface
DirectHW macOS kernel extension for physical memory and PCI config space operations (joevt)
pciutils Implementation of the darwin2 IOPCIBridge user-client method enabling kext-free macOS access (joevt)

Metadata

Release files for zenmaster 1.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zenmaster 1.2.2
File Size Uploaded Provenance Actions
zenmaster-1.2.2.tar.gz 67.6 kB With provenance Details for zenmaster-1.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zenmaster 1.2.2
File Interpreter ABI Platform Actions
zenmaster-1.2.2-py3-none-any.whl Python 3 none any Details for zenmaster-1.2.2-py3-none-any.whl

Total release size: 136.4 kB

Release files / zenmaster-1.2.2.tar.gz

Download URL zenmaster-1.2.2.tar.gz
Size 67.6 kB
Tags Source
SHA-256 checksum
How to use checksums
62a582e814289d12728ecbc8bd87de6b1baf76d722fc8aa1e9512e9a0fda79b1
BLAKE2b-256 checksum
How to use checksums
8bafa6a9e6893dd0cd894ca3b8191ed32fff495ccf2b51986885bbc949c9ba64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / zenmaster-1.2.2-py3-none-any.whl

Download URL zenmaster-1.2.2-py3-none-any.whl
Size 68.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e00d7ecc91edd852f06952807dec8f4a7cde6bba22eeea0ccd7052c1ea82e839
BLAKE2b-256 checksum
How to use checksums
cb7c1d3338bde13214e5d901da78ab07d1bb50ff140c1b02de0f3b2e9c2a0ea3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for zenmaster 1.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zenmaster-1.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page