Tuning Arguments

Tuning Arguments

ZenMaster configures AMD power management, thermal ceilings, electrical current rails, and clock setpoints by dispatching register payloads to the System Management Unit (SMU). Hardware argument mappings and units align with RyzenAdj conventions while extending support to multi-chiplet topologies, per-core Curve Optimizer addressing, and enterprise server interfaces.

Processor families support different subsets of tuning commands depending on socket architecture. Execute zenmaster --help on the target host to view the exact commands enabled for your platform.

---

Units and Parameter Formats

• Power limits: Expressed in milliwatts (mW). Example: 25000 corresponds to 25.0 Watts.
• Current limits: Expressed in milliamps (mA). Example: 45000 corresponds to 45.0 Amperes.
• Thermal limits: Expressed in degrees Celsius (°C). Example: 85 corresponds to 85 °C. Values greater than or equal to 1000 (such as 85000) are automatically divided by 1000 to convert from millidegrees.
• Clock frequencies: Expressed in megahertz (MHz). Example: 3200 corresponds to 3200 MHz.
• Time constants: Expressed in seconds (s).
• Core voltage override: Set via --oc-volt using Voltage Identification (VID) steps. Formula: VID = (1.55 - target_voltage) / 0.00625. For 1.20 V target, VID equals (1.55 - 1.20) / 0.00625 = 56.
• Parameter Aliases: tctl-limit functions as an exact alias for tctl-temp.

---

Curve Optimizer Addressing and Mathematical Encoding

ZenMaster provides two methods for Curve Optimizer (CO) undervolting: all-core offset via --set-coall and per-core offset via --set-coper.

Multi-Token Syntax (--set-coper)

The --set-coper command allows targeted voltage offsets per physical core across complex multi-die topologies. ZenMaster parses single values or compound tokens using either colon (:) or comma (,) delimiters:

1. core:val (2 tokens): Specifies logical core index and offset value. Assumes CCD 0. Example: --set-coper=2:-20.
2. ccd:core:val (3 tokens): Specifies physical CCD index, logical core index, and offset value. Example: --set-coper=1:4:-15.
3. ccd:ccx:core:val (4 tokens): Specifies physical CCD, CCX, core, and offset. The explicit CCX parameter is ignored during packing because CCX is derived directly from core // 8. Example: --set-coper=1:0:4:-20.
4. val (1 token): Applies offset to Core 0 or acts as single-core fallback.

Values parse via Python integer conversion, accepting standard base-10 integers or hexadecimal numbers prefixed with 0x.

20-Bit Two's Complement Offset Mathematics

AMD SMU firmware interprets Curve Optimizer counts as 20-bit signed integers in two's complement representation:

• For negative offsets (undervolting): $$\text{enc20} = (0x100000 - |\text{value}|) \ & \ 0xFFFFF$$
• For positive offsets (overvolting): $$\text{enc20} = \text{value} \ & \ 0xFFFFF$$

Conversion Reference

Input Value	Offset Type	Two's Complement Hex (enc20)	Decimal Value Sent
+5	Overvolt	0x00005	5
0	Baseline	0x00000	0
-1	Undervolt	0xFFFFF	1048575
-5	Undervolt	0xFFFFB	1048571
-15	Undervolt	0xFFFE1	1048561
-30	Undervolt	0xFFFE2	1048546

Client Mailbox Bitfield Layout (MP1 / RSMU)

On standard client processors (Ryzen desktop and APUs), ZenMaster packs the target core address and 20-bit offset into a 32-bit register (Arg0) before dispatching SMU opcode 0x06 (set-coper) or 0x07 (set-coall):

 31      28 27      24 23      20 19                               0
+----------+----------+----------+----------------------------------+
|  CCD ID  |  CCX ID  | Core ID  |    20-bit Signed CO Offset       |
| (4 bits) | (4 bits) | (4 bits) | (Bits [19:0], two's complement)  |
+----------+----------+----------+----------------------------------+

• Bits [31:28]: CCD identifier (ccd & 0xF).
• Bits [27:24]: CCX identifier within CCD (core // 8).
• Bits [23:20]: Physical core identifier within CCX (core % 8).
• Bits [19:0]: 20-bit two's complement offset value (enc20).

Packed Bitfield Examples

• --set-coper=0:-30: Core 0 on CCD 0 with offset -30. $$\text{CCD}=0,\ \text{CCX}=0,\ \text{Core}=0,\ \text{Offset}=0xFFFE2 \implies \mathbf{0x000FFFE2}$$
• --set-coper=1:2:-15: Core 2 on CCD 1 with offset -15. $$\text{CCD}=1,\ \text{CCX}=0,\ \text{Core}=2,\ \text{Offset}=0xFFFE1 \implies \mathbf{0x102FFFE1}$$
• --set-coper=1:0:4:-20: Core 4 on CCD 1 with offset -20. $$\text{CCD}=1,\ \text{CCX}=0,\ \text{Core}=4,\ \text{Offset}=0xFFFEC \implies \mathbf{0x104FFFEC}$$

Enterprise Server Mailbox Layout (HSMP)

On EPYC server and workstation processors configured with socket profile FP10_AM5, Curve Optimizer offsets route through the High-Speed System Management Port (HSMP). The bitfield format maps the target APIC identifier and signed Power Steering Margin (PSM):

 31                              16 15                             0
+----------------------------------+--------------------------------+
|             APIC ID              |    Signed 16-bit PSM Margin    |
|    (((ccd << 4) | core) << 1)    |   (16 bits, [-32768, 32767])   |
+----------------------------------+--------------------------------+

• Bits [31:16]: Calculated APIC identifier ((ccd << 4) | core) << 1.
• Bits [15:0]: Signed 16-bit PSM margin value clamped to [-32768, 32767].
• Example: Targeting Core 4 on CCD 0 with offset -10 computes APIC ID 8 and margin 0xFFF6, yielding packed word 0x0008FFF6.

---

Per-Core Overclocking Frequency Packing (--oc-clk-per-core)

Static core clock frequency overrides accept the multi-token syntax core:freq, ccd:core:freq, or ccd:ccx:core:freq. Frequency values are specified in MHz and automatically clamped to an upper limit of 8000 MHz.

 31      28 27      24 23      20 19                               0
+----------+----------+----------+----------------------------------+
|  CCD ID  |  CCX ID  | Core ID  |    Target Frequency in MHz       |
| (4 bits) | (4 bits) | (4 bits) | (20 bits, clamped to 8000 MHz)   |
+----------+----------+----------+----------------------------------+

• Bits [31:28]: CCD index (ccd & 0xF).
• Bits [27:24]: CCX index (ccx & 0xF).
• Bits [23:20]: Core index (core % 8).
• Bits [19:0]: Frequency in MHz (min(freq, 8000) & 0xFFFFF).

Example: Setting Core 2 on CCD 0 to 4800 MHz (--oc-clk-per-core=2:4800) generates packed payload 0x002012C0 (where 4800 = 0x12C0).

---

APU Skin Temperature Protection

Mobile laptops use Surface Temperature Tracking (STT) thermistors placed on notebook chassis skins to enforce comfort limits. ZenMaster handles skin limits with two dedicated protections:

1. Fixed-Point 8.8 Scaling: Commands --apu-skin-temp and --dgpu-skin-temp accept temperatures in degrees Celsius. The driver scales input values by 256 prior to SMU transmission ($1^\circ\text{C} = 256$ units). An argument of 45 sends 11520 (0x2D00).
2. APU Family Validation Gate: Skin temperature registers exist solely within mobile monolithic APU firmware. ZenMaster restricts --apu-skin-temp strictly to 13 verified APU families:
   • Renoir, Lucienne, Cezanne_Barcelo, VanGogh
   • Rembrandt, Mendocino, PhoenixPoint, PhoenixPoint2
   • HawkPoint, HawkPoint2
   • StrixPoint, KrackanPoint, KrackanPoint2

If executed on desktop platforms (such as Raphael or Granite Ridge) or EPYC servers, ZenMaster rejects the command immediately:

apu-skin-temp: apu-skin-temp is not supported on Raphael

This validation prevents unmapped mailbox dispatch and avoids platform hangs. Note that --skin-temp-limit specifies a power ceiling in milliwatts and does not apply 256x temperature scaling.

---

Dragon Range and Fire Range Silicon Topology and VRM Omission

Dragon Range (Zen 4 Mobile HX, including Ryzen 9 7945HX) and Fire Range (Zen 5 Mobile HX, including Ryzen 9 9945HX) represent high-performance desktop-replacement processors packaged for mobile FL1 BGA motherboards.

Desktop Multi-Chiplet Architecture

Unlike monolithic mobile APUs where CPU cores, GPU compute units, memory controllers, and system agents reside on a single continuous die, Dragon Range and Fire Range use desktop multi-chiplet module (MCM) silicon identical to Raphael and Granite Ridge:

• One or two 5nm/4nm Core Complex Dies (CCDs) containing Zen cores and L3 cache.
• One 6nm Client I/O Die (cIOD) containing memory controllers, PCIe root complexes, and display engines.
• Inter-die communication routed over substrate Infinity Fabric links.

Motherboard VRM Topology

On monolithic mobile platforms, the SMU actively throttles SoC rail currents via integrated mailbox regulators. On desktop AM5 silicon and its mobile HX derivatives, the SoC power plane (VDDCR_SOC) is powered directly by external multi-phase motherboard VRM controllers without autonomous mailbox current regulation loops.

Because AM5 desktop SMU firmware does not implement runtime mailbox commands for SoC current regulation, sending --vrmsoc-current or --vrmsocmax-current results in SMU command rejection (CMD_REJECTED / status 0xFE).

To preserve system stability, ZenMaster dispatches:

• Dragon Range to SOCKET_AM5_MOBILE
• Fire Range to SOCKET_AM5_FIRERANGE

Both command maps deliberately omit vrmsoc-current and vrmsocmax-current. Primary Core VRM limits (vrm-current, vrmmax-current, tdc-limit, edc-limit) remain fully accessible. Fused factory SoC current limits can still be queried safely via get-pbo-fused-vrmsoc-current (RSMU opcode 0xD9).

---

Complete Argument Reference

Power Limits

Argument	Unit	Type	Description
--stapm-limit	mW	value	Sustained Power Limit (STAPM LIMIT)
--fast-limit	mW	value	Actual Power Limit (PPT LIMIT FAST)
--slow-limit	mW	value	Average Power Limit (PPT LIMIT SLOW)
--ppt-limit	mW	value	Platform Package Tracking power limit
--apu-slow-limit	mW	value	APU PPT Slow limit for A+A dGPU platform (PPT LIMIT APU)
--fast-spm-limit	mW	value	Fast SPM Power Limit
--slow-spm-limit	mW	value	Slow SPM Power Limit
--core-power-limit-offset	mW	value	Core power limit offset
--stapm-time	s	value	STAPM time constant
--slow-time	s	value	Slow PPT time constant

Thermal Limits

Argument	Unit	Type	Description
--tctl-temp	°C	value	Tctl temperature ceiling (THM LIMIT CORE). Millidegrees (>= 1000) converted automatically
--tctl-limit	°C	value	Direct alias for --tctl-temp
--chtc-temp	°C	value	CHTC temperature ceiling
--apu-skin-temp	°C	value	APU skin temperature limit (STT LIMIT APU). Scaled 256x; restricted to verified APUs
--dgpu-skin-temp	°C	value	Discrete GPU skin temperature limit (STT LIMIT dGPU). Scaled 256x
--skin-temp-limit	mW	value	Skin temperature power limit

VRM and Electrical Current Limits

Argument	Unit	Type	Description
--tdc-limit	mA	value	Thermal Design Current limit (TDC LIMIT)
--edc-limit	mA	value	Electrical Design Current limit (EDC LIMIT)
--vrm-current	mA	value	VRM current ceiling (TDC LIMIT VDD)
--vrmmax-current	mA	value	VRM peak current ceiling (EDC LIMIT VDD)
--vrmsoc-current	mA	value	VRM SoC current limit (TDC LIMIT SOC; monolithic APUs only)
--vrmsocmax-current	mA	value	VRM SoC peak current limit (EDC LIMIT SOC; monolithic APUs only)
--vrmcvip-current	mA	value	VRM CVIP current limit (VanGogh only)
--vrmgfx-current	mA	value	VRM graphics current limit (TDC LIMIT GFX)
--vrmgfxmax-current	mA	value	VRM graphics peak current limit (EDC LIMIT GFX)
--psi0-current	mA	value	Power State Indicator 0 VDD current threshold
--psi0soc-current	mA	value	Power State Indicator 0 SoC current threshold
--psi3cpu-current	mA	value	Power State Indicator 3 CPU current threshold
--psi3gfx-current	mA	value	Power State Indicator 3 graphics current threshold
--prochot-deassertion-ramp	index	value	Thermal throttle ramp recovery delay after PROCHOT deassertion
--disable-prochot	n/a	flag	Inhibit external PROCHOT thermal throttle signal

Clock Frequencies

Argument	Unit	Type	Description
--max-cpuclk	MHz	value	Maximum CPU core frequency ceiling
--min-cpuclk	MHz	value	Minimum CPU core frequency floor
--max-gfxclk	MHz	value	Maximum graphics engine clock ceiling
--min-gfxclk	MHz	value	Minimum graphics engine clock floor
--gfx-clk	MHz	value	Fixed graphics clock override
--max-socclk-frequency	MHz	value	Maximum SoC clock frequency
--min-socclk-frequency	MHz	value	Minimum SoC clock frequency
--max-fclk-frequency	MHz	value	Maximum Infinity Fabric frequency
--min-fclk-frequency	MHz	value	Minimum Infinity Fabric frequency
--fclk-overclock-on-the-fly	n/a	flag	Real-time dynamic FCLK adjustment flag
--cclk-fmax-offset	MHz	value	Core clock maximum boost frequency offset
--max-vcn	MHz	value	Maximum Video Core Next clock frequency
--min-vcn	MHz	value	Minimum Video Core Next clock frequency
--max-lclk	MHz	value	Maximum Data Launch Clock frequency
--min-lclk	MHz	value	Minimum Data Launch Clock frequency
--oc-clk	MHz	value	Forced all-core overclock frequency
--oc-clk-per-core	MHz	value	Packed per-core overclock frequency (core:freq)
--set-boost-limit-frequency	MHz	value	Programmed boost clock ceiling
--set-vmin-freq	MHz	value	Minimum operational voltage frequency floor

Overclocking and Voltage Curves

Argument	Unit	Type	Description
--enable-oc	n/a	flag	Unlock manual overclocking control mode
--disable-oc	n/a	flag	Restore automated factory clock management
--oc-volt	VID	value	Target core voltage step: (1.55 - V) / 0.00625
--pbo-scalar	multiplier	value	Precision Boost Overdrive scalar multiplier (1x-10x)
--fit-limit-scalar	index	value	Silicon FIT reliability limit scalar
--set-coall	counts	value	All-core Curve Optimizer offset (negative undervolts)
--set-coper	counts	value	Per-core Curve Optimizer offset with bitfield packing
--set-cogfx	counts	value	Integrated graphics Curve Optimizer offset
--set-gpuclockoverdrive-byvid	index	value	Graphics clock overdrive step by voltage point
--disable-gpuclockoverdrive	n/a	flag	Inhibit graphics clock overdrive
--extra-psm-guardband	margin	value	CPU Power Steering Margin guardband adjustment
--extra-psm-guardband-gfx	margin	value	Graphics PSM guardband adjustment
--set-fll-btc-enable	n/a	flag	Enable Frequency Locked Loop BTC tracking
--set-vddoff-vid	VID	value	Program VDD power-off VID state
--set-ulv-vid	VID	value	Program Ultra-Low Voltage VID state

Power Profiles and State Controls

Argument	Unit	Type	Description
--power-saving	n/a	flag	Activate energy-efficient SMU operating profile
--max-performance	n/a	flag	Activate peak performance SMU operating profile
--enable-feature	bit	value	Enable individual SMU feature by bit index
--disable-feature	bit	value	Disable individual SMU feature by bit index
--setcpu-freqto-ramstate	n/a	flag	Lock core operating frequencies to memory power state
--stopcpu-freqto-ramstate	n/a	flag	Release core operating frequencies from memory power lock

Non-Destructive Query Commands

All query arguments execute as flags without an assigned value. The SMU evaluates queries without modifying active power thresholds.

Argument	Interface	Description	Returned Measurement
--test	HSMP	Verifies mailbox handshake response	Status code
--get-smu-version	SMU / HSMP	Firmware revision word	32-bit integer
--get-interface-version	HSMP	HSMP specification revision	Version integer
--get-metrics-table-version	HSMP	Enterprise metrics table revision	Version integer
--get-metrics-table	HSMP	Trigger DMA transfer of metrics buffer	Status code
--get-metrics-table-dram-address	HSMP	Physical DRAM address of telemetry table	64-bit physical address
--get-pbo-scalar	SMU / HSMP	Current Precision Boost Overdrive scalar	Multiplier integer
--get-sustained-power-and-thm-limit	SMU	Factory fused STAPM and thermal ceiling	Packed power and temp
--get-overclocking-support	SMU	Hardware overclocking feature bitmask	Bitfield flags
--get-max-cpu-clk	SMU	Factory fused maximum core clock limit	Frequency in MHz
--get-min-gfx-clk	SMU	Factory fused minimum graphics clock limit	Frequency in MHz
--get-max-gfx-clk	SMU	Factory fused maximum graphics clock limit	Frequency in MHz
--get-curr-gfx-clk	SMU	Current active graphics clock frequency	Frequency in MHz
--get-core-performance-order	SMU / HSMP	Preferred core performance rankings	Packed core indices
--get-coper	SMU / HSMP	Query Curve Optimizer offset or PSM margin	Offset value
--get-cogfx	SMU / HSMP	Query iGPU Curve Optimizer offset	Offset value
--get-pbo-fused-power-limit	SMU	Factory fused PPT sustained power limit	Power in mW
--get-pbo-fused-slow-limit	SMU	Factory fused PPT slow power limit	Power in mW
--get-pbo-fused-fast-limit	SMU	Factory fused PPT fast power limit	Power in mW
--get-pbo-fused-apu-slow-limit	SMU	Factory fused APU slow power limit	Power in mW
--get-pbo-fused-vrmtdc-limit	SMU	Factory fused VRM TDC current limit	Current in mA
--get-pbo-fused-vrmsoc-current	SMU	Factory fused VRM SoC current limit	Current in mA
--get-pbo-fused-tctl-temp	SMU	Factory fused Tctl temperature ceiling	Temperature in °C
--get-coper-options	SMU	Permitted per-core Curve Optimizer range	Capability bitfield
--get-cogfx-options	SMU	Permitted iGPU Curve Optimizer range	Capability bitfield

---

Safe Tuning Guidelines

1. Verify Base Telemetry First: Execute zenmaster --info and zenmaster --sensors to verify hardware detection and baseline operating temperatures prior to altering parameters.
2. Apply Single Changes: Adjust power ceilings or Curve Optimizer steps individually to identify unstable thresholds cleanly.
3. Validate Curve Optimizer Steps: Test per-core offsets incrementally (-5 counts at a time). Undervolting too aggressively results in idle clock instability (watchdog resets during low-load C-state transitions).
4. Firmware Overrides: If system management software or BIOS resets parameters during runtime, pass the --reapply=N flag to periodically re-assert limits.
5. Troubleshooting: Consult Troubleshooting and the FAQ if the SMU rejects specific commands or returns error codes during execution.