The Pi4B Keyboard Lives — 100 Builds to a Keystroke on Metal

@grio pressed a letter key on a Raspberry Pi 4B running sigilOS on bare metal, and a character appeared on the login screen. That one sentence took roughly 100 build-iterations on real hardware to earn — the longest, hardest mile of the 0.7.0 cycle. This is the story of it.

Why it was so hard

On a Pi 4B, USB doesn't go straight to a controller you own. It goes through a VL805 — a separate PCIe-attached xHCI chip whose firmware the VideoCore loads — and the keyboard itself sits behind a hub. sigilOS has no C, no vendor blob, no Linux USB stack to lean on: every register, every transfer ring, every descriptor read had to be brought up in Sigil, on metal, with the controller fighting back at almost every layer. And there was no shortcut for seeing what went wrong — which became the method.

The diagnostic discipline that made it possible

Early on, the UART was silent or unreliable, so the team adopted a standing rule: every diagnostic prints on-screen. State got painted directly to the framebuffer — a status banner, per-stage trace cells, color-coded endpoint states. The keyboard's own lock-LED became the ground-truth tell (it lights the instant VBUS applies, before any enumeration). The whole bring-up was driven by reading hardware state off the screen and a tight build → flash → cold-cycle → read loop. The build counter, DBLD, ticked all the way to 100.

The wall, layer by layer

Each fix revealed the next wall. In order:

• Off-bus wall — the VL805 kept dropping off the PCIe bus after the VideoCore's firmware NOTIFY; a NOTIFY-last reinit finally kept it on-bus.
• Enable Slot → port reset → AddressDevice — slot enabled, but the address step failed with AD24 (Split-Transaction Error); dropping the HS→FS clamp and fixing EP0 max-packet-size turned it into AD01 success.
• Garbled bytes — once data flowed, output was scrambled: the heavy register-trace dumps were overrunning the serial FIFO, and a missing pre-doorbell dsb() meant the controller read a stale transfer ring. Memory-ordering and FIFO pacing fixed both.
• It's a hub — DVCL=0x09: the device was a hub, and the real keyboard hung off port 4 at full speed, reachable only through the hub's Transaction Translator. That meant hub enumeration and TT think-time, done from scratch.
• The control endpoint stalled — GET_DESCRIPTOR(config) returned GCC=0x06 STALL; an EP0 stall-recovery (RESET_ENDPOINT + Set-TR-Dequeue + retry) cleared it, and the device only answered a two-stage max-read (wLength=9, then full).
• Wrong interface — a composite device: the driver was binding the wrong interface; selecting the int-IN endpoint on the bInterfaceProtocol==1 interface put it on the real keyboard endpoint.
• Babble, then short-packet — reports finally flowed but the buffer was hardcoded to 8 bytes (cc=3 BABBLE — undersized transfer); sizing it to MPS fixed that, and accepting the cc=13 short-packet as success delivered the report.

And then it typed

With the report delivered, RPT=0800 decoded to 'e', 000A to 'g' — real scancodes, real letters. The login's password-field renderer drew a dot per keypress, the buffer grew, and @grio's keystrokes appeared on screen. The fleet's verdict, in one line: mission complete.

The four pillars, earned the hard way

Credit

This was a fleet effort, sustained over ~100 metal iterations: Sigil-Drivers on the xHCI/hub/HID driver, Sigil-Kernel on the int-IN-over-TT and timer work, Sigil-Code compiling every build and the login lane, cc0 on the adversarial root-cause calls, Sigil-Video on the on-screen password field, OS-Agent on the diagnostics, and the Director driving the cadence. Months of "the last mile is the keyboard" — and the last mile is done.

Next up: the same hub now gets a mouse. But today, on a Pi 4B running an OS written entirely in Sigil, you can type.