Skip to content

FAQ

Jump to bottom
Le Khanh Binh edited this page Sep 12, 2026 · 2 revisions

FAQ

How does ZenMaster differ from RyzenAdj?

ZenMaster is a Python implementation of AMD SMU communication interfaces. Key differences from RyzenAdj:

  • Distribution: Installs via standard Python package management (pip install zenmaster) without requiring local C compilers or build toolchains.
  • Windows Driver: Uses the Microsoft-attested PawnIO driver runtime instead of legacy WinRing0 drivers.
  • Expanded Hardware Support: Covers 44 CPU families spanning Zen 1 through Zen 5/6, server EPYC, Threadripper HEDT, and mobile chiplet architectures (Dragon Range and Fire Range).
  • Concurrency Safety: Enforces system-wide named mutex locking (/run/lock/access_pci.lock on Linux, Global\Access_PCI on Windows) to prevent register corruption during concurrent bus access.
  • Programmatic Integration: Exposes a typed Python library interface (import zenmaster) and provides structured JSON output (--json) for automation.

Does ZenMaster support Intel processors?

No. ZenMaster interfaces exclusively with AMD System Management Unit (SMU) coprocessors and System Management Network (SMN) registers. Non-AMD architectures are rejected during hardware detection with an UnsupportedCPU exception.

Does Secure Boot need to be disabled to use ZenMaster?

No. Secure Boot does not need to be disabled in UEFI firmware:

  • Windows: The required PawnIO kernel driver is Microsoft-attested and loads under standard Secure Boot policies.
  • Linux: Direct PCI root complex configuration access operates under Secure Boot on distributions where kernel lockdown does not restrict PCI configuration space writes. On systems where kernel lockdown restricts PCI configuration access or /dev/mem, users can load the out-of-tree ryzen_smu DKMS module signed with a Machine Owner Key (MOK) without disabling Secure Boot.
  • Diagnostic Output: The --info command does not inspect or display Secure Boot state, as backend driver selection is decoupled from CLI information rendering.

See Installation for driver setup details.

Which AMD CPU families are supported?

ZenMaster recognizes 44 processor families spanning five microarchitectural generations, plus forward-compatible Family 27 mappings:

Generation Architecture Family Matrix
Zen 1 / Zen+ SummitRidge, Threadripper (1000/2000), Naples, PinnacleRidge, Colfax, RavenRidge, RavenRidge2, Picasso, Dali, Pollock, FireFlight, Hygon Dhyana (CPUID Family 24)
Zen 2 Rome, CastlePeak, Matisse, Renoir, Lucienne, VanGogh, Mendocino
Zen 3 / Zen 3+ Milan, Chagall, Vermeer, Cezanne_Barcelo, Rembrandt
Zen 4 Genoa, Bergamo, Siena, StormPeak, Raphael, DragonRange, PhoenixPoint, PhoenixPoint2, HawkPoint, HawkPoint2
Zen 5 / Zen 6 Turin, TurinDense, GraniteRidge, FireRange, StrixPoint, KrackanPoint, KrackanPoint2, StrixHalo, SonomaValley, Medusa1, OlympicRidge, Medusa2, Family 27

Run zenmaster --info to verify detected CPU family and socket classification.

How does ZenMaster determine active CCD counts on multi-chiplet CPUs?

ZenMaster queries hardware fuse registers via the System Management Network (SMN) using smu.get_ccd_count(). Rather than estimating CCD counts from visible OS core counts, ZenMaster reads registers 0x0005D218 and 0x0005D21C (offset by +0x40 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 identifies active physical CCDs (1 to 16), allowing telemetry decoders and Curve Optimizer routines to map multi-die topologies accurately.

How does the Curve Optimizer per-core syntax work on multi-CCD processors?

The --set-coper command supports single-token and multi-token addressing using : or , delimiters:

  • core:val: Targets a logical core on CCD 0 (e.g. --set-coper=2:-20).
  • ccd:core:val: Targets a specific core within a designated CCD (e.g. --set-coper=1:4:-15).
  • ccd:ccx:core:val: Specifies CCD, CCX, and local core offset (e.g. --set-coper=1:0:4:-15).

Bitfield Packing

Negative offsets are converted to 20-bit two's complement integers: $$\text{enc20} = (0x100000 - |\text{offset}|) \ &amp; \ 0xFFFFF$$

The 32-bit payload passed to SMU Arg0 is packed as:

  • Bits [31:28]: Target CCD ID (0..15)
  • Bits [27:24]: Target CCX ID (core // 8)
  • Bits [23:20]: Local core index (core % 8)
  • Bits [19:0]: 20-bit Curve Optimizer offset

Enterprise HSMP Addressing

On enterprise HSMP platforms (SOCKET_FP10_AM5), Curve Optimizer offsets are mapped to core APIC IDs:

  • Bits [31:16]: Physical APIC ID calculated as (((ccd << 4) | core) << 1)
  • Bits [15:0]: Signed 16-bit Power Steering Margin (PSM) clamped to [-32768, 32767]

Why do Dragon Range and Fire Range processors reject vrmsoc commands?

Dragon Range (Ryzen 7045HX series) and Fire Range (Ryzen 9000HX series) are mobile BGA adaptations of desktop AM5 multi-chiplet silicon (Raphael and Granite Ridge), pairing client CCDs with a desktop 6nm Client I/O Die (cIOD).

On desktop AM5 silicon:

  1. SoC voltage rail delivery (VDDCR_SOC) is regulated by external motherboard power delivery circuits, not through autonomous APU mailbox controllers.
  2. Firmware command tables for SOCKET_AM5_MOBILE and SOCKET_AM5_FIRERANGE deliberately omit vrmsoc-current and vrmsocmax-current opcodes.
  3. Monolithic mobile APUs (Phoenix, Strix Point) integrate SoC components on a unified substrate and support SMU mailbox SoC current limits. Attempting to dispatch vrmsoc commands on AM5-derived desktop or mobile HX processors causes the SMU to return rejection codes (0xFE or 0xFD).

Core VRM current limits (--vrm-current, --vrmmax-current, --tdc-limit, --edc-limit) operate normally. Fused factory SoC limits can be checked non-destructively via zenmaster --get-pbo-fused-vrmsoc-current.

How does ZenMaster extract per-core metrics on asymmetric or down-fused CPUs?

ZenMaster decodes telemetry per core through read_core_sensors() and displays it via zenmaster --sensors:

  1. The decoder calculates the candidate core allocation as max(core_count, ccd_count * 8).
  2. Telemetry structures in DRAM are traversed using architecture-specific base offsets for power, voltage, temperature, clock, effective clock, and C-state residencies (C0, CC1, CC6).
  3. Cores disabled or down-fused during fabrication (such as on 12-core dual-CCD processors with 6 active cores per die) report null, negative, or out-of-range floats. ZenMaster validates each core entry against physiological bounds (0.0 < power < 500.0, 0.0 < volt < 2.0, 0.0 < temp < 130.0), dropping inactive cores from output while keeping physical core indices intact.

Why does Windows require PawnIO instead of WinRing0?

WinRing0 is an unmaintained third-party driver with published security vulnerabilities (CVE-2020-14979) allowing unprivileged arbitrary physical memory and I/O port read/write access. PawnIO provides a modern, Microsoft-attested alternative that restricts kernel-mode operations to defined IOCTL dispatch routines and requires Administrator elevation to acquire device handles.

How does ZenMaster handle hardware access on macOS Hackintosh systems?

macOS does not run natively on AMD processors. On AMD Hackintosh configurations, ZenMaster queries CPUID directly via sysctlbyname, remaining functional regardless of OpenCore SMBIOS model spoofing.

Hardware communication operates through two paths:

  • DirectHW.kext: Provides direct port and physical memory mapping for full SMU parameter tuning and PM table reading (--sensors, --table). Requires setting SIP csr-active-config to 03080000.
  • IOPCIBridge (--iopci): Kext-free diagnostics client interface native to Apple's IOPCIBridge framework. Requires the debug=0x144 boot-arg. Supports parameter tuning; does not support physical memory mapping for PM table decoding.

See How ZenMaster Talks to the SMU and Installation.

Are SMU parameter modifications permanent?

No. SMU mailbox writes update volatile registers in the processor coprocessor memory. No values are committed to UEFI NVRAM. A system reboot or hard power cycle resets all voltages, clocks, and power ceilings to motherboard firmware defaults.

To maintain parameters across runtime sessions, use the daemon reapply mode:

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

What measurement units are used for tuning arguments?

  • Power limits (stapm-limit, fast-limit, slow-limit, etc.): Milliwatts (15000 = 15 W).
  • Current limits (vrm-current, vrmmax-current, tdc-limit, etc.): Milliamps (60000 = 60 A).
  • Temperatures (tctl-temp, tctl-limit, apu-skin-temp): Degrees Celsius (85 = 85 °C). Values >= 1000 passed to tctl-temp are automatically scaled from millidegrees.
  • Clock frequencies (oc-clk, oc-clk-per-core, gfx-clk): Megahertz (MHz).
  • Voltage overrides (oc-volt): Raw VID integer, not millivolts.

Consult Tuning Arguments for complete specifications.

What causes SMU parameter rejection?

When an argument returns a rejection status:

  1. 0xFE (Unknown command): The parameter is not supported by the processor family or active BIOS microcode.
  2. 0xFD (Rejected prerequisite): The SMU requires an enabling state prior to configuration (such as issuing --enable-oc before setting manual frequencies).
  3. 0xFC (Rejected busy): The SMU coprocessor is processing another request.
  4. Range Exceeded: The specified value falls outside hardware safety boundaries configured in AGESA firmware.

Detailed remediation steps are documented in Troubleshooting.

How can third-party programs integrate ZenMaster?

  • Python Applications: Import the package directly via import zenmaster. The package includes type definitions (py.typed) and exports 53 top-level functions, submodules, and dataclasses (see Library API).
  • External Languages: Invoke the CLI utility with the --json flag to obtain structured JSON payloads suitable for parsing in C, Rust, Go, or shell scripts.

Under what license is ZenMaster distributed?

ZenMaster is open-source software licensed under the GNU General Public License v3.0 (GPL-3.0) by HorizonUnix.

PyPI | Report an Issue | Releases | Under GPL-3.0 by HorizonUnix

Home

Getting started

Monitoring

Developers

Help

Clone this wiki locally