Skip to content

Instantly share code, notes, and snippets.

@ginkage

ginkage/rk3588s-retroled-cm5-porting-notes.md

Created March 3, 2026 10:27
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ginkage/d9a542e18d10ca2ef50ed42ccda70ab4 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ginkage/d9a542e18d10ca2ef50ed42ccda70ab4 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
rk3588s-retroled-cm5-porting-notes.md

RetrOLED CM5: DTS Porting Notes (6.1 → 6.19)

Summary of changes made when porting rk3588s-retroled-cm5.dts from the rk35xx vendor kernel (6.1) to the mainline rockchip64 kernel (6.19).

Reference files:

  • 6.1__rk35xx__arm64/arch/arm64/boot/dts/rockchip/rk3588s-retroled-cm5.dts (source)
  • 6.1__rk35xx__arm64/arch/arm64/boot/dts/rockchip/rk3588s-radxa-cm5-io.dts (6.1 IO board reference)
  • 6.19__rockchip64__arm64/arch/arm64/boot/dts/rockchip/rk3588s-radxa-cm5-io.dts (6.19 IO board reference)
  • rk3588s-retroled-cm5.dts (output, in this directory)

Structural / Architectural

Area 6.1 (rk35xx vendor) 6.19 (mainline)
Compatible rockchip,rk3588 rockchip,rk3588s
PMIC External rk3588-rk806-single.dtsi Defined inline in cm5.dtsi (SPI-attached RK806 with all regulators)
NPU rknpu / rknpu_mmu rknn_core_0/1/2 + rknn_mmu_0/1/2 (in DTSI, no board-level override needed)
chosen node /delete-node/ chosen Proper chosen { stdout-path = "serial2:1500000n8"; }
Media engines vdpu, vepu, av1d, rga3, etc. in board DTS Handled in DTSI or not present; removed from board DTS

Regulators

  • Removed vcc_1v1_nldo_s3 — now defined in rk3588s-radxa-cm5.dtsi, but references vcc_sysin which must exist in the board DTS.
  • Added vcc_sysin (4V) — required by the DTSI's inline RK806 PMIC vcc*-supply inputs. Modelled as a fixed rail from vcc5v0_sys, matching the Radxa CM5 IO board design.
  • Renamed vcc3v3_pcie2x1l0 → vcc3v3_wf (WiFi PCIe slot power, same GPIO gpio1 RK_PD3).
  • Replaced wifi_disable / bt_wake regulator-fixed workaround nodes with proper rfkill-gpio nodes for WLAN and Bluetooth.
  • vcc_3v3_s3, vccio_sd_s0, vcc_1v8_s3 etc. are now provided by the inline RK806 PMIC in the DTSI — no board-level definition needed.

Display

VOP2 routing

  • 6.1 vendor: rockchip,plane-mask / rockchip,primary-plane on VP nodes, plus vendor route_* nodes (route_hdmi0, route_dsi1, route_dp0).

  • 6.19 mainline: Endpoint graph topology. Each VP port gets an endpoint:

    Output VP Endpoint name
    HDMI0 vp0 vp0_out_hdmi0 @ ROCKCHIP_VOP2_EP_HDMI0
    DP0 vp2 vp2_out_dp0 @ ROCKCHIP_VOP2_EP_DP0
    DSI1 vp3 vp3_out_dsi1 @ ROCKCHIP_VOP2_EP_MIPI1

  • Removed display_subsystem clock overrides (vendor-only).

HDMI0

  • Added hdmi0-con connector node.
  • Wired via hdmi0_in / hdmi0_out port endpoints (defined in rk3588-base.dtsi).

DSI1 (Raydium RM67199 panel)

  • Panel now connected through dsi1_in / dsi1_out port graph (defined in rk3588-base.dtsi).
  • MIPI DCPHY node renamed: mipi_dcphy1 → mipidcphy1.
  • dsi1_in_vp2 / dsi1_in_vp3 vendor enable nodes replaced by endpoint in &dsi1_in.

DP0 (external display)

  • Connected via dp0_in / dp0_out ports (defined in rk3588-base.dtsi).
  • Uses force-hpd in place of the vendor hpd-gpios (GPIO0 RK_PD3). The mainline rockchip,rk3588-dp driver uses PHY-native HPD.

Audio

  • HDMI: Vendor rockchip,hdmi-compatible hdmi0_sound node removed. The mainline rk3588-base.dtsi defines hdmi0_sound as a simple-audio-card using i2s5_8ch. Board DTS just enables it: &hdmi0_sound { status = "okay"; }.
  • DP audio (dp0_sound via spdif_tx2): Removed — vendor-specific binding with no mainline equivalent yet.
  • WM8960 simple-audio-card: Retained as-is; works in mainline.

USB

6.1 vendor node 6.19 mainline equivalent
usbdrd3_0 + usbdrd_dwc3_0 (dr_mode = "host") usb_host0_xhci (dr_mode = "host")
usbhost3_0 + usbhost_dwc3_0 usb_host2_xhci
usb_host0_ehci / usb_host0_ohci unchanged
usb_host1_ehci / usb_host1_ohci unchanged
  • Dropped vendor-specific /delete-property/ rockchip,usbctrl-grf and rockchip,typec-vbus-det from u2phy0_otg.
  • u2phy2_host / u2phy3_host: added phy-supply = <&vcc5v0_sys>.
  • No USB-C on RetrOLED: usb_host0_xhci runs in plain host mode, no role-switch or fusb302 connector.

Thermal / Fan

  • 6.1: Custom trips on soc_thermal with fan0 cooling device.
  • 6.19: Trips and cooling maps added to package_thermal (the mainline SoC-center thermal zone defined in rk3588-base.dtsi). Fan cooling levels mapped across three temperature thresholds (55 / 65 / 75 °C).

SD Card

  • &sdmmc_det removed from pinctrl-0 (vendor pinctrl group).
  • Card-detect now uses cd-gpios = <&gpio0 RK_PA4 GPIO_ACTIVE_LOW>, matching the Radxa CM5 IO board 6.19 DTS.

RTC (HYM8563)

  • Node renamed from hym8563: hym8563@51 to rtc@51 (mainline style).
  • clock-frequency property removed (not needed in mainline driver).
  • wakeup-source added.
  • Pinctrl label renamed: rtc_int → rtc_int_l (active-low, pull-none).

Pinctrl

  • BT/WiFi: Added bt_reg_on_h and host_wake_bt_h groups (for rfkill-gpio).
  • PCIe: Added pcie20x1_2_perstn_m0 and wifi_pwr_en groups.
  • vbus5v0_typec_en, usbc0_int, usbc_sbu_dc removed (no USB-C).
  • hp_det GPIO changed from pcfg_pull_up on GPIO1 RK_PB2 (unchanged).

Removed (vendor-only nodes)

  • rockchip_suspend — vendor power management node, not present in mainline.
  • display_subsystem clock overrides.
  • vdpu, vdpu_mmu, vepu — now handled in vendor DTSI; not in mainline DTSI, but also not needed in the board DTS.
  • rknpu, rknpu_mmu disabled overrides — replaced by rknn_core_* in DTSI.
  • vop, vop_mmu — already enabled in the 6.19 cm5.dtsi.
  • hdptxphy_hdmi0 duplicate node (only hdptxphy0 is the correct mainline name).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment