HDMI hot-plug: can plugging in HDMI switch the display automatically?

Researched 2026-09-28 on worktree k230-hdmi-hotplug, branch spec/hdmi-hotplug, base e843c5d6. Research only — no board access, no push/merge. Answers the six questions from the task brief, in order, each grounded per .skills/k230-spec-change/SKILL.md’s tiering (board observation

vendor source read > nothing, which gets <!-- UNVERIFIED -->). Nothing in this document is tier-1 (board-observed); every claim below is tier 2 (vendor or our own source, read and cited by path/line) unless flagged UNVERIFIED.

Headline answer: there is no mux chip. The four DSI data lanes and clock are wired in bare parallel to both the RM69A10 panel and the LT9611 bridge — confirmed from the schematic, not inferred. The panel and the LT9611 also share their reset and interrupt GPIOs as literal single nets, not merely as reused pin numbers in different device trees. Every vendor source we found (LILYGO’s own abandoned merge attempt, their shipped launcher UI, and our own nix/sd-image.nix’s documented U-Boot behavior) selects HDMI vs. panel by which device tree blob boots, and switches by rebooting. Nobody — not LILYGO, not Canaan’s reference tree, not our own kernel — has ever switched the K230’s single DSI host between a panel and a bridge without a reboot. Our kernel’s bridge-attach path is additionally missing a connector creation call, so even the reboot-based switch does not work out of the box. True hot-plug-without-reboot, which is what the user asked for, is therefore a real, unproven engineering project, not a device-tree edit. Section 5 stages the work so the reboot-based switch (which mirrors a demonstrated vendor mechanism) ships first, and the no-reboot goal is pursued after it as explicitly higher-risk, possibly-infeasible follow-on work.

Sources used

• Xinyuan-LilyGO/T-Display-K230_canmv_rt @ abb07090ad8a666ed7a5e097b3c714b918731645 (fetched via gh api, 2026-09-28) — carries schematic/T-Display K230_V1.0_NEW.pdf (8 sheets, Altium-exported, pdfinfo-confirmed) and the full RT-Smart/U-Boot/CanMV SDK tree (canmv_k230/...) that docs/findings.md and docs/dts-evidence.md already cite as repo/.... No local checkout of this repo exists in this worktree; the earlier repo/ paths cited in docs/findings.md were a transient clone from a prior session and are gone. This document re-fetched the specific files it needed directly from GitHub rather than re-cloning ~750 MB.
• Xinyuan-LilyGO/T-Display-K230 @ bb831ab358b66f5bd9a87ecd7c580fee4537492e — carries the k230_bsp/ patch set against kendryte/k230_linux_sdk (same grounding tier established in docs/research/board-capability-inventory.md) and the k230_launcher/ LVGL source, including ui_hdmi_test.c, the actual shipped “switch to HDMI” UI.
• Our pinned kernel, ruyisdk/linux-xuantie-kernel @ 7d4e1f444f461dbe3833bd99a4640e7b6c2cd529, built locally at /nix/store/prjax8g4y7x40j641qipjk4cwp45fd72-linux-xuantie-k230-src via nix build .#nixosConfigurations.k230.config.boot.kernelPackages.kernel.src. Every “our tree has/lacks X” claim below was read from that exact checkout.
• Our own nix/sd-image.nix, nix/kernel.nix, nix/dts/k230-tdisplay.dts.

1. Hardware routing: how do the DSI lanes and clock reach both outputs?

No mux or switch chip exists on this board. The schematic shows plain parallel copper: the SoC’s four DSI data-lane pairs and clock pair are one set of nets, and both the panel connector and the LT9611 bridge are wired directly to that same set.

Evidence, from T-Display K230_V1.0_NEW.pdf (Altium export, 8 sheets, A4 and A3/A2 title blocks, drawn by LILYGO, dated 2026-06-26):

• Sheet “K230” (page 4 of the PDF), the SoC’s own MIPI block (U22C, labelled MIPI), left column: pins MIPI_TX0_CLK_P/N and MIPI_TX0_D0_P/N..MIPI_TX1_D3_P/N are wired to net labels DSI_CLK_P/DSI_CLK_N and DSI_D0_P/N..DSI_D3_P/N (pins Y9/W9, W10/Y10, Y11/W11, W8/Y8, Y7/W7). These are the SoC package pins for its one DSI host.
• Sheet “HDMI+ETH” (page 7), the LT9611 (U18), right-hand pin block: its second MIPI RX port (MLRXB_D0P/N..MLRXB_D3P/N, pins 49–58) is wired to net labels DSI_D0_P/N, DSI_D1_P/N, DSI_D2_P/N, DSI_D3_P/N, DSI_CLK_P/N — the identical net names from the MIPI sheet above. Its first MIPI RX port (MLRXA_*, pins 38–47) is drawn with only the chip’s own alternate pin-function silkscreen text (TX_C+/TX_D0+, etc.) and carries no wire or net label — unpopulated, not stuffed onto anything.
• This is a direct, unambiguous conclusion from Altium net-name matching: a wire segment on one sheet and a wire segment on another sheet with the same net label are the same electrical node. The SoC’s DSI TX pins, the panel connector, and the LT9611’s DSI RX pins all sit on that one set of nets. There is no resistor array, no analog switch (e.g. no TS3USB-style part, no FSA-family switch, no relay) anywhere between them — R74–R77 on the HDMI sheet are 10k pull-ups on the LT9611’s I2C/reset/interrupt lines, not lane-isolation components.
• The LT9611’s TMDS output side (TX_D0–TX_D2, TX_C, its transmit pins) goes through two TPD4E05U06 ESD arrays to the physical HDMI1 connector (page 7, right half), confirming the LT9611 is doing real DSI→TMDS protocol conversion (a genuine bridge IC), not passing signals through unmodified.

The panel connector only breaks out two of the four lanes. Sheet “Video” (page 4 in file order, titled “Video”), the 15-pin LCD/touch FPC connector lists pins DSI_CLK_N/DSI_CLK_P, DSI_D0_P/N, DSI_D1_P/N only — no D2/D3 pins on that connector. This matches our own device tree’s panel-dsi-lane = <2> (nix/dts/display-rm69a10-568x1232.dtsi:72) and confirms the RM69A10 runs 2-lane while the LT9611, wired to all four pairs, would run 4-lane. UNVERIFIED: whether D2/D3 being simultaneously driven by the host (if a future DT ran the DSI host in 4-lane mode for HDMI) while left floating/unterminated at the panel connector causes any signal-integrity concern for the panel’s own 2-lane reception; not measured, and the two lane counts are configured by two different, mutually exclusive device trees today (see §3), so they have never been electrically simultaneous in any observed boot.

GPIO23/24 are literal shared nets, not just reused GPIO numbers. Sheet “Video”, the net-label table directly above the 15-pin LCD/touch connector reads (transcribed from the rendered schematic):

I2C3_SCL  ->  HDMI_CSCL  ->  TP_SCL   (connector pin 3)
I2C3_SDA  ->  HDMI_CSDA  ->  TP_SDA   (connector pin 4)
HDMI_RSTN ->  TP_RST                  (connector pin 5)
HDMI_INT  ->  TP_INT                  (connector pin 1)

Each arrow is the same wire carrying two net-label annotations, not two separate nets tied by a jumper — this is one continuous, unbroken run connecting the LT9611’s RSTN pin (33) and CSCL/CSDA pins (34/35) on the HDMI sheet to the touch/LCD FPC connector’s TP_SCL/TP_SDA/TP_RST pins, and the LT9611’s INT_ATST_GPIO3 pin (12) to that connector’s TP_INT pin. This resolves the “not established” flag in docs/dts-evidence.md:157-159 and docs/findings.md:207-208: the schematic has now been read for this exact question, and the answer is yes, LT9611 reset/interrupt/I2C and touch reset/interrupt/I2C are the same physical nets. The panel’s own reset (LCD_RST, connector pin 11, GPIO22) is a separate, standalone net not tied to HDMI_RSTN — the LT9611 does not touch the panel’s own reset or enable lines, only touch’s.

This single-net sharing has a consequence beyond “pick one in the device tree”: vendor and our own device trees disagree about the electrical convention on that shared line. The vendor’s k230-canmv-v3.dts LT9611 node requests reset-gpios = <&gpio0_ports 24 GPIO_ACTIVE_HIGH> (k230-canmv-v3.dts:64, in our pinned kernel tree), while our board’s touch node requests reset-gpios = <&gpio0_ports 24 GPIO_ACTIVE_LOW> (nix/dts/k230-tdisplay.dts:200) on the same physical pin. Similarly the vendor LT9611 node asks for interrupts = <23 IRQ_TYPE_EDGE_FALLING> (k230-canmv-v3.dts:66) while our touch node asks for interrupts = <23 IRQ_TYPE_LEVEL_LOW> (nix/dts/k230-tdisplay.dts:224, deliberately changed from edge to level per that file’s own comment, because edge-triggered lost interrupts on this exact silicon). Two drivers wanting different trigger types and different active-sense on one wire is a real conflict, not a naming coincidence — reinforcing why no vendor source ever wires both nodes into one device tree at once (§3).

2. What GPIO23/24 do, and what else is nearby

• GPIO24: touch reset (our DT, active-low) and LT9611 reset (vendor DT, active-high) — the same physical net, different requested polarity. Plain GPIO output in both roles.
• GPIO23: touch interrupt (our DT, level-low) and LT9611 host interrupt (vendor DT, edge-falling) — same physical net, different requested trigger type. Plain GPIO input in both roles.
• GPIO22/GPIO25: panel-only (reset / backlight-enable). Not touched by the LT9611 net set. No conflict.
• I2C3 (GPIO36/GPIO37, SCL/SDA): shared bus, not a shared net in the problematic sense — I2C buses are designed for multiple devices. Touch is 0x5d, LT9611 is 0x3b; no address collision (docs/dts-evidence.md:151-155, confirmed again here from the schematic).
• HDMI hot-plug sense: the physical HDMI receptacle’s HOTPLUG pin (connector pin 19, sheet “HDMI+ETH”) is wired only to the LT9611’s own HPD_GPIO2 input (pin 13) — there is no independent HPD-sense line run to a spare K230 GPIO. The K230 can only learn a cable was plugged in by asking the LT9611 (over I2C, or via its INT_ATST_GPIO3 output on the GPIO23 net), which means the LT9611 must already be a live, un-reset, I2C-probed device for HDMI plug detection to work at all. This is the central hardware constraint on any no-reboot design (§5).
• No other GPIO used by an already-populated peripheral (LoRa: GPIO5, 14–20, 44; camera: GPIO21, 48/49; SD: GPIO54–59; Wi-Fi: GPIO45) overlaps GPIO23/24 or the DSI lanes.

3. How LILYGO’s own firmware enables HDMI

It is a boot-time device-tree choice with a full reboot, not a runtime switch — and LILYGO’s own engineering history shows they tried a merged device tree first and abandoned it.

Evidence, Xinyuan-LilyGO/T-Display-K230, k230_bsp/overlay/buildroot-overlay/linux/:

• Patch 0055-riscv-dts-add-rm69a10-hdmi-output-dtb.patch adds a new, separate k230-canmv-rm69a10-hdmi.dts, built as its own .dtb (dtb-$(CONFIG_ARCH_CANAAN) += k230-canmv-rm69a10-hdmi.dtb, a new line in the DTS Makefile, not a modification of the panel DTS). It puts the LT9611 bridge on &dsi’s single port@1 (reset-gpios = <&gpio0_ports 24 GPIO_ACTIVE_HIGH>, matching the shared net found in §1) and carries no touch node and no RM69A10 panel node at all.
• Patch 0062-riscv-dts-rm69a10-hdmi-use-sdk-v3-baseline.patch then #if 0s that entire custom file and replaces it with a bare #include "k230-canmv-v3.dts" — the generic Canaan reference-board tree, unrelated to this board’s panel or touch silicon, whose own comment explains why: “The board-specific HDMI attempt above is kept for reference but is not used. The SDK CanMV v3 HDMI DTB was verified on T-Display K230: LT9611 probes, EDID is read, and HDMI-A-1 exposes 800x480@60. Reuse that known-good HDMI graph until a reduced board-specific DTS is proven.” LILYGO’s own working, verified HDMI mode is therefore the unmodified upstream reference-board DTB, output at 800x480@60 (not 720p), with no panel and no touch node present in that boot image at all — the two silicon paths were never merged into one working device tree by LILYGO either.
• The actual switch mechanism, k230_launcher/k230_phone_ui/src/ui_hdmi_test.c (490 lines), is a double-tap-confirm, reboot-based, self-reverting boot-DTB swap:
  • HDMI_ACTIVE_DTB "/boot/k.dtb" is the file U-Boot actually loads. HDMI_PANEL_DTB and HDMI_OUTPUT_DTB are the two alternatives.
  • Tapping the HDMI button once arms a confirmation ("Tap again to confirm HDMI reboot", 8-second window, ui_hdmi_test.c:384-389); a second tap within that window calls hdmi_start_boot_switch().
  • hdmi_boot_switch_thread() (ui_hdmi_test.c:312-343) runs: remount /boot read-write, write a one-shot restore marker (/boot/k230_hdmi_next_boot_only, containing restore=<panel DTB path>), cp the HDMI DTB over the active k.dtb, sync, reboot.
  • ui_hdmi_test_restore_one_shot_boot() (ui_hdmi_test.c:279-300) runs early on every subsequent boot: if the marker file exists, it immediately copies the panel DTB back over k.dtb, deletes the marker, and syncs — so HDMI mode is automatically good for exactly one boot. Power-cycle again (for any reason, not just to leave HDMI mode) and the board silently reverts to the AMOLED panel. There is no path in this source that switches without a reboot call.
  • The same file also polls /sys/class/drm at runtime (read-only, hdmi_find_connector(), ui_hdmi_test.c:147-172) for entries matching "HDMI" / "DSI" and shows live connected/mode status plus a “next boot: HDMI boot / AMOLED boot / AMOLED restore pending” line — confirming the vendor’s own kernel enumerates connectors as *-HDMI-* / *-DSI-*, consistent with standard DRM connector naming and with the HDMI-A-1/DSI-1 names used in this document.
• Init sequence / timings: not separately re-derived here since LILYGO’s working HDMI path uses the unmodified upstream k230-canmv-v3.dts and the mainline lontium-lt9611.c driver’s own internal register sequences (drivers/gpu/drm/bridge/lontium-lt9611.c, §4) — there is no board-specific LT9611 init sequence to transcribe, unlike the panel.

Our own vendored U-Boot already has an equivalent selection mechanism, independently confirmed from our own committed, hardware-tested source comments in nix/sd-image.nix:142-156: U-Boot’s bootcmd runs a k230_set_dtb command that reads a text file naming a DTB — trying force_dtb first (short-circuits selection), then falling back to hdmi_dtb, then lcd_dtb twice, observed on hardware to fail all three and drop to a U-Boot prompt if none of the three files exist. Our SD image writes all three names pointing at the same panel DTB today, to keep first boot simple. UNVERIFIED: whether U-Boot’s hdmi_dtb/lcd_dtb fallback path performs its own live display-presence probe (i.e., a stage-1 auto-detect independent of LILYGO’s userspace toggle) or is purely an operator-set preference file read at boot with no hardware probing; the U-Boot C source for k230_set_dtb was not read for this document (it ships as a prebuilt blob per nix/uboot-k230.nix, not as buildable source we have checked out). This is worth resolving before design work in §5, since if U-Boot itself already probes for a live cable, that is a much cheaper place to do boot-time selection than anything in Linux.

4. Our kernel

• CONFIG_DRM_LONTIUM_LT9611=y is set in the pinned kernel’s own arch/riscv/configs/k230_defconfig:286, and nix/kernel.nix (defconfig = "k230_defconfig", structuredExtraConfig starting line 610) does not touch that symbol — so it inherits y and the mainline drivers/gpu/drm/bridge/lontium-lt9611.c driver is already built into every kernel we produce today. It is simply unused: no device tree we ship references an LT9611 node.
• The DSI host is architecturally single-output, resolved once at boot, not switchable at runtime. drivers/gpu/drm/canaan/canaan_dsi.c’s canaan_dsi_bind() (line 695) calls drm_of_find_panel_or_bridge(dsi->dev->of_node, 1, -1, &dsi->panel, &dsi->bridge) — a single lookup of &dsi’s port@1, executed exactly once, during component-master bind at driver probe (module load / boot time). Whichever single endpoint is described under port@1 in the loaded DTB (the RM69A10 panel node in our DT, or the LT9611 bridge node in the vendor DT — never both; a DT graph port has one endpoint) becomes dsi->panel XOR dsi->bridge for the life of that boot. There is no code path anywhere in canaan_dsi.c that re-invokes this lookup, and canaan_dsi_detach() (line 560) only clears these fields when the child mipi_dsi_device itself unregisters (its own probe/remove), not as a general “swap to a different device” API. A true runtime swap between panel and bridge does not exist in this driver as written, which matches every vendor source found in §3: nobody switches without a reboot because the driver genuinely cannot.
• The bridge path is currently missing its connector. In canaan_dsi_bind(), the panel branch (if (dsi->panel), lines 699-711) creates a drm_connector (DRM_MODE_CONNECTOR_DSI) and attaches it to the encoder. The bridge branch (if (dsi->bridge), lines 713-714) only calls drm_bridge_attach(&dsi->encoder, dsi->bridge, NULL, DRM_BRIDGE_ATTACH_NO_CONNECTOR) — and DRM_BRIDGE_ATTACH_NO_CONNECTOR means the caller promises to create the connector itself, elsewhere. Neither canaan_dsi.c nor canaan_drv.c (grepped for drm_bridge_connector, zero hits in drivers/gpu/drm/canaan/canaan_drv.c and canaan_dsi.c) ever calls drm_bridge_connector_init(). As our kernel stands today, wiring an LT9611 node into a board DTB would attach the bridge to the encoder but create no DRM connector at all — no HDMI-A-1 would ever appear to modetest, Sway, or anything else. This is a small, well-understood kernel patch (add drm_bridge_connector_init(dsi->drm, &dsi->encoder) + drm_connector_attach_encoder() in the bridge branch), but it is a real gap, not merely a missing DT node, and is a prerequisite for any HDMI output under our kernel, reboot-based or not. Task 2.1 of openspec/changes/plugging-in-hdmi-moves-the-display implements exactly this call as nix/patches/canaan-dsi-bridge-connector.patch, applied unconditionally in nix/kernel.nix; it is inert on the panel boot path because it only runs when dsi->bridge is non-NULL.
• The vendor k230-canmv-v3.dts LT9611 port numbering does not satisfy this kernel’s own lontium-lt9611.c as written. That file’s node (§1, §3) wires the LT9611’s DSI-input endpoint at port@1 (reg = <1>) and its downstream-connector endpoint at port@2, with no port@0 at all. But lt9611_parse_dt() (lontium-lt9611.c:906-919, this same pinned tree) reads the primary DSI node from port 0 (of_graph_get_remote_node(dev->of_node, 0, -1), fatal to probe if absent — "failed to get remote node for primary dsi"), an optional dual-link DSI node from port 1, and the downstream bridge/connector from port 2. of_graph_get_remote_node() matches a port node’s reg property, not its position in the file (drivers/of/property.c:837-855), so a node with only reg=1/reg=2 has no reg=0 port and lt9611_probe() would fail lt9611_parse_dt() before ever touching hardware. Whether Canaan’s or LILYGO’s own kernel fork’s lontium-lt9611.c tolerates the vendor file’s own 1/2 numbering was not checked — that is a different source tree, not read for this document. What is established is that this pinned tree’s driver needs port@0/port@2, and task 2.2’s nix/dts/k230-tdisplay-hdmi.dts is written against that reading rather than copied from k230-canmv-v3.dts’s numbers. This is unverified on hardware either way — it changes the DTB compile-time facts only; the probe that would confirm or refute it is tasks.md group 3/4’s board time.
• DSI lane rate is not a blocker. canaan_dsi_clk_cfg() (canaan_dsi.c:330-405) derives the pixel clock as an integer division of a fixed 594 MHz reference (div = DIV64_U64_ROUND_CLOSEST(594000, clk)), and canaan_dsi_encoder_mode_fixup() (line 497) snaps any requested mode clock onto that same 594/n grid. The panel’s 49.5 MHz is exactly 594/12; 720p60’s 74.25 MHz is exactly 594/8; 1080p60’s 148.5 MHz is exactly 594/4 — all three land precisely on-grid, so no new clock-generation code is needed. The PHY bit-rate bound checked in the same function (phy_clk_freq must be 40,000–1,250,000 kbps) comfortably covers 4-lane 1080p60 RGB888 (≈891 Mbps/lane) and 720p60 (≈445.5 Mbps/lane); the panel runs 2-lane at 594 Mbps aggregate today (docs/evidence/dsi-hsfreqrange-hardcoded.md records 594 Mbps measured). Lane count does change (2 for the panel connector, 4 for the LT9611, per §1) and is a mipi_dsi_device->lanes / DT property difference between the two mutually-exclusive board files, not a runtime-negotiated value.
• The LT9611 HPD interrupt is fully implemented in the mainline driver but shares hardware with touch. lt9611_irq_thread_handler() (drivers/gpu/drm/bridge/lontium-lt9611.c:413-450) reads the chip’s own status registers (0x820f, 0x820c), distinguishes HPD-low/HPD-high internally, and the bridge implements .detect, .hpd_enable (lt9611_bridge_funcs, lines 888-903) — standard drm_bridge hotplug machinery. canaan_drv.c:265 already calls drm_kms_helper_poll_init(), so a correctly-connectored LT9611 bridge would propagate a real hotplug uevent to userspace. But the physical interrupt line the mainline driver expects (client->irq, from the i2c node’s interrupts property) is the GPIO23 net shared with touch (§1/§2) — using it live, concurrently with touch, requires IRQF_SHARED-compatible handling on both drivers’ request calls and, UNVERIFIED, depends on whether the LT9611’s INT_ATST_GPIO3 output and the GT9895’s own interrupt output are both genuinely open-drain (safe to wire-OR) rather than push-pull (which would contend electrically) — not established from the schematic (drive type isn’t shown on a schematic net) and not measured on hardware.

5. Designing a hot-swap

Given §3 and §4, split the goal into what is demonstrated to work (reboot-based switching, once our kernel gets the missing connector patch) and what is not demonstrated anywhere (no-reboot switching while Linux keeps running). The OpenSpec proposal (openspec/changes/plugging-in-hdmi-moves-the-display/) stages exactly this split; summarized here:

1. Read-only board probe (board-gated, narrow, no writes): confirm the 0x3b I2C identity actually answers on &i2c3 with touch present and read the LT9611’s HPD status register through it, and read GPIO23/24’s current direction/level with touch running, without changing anything. This is the answer to “what is the first board probe command” below.
2. Driver/DT build (host-build-proof only, no board changes): add the missing drm_bridge_connector_init() call to canaan_dsi.c, and build (not boot) a second, HDMI-only DTB derived from k230-tdisplay.dts’s own &dsi graph (our own board’s I2C/GPIO facts, not the vendor’s generic tree) so the resulting HDMI-A-1 connector is genuinely this board’s LT9611, not a copy of the unrelated Canaan reference tree. Verified by nix build, not by booting.
3. Manual switch, reboot-based (board-gated): the credible near-term deliverable. Mirrors LILYGO’s own proven, self-reverting one-shot mechanism (§3) using our own nix/sd-image.nix/nix/device-tree.nix machinery: write an alternate /boot/k230-tdisplay-hdmi.dtb, flip U-Boot’s DTB-selector text file, reboot; a one-shot marker restores the panel DTB on the next boot regardless of why it happened, so a bad probe or an unrelated crash always self-heals back to the panel. This satisfies the AGENTS.md/task risk requirement directly: recovery is a plain reboot, and it defaults to the panel.
4. Hotplug automation, no reboot (board-gated, explicitly high risk): attempt the design the user actually asked for. The concrete blockers, all found above, that make this uncertain rather than merely large:
   • The LT9611 can only be found by the K230 (§2) if it is already a live, un-reset, I2C-probed device — which means it must be present in the running boot’s device tree even while the panel is the active display, contradicting §4’s one-endpoint-per-port finding. A DT where the LT9611 exists as a plain I2C client (for HPD/status polling) without being the &dsi port@1 endpoint might let it probe and raise its shared-GPIO23 interrupt without contending for the DSI graph — untested, and depends on the open-drain question in §4.
   • GPIO24 (reset) is a single net with two disagreeing polarity conventions (§1). A no-reboot design cannot reset one chip without also resetting the other; the only safe pattern is to never re-toggle GPIO24 after both chips’ initial power-on reset, and confirm — UNVERIFIED, not measured — that neither driver retoggles it during normal atomic_enable/mode-change operation.
   • Actually repainting the DSI host from panel to bridge live requires new canaan_dsi.c logic (tear down the panel connector/encoder state, bring up a bridge connector/encoder, without the one-shot drm_of_find_panel_or_bridge() this driver currently relies on) — real, unbounded-until-attempted kernel work, not present in any source surveyed.
   • Sway/card-shell must additionally handle the resulting output-topology change (DSI-1 disappearing, HDMI-A-1 appearing at a different resolution and orientation) — see the landscape audit below, and note it is Large on its own. Given this, task the OpenSpec proposal to attempt automation but mark it explicitly speculative, separate from the reboot-based switch, so the reboot-based switch is not held hostage to an unproven no-reboot design.
5. Manual override in Settings: a Settings row that triggers the reboot-based switch (stage 3) directly, independent of whether stage 4 ever lands — cheap, and gives the user a working “go to HDMI” control immediately even if true hot-plug automation stalls.

What in the shell and card-shell assumes a fixed 568×1232 portrait panel

Grep for 568/1232 and output names across nix/shell.nix and nix/rust-shell-client/src/*.rs (the “shell” capability) and nix/card-shell/, nix/card-shell-policy/ (the “card-shell” capability):

• nix/shell.nix:679: Sway config hardcodes output DSI-1 mode 568x1232 transform normal scale 1 render_bit_depth 6 max_render_time 8, and :680 hardcodes input type:touch map_to_output DSI-1. Nothing here recognizes or positions an HDMI-A-1 output; a second connector today gets whatever Sway’s own default heuristic does with it, unconfigured.
• nix/rust-shell-client/src/lib.rs:82: const DESIGN_ASPECT: f64 = 568.0 / 1232.0; — a single compiled-in portrait aspect ratio checked throughout rendering and hit-testing (configure_preserves_aspect, frame_bytes, etc., lib.rs:222-282).
• 476 lines across nix/rust-shell-client/src/*.rs contain a literal 568 or 1232 (grep -rn "568\|1232" nix/rust-shell-client/src/*.rs | wc -l; 380 of those lines are outside anything matching #[test], assert_eq, assert! or fn test_, i.e. not test-only). Heaviest concentrations: render.rs (167 hits, the largest file), navigation.rs (66, including tile-grid math like navigation.rs:10’s 2*24 + 3*24 + 4*112 = 568), main.rs (61), home_grid.rs (55), service_ui.rs (52). Representative non-test examples: render.rs:1098 (cr.scale(width / 568.0, height / 1232.0)), wifi_ui.rs:400-401 (touch-point rescaling hardcoded to 568/1232 rather than derived from the actual output geometry).
• nix/card-shell-policy/card-shell-policy.c:58 independently notes the card shape as “(568:1232), i.e. a phone-shaped card” in a comment — confirming the card-shell’s own policy layer also assumes this aspect ratio, though it has no other numeric 568/1232 occurrences (grepped, one hit total).
• No occurrence of landscape as a real code path was found; the shell has never run at a non-portrait aspect ratio.

This is a Large item on its own (476 raw literal-constant hits, 380 of them outside test code), separate from and larger than the DSI/DT work above. It needs, at minimum: deriving the design-space transform from the actual output’s reported geometry instead of the 568.0/1232.0 literals in lib.rs/render.rs/wifi_ui.rs; a landscape layout for the grid/navigation/service-UI screens (navigation.rs, home_grid.rs, service_ui.rs) rather than a naive stretch of the portrait design; and a Sway output/input stanza for HDMI-A-1 alongside the existing DSI-1 one in nix/shell.nix. None of this can be host-verified beyond compiling and unit-testing the now-parameterized math; the actual on-monitor layout needs a board with an HDMI display attached.

6. Risk and recovery

A wrong mux/modeset gives a black panel or a black HDMI output. Because there is no mux (§1), “wrong mux” in practice means “wrong DTB” or “wrong GPIO polarity on the shared reset net” — both are boot-time, not runtime-silent, failure modes once stage 3 exists. Recovery is a reboot, and it must default to the panel:

• The U-Boot DTB-selector text files (force_dtb, lcd_dtb, hdmi_dtb, nix/sd-image.nix:154-156) must keep pointing at the panel DTB by default on every fresh image build; only an explicit, one-shot runtime action (mirroring LILYGO’s HDMI_ONE_SHOT_MARKER restore-on-next-boot pattern, §3) may switch them, and that action must itself write the restore marker before rebooting, so any subsequent reboot — deliberate or a crash — lands back on the panel automatically. This is the same property LILYGO already ships and is directly reusable.
• Nothing about this design touches stage 1 binaries, U-Boot SPL, or the boot partition’s fixed files (Image, fw_jump_add_uboot_head.bin, boot/bootargs.txt) — only which named .dtb file the existing, already-hardware-proven selector mechanism points at. A failed HDMI probe or a bad DTB build therefore cannot break the existing boot path; at worst it leaves the board on the panel DTB, unchanged from today.

Answers to the report questions

• Mux or not: not a mux. Bare parallel wiring of all four DSI lanes and the clock (schematic-confirmed, §1); the panel and LT9611 additionally share their reset and interrupt GPIOs as one literal net each, with disagreeing polarity/trigger-type conventions between the vendor’s LT9611 node and our own touch node.
• Runtime hot-swap feasibility: not demonstrated anywhere (LILYGO, Canaan’s reference tree, or our own kernel), and our DSI host driver’s architecture (one-shot drm_of_find_panel_or_bridge() at boot, canaan_dsi.c:695) does not support it as written. A reboot-based switch is feasible and has a working precedent to copy (§3, §5 stage 3). True no-reboot hot-plug is unproven, high-risk new kernel work (§5 stage 4).
• Effort per stage: probe = S (board time, no writes); driver/DT build = M (one kernel patch + one alternate DTB, host-verified only); manual reboot-based switch = M (mirrors a proven mechanism, board-gated); no-reboot hotplug automation = L, high risk, possibly infeasible without further kernel rearchitecture; shell/card-shell landscape support = L (476 literal-constant call sites).
• First board probe command: read-only, on the reserved board/serial port, with touch running and untouched — i2cdetect -y $(cat /sys/class/i2c-adapter/*/name | grep -l i2c3 2>/dev/null; echo 3) to confirm something answers at 0x3b alongside touch’s 0x5d, then i2cget -y 3 0x3b 0x00 (chip-ID/status register read only, no write) to attempt to read back an LT9611 identity byte without touching GPIO23/24 or any reset state. Exact adapter number for &i2c3 on this board should be confirmed from /sys/class/i2c-adapter/*/name at probe time rather than assumed, since Linux adapter numbering is not guaranteed to match the DT alias.