UnstableOS

---

A somewhat UNIX-like somewhat POSIX compliant x86 32-bit preemptive multitasking monolithic kernel targeting the i486 feature set written in C and a tiny bit of assembly

Warning

UnstableOS is primarily tested on TCG, there are bound to be issues on real hardware and/or with KVM
It is not meant as a production OS, there is no testing, there is no fuzzing. I try to make it safe, but I am not perfect, anything is possible...

Features

---

• 32-bit paging (without PAE)
• Round-robin scheduler supporting threads
• Standard VFS functions you'd expect
• ELF loading & userspace processes
• Ramdisks & Tar as initial ramdisk
• exec(), CoW fork(), spawn(), wait()
• Signals - most of sig*, kill(), tgkill()
• Both shared and private mappings with mmap(), mprotect(), munmap()
• Semaphores and kernel spinlocks (technically mutexes)
• POSIX compliant TTY with most of termios
• DEC VT102 inspired framebuffer console
• Lame and lacking custom libc
• Custom (lame and lacking) shell
• Partial pthread.h

List of defined syscalls can be found in <UnstableOS/syscalls.h>

Drivers

---

• PS/2 keyboards and mice
• RS/232 (serial)
• Tar as a filesystem, FAT
• mountable devtmpfs
• RTC
• VGA, VBE, BGA
• PCI
• ATA PIO using the legacy ports (4 drive max)
• MBR partition tables

Building

---

Currently, you need:

• make
• i686-gcc-elf (and associated liker and assembler)
• tar
• qemu (or similar to test)

For making an ISO, you additionally need:

• limine
• cdrtools (or something providing mkisofs)

Then either do make kernel to build just the kernel,
make all to create the kernel, utils and memdisk, or
make iso to create an iso from the kernel, utils and memdisk

Minimum requirements

---

CPU: 486 class with built-in x87 math coprocessor
RAM: at least 2.5MiB for basic kernel, 3.5MiB for stable fork()
HDD: either boot live or 5MiB ATA1+ to store all utilities
GFX: IBM Video Graphics Array and a monitor with a resolution of 640x480 ¹

Testing in a VM

---

UnstableOS.bin is an ELF image conforming to the Multiboot specification
So you need to load it as a Multiboot kernel

The last multiboot module is considered as the initial filesystem
In case no module is found, hd0p1 and then hd0 formatted as FAT are assumed to be root
/init is assumed to be the init process and must exist on the root device
For qemu you can do (assuming make iso):
qemu-system-i386 -m 100M -cdrom build/UnstableOS.iso

Known bugs/issues/quirks

---

see caveats.md for info

TODO in Near Future

---

• mmap(), munmap(), msync() (only with MAP_FIXED)
• stat()
• mkdir(), rmdir()
• unlink()
• monotonic clock sleep()/nanosleep() using the RTC clock
• the rest of clock types and waiting functions
• some missing time.h functions
• HPET timer
• shared memory (basic IPC)
• ATA PIO with read cache
• ATA DMA
• AHCI
• VFAT, without LFNs so far
• ATAPI
• ISO9660
• pipes
• sockets and named pipes
• symlinks
• signals
• proper (linked) ucontext_t
• signal alternative stacks
• implement priority for realtime signals
• waitid(), waitpid()
• alarm()
• finish implementing sessions and foreground groups for TTY
• implement setsid()
• implement controlling terminal allocation
• errno in userspace instead of returning negative numbers
• scheduler priorities?
• any form of fpu - currently supported: x87, MMX, SSE, SSE2
• PCI
• ACPI
• Ethernet (ne2000)
• Virtual-8086 mode
• VBE linear framebuffer instead of VGA text mode
• proper direct VRAM access
• ioctls for framebuffer devices - so far only for VGA
• SMP - multicore support
• argv, argc, envp/environ, execve
• functional execve() and spawn() for ring 0 processes
• auxiliary vector (for elf interpreters)
• Thread-Local Storage + proper errno
• Core utils
• pthread.h see pthread_progress.md for more info

Footnotes

1. or edit src/vga.c:394 to vga_set_mode_13 and a 320x200 composite monitor ↩