Add clocks and cpubench subcommands; fix #161 PLL decode

[widgetii]

Summary

• Adds ipctool clocks (alias freq) — reports CPU PLL, DDR clock, and per-die HPM characterization of the running SoC as YAML (default) or JSON. Also surfaces as a top-level clocks: section in the default ipctool no-arg survey.
• Adds ipctool cpubench — multi-pattern inline-asm CPU clock triangulation. Three Cortex-A7-tuned patterns (dep_add, indep_add, dep_mul) cross-validate the register-based clock decode. Kept as a battle-proven test for future board bring-up when a PLL register decode is suspect.
• Fixes the PLL register identification asserted in Show current CPU clock, DDR clock, and per-die HPM characterization #161: 0x12010014 is not the CPU PLL FBDIV; the real CPU PLL (APLL) is the register pair (0x12010000, 0x12010004) with multi-field decode (FRACDIV/POSTDIV1/POSTDIV2 + FBDIV/REFDIV). All current V4 boards run at 900 MHz.

Closes #161.

Falsifying the issue's register interpretation

The issue body identifies 0x12010014 as "CPU PLL FBDIV" with values 0x01770000 → 952 MHz (Board A) vs 0x018F0000 → 1144 MHz (Board B), attributed to per-die HPM-driven mask-ROM binning.

Bench on three V4 lab boards with three different values at 0x12010014:

Board	0x12010014 raw	cpubench median MHz	cpubench dep_mul MHz
hi3516ev300 OpenIPC	0x00000000	882	900
gk7205v300 OpenIPC	0x01770000 (claimed 952)	874	892
gk7205v300 XM Sofia	0x018F0000 (claimed 1144)	844*	863*

* XM has unkillable kernel/userspace background load that drags estimates ~5% low.

All three boards run at the same CPU clock regardless of the 0x12010014 value, so it cannot be the live CPU PLL FBDIV. The value at 0x12010014 is mask-ROM-written and correlates with per-die HPM binning, but doesn't drive any active clock.

What 0x12010004 is

The Hi3516A SDK kernel patch (Hi3516EV200_SDK_V1.0.1.2/osdrv/opensource/kernel/linux-4.9.37.patch) defines struct hi3516a_pll_clock for APLL as a register pair (0x0, 0x4):

ctrl_reg1 = 0x00:  FRACDIV[23:0]   POSTDIV1[26:24]  POSTDIV2[30:28]
ctrl_reg2 = 0x04:  FBDIV[11:0]     REFDIV[17:12]
f = 24 MHz * FBDIV / (REFDIV * POSTDIV1 * POSTDIV2)

The V4 SDK kernel patch itself defines no PLL struct (clk-hi3516ev300.c declares only fixed-rate and mux/gate clocks — the V4 Linux clock driver treats CPU clock as fixed-rate post-boot). Applying the Hi3516A layout to V4's actual reads (0x12010000, 0x12010004) = (0x12000000, 0x0100104B) gives FBDIV=75, REFDIV=1, POSTDIV1=2, POSTDIV2=1 → 900 MHz, within 0.2% of the cpubench triangulation.

Cross-checked: both u-boot-hi3516ev200/reg_info_hi3516ev300.bin and u-boot-gk7205v200/reg_info_gk7205v300.bin write only 0x12010080 (DDR cksel). Neither writes the APLL register pair — the mask ROM is the sole writer and the value is identical across all V4 boards (HiSi and Goke brandings).

V4 family register map shipped in this PR

Field	Address	Decode
cpu_pll (APLL)	(0x12010000, 0x12010004)	5-field multi-register
ddr cksel	0x12010080 bits [5:3]	mux: 24 / 450 / 300 / 297 MHz (DDR3 ×4)
hpm	0x1202015C bits [25:16]	value + binning thresholds 190/310
hpm.aux (HPM_CORE_REG0)	0x120280D8	per-die fingerprint
pll_shadow_0c (raw)	0x1201000C	"not a live FBDIV" diagnostic
pll_shadow_14 (raw)	0x12010014	"not a live FBDIV" diagnostic

The two pll_shadow_* entries are kept so users can still spot per-die HPM correlations in the field, but with an explicit note that they don't drive any clock.

Sample output (gk7205v300 OpenIPC)

clocks:
  family: Hisilicon V4 / Goke V300
  cpu_pll:
    ctrl_reg1: 0x12010000
    ctrl_reg1_raw: 0x12000000
    ctrl_reg2: 0x12010004
    ctrl_reg2_raw: 0x0100104b
    fbdiv: 75
    refdiv: 1
    postdiv1: 2
    postdiv2: 1
    fracdiv: 0x000000
    freq_mhz: 900
  ddr:
    reg: 0x12010080
    cksel: 1
    freq_mhz: 450
    data_rate_mbps: 1800
  hpm:
    value: 241
    bin: mid
    binning_window: [190, 310]
    aux_reg: 0x120280d8
    aux_value: 0x81020103
  pll_shadow_14:
    reg: 0x12010014
    raw: 0x01770000
    note: mask-ROM HPM-bin shadow; not a live FBDIV (see clocks_v4.c)

cpubench:
  patterns:
    dep_add:    {ops_per_sec_M: 736.1, cycles_per_op: 1.1875, freq_mhz: 874.1, model: "A7: 1 cyc/op dep ALU"}
    indep_add:  {ops_per_sec_M: 1398.4, cycles_per_op: 0.594, freq_mhz: 830.3, model: "A7: 0.5 cyc/op dual-issue"}
    dep_mul:    {ops_per_sec_M: 279.8, cycles_per_op: 3.1875, freq_mhz: 891.8, model: "A7: 3-cyc latency dep MUL"}
  consensus_freq_mhz: 874  # median, robust to indep_add under-shoot
  spread_pct: 7.0

Test plan

• Cross-build with arm-openipc-linux-musleabi (CI baseline, hi3516cv100 toolchain) + bare UPX — no warnings under -Wextra -O0/-Os.
• ipctool clocks on hi3516ev300 OpenIPC → 900 MHz, shadow regs both zero (mask ROM didn't write them on the HiSi brand).
• ipctool clocks on gk7205v300 OpenIPC → 900 MHz, shadow regs 0x01770000/0x018F0000 (HPM-bin shadow only, properly labeled).
• ipctool clocks on gk7205v300 XM Sofia → 900 MHz, shadow regs 0x018F0000/0x01970000.
• ipctool no-arg → clocks: section appears alongside chip:, ram:, sensors:, etc.
• ipctool cpubench on all three boards → median 844-882 MHz, dep_mul 863-900 MHz (within model noise of 900).
• ipctool clocks --json and ipctool cpubench --json → valid JSON via jq.
• ipctool freq alias works.

Out of scope (TODOs in code comments)

• V1/V2/V3/V3A/V4A/OT/3536C/3536D family tables (the table-driven structure makes each a pure-data addition).
• DDR type auto-detect from DDRC mode registers at 0x120d0000 (currently assumes DDR3 quad-pumped via rate_mult = 4).
• A53 cluster PLL, ETH PLL on V4 once their register layouts are verified.
• Per-CPU scaling_cur_freq for SMP variants (cpu0 only).

🤖 Generated with Claude Code