K230 clock gates: vendor tree versus mainline clk-k230.c

Compiled 2026-10-06 for openspec/changes/the-mainline-shell-reaches-parity from the mainline 7.3.0-rc5 source (drivers/clk/clk-k230.c) and the vendor 6.6 tree (arch/riscv/boot/dts/canaan/k230_clock_provider.dtsi), matched by register offset and bit. Read-only source comparison; no board involved.

Recorded decisions

• dphy_dft_gate was wired to 0x100 bit 0 in mainline; the vendor dphy_test_clk gates at 0x104 bit 0. Fixed in k230-clk-vpu-ddrcp2-dphy.patch.
• usb_480m_gate and usb_100m_gate both use 0x100 bit 0. The vendor tree gates usb_clk480 and usb_clk100 on the same bit, so this is one hardware gate feeding two clocks, not a mainline aliasing bug. No change.
• The vendor disp_clkext gate (0x74 bit 5) has no mainline gate. Linux never writes the bit, U-Boot’s setting stands, and the panel works (2026-10-06 full-shell evidence). Modelling it without a consumer would let unused-clock cleanup gate it, the failure class this work removed. Left unmodelled on purpose.
• cpu1_*, ai_src/ai_axi and camera0/1/2 gates have no vendor composite node to compare against; they are unvalidated, not known-bad.
• The vendor driver never marks any gate critical and its display drivers do no clock management; the vendor kernel works because its composite clocks are not gated as unused. Mainline needs explicit consumers or CLK_IS_CRITICAL (see docs/evidence/mainline-clock-ownership-2026-10-06/ and docs/evidence/mainline-full-shell-2026-10-06/).

Full table

Vendor gate-capable composite nodes with NO mainline gate at the same reg+bit

Mainline gates with NO vendor composite node at the same reg+bit (no vendor ground truth)

Answers

1. Gates whose register offset/bit differs from the vendor tree (mislabeled gates)

Confirmed bug: dphy_dft_gate (K230_DPHY_DFT_GATE). Mainline wires its GATE to reg 0x100 bit 0:

K230_CLK_GATE_FORMAT(dphy_dft_gate, K230_DPHY_DFT_GATE, 0x100, 0, 0, 0, &pll0.hw);

That is the exact same reg+bit as usb_480m_gate and usb_100m_gate. The vendor’s dphy_test_clk node gates at reg 0x104 bit 0 instead — a different register entirely. Mainline’s own rate divider for this clock (dphy_dft_rate) correctly uses 0x104 for its divider field, so only the GATE half of the definition is wrong; someone copy-pasted the usb_100m_gate/usb_480m_gate block and forgot to repoint the gate register to 0x104. Practical effect: toggling mainline’s dphy_dft_gate actually toggles the shared USB-480M/100M test-clock enable bit, while the real D-PHY test/DFT clock enable at 0x104 bit 0 is never touched by anything in the mainline driver — it is an orphan bit, left exactly as the bootloader set it. This is a real, fixable driver bug independent of the display-blanking investigation, but it’s not purely cosmetic: it means holding dphy_dft_gate “open” (as in the already-tried DDRC+SHRM+VPU_CFG+AI_AXI+DPHY_DFT combination) has zero effect on the real 0x104 bit, and silently duplicates whatever usb_480m_gate/usb_100m_gate already do to 0x100 bit 0.

Structural gap, not a mislabeling, but display-relevant: K230_DISPLAY_CLKEXT_RATE. The vendor’s disp_clkext composite node (comment: “display clkext DIV & GATE”) gates at reg 0x74 bit 5, parented from pll0_div3 (the same PLL tap that also feeds disp_gpu/display_gpu at bit 6 of the same register). Mainline has no gate at all for this: display_clkext_rate is wired straight to &pll0_div3.hw with no intervening K230_CLK_GATE_FORMAT, and there is no K230_DISPLAY_CLKEXT_GATE ID in canaan,k230-clk.h at all. So bit 5 of the DISPLAY control register (0x74) — sitting between display_dpip_gate (bit 2) and display_gpu_gate (bit 6), inside the same register as the already-held display_ahb/axi/dpip/cfg/ref gates — is completely unmanaged by the mainline clk driver. It is whatever the bootloader left it as, and the “already held” display gates do not cover it.

No other reg/bit mismatches were found; every other matched pair lines up exactly (see full table). usb_480m_gate/usb_100m_gate sharing 0x100 bit 0 is not a mainline bug — the vendor DT does the same thing (usb_clk480/usb_clk100 both gate at 0x100/0), so that’s an inherited vendor quirk (shared USB PHY test-clock enable), faithfully copied.

2. Gates plausibly on the VO memory-fetch path (0x90840000 reading DDR over AXI)

Working backwards from the vendor DT and driver:

• No DT consumer anywhere ties any of the “remaining 34” gates (USB ref/480m/100m, hs_sd0_, ls_ audio/codec/adc/i2c/jamlink/pdm/pwm/gpio_debounce) to the display subsystem. The vendor’s own vo@90840000 and dsi@90850000 nodes carry no clocks property at all — power for the DISP domain is handled purely by sysctl_power’s K230_PM_DOMAIN_DISP bit-banger (drivers/soc/canaan/k230-power-domains.c), not by clk consumers. disp_gpu is the only display-register clock with any consumer, and it feeds the gc8000ul 2.5D GPU (vglite), not the VO pixel pipe. ls_pwm_apb_gate/pwm_pclk_gate feeds pwm0/pwm1, but none of the vendor reference LCD boards (k230-canmv-lcd.dts, -lckfb-lcd.dts, -v3-lcd.dts, -01studio-lcd.dts) wire backlight to PWM — they all use a plain backlight_gpio-gpios GPIO line instead. jamlink* has zero consumers anywhere in this tree (camera serial link, unrelated to VO). So the “ls_pwm for backlight” and “jamlink” hypotheses are not supported by this vendor source drop.
• The two concrete register bugs above are the most display-register-proximate candidates and worth testing first, in this order:
  1. Hold the real 0x74 bit 5 (vendor’s disp_clkext) open — mainline has no clk node for it, so this requires a direct register poke/new clk entry, not an existing gate name. This is the one bit in the DISPLAY control register that is provably never touched by mainline, sitting right next to the bits that already are held.
  2. Hold 0x104 bit 0 (the real D-PHY DFT/test clock) open directly — separately from dphy_dft_gate, which (per the bug above) never reaches it.
• Beyond those two, nothing in the vendor DT/driver gives a principled reason to expect any single gate among USB/SD0/LS-peripheral clocks to sit on the VO-DDR path. A more likely explanation for “all 68 works, two ~half-sized subsets don’t” is a shared-register/interconnect side effect rather than one functionally-wired clock: every vendor composite clock (including PLLs) has clk_hw.init.flags = CLK_IS_BASIC only — never CLK_IGNORE_UNUSED/CLK_IS_CRITICAL — and almost none of the ~150 composite nodes have a DT consumer (see table). The vendor VO/DSI drivers do no clk management whatsoever. That means, read literally, even the vendor kernel’s generic clk_disable_unused() should prune nearly everything including the display pipeline; it evidently doesn’t in practice, which means something outside this source tree (U-Boot/SPL bootargs, or BootROM/firmware register state) is what’s actually keeping the real hardware alive. If so, “holding all 68” may simply be the easiest way from Linux to reproduce that unknown external state, without any one gate in the list being individually load-bearing for display.

3. Gates the vendor DT marks read-only, or that the vendor driver never registers

• Read-only: none. Every node checked across the ~150-entry k230_clock_provider.dtsi (PLLs, composites, fixed-factor) has read-only = <0> and status = "okay". The vendor driver’s read-only/composite_read_only machinery exists in code (k230_clk_composite_{enable,disable,set_rate} all check it and refuse with pr_err("...is read-only!") if set) but is never actually invoked by any shipped .dtsi value in this tree.
• Never registered by the vendor driver: cpu1_src/plic/apb_gate (reg 0x4), ai_src/ai_axi_gate (reg 0x8), and camera0/1/2_gate (reg 0x6C) have no corresponding canaan,k230-clk-composite node anywhere in k230_clock_provider.dtsi — mainline added clk support for these with no vendor ground truth to validate the reg/bit choices against in this source drop. Either this vendor tree snapshot is for a configuration without a second CPU/AI/camera clock domain, or those trees live in a file not present here; either way, mainline’s reg/bit values for those IDs cannot be cross-checked.