Ultimate Amiga OS (UAOS)

A bare-metal x86_64 hobby operating system inspired by the Amiga Workbench 3.x aesthetic, built from scratch using NASM, C11, GRUB2, and OVMF/UEFI.

UAOS boots directly from a hybrid ISO via GRUB2 Multiboot2, initialises a linear framebuffer, and presents a graphical Workbench-style desktop with a window manager, PS/2 mouse and keyboard support, and an interactive shell.

---

Features

• Workbench-style desktop — solid Amiga grey backdrop, menu bar, status bar, disk icons
• Window manager — multiple windows, click-to-focus, z-order, title bar drag, resize grip
• PS/2 mouse — IRQ12-driven relative tracking, 16×16 Amiga-style software cursor
• PS/2 keyboard — IRQ1-driven, scancode set 1, ring buffer
• Shell window — scrollable history, input line, built-in commands: help, cd, alias, unalias, set, unset, path, setenv, unsetenv, showconfig
• Native C: commands — 65+ x86-64 kernel commands including version, mem, libs, dir, makedir, delete, type, copy, rename, echo, protect, attr, info, date, which, disks, fdisk, format, assign, execute, loadwb, run, ping, ifconfig, route, nslookup, ntpd, netstart, netstop, netinfo, grep, more, list, search, sort, ps, jobs, wait, ask, newcli, calculator, clock, pointer, vim, status, avail, filenote, relabel, install, diskchange, addbuffers, requestchoice, requestfile, changetaskpri, prompt, stack, why, failat, quit, endcli, getenv, unset, resident, join
• Ring-3 userspace programs — hello, pwd, file, strings, find, Guide built as native x86-64 ELF64 binaries using the INT 0x80 syscall interface
• IDT / 8259A PIC — 256-vector IDT, PIC remapped to vectors 32–47, plus local APIC setup
• MMU sandbox — 4-level paging, 2 MB huge pages
• M68k emulation — Musashi CPU, ILLEGAL opcode dispatch, LVO stubs; runs raw Amiga Hunk binaries and embedded M68k binaries
• ROM module system — Native AmigaOS-compatible library implementations:
  • exec.library v45 — Process management, memory allocation, signals, IPC
  • utility.library v37 — String functions, memory utilities
  • console.device v40 — Console I/O
  • mathffp.library v40 — Floating-point operations
  • locale.library v38 — Localization support
  • ixemul.library v53 — Unix compatibility layer
  • timer.device v40 — Timing functions (connected to RTC)
  • keyboard.device v40 — Keyboard input (connected to PS/2 driver)
  • graphics.library v40 — Graphics primitives
  • dos.library v40 — File system operations
  • bsdsocket.library v4 — BSD socket API mapped to the native TCP/IP stack
  • workbench.library v45 — Workbench desktop integration
  • intuition.library v40 — Intuition GUI API
• VFS / RAM filesystem — In-memory node tree (1024 nodes, 512 KB per file), auto-mounted at boot with T, ENV, CLIPS, S dirs; partition volumes mountable by display name or FAT32 volume label
• Filesystem drivers — FAT32, PFS3, EXT4 (read-only), ISO9660 (CD-ROM), and RAMFS
• VirtIO block device driver — PCI scanning, device detection, capacity reporting
• IDE / ATAPI driver — Storage controller for CD-ROM and hard disks
• Block device layer — Unified interface for storage devices; partition registration and MBR parsing
• RTC driver — CMOS real-time clock with UIE interrupt
• TCP/IP networking stack — IPv4, ARP, ICMP, TCP, UDP, DHCP, DNS, NTP; Intel e1000 and VirtIO-Net drivers
• EFI + BIOS hybrid ISO — boots on OVMF UEFI and legacy BIOS via GRUB2

---

Repository Layout

uaos/
├── kernel/
│   ├── boot/           # NASM entry point, C kernel main, linker script
│   ├── display/        # Framebuffer, desktop, cursor, window manager, shell window
│   ├── irq/            # IDT, 8259A PIC, PS/2 mouse, PS/2 keyboard, VMware mouse, RTC, VirtIO block
│   ├── exec/           # Thunk handler, MMU sandbox, page fault ISR, ROM modules, task scheduler,
│   │                   # syscall dispatch, native x86-64 ELF64 loader
│   ├── dos/            # VFS layer, RAM filesystem, block device layer, FAT32/PFS3/EXT4/ISO9660
│   ├── net/            # TCP/IP stack (IPv4, ARP, ICMP, TCP, UDP, DHCP, DNS, NTP)
│   ├── drivers/        # Network and IDE storage drivers (e1000, virtio-net, IDE)
│   └── shell/          # Native C: command implementations (cmd_*.c) and resident command system
├── emulation/
│   ├── binaries/       # Embedded M68k binaries (auto-wrapped into the kernel image)
│   ├── rom_patches/    # M68k Vasm/Devpac stubs, kickstart config
│   ├── src/musashi/    # M68k CPU emulator
│   ├── uaos_m68k_glue.c # M68k emulator glue, LVO stubs, DOS stubs
│   ├── uaos_uae_bridge.c  # UAE bridge and RAM-base management
│   └── uaos_emu_registry.c
├── system/             # Amiga-style filesystem skeleton (C, S, LIBS, L, DEVS, SYS, Tools)
│   ├── libuaos/        # Userspace C library headers and startup code
│   ├── userspace/      # Native x86-64 Ring-3 ELF64 programs (pwd, file, strings, find, Guide, ...)
│   ├── gnusrc/         # GNU coreutils (cat, wc, sort, ls, cp, chmod, md5sum, ...)
│   ├── gnu/            # POSIX directory skeleton exposed via the `gnu:` assign
│   └── S/              # Startup-Sequence, network, NTP, timezone configs
├── scripts/
│   ├── build_iso.sh    # Full build pipeline
│   └── grub.cfg        # GRUB2 multiboot2 configuration
├── tools/              # Host-side build helpers (gen_uaos_native, gen_uaos_m68k, gen_uaos_x64)
├── documentation/
│   ├── uaos.guide      # AmigaGuide database
│   ├── manual.md       # Markdown technical reference
│   ├── manual.tex      # LaTeX technical reference
│   └── Dos_Manual.md   # Shell and scripting reference
└── build/              # Generated output (created by build script)
    └── Ultimate_Amiga_OS.iso

---

Dependencies

Install on Debian/Ubuntu:

sudo apt install \
    nasm \
    gcc \
    binutils \
    grub-pc-bin \
    grub-efi-amd64-bin \
    grub-common \
    xorriso \
    ovmf \
    qemu-system-x86

---

Building the ISO

From the repository root:

bash scripts/build_iso.sh

To do a clean rebuild from scratch:

bash scripts/build_iso.sh --clean

On success the ISO is written to:

build/Ultimate_Amiga_OS.iso

What the build script does

---

Native x86-64 Userspace Programs

Programs in system/userspace/ are compiled as position-independent x86-64 ELF64 binaries, linked against system/libuaos/uaos_start.c, and wrapped with a 32-byte UAOS header (UAOS_BIN_TYPE_X64). At runtime the kernel loads them into Ring-3 tasks and enters user mode via iretq. They communicate with the kernel through the INT 0x80 syscall ABI:

RAX = syscall number        RDI = arg 1   RSI = arg 2   RDX = arg 3

Current userspace tools:

The syscall numbers are defined in kernel/exec/syscall_table.h (kernel) and system/libuaos/uaos_syscall.h (userspace).

---

GNU Core Utilities (gnu: layer)

UAOS ships the complete GNU coreutils suite (86 utilities) alongside the AmigaDOS-style commands. The GNU tools use GNU-style flags (--long, -s, -n 5) parsed by system/libuaos/uaos_getopt.h, a freestanding getopt_long implementation. The existing AmigaDOS commands in C: (e.g. sort, join) are kept unchanged; the GNU equivalents live under the gnu: assign, which S:Startup-Sequence maps to Workbench:gnu.

Directory layout

gnu:
├── bin/              # symlink-style bin directory
├── usr/
│   └── bin/          # GNU coreutils binaries (cat, wc, sort, md5sum, ...)
└── usr/local/bin/    # reserved for user-installed tools

Available utilities (86 tools)

Sources live in system/gnusrc/ and are compiled by Step 2ga of scripts/build_iso.sh:

The checksum tools use system/libuaos/uaos_hash.h, a freestanding implementation of MD5, SHA-1, SHA-256, SHA-512, BLAKE2b, and CRC32.

chmod maps POSIX octal/symbolic permission modes to AmigaDOS FIBF_* protection bits. chown and chgrp accept arguments but are no-ops on the single-user UAOS system.

---

Running in QEMU

First-time setup — copy OVMF variables file

OVMF requires a writable variables file. Copy a fresh copy before each run — stale vars can save a changed boot order and cause the firmware to drop to the UEFI shell instead of booting from CD:

cp /usr/share/OVMF/OVMF_VARS_4M.fd /tmp/ovmf_vars.fd

If your OVMF package uses a different path, check with: find /usr/share -name 'OVMF_VARS_4M.fd' 2>/dev/null

Launch QEMU

qemu-system-x86_64 \
  -machine q35,usb=off \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=/tmp/ovmf_vars.fd \
  -device piix3-ide,id=ide \
  -drive if=none,id=cdrom,media=cdrom,file=build/Ultimate_Amiga_OS.iso \
  -device ide-cd,drive=cdrom,bus=ide.0 \
  -m 512M \
  -vga virtio \
  -no-reboot \
  -no-shutdown

Optional: serial debug output

Add -serial stdio to see serial debug output from the kernel on your terminal:

qemu-system-x86_64 \
  -machine q35,usb=off \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,file=/tmp/ovmf_vars.fd \
  -device piix3-ide,id=ide \
  -drive if=none,id=cdrom,media=cdrom,file=build/Ultimate_Amiga_OS.iso \
  -device ide-cd,drive=cdrom,bus=ide.0 \
  -m 512M \
  -vga virtio \
  -no-reboot \
  -no-shutdown \
  -serial stdio

Or log to a file:

  -serial file:/tmp/uaos_serial.log

---

Using the Desktop

Once booted you will see a Workbench-style desktop.

Mouse

QEMU captures the mouse when you click inside the window. Press Ctrl+Alt+G to release it.

Shell window

Click the UAOS Shell title bar to focus it, then type commands:

---

Architecture Overview

For a full interactive diagram see ARCHITECTURE.md.

GRUB2 Multiboot2
    └── uaos_kernel_entry.asm   (32-bit protected → 64-bit long mode)
            └── uaos_kernel_main.c
                    ├── FB_Init()           framebuffer from Multiboot2 tag
                    ├── IDT_Init()          256-vector IDT + 8259A PIC remap
                    ├── APIC_Init()         Local APIC configuration
                    ├── PS2Mouse_Init()     IRQ12 PS/2 mouse driver
                    ├── PS2Kbd_Init()       IRQ1  PS/2 keyboard driver
                    ├── RTC_Init()          CMOS real-time clock (IRQ8)
                    ├── VFS_Init()          VFS layer + RAM filesystem
                    ├── BlockDev_Init()     Block device layer
                    ├── virtio_blk_init()   VirtIO block device driver
                    ├── ide_init()          IDE/ATAPI controller
                    ├── UAOS_MMU_Init()     MMU sandbox page tables
                    ├── UAOS_ROM_RegisterAll()  Register ROM modules
                    │   ├── exec.library v45
                    │   ├── utility.library v37
                    │   ├── console.device v40
                    │   ├── mathffp.library v40
                    │   ├── locale.library v38
                    │   ├── ixemul.library v53
                    │   ├── timer.device v40 (→ RTC)
                    │   ├── keyboard.device v40 (→ PS/2)
                    │   ├── graphics.library v40
                    │   ├── dos.library v40 (→ VFS)
                    │   ├── bsdsocket.library v4 (→ TCP/IP stack)
                    │   ├── workbench.library v45
                    │   └── intuition.library v40
                    ├── net_stack_init()    TCP/IP stack + NIC auto-probe
                    ├── Task_Init()         Ring-3 task scheduler / TSS
                    ├── Desktop_Draw()      Workbench backdrop + icons
                    ├── ShellWin_Init()     Shell window → registers with WM
                    └── event loop
                            ├── WM_MouseEvent()   drag / focus / resize
                            ├── WM_KeyEvent()     routes keystrokes to focused window
                            ├── net_stack_poll()  process RX frames
                            └── Syscall_Dispatch()  INT 0x80 from Ring-3 tasks

---

Known Limitations

• No audio support — audio drivers are not implemented yet.
• M68k emulation is partial — the Musashi CPU core, Hunk loader, and trap-based thunking can run simple M68k binaries and embedded programs; full custom-chip emulation and complex AmigaOS software compatibility are still being completed.
• ROM library coverage is incomplete — the native AmigaOS-compatible libraries are functional implementations, but not every AmigaOS API is available.
• Storage driver coverage is limited — VirtIO block read/write and FAT32 are implemented, but IDE, PFS3, EXT4, and ISO9660 support varies and is not fully exercised.
• Single CPU only — no SMP/multicore support.
• Clock display uses RTC time — full timezone, calendar arithmetic, and date/time formatting integration are still being completed.

---

License

UAOS-original code is released under the MIT License.

The UAOS kernel and system files are MIT-licensed. The bootable ISO image also contains GNU GRUB (GPL-3.0-or-later) as the bootloader — GRUB is a separate work loaded via the multiboot2 protocol and is not linked into the UAOS kernel.

Third-party source code bundled in this repository (Musashi M68k emulator, SoftFloat 2b, M68k PMMU) is licensed under their own terms. SoftFloat 2b and the M68k PMMU file are retained in the source tree for reference but are not compiled into the kernel. See THIRD_PARTY_NOTICES.md for full details including build tool licenses.