From a252735992bb37d557fa2366292e316453c4bfce Mon Sep 17 00:00:00 2001 From: vhaudiquet Date: Sun, 30 Aug 2026 18:43:09 +0200 Subject: [PATCH] Handoff doc: keyboard (USB HID) bring-up --- HANDOFF-KEYBOARD.md | 130 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 HANDOFF-KEYBOARD.md diff --git a/HANDOFF-KEYBOARD.md b/HANDOFF-KEYBOARD.md new file mode 100644 index 0000000..eb819fa --- /dev/null +++ b/HANDOFF-KEYBOARD.md @@ -0,0 +1,130 @@ +# HANDOFF: U-Boot keyboard bring-up on Lenovo IdeaPad Duet (google,krane, MT8183) + +You are taking over a working U-Boot bring-up. **The banner and prompt already +work on the panel.** Your job: make the keyboard work at the U-Boot prompt. + +## Environment + +- U-Boot tree: `/home/vhaudiquet/u-boot`, branch `krane` (mainline main @ + 527115ef + board commits + temporary diagnostics). Build: + `cd /home/vhaudiquet/u-boot && export CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm + && make mt8183_kukui_krane_defconfig && make -j8` + **After editing the defconfig you MUST re-run `make + mt8183_kukui_krane_defconfig`** — gc-sections otherwise silently drops code. +- Payload/build/flash script: `/home/vhaudiquet/krane-fb-stub/build-uboot-payload.sh` + (assembles wrapper + u-boot.bin, packs with mkdepthcharge via + `PYTHONPATH=/root/krane-fb-stub/src/depthcharge-tools`, asserts link `_start == + 0x4C001000` from u-boot.sym, writes `krane-uboot-payload.bin`). +- Flash + verify: `dd if=krane-uboot-payload.bin of=/dev/mmcblk0p1 bs=4M + conv=fsync`, then `cmp -n krane-uboot-payload.bin /dev/mmcblk0p1`, then + `futility vbutil_kernel --verify /dev/mmcblk0p1` (must print "Body + verification succeeded"). The kernel partition is `mmcblk0p1` (pmOS installed, + chroot lives on `mmcblk0p3`; USB stick on sda). +- Lab notebook: `/home/vhaudiquet/krane-fb-stub/RESEARCH.md` — READ IT, especially + Rounds 19–32. Every verified step gets a round entry + a commit in BOTH repos + (u-boot branch `krane`, stub repo). +- The user tests on the real device: you flash, they reboot, select "Internal + storage" in the depthcharge dev menu, and report what appears on screen. Write + short observation→meaning decision trees for them. Devkeys only; the SPI + firmware is never modified. +- Backup of the original kernel partition: `/home/vhaudiquet/mmcblk0p1-pmos-backup.img` + (sha256 20951a54…), also on the USB stick (sda3). + +## Current working state (payload `34b9660f…` lineage) + +- depthcharge (device-era, `.12573.351.0`) loads the payload to 0x40000000 and + jumps to +0x40; our wrapper (`/home/vhaudiquet/krane-fb-stub/uboot-wrapper.S`) + revives the display (OVL_EN@0x14008000+0xc, OVL0_2L_EN@+0x100c, backlight + GPIOs 43/176 via 0x10005114/0x10005154) and jumps to U-Boot `_start` at + 0x40001000. Do NOT break the placement: `CONFIG_TEXT_BASE=0x4C001000` + (8-aligned — a 4-byte linker fill shifts `_start` and corrupts the PIE fixup), + U-Boot file at image offset 0x1000 so runtime `_start = 0x40001000`. +- Display: `drivers/video/mt8183_scanout.c` (UCLASS_VIDEO on the upstream + `ovl0@14008000` node) revives the depthcharge scanout (fb 0xFD536000, + 1200×1920×32bpp, bpl 4800, addr from the coreboot table at 0xffed9000 with + OVL_L0_ADDR fallback) and the standard vidconsole renders the banner. +- Console: `ENV_IS_NOWHERE` + `board/mediatek/mt8183/krane.env` + (`stdin=serial`, `stdout=serial,vidconsole`, `stderr=serial,vidconsole`). + The video device is probed only through the iomux lazy path — keep that + env intact. +- `get_page_table_size()` is overridden in `board/mediatek/mt8183/mt8183.c` + (0x40000): the driver maps the coreboot table and fb dynamically + post-relocation; the default budget panics ("Insufficient RAM for page table"). + Any new dynamic `mmu_map_region` calls rely on this headroom. + +## The problem + +The prompt is dead to keyboard input. Krane is the IdeaPad **Duet** — a tablet; +its keyboard is the **detachable pogo-pin keyboard, which is a USB HID device** +(it enumerates as USB). So the work is USB bring-up + USB keyboard, not i2c: + +- The krane defconfig (`configs/mt8183_kukui_krane_defconfig`) was forked from + mt8183_pumpkin **minus USB/fastboot/PHY** — `CONFIG_USB*`, `CONFIG_PHY_MTK_*` + are all absent. Re-add the USB stack: + `CONFIG_DM_USB`, `CONFIG_USB=y`, `CONFIG_USB_XHCI_HCD=y` (MT8183 has a + MediaTek xHCI, node `ssusb@11201000` in the upstream DT), the MTK T-PHY + (`CONFIG_PHY_MTK_TPHY`, node `usb-phy@11e10000`/`u3phy`), `CONFIG_USB_KEYBOARD=y` + and whatever DM_REGULATOR/power nodes the DT needs for VBUS. +- Upstream device tree: `dts/upstream/src/arm64/mediatek/mt8183-kukui*.dtsi` + (do NOT fork the DTs; `CONFIG_OF_UPSTREAM=y` and the include-order fix in + `scripts/Makefile.lib` from earlier rounds is already in place). Check which + USB nodes/phy/regulators the kukui DT provides and whether the U-Boot drivers + bind them (`bootph-all` flags may be needed for pre-reloc, but the keyboard is + post-reloc so plain nodes usually suffice). +- The MTK xHCI glue in mainline U-Boot: check `drivers/usb/host/xhci-mtk.c` + (mt7622-era) vs plain `xhci` with `phys`. The Duet's keyboard port may be the + dedicated pogo USB port — check the kukui DT for which controller/port the + keyboard uses, and whether VBUS is switched by a PMIC regulator + (mt6358, `CONFIG_DM_REGULATOR`). +- After USB works: add `usbkbd` to `stdin` in `board/mediatek/mt8183/krane.env` + (`stdin=serial,usbkbd`) — USB devices are only probed when the USB stack + runs; check how `usb_kbd` gets probed pre-prompt (`CONFIG_USB_KEYBOARD` + + `usb_kbd_register`, `initr_usb`, or `usb start` in BOOTCOMMAND — with + `CONFIG_BOOTDELAY=-1` there is no autoboot window, so USB init must happen + in an initcall (`initr_usb`) or you must set a small bootdelay/usb start). +- Do NOT disturb the display path; `CONFIG_USB_KEYBOARD` pulls in font/console + bits that are already fine. + +## Debugging aids already in the tree (TEMPORARY, to revert before upstreaming) + +- `CONFIG_PANIC_HANG=y`: any synchronous abort freezes the screen with a dump — + and `do_sync` in `arch/arm/lib/interrupts_64.c` draws + `ABORT! ESR=0x… ELR=0x… FAR=0x…` on the panel (via the fb text logger in + `drivers/video/mt8183_scanout.c`). If the device instead RESETS to the + depthcharge menu in <1 s, that's a panic without the hang — check + `CONFIG_PANIC_HANG` is still set. +- `krane_fb_log()` in `drivers/video/mt8183_scanout.c` — minimal 8×16-font + framebuffer text logger (white text, bottom rows y≥1700, static cursor). + Reuse it freely for USB bring-up logs (e.g. "XHCI-PROBE", "PORT-OK", + "KB-ENUM") — it works before the console exists. +- Colored band checkpoints: `krane_diag_band()` (same file), + video-uclass.c/board_f.c/main.c/mt8183.c have band calls. All marked + TEMPORARY. +- There is no working serial on the device (baud 921600 debug UART exists in + config but the user cannot see it) — the panel logger is your only output + channel. Keep log lines short (the logger wraps at 1200 px / 150 chars). + +## Constraints + +- Everything upstreamable: checkpatch-clean, DM/uclass APIs, Kconfig/Makefile + style of neighbours, small single-purpose commits, MAINTAINERS entries. + Board-specific workarounds in board code, magic registers documented with + sources. Do not fork upstream DTs. +- Never break the working display/prompt path; the payload layout constants are + load-bearing (see above). +- Record every verified step as a RESEARCH.md round + commits in both repos; + before flashing, always dd + cmp + vbutil verify. + +## Suggested first steps + +1. Read RESEARCH.md (esp. Rounds 30–32) and `git log` both repos. +2. Dump the upstream kukui DT USB nodes (`ssusb`, `u3phy`, regulators) and + mainline's mt8183-compatible xhci/tphy drivers; decide glue vs plain xhci. +3. Add the USB/PHY/keyboard Kconfigs + any `bootph` flags; re-run defconfig; + build; log probe stages with `krane_fb_log` (XHCI probe, PHY init, port + status, device enumeration, HID attach). +4. If enumeration works but no keys: check `stdin` env, `usb_kbd` stdio + registration, and that the console's `stdio_devices[stdin]` includes it + (`coninfo` would tell you — you can print it to the panel via the logger). +5. Deliver: a fix commit + a RESEARCH.md round; leave the diagnostics in place + unless they break something.