krane-fb-stub/u-boot-krane-prompt.md

Task: bring up mainline U-Boot on the Lenovo IdeaPad Duet (google,krane sku176, MT8183)

You are taking over a bring-up that just passed its first milestone: a minimal bare-metal payload ("krane-fb-stub") boots via depthcharge and draws to the panel. Your job is to replace it with mainline U-Boot as the payload, with a working framebuffer console, in a form that is upstreamable to mainline U-Boot later.

Hard requirement: upstreamable work

All changes must be written so they can be sent to the U-Boot mailing list with minimal rework:

• Follow U-Boot conventions: scripts/checkpatch.pl clean, Kconfig/Makefile style of neighbouring drivers, DM/uclass APIs (vidconsole, VIDEO, MMC, serial), proper bind()/probe() structure.
• Board support as a proper target: board/mediatek/, configs/*_defconfig, MAINTAINERS entry, defconfig minimal and matching pumpkin's style.
• Any DT additions must match the upstream Linux DTS files (the krane DTs are already synced from Linux into dts/upstream/src/arm64/mediatek/ — reuse them, do not fork them).
• Keep board-specific workarounds in board code, never inside common drivers; document every magic register with its source (see the device facts below).
• Small, reviewable, single-purpose commits.

Current state and where things live

• U-Boot shallow clone: /home/vhaudiquet/u-boot (mainline main, ~2026-08). SoC support exists: arch/arm/mach-mediatek/mt8183/. Reference target: configs/mt8183_pumpkin_defconfig (CONFIG_POSITION_INDEPENDENT=y, MTK serial, mtk-sd MMC, WDT, USB). dts/upstream/src/arm64/mediatek/mt8183-kukui-krane-sku176.dts exists; there is NO krane/kukui defconfig or board dir yet — that is your starting point.
• Validated stub project (read it first): /home/vhaudiquet/krane-fb-stub/ — contains main.c (the working payload: display revival + parse + fills), build.sh, build-payload.sh (packing via depthcharge-tools mkdepthcharge + vbutil devkeys), the stub's ARM64 Image-header wrapper stub.S, and RESEARCH.md — the full lab notebook of the display bring-up. READ RESEARCH.md before touching anything; it documents every [REVERSED] claim.
• The stub's working payload is currently flashed to mmcblk0p1; keep it as the regression test. Its payload hash and the exact flash/verify procedure are in RESEARCH.md.

Environment

• The target device is this machine. It boots postmarketOS from USB (sda); you work inside a chroot into the internal rootfs (/dev/mmcblk0p3 mounted at /). The boot firmware (coreboot + depthcharge) lives in SPI and is NEVER modified.
• mmcblk0p1 (32 MiB, ChromeOS kernel partition) is the only thing you flash. Tools available: aarch64-linux-gnu-gcc, futility vbutil_kernel, depthcharge-tools (mkdepthcharge), dtc.
• Flash procedure (same as the stub): dd if=payload of=/dev/mmcblk0p1 bs=4M conv=fsync, then cmp -n <size> against the payload, then futility vbutil_kernel --verify /dev/mmcblk0p1. After flashing, hand the device to the user to reboot into internal — the user reports what the screen shows. Never flash anything else. Recovery exists: USB boot
  • ~/mmcblk0p1-pmos-backup.img (see RESEARCH.md).
• There is NO serial console. The framebuffer is the only output channel; the user photographs/describes the screen.

Boot contract (verified on device, RESEARCH.md Round 10)

depthcharge (R93-era, in SPI) boots the dev-signed FIT from mmcblk0p1, decompresses the kernel subimage to an arbitrary 2 MiB-aligned DRAM slot, checks the ARM64 Image header magic (0x644d5241), and jumps to the first byte with x0 = FDT pointer, x1-x3 = 0, MMU off. U-Boot's u-boot.bin has no Image header — wrap it: 64-byte header (branch past header, text_offset=0, image_size patched at 0x10 LE, flags bit 3, magic at 0x38) exactly like krane-fb-stub/stub.S, then pack with mkdepthcharge.

Device facts for the display (all verified — do not re-derive)

• Panel: BOE TV101WUM_NL6, 1200×1920, 32bpp xRGB (r@16/8 g@8/8 b@0/8), 4-lane DSI, xres*bpl-style geometry comes from the coreboot LBIO record (1200×1920, bpl 4800, bpp 32).
• coreboot initializes the panel and DSI before depthcharge; at payload handoff the display pipeline is live but STOPPED: depthcharge's display_cleanup() disabled the overlay engines and killed the backlight. The panel/DSI link stays up — no panel re-init is needed.
• Revive = three MMIO/GPIO writes (offsets verified against device-era depthcharge sources; the two Round-1 misreads cost nine rounds — trust these):
  • OVL_EN = 1 at OVL0 base + 0x000C (OVL0 base 0x14008000)
  • OVL0_2L_EN = 1 at OVL0 base + 0x100C
  • backlight GPIOs high: GPIO controller 0x10005000, dout block at +0x100 (NOT 0x140), 16 B per 32-pin group, set@+4: pin 43 (DISP_PWM) → 0x10005114, pin 176 (EN_LCD_BL) → 0x10005154.
• Scanout address: read OVL_L0_ADDR at OVL0 base + 0x0F40. The coreboot LBIO record (fixed address 0xffed9000, size 0x380, verified live via sysfs + /sys/firmware/fdt) may report physical_address = 0; upstream coreboot 4.14 kukui does that, and libpayload's cbgfx rejects pa=0. The live scanout on this unit was 0xFD536000 (top-of-DRAM reserved). Strategy: geometry from the LBIO record, address from the record if non-zero else from OVL_L0_ADDR (guard: >= 0x40000000).
• The LBIO table parse reference implementation is krane-fb-stub/main.c (find_framebuffer); its layout comments are verified.
• Panel geometry facts also matter for the console: portrait 1200 wide; pick a font/rotation accordingly.

Known trap (open bug — carry it, don't trip on it)

depthcharge hands off x0 = _fit_fdt_start = 0x5F800000 (its internal FDT buffer; the kernel reserves 5f800000-5f815fff for it), but at payload entry that buffer reads as ALL ZEROS. The kernel boot path works (the kernel sees a valid FDT there), the payload path does not — root cause open, leading suspicion cache-flush asymmetry between depthcharge's cached writes and our MMU-off reads (pmOS kernel ~30 MB vs 18 KB stub is the variable). Consequence: U-Boot MUST NOT depend on the handoff FDT. Use U-Boot's own embedded control DTB (CONFIG_DEFAULT_DEVICE_TREE with the krane dts), and get the coreboot table from the fixed 0xffed9000 when needed. Investigating/fixing the zeros (e.g., adding cache clean to the wrapper's handoff, or reading with cache disabled) is a stretch goal.

Milestones

1. Buildable target: board/mediatek/ krane board + configs/mt8183_kukui_krane_defconfig forked from mt8183_pumpkin_defconfig; CONFIG_DEFAULT_DEVICE_TREE=mt8183-kukui-krane-sku176; keep CONFIG_POSITION_INDEPENDENT=y (depthcharge's slot is arbitrary), DEBUG_UART params (0x11002000 @ 26 MHz) as harmless default, drop pumpkin-specific bits (fastboot, TPHY, mtu3 gadget) for now. Deliverable: make mt8183_kukui_krane_defconfig && make -j with aarch64 toolchain produces u-boot.bin.
2. Boot wrapper + flash: prepend the 64-byte ARM64 Image header (reuse/wrap krane-fb-stub/stub.S pattern; patch image_size = header + u-boot.bin size), pack with mkdepthcharge, flash, verify. User reboots. Expected: something — U-Boot's debug UART goes nowhere visible, so absence of colors is NOT failure. This milestone is only worth flashing together with 3, or with a crude framebuffer "hello" (write RGB stripes at the scanout address early in U-Boot, e.g. from board_early_init) as a life sign.
3. Framebuffer console: minimal U-Boot video driver + vidconsole using the facts above (no full display init — reuse the live pipeline): revive writes, scanout discovery (LBIO @0xffed9000 / OVL_L0_ADDR), a simple 8x16 font vidconsole drawing into the framebuffer. Upstreamable shape: a drivers/video/ driver + Kconfig (e.g. VIDEO_MT8183_SCANOUT or a proper "coreboot framebuffer" video driver — check what exists in tree first and fit the uclass). Deliverable: U-Boot banner + prompt visible on the panel; user confirms.
4. Then: eMMC via the krane DT (mtk-sd should work out of the box), bootflow/distro boot of the pmOS kernel from mmcblk0p3, USB keyboard (Duet keyboard is USB over the pogo connector) for a real shell.

Working rules

• Update /home/vhaudiquet/krane-fb-stub/RESEARCH.md with one numbered round per experiment: observation, root cause, fix, verification. That notebook is the project's memory.
• Commit every verified step (the stub repo history shows the expected style); U-Boot work happens in /home/vhaudiquet/u-boot on a branch (e.g. krane).
• Verify before every reboot: build → wrap → mkdepthcharge → vbutil_kernel --verify → dd → cmp → on-device vbutil verify. Never yield an unverified flash claim.
• The user performs reboots and reports the screen; frame your asks as one flash-reboot per experiment with the expected observation spelled out.