Developer guide: overview & architecture
This section is for people building or extending UnoDOS pc64 itself, or writing apps for it. End users do not need any of it; the flasher covers them.
pc64 is a bare-metal x86-64 UEFI operating system written entirely in freestanding C: no host C library, no underlying OS. It ships two interchangeable desktops, selected at build time:
- unoui (the default,
./build.sh): the modern themed desktop this manual documents, built on the cross-platform unoui widget toolkit. - legacy (
./build.sh legacy): the older core with 14 hand-drawn apps, kept only as reference. Everything it did now runs in the unoui desktop.
The layers
From the top down:
| Layer | What it is |
|---|---|
| Apps | Native unoui widget apps, custom-drawn canvas apps (games, Paint, browser, Runner3D), and bridged legacy apps. |
| Shell | pc64_uui.c: the themed desktop, icons, taskbar, window z-order, and app open/close. |
| Toolkit (unoui) | The portable widget core: windows, widgets, events, and a swappable theme (ten themes ship). |
| Framebuffer (fb) | A 32-bit software framebuffer: clipping, alpha blend, gradients, anti-aliased rounded rects, fractional fill-scaling, and dirty-row present-on-change. |
| Platform (UEFI) | A hand-rolled UEFI surface: the GOP framebuffer, keyboard, pointer, and Boot Services. No gnu-efi or EDK2. |
| Drivers (tail) | Intel e1000 / e1000e / igb NICs (plus a Realtek RTL816x driver) and the TCP/IP + TLS stack, xHCI USB with ASIX and Realtek USB Ethernet, native AHCI / NVMe / SDHCI and USB mass storage, HD Audio and AC'97 PCM audio, Intel Wi-Fi (AX201 / AX210: joins a WPA2 network and takes an address, on one laptop so far) and early Realtek / Marvell Wi-Fi (firmware loads, not yet connecting), uno3d 3D, UnoSound, and the TrueType engine. |
| Device manager (unodevices) | Enumerates the PCI tree into a registry that reports every device and which driver, if any, claimed it - surfaced on-device through the devices remote verb and uno.devices()/uno.pci(). Read-only introspection today; driver auto-binding is a planned phase. A hardware-watchdog primitive (the PCH TCO) lives alongside it as the remote guard's last-resort backstop. |
Boot flow
- Firmware handoff. UEFI GOP provides a linear 32-bit framebuffer; Simple Text Input provides the keyboard with modifier state; the Simple and Absolute Pointer protocols provide a mouse where the firmware binds one.
- Boot Services stay alive. UEFI Boot Services take the role the old INT 10h/13h/15h calls
played for the 16-bit kernel.
ExitBootServicesand native drivers are the driver tail, not a bring-up requirement. - Platform + shell init, then the desktop paints and a start-up chime plays. The UEFI
watchdog is disabled at startup (
SetWatchdogTimer(0, ...)) so a long-running app is not reset after five minutes.
The freestanding model
The build target is a PE32+ UEFI application (EFI/BOOT/BOOTX64.EFI) produced by
mingw-w64. There is no host libc: the project ships its own headers in pc64/include/, a small libc
in pc64_libc.c, and float math in pc64_math.c. Hot paths avoid dynamic allocation
(the TLS engine, the browser JavaScript engine, and the 3D math are all no-malloc).
unsigned long long or uintptr_t for every address and 64-bit value. A truncated 64-bit DMA address was a real, hard-to-find bug in the NIC driver.The Contract (unodef)
The wider UnoDOS family is generated from, or checked against, a single machine-readable Contract
in unodef/. It keeps every port (from the 8-bit consoles to pc64) consistent. For a pc64 app author
it is background: you code against the concrete C headers, unoui.h and uno_app.h.
Next: Writing apps, the worked sample programs, the UnoC and Python SDK references, and Building & tooling.