Handoff doc: keyboard (USB HID) bring-up

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 <size> 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.