Real Hardware & Interaction

The moment firmware was told to leave

Everything up to this point in the substrate's life had one honest asterisk on it: UEFI firmware was still in the room. Keyboard input, console output, even knowing where the screen's memory lived, all of it borrowed firmware's own services. A real operating environment cannot spend its whole life as a guest in someone else's house.

So the substrate was handed a real PS/2 driver and a real USB HID keyboard driver, each written from register-level first principles, each proven twice: once reading a keystroke while firmware was still present, and once reading a second keystroke immediately after firmware had been formally, permanently told to leave. Both worked, the first time it mattered. The machine could hear a key being pressed with nobody else's help.

What exists now

Real PS/2 and real USB HID keyboard drivers, written directly against hardware, with zero dependency on any UEFI protocol
A real xHCI USB host-controller driver, including the discovery that firmware's own driver has to be told, explicitly, to let go of the hardware first
A live boot dashboard: real subsystems shown assembling themselves in the order they actually come online, not a percentage bar counting up on a timer
General Shift-key support on both input paths, so a real keyboard can finally type a capital letter, a symbol, anything past lowercase and digits
A real, typable programming prompt: numbered lines, `RUN`, `LIST`, `GOTO`, and a real `Escape`-key interrupt for a program that would otherwise run forever
A dedicated, legible on-screen terminal font, separate from the dashboard's own display font, rebuilt twice after real hardware showed the first two attempts were still too easy to misread
A real, vendor-neutral fix for framebuffer write performance, and the first working steps of a native, from-scratch display driver

A program you can type, run, and interrupt

This is not a simulation of a command loop. It is the real interpreter: a person types a numbered line, the substrate remembers it, `RUN` walks the stored program in order, and a `GOTO` can send it back to an earlier line -- which means a real infinite loop is a real, reachable state. Supporting that honestly meant answering a question a lot of toy interpreters quietly duck: how do you stop a program that was never going to stop on its own? The answer here is a real keystroke check on every single step, cheap enough that a human could never type faster than it polls.

ArcoBASICArcology source: the real interpreter loop, real Escape interrupt included

' Walks the stored program in real line-number order. GOTO re-seeks by the
' real target line (the table is sparse, not addressed by array index).
' A cooperative ESC check runs once per statement -- the real, necessary
' answer to "how do you stop a running program" that supporting GOTO at
' all requires, since this backend has no keyboard interrupt yet, only
' polling.
FUNCTION RpmRun(usbSlotId AS U32) AS U64
    LET idx AS U32 = 0
    LET looping AS BOOL = 1
    WHILE looping = 1
        IF idx >= RpmCount() THEN
            looping = 0
        ELSE
            LET line AS MMIOPTR = RpmEntryAddress(idx)
            LET key AS U16 = PollAnyKey(usbSlotId)
            IF key = 27 THEN
                ' A real person just asked, mid-thought, to stop.
                PrintBreakMessage(RpmLineNumber(line))
                looping = 0
            ELSE
                IF RpmStatementType(line) = STATEMENT_PRINT THEN
                    RpmEchoLineText(line)
                    idx = idx + 1
                ELSE
                    ' STATEMENT_GOTO: find the real line this jumps to,
                    ' by number, not by position.
                    idx = RpmFindLineIndex(RpmGotoTarget(line))
                END IF
            END IF
        END IF
    WEND
    RETURN 0
END FUNCTION

What the laptop actually said back

The honest version of this story includes the part where the laptop refused, more than once. The first real boot froze silently at a fixed checkpoint, with nothing but a color on the screen to say how far it got before stopping -- a page-table assumption that had been quietly true under an emulator for months turned out to be false the instant real memory disagreed with it. The fix was to stop guessing which part of memory the running code could possibly be in, and just map all of it.

Once the machine was reliably staying on, the next honest report was blunter: the on-screen font was hard to read, and a lowercase h looked enough like an n to matter. Two real attempts later, guided directly by what a person looking at an actual screen said back, the letterforms finally had enough room to be unmistakable. Somewhere in the middle of that same conversation came the plainest, least negotiable request of the whole effort: shift key support, because a person trying to actually use the thing kept wanting to type a capital letter and couldn't. That, too, got built, generally, not just enough to satisfy one specific character.

Starting the display driver honestly, not vaguely

Every pixel this project has ever drawn went through firmware's own borrowed framebuffer, one write at a time, with no memory-type hint telling the processor those writes could be batched. That is a real, fixable performance problem, and it got fixed first, before anything more ambitious: a standard x86 feature called a Memory Type Range Register can mark the framebuffer as write-combining, and doing so needed nothing vendor-specific at all, which matters, because the eventual driver has to mean the same thing on Intel and AMD hardware alike.

The excerpt below is the real first step of the actual display driver: a genuine PCI bus scan, looking specifically for display-class hardware, run for real under an emulator first and reporting back exactly, honestly, what it found -- including correctly admitting when the hardware in front of it is neither Intel, AMD, nor NVIDIA. Knowing what is actually there, rather than assuming, is the whole point of doing this step before touching a single display register.

ArcoBASICArcology source: real PCI discovery for the native display driver

' A real bus/device/function walk for PCI base class 0x03 (Display
' Controller). Records EVERY match, not just the first -- a real machine
' can have both an integrated and a discrete GPU, and knowing which one(s)
' are actually present decides the next real step, rather than assuming.
FUNCTION GpuDiscovery.Discover(systemTable AS UEFI.SystemTable) AS U32
    LET count AS U32 = 0
    LET bus AS U32 = 0
    WHILE bus < 256
        LET device AS U32 = 0
        WHILE device < 32
            LET func AS U32 = 0
            WHILE func < 8
                LET vendorDevice AS U32 = PciConfigReadU32(bus, device, func, 0)
                IF (vendorDevice AND 65535) <> 65535 THEN
                    LET classReg AS U32 = PciConfigReadU32(bus, device, func, 8)
                    IF ((classReg SHR 24) AND 255) = 3 THEN
                        ' A real display controller. Record it and keep looking.
                        RecordDisplayDevice(count, bus, device, func, vendorDevice, classReg)
                        count = count + 1
                    END IF
                END IF
                func = func + 1
            WEND
            device = device + 1
        WEND
        bus = bus + 1
    WEND
    RETURN count
END FUNCTION

Honest current limits

The interpreter today understands two kinds of line: print a message, jump to another line. No variables, no arithmetic, no conditionals yet -- each is real, separate, planned work, not a secret the page is hiding. The display driver is further behind still: a real performance fix and a real hardware-discovery step exist; the actual display engine, the part that sets a mode without firmware's help at all, has not been touched yet, and is honestly named as the hardest, highest-risk phase of the whole undertaking before it has even started.

None of that is a hedge. It is the same discipline every other page on this site tries to keep: say exactly what is proven, say exactly what is not, and let the gap between them be the roadmap instead of a secret.

An emulator can prove correctness. Only the world proves the rest.

The real lesson of this whole chapter is not any single bug. It is that a virtual machine, however careful, is still a piece of software choosing to be reasonable with another piece of software, and a real laptop has made no such promise. Both are necessary. Neither is sufficient alone.

Prove correctness cheaply and repeatedly in a controlled environment first -- every one of these fixes was reproduced and re-verified under an emulator before it was trusted anywhere else. Cheap, repeatable proof is what makes real hardware time worth spending at all.
Then spend the real hardware time anyway. A page-table assumption that was quietly false for months only became visible the moment reality was allowed to disagree with the plan; no amount of additional emulated testing would ever have surfaced it, because the emulator itself was the thing being too agreeable.
When a real person looks at a real result and says it is not good enough, that is not scope creep, it is the actual specification arriving late. "The font is hard to read" and "I want to be able to type a capital letter" were not asks to negotiate down; they were the product finally being tested by someone it was for.
Fix the boring, structural problem before reaching for the exciting one. A vendor-neutral memory-type fix, requiring no driver at all, was the right first move before a single register of an actual display engine got touched -- the unglamorous fix is often the one that was actually blocking everything.

LEARNING LAYER

Key terms, in plain language

You do not need a systems background to follow the work. These are the specialized terms used on this page.

UEFIUnified Extensible Firmware Interface: The standardized firmware environment that starts a modern computer before an operating system takes control. Arcology OS currently enters through UEFI during hardware bring-up.
Framebuffer: A region of memory whose values become pixels on a display. Writing a color value into the right location changes the corresponding pixel.
GOPGraphics Output Protocol: The UEFI service that exposes a basic display framebuffer before a full graphics driver exists.
MMIOMemory-Mapped Input/Output: A way to control a hardware device by reading and writing special address ranges as if they were memory. A framebuffer is a common example.
Firmware: Software supplied with the machine that initializes hardware and starts the next stage of the system. It sits below ordinary applications and usually below the operating system.