krane-fb-stub/HANDOFF-KEYBOARD.md

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