Home

ZenMaster

ZenMaster is a hardware power, thermal, and frequency management utility and Python library for AMD Zen processors on Linux, Windows, and macOS. It configures processor operating boundaries directly through the AMD System Management Unit (SMU) coprocessor. This eliminates BIOS dependencies and reboots. Parameters modified at runtime include sustained power limits, thermal ceilings, electrical current thresholds, peak clock targets, and Curve Optimizer voltage offsets.

The software functions as a standalone command-line interface tool and as an embeddable Python package (import zenmaster). It requires zero external runtime dependencies. Hardware interactions execute through physical index-data registers on the System Management Network (SMN), native kernel interfaces, and platform device drivers.

pip install zenmaster
sudo zenmaster --stapm-limit=28000 --fast-limit=35000 --slow-limit=30000 --tctl-temp=85

---

Technical Comparison with Legacy Tools

Earlier utilities such as RyzenAdj introduced userspace tuning for AMD mobile APUs. ZenMaster provides a cross-platform implementation with kernel-level direct hardware communication, rigorous concurrency controls, and broader processor support.

Technical Dimension	Legacy Userspace Tools (e.g. RyzenAdj)	ZenMaster
Hardware Access Interface	Userspace port I/O and legacy WinRing0 kernel driver (known CVE-2020-14979).	Direct kernel PCI root complex access (0000:00:00.0/config), Microsoft-signed PawnIO driver, or IOPCIBridge.
Concurrency Synchronization	None. Unsynchronized index/data port accesses produce bus collisions under concurrent access.	Cross-process named PCI mutex (/run/lock/access_pci.lock on Linux, Global\Access_PCI on Windows) with 5000 ms timeout.
Software Integration	Compiled C/C++ binary requiring external process spawning and text output scraping.	Pure Python package (import zenmaster) exposing typed functions, dataclasses, and ctypes bindings with zero dependencies.
Die Topology Discovery	Static core counts inferred from CPU model tables.	Dynamic SMN fuse reading (0x5D218 / 0x5D21C) resolving active Core Complex Dies (CCDs) at hardware initialization.
Hardware Family Matrix	Limited to select mobile APU generations.	Comprehensive 44-family matrix covering Zen 1 through Zen 6, server EPYC, Threadripper, mobile MCMs, and handhelds.
Telemetry Pipeline	Basic sysfs or vendor registers with limited parsing.	Full 86-size PM table decoding engine, DRAM address negotiation, and dynamic multi-CCD per-core telemetry extraction.
Enterprise Protocol Support	Unimplemented. Client SMU opcodes only.	Dedicated Server Host System Management Port (HSMP 0x3B10A8C) mailbox driver for EPYC and Threadripper.

---

Supported Processor Matrix

ZenMaster supports 44 distinct AMD CPU families spanning desktop AM4/AM5, server EPYC, high-end desktop (HEDT) Threadripper, mobile desktop-replacement multi-chiplet modules, monolithic APUs, and x86 architectural derivatives.

Microarchitecture Overview

• Zen 1 / Zen+ / Zen 2 (CPUID Family 23 / 0x17):
  • Desktop AM4: Summit Ridge, Pinnacle Ridge, Matisse.
  • HEDT & Server: Threadripper (1000/2000 series), Colfax, Naples, Rome, Castle Peak (Threadripper 3000 series).
  • APU & Embedded: Raven Ridge, Raven Ridge 2, Picasso, Pollock, Dali, FireFlight, Renoir, Lucienne, VanGogh (Steam Deck), Mendocino.
• Zen 1 Derivative (CPUID Family 24 / 0x18):
  • Server: Hygon Dhyana C86 enterprise server silicon.
• Zen 3 / Zen 3+ / Zen 4 / Zen 4c (CPUID Family 25 / 0x19):
  • Desktop AM4 & AM5: Vermeer, Raphael.
  • HEDT & Server: Milan, Chagall (Threadripper 5000 series), Storm Peak (Threadripper 7000 series), Genoa, Bergamo (Zen 4c), Siena.
  • Mobile Desktop-Replacement MCM: Dragon Range (mobile HX series).
  • Mobile APUs: Cezanne / Barcelo, Rembrandt, Phoenix Point, Hawk Point, Phoenix Point 2, Hawk Point 2.
• Zen 5 / Zen 5c / Zen 6 (CPUID Family 26 / 0x1A):
  • Desktop AM5: Granite Ridge.
  • Server: Turin, TurinDense (Zen 5c).
  • Mobile Desktop-Replacement MCM: Fire Range (mobile HX series).
  • Mobile APUs & Handhelds: Strix Point, Sonoma Valley, Krackan Point, Krackan Point 2, Strix Halo, Medusa 1, Olympic Ridge, Medusa 2.
• Zen 6 Forward-Compatible Fallback (CPUID Family 27 / 0x1B):
  • Reserved for future processor steppings and revisions.

Every detected CPU resolves into either Amd_Desktop_Cpu (desktop processors, HEDT platforms, and EPYC servers) or Amd_Apu (monolithic mobile and handheld chips). Non-AMD processors (Intel) are identified and rejected at initialization.

---

Core Architecture and Hardware Primitives

ZenMaster operates directly on AMD silicon via low-level primitives implemented across dedicated modules:

1. Tri-Mailbox Protocol Engine (mailbox.py)

Hardware communication targets three distinct mailbox coprocessors depending on platform topology:

• MP1 Mailbox: Primary power management processor on client desktop CPUs and APUs (0x3B10528 msg, 0x3B10564 rsp, 0x3B10998 arg default; 0x3B10530, 0x3B1057C, 0x3B109C4 on Matisse/Raphael/Granite Ridge).
• RSMU Mailbox: Secondary power management coprocessor on mobile APU platforms (0x3B10A20 msg, 0x3B10A80 rsp, 0x3B10A88 arg default; 0x3B10524, 0x3B10570, 0x3B10A40 on Matisse/Raphael/Granite Ridge).
• Server HSMP Mailbox: Host System Management Port register triplet on enterprise EPYC and Threadripper silicon (0x3B10A8C msg, 0x3B10A90 rsp, 0x3B10A94 arg).

Transactions execute through a four-phase handshake: clearing the response register to 0x00, writing 32-bit input arguments, transmitting the message opcode, and polling the response register. The controller evaluates hardware status codes:

• 0x01 (SMU_OK): Transaction completed successfully.
• 0xFF (SMU_FAILED): Coprocessor timeout or bus failure.
• 0xFE (SMU_UNKNOWN_CMD): Unrecognized opcode on active SMU firmware.
• 0xFD (SMU_REJECTED_PREREQ): Prerequisite failure (triggers automated two-stage retry at 0.01s and 0.1s).
• 0xFC (SMU_REJECTED_BUSY): SMU coprocessor busy.

2. Dynamic CCD Fuse Detection (smu.py)

Rather than relying on static core tables, ZenMaster inspects hardware fuses via SMN registers 0x5D218 and 0x5D21C (with +0x40 offset on Zen 1 Family 23 non-Matisse processors):

disabled = ((down & 0x3F) << 2) | ((present >> 30) & 0x3)
enabled = ((present >> 22) & 0xFF) & ~disabled
count = enabled.bit_count()

This formula determines the exact number of physically enabled Core Complex Dies. It prevents communication faults on partially fused or asymmetric processors.

3. Cross-Process Concurrency Synchronization (linux.py, windows.py)

Accessing SMN index/data registers (NB_ADDR = 0xB8, NB_DATA = 0xBC) requires atomic read-modify-write operations. To prevent collisions with third-party monitoring utilities or parallel processes, ZenMaster synchronizes every transaction via a named OS mutex:

• Linux: /run/lock/access_pci.lock (fallback /tmp/access_pci.lock) via fcntl.flock.
• Windows: Global\Access_PCI named Win32 mutex via WaitForSingleObject and ReleaseMutex.

Both backends apply a 5000 ms timeout window and cleanly handle abandoned locks.

4. Telemetry and PM Table Decoding (pmtable.py, sensors.py)

ZenMaster decodes comprehensive runtime telemetry through the SMU Power Management (PM) table:

• 86 Struct Layouts: The mapping table covers 86 distinct versioned struct definitions, including 28 new sizes added in v1.2.0 ranging from 1296 to 7752 bytes.
• 5-Tuple Opcode Dispatch: Mailbox negotiation uses family-specific quintuples (ver_op, addr_op, transfer_op, addr_64bit, extra) to retrieve version tags, negotiate physical DRAM buffer addresses, and trigger DMA transfers.
• Multi-CCD Per-Core Telemetry: The read_core_sensors decoder scales candidate core counts via max(core_count, ccd_count * 8) up to 16 cores. It traverses 4-byte base strides from architectural offsets and discards invalid readings to filter out down-fused cores.

5. Tuning and Curve Optimizer Engine (apply.py, runner.py)

The tuning subsystem validates and scales user arguments across 10 socket groups:

• Multi-Token Addressing: The --set-coper flag accepts core:val, ccd:core:val, ccd:ccx:core:val, or global offset tokens with : and , delimiters.
• 20-Bit Two's Complement Scaling: Negative Curve Optimizer offsets are scaled into SMU bitfield format via (0x100000 - abs(val)) & 0xFFFFF.
• Arg0 Bitfield Packing: Client systems pack CCD [31:28], CCX [27:24], Core [23:20], and offset [19:0]. Enterprise HSMP systems pack APIC ID ((ccd << 4) | core) << 1 in [31:16] and signed 16-bit PSM margin in [15:0].
• Per-Core Clocks: Frequency arguments (--oc-clk-per-core) pack die coordinates alongside frequency targets clamped to 8000 MHz.
• APU Skin Temperature Guard: Skin temperature arguments (--apu-skin-temp) scale by 256 for fixed-point 8.8 representation and enforce strict gating to 13 verified APU families.
• Architectural VRM Omission: Mobile desktop-replacement processors (Dragon Range and Fire Range) combine mobile BGA packaging with desktop client I/O dies (cIOD). Their SoC voltage rails (VDDCR_SOC) are regulated by external motherboard controllers without SMU mailbox loops. ZenMaster intentionally omits vrmsoc-current and vrmsocmax-current on these processors to prevent SMU execution rejections (0xFE).

6. Modular Library Architecture (zenmaster)

The Python package provides clean separation between public interfaces and low-level drivers:

• Module Hierarchy: Telemetry interfaces reside in zenmaster.sensors (with zenmaster.table maintained as a backward-compatible alias). macOS transport interfaces reside in zenmaster.iopci and zenmaster.iokit (with zenmaster.iokitcore alias).
• Typed Exception Hierarchy: Errors derive from ZenMasterError, including BackendUnavailable (with automated installation guide URL injection), SMUNotInitialized, and UnsupportedCPU.
• 53 Top-Level Exports: The package exposes 53 functions, classes, and constants in zenmaster.__all__ (detect, resolve, apply, send_arg, read_smn, write_smn, get_ccd_count, read_sensors, read_core_sensors, CoreSensors, and related symbols; note lookup resides under zenmaster.runner.lookup).

---

Operating System Prerequisites

Operating System	Access Privilege	Kernel Transport Interface	Mutual Exclusion Lock
Linux	root (sudo)	Direct PCI config (/sys/bus/pci/devices/0000:00:00.0/config) or ryzen_smu sysfs	/run/lock/access_pci.lock (fcntl.flock)
Windows	Administrator	Microsoft-signed PawnIO kernel driver (\\?\GLOBALROOT\Device\PawnIO)	Global\Access_PCI (Win32 Mutex)
macOS (Hackintosh)	root (sudo)	DirectHW.kext (/dev/directhw) or kext-free IOPCIBridge (debug=0x144)	/tmp/access_pci.lock (fcntl.flock)

---

Documentation Map

• Installation: System requirements, package deployment, kernel module configuration (ryzen_smu), and signed driver setup (PawnIO, DirectHW, IOPCIBridge).
• CLI Usage: Command-line interface syntax, global options, --info output schema, 25 non-destructive query arguments, monitoring flags, and JSON output formats.
• Tuning Arguments: Complete reference of tuning parameters, measurement units, Curve Optimizer syntax, Arg0 bitfield layouts, frequency clamping, and architectural VRM rules.
• PM Table and Monitoring: Power management table telemetry architecture, 86 table sizes, 46-family quintuple mailbox commands, and dynamic multi-CCD per-core sensor extraction.
• Library API: Programmatic integration guide, module hierarchy, typed exception classes, and top-level exported functions in zenmaster.__all__.
• How ZenMaster Talks to the SMU: Low-level SMU mailbox protocols (MP1, RSMU, HSMP), handshake state machines, status codes, retry logic, and direct SMN primitives.
• Architecture: Codebase module structure, execution pipelines, unprivileged platform CPUID resolution, 44-family matrix, and dynamic CCD fuse detection.
• Troubleshooting: Resolution workflows for hardware permission failures, named mutex contention, SMU rejection codes, driver bindings, and platform edge cases.
• FAQ: Technical answers regarding CPU family compatibility, Secure Boot operation, Curve Optimizer bitfields, and hardware safety boundaries.

---

Warning: ZenMaster executes direct write transactions to processor SMU mailbox registers and System Management Network memory addresses. Applying values outside silicon operational limits can trigger thermal throttling, system instability, or kernel panics. Verify parameters against hardware capabilities before deployment.