Installation

Installation

ZenMaster is distributed as a standard Python package available from PyPI. It has no third-party library dependencies across Linux, Windows, or macOS. Direct interaction with the AMD System Management Unit (SMU) requires elevated privileges and platform-specific hardware access interfaces.

pip install zenmaster

To update an existing installation:

pip install -U zenmaster

To check the installed version:

zenmaster --version

---

Linux

Hardware access on Linux requires root privileges (sudo). ZenMaster communicates with the SMU via direct PCI root complex configuration access or through the ryzen_smu kernel module.

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

Backend Selection and Prerequisites

ZenMaster evaluates hardware access mechanisms automatically:

1. Direct PCI Config Access (Default)

   • Target device: Root complex Host Bridge (/sys/bus/pci/devices/0000:00:00.0/config).
   • Registers: Northbridge Address Register 0xB8 (NB_ADDR) and Data Register 0xBC (NB_DATA).
   • Synchronization: Cross-process file lock at /run/lock/access_pci.lock (falls back to /tmp/access_pci.lock) with a 5000 ms timeout.
   • Operating condition: Standard kernels where PCI configuration space writes are permitted.

2. Kernel Driver (ryzen_smu)

   • Sysfs interface: /sys/kernel/ryzen_smu_drv/smn.
   • Minimum version requirement: 0.1.7 or newer.
   • Operating condition: Required when Linux kernel lockdown restricts physical memory access (/dev/mem) or blocks direct PCI configuration writes (such as under active Secure Boot policies).

Installing the ryzen_smu Kernel Module

When kernel lockdown prevents direct PCI access, install the out-of-tree DKMS driver:

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

Systems enforcing module signature verification under Secure Boot require enrolling a Machine Owner Key (MOK) using mokutil prior to loading the compiled module.

User Environment vs. System Python

SMU operations require elevation. When installed in a user-specific virtual environment or local prefix (~/.local), sudo zenmaster may fail to locate the binary on PATH. Execute the module directly through the target Python interpreter:

sudo python3 -m zenmaster --info

---

Windows

Windows restricts user-mode access to PCI configuration registers and physical memory. ZenMaster accesses the SMU through PawnIO, a Microsoft-attested kernel driver, replacing legacy drivers such as WinRing0.

Setup Instructions

1. Download and run the official PawnIO installer: https://github.com/namazso/PawnIO.Setup/releases/latest/download/PawnIO_setup.exe
2. Reboot the system to finalize driver registration.
3. Launch an elevated command prompt or PowerShell instance (Run as Administrator).

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

Architecture and Synchronization

• Driver Interface: \\?\GLOBALROOT\Device\PawnIO using IOCTL 0xA1B22084 (LOAD) and 0xA1B22104 (EXEC).
• Payload: ZenMaster embeds the compiled RyzenSMU.bin micro-payload and transfers it directly into the PawnIO driver runtime.
• Mutex Synchronization: Inter-process coordination is enforced via the Win32 named mutex Global\Access_PCI with a 5000 ms wait ceiling.

---

macOS (AMD Hackintosh)

ZenMaster operates on AMD-based macOS installations. CPU identification executes via sysctlbyname querying hardware CPUID parameters directly, remaining unaffected by OpenCore SMBIOS model spoofing.

Root privileges are required (sudo). Two hardware access paths are supported:

1. DirectHW User Client (DirectHW.kext)

   • Provides full register and DRAM mapping access for both SMU tuning and telemetry PM table reading (--sensors, --table).
   • Repository: https://github.com/joevt/directhw.
   • System Integrity Protection (SIP): Requires enabling third-party kernel extensions via csr-active-config set to 03080000 in OpenCore or Clover.

2. Apple IOPCI Diagnostics (--iopci, Kext-Free)

   • Communicates directly through Apple's native IOPCIBridge framework (_kIOPCIDiagnosticsClientType = 0x99000001).
   • Requires setting the debug=0x144 boot argument in boot-args.
   • Capability: Supports SMU parameter writes; does not support physical memory mapping for PM table decoding.

pip3 install zenmaster
sudo python3 -m zenmaster --stapm-limit=15000 --fast-limit=20000 --tctl-temp=90

To force the kext-free IOPCIBridge backend explicitly:

sudo python3 -m zenmaster --iopci --info

---

Verifying Installation

Verify platform detection, driver connectivity, and mailbox communication using --info:

# Linux
sudo zenmaster --info

# Windows (Elevated Terminal)
zenmaster --info

# macOS
sudo python3 -m zenmaster --info

Example Verification Output

Name       : AMD Ryzen 9 7950X 16-Core Processor
Family     : Raphael  (Zen 4)
Type       : Amd_Desktop_Cpu
Socket     : AM5_V1
CCDs       : 2
CPUID      : Family 25 (0x19), Model 97 (0x61), Stepping 2
PM Table   : Supported (0x00540004, 2236 bytes)
Tuning     : 44 commands supported
Mailbox    : MP1 / RSMU
Backend    : pci
Driver     : PCI direct access
SMU BIOS IF: 13
SMU Version: 84.79.0 (0x00544F00)

The --info command reports hardware CCD topology, decoded CPUID integers, PM table structural dimensions, active mailbox protocol, and SMU firmware revision.

For operational usage and syntax, consult CLI Usage and Tuning Arguments. For hardware error codes or initialization failures, consult Troubleshooting.