Know every instruction.

What noOS is

noOS is an experimental x86 operating system. A BIOS loads its boot sector, which loads a second stage and then a protected mode Assembly kernel. It runs directly on the virtual hardware QEMU provides.

All code executed by noOS is NASM Assembly. Python and Make build the disk image and run tests on the host; neither is part of the operating system runtime. There is no libc or host operating system inside the guest.

Boot & architecture

Kernel initialization

kernel/main.asm initializes and checks the VGA terminal, IDT, PIC, physical allocator, heap, paging, read-only initrd, and ATA-backed noFS mount. It then installs the PS/2 keyboard, detects the CPU, configures the PIT, enables interrupts, checks tick-based delay, and starts the shell.

Hardware ownership

The kernel writes its VGA terminal through 0xB8000. The PS/2 driver receives keyboard events through IRQ1 after the PIC is remapped and the IDT installed. The PIT drives IRQ0. COM1 serial output exposes boot and diagnostic events to QEMU’s host terminal.

The source modules live in kernel/. The roadmap below records each implementation’s verification status.

Memory & paging

The second stage preserves BIOS E820 records. The kernel validates the map, distinguishes usable from reserved ranges, reserves the first MiB, and allocates complete 4 KiB physical frames from usable RAM below 128 MiB.

Physical frames and heap

The physical allocator tracks eligible, busy, and pinned frames. It handles exhaustion and rejects unaligned, out-of-range, invalid, double, and pinned-frame frees. The 64 KiB heap uses 16-byte aligned allocations, first fit, block splitting, and adjacent free block coalescing.

mem reads the actual E820 usable total, managed usable frames, unavailable frames inside the managed window, allocated/free frames, and heap usage. Detected usable memory above 128 MiB contributes to the E820 total but is outside the allocator’s current management window.

Supervisor paging

The kernel identity maps the first 128 MiB with supervisor-only page tables. The null page is absent, and the VGA page is uncached. CR0 paging and supervisor write protection are enabled. The bootstrap page directory and 32 page tables occupy 33 pinned frames that cannot be released through the allocator.

Shell commands

The shell runs inside the kernel and implements twenty-seven commands. Type help in the guest to see the command menu for your build.

Line editing

Left and Right move the cursor. Home and End jump within the line. Delete and Backspace remove characters; Escape clears the draft. Tab inserts one space. Up and Down navigate eight history entries while preserving the current draft. Input is bounded to 127 ASCII characters.

Filesystem commands operate on the current writable noFS directory or the read-only /initrd mount. Kernel task and user mode commands expose the verified scheduler and synchronous ring 3 runtime.

Files & storage

The writable root, /, is backed by noFS on a separate primary IDE slave disk. The kernel uses ATA PIO for actual sector reads, writes, and cache flushes. It never writes the primary master boot disk.

Persistent noFS

mkdir creates directories; touch creates empty files. write replaces the contents of an existing file. rm removes a file or an empty directory. cd accepts /, /initrd, .., or a child directory name; pwd prints the current path.

mkdir notes
cd notes
touch note.txt
write note.txt Hello from noOS
cat note.txt
pwd
cd /

The volume has 32 file/directory slots and supports at most three directory components. Names are 1–31 printable ASCII characters with no spaces or slash; . and .. are reserved path components. File storage is bounded to 4 KiB. The shell has a 127-character line limit, so text entered through write is also constrained by the command and file name.

The read-only mount

/initrd is a virtual, flat, read-only mount embedded in the boot image. It bundles hello.txt, manual.txt, and the three sample ELF programs; cat prints their actual bytes from validated initrd data. Write commands are refused in this mount.

cd /initrd
ls
cat hello.txt
pwd
cd /

Initrd startup validates magic, version, entry count, total length, bounded printable names, duplicates, and data bounds. Overflow, overlap, and invalid metadata are rejected before file access.

Disk integrity and recovery

noFS keeps two five-sector metadata banks with generation counters and FNV-1a checksums. It writes and flushes directory sectors before writing the header commit record last. Each file alternates between two eight-sector data banks, with an integrity checksum checked before contents are displayed.

Mounting uses a structurally valid metadata bank and can fall back to the other bank. If neither is valid, the disk is left untouched and writes are refused; /initrd remains readable. An uncertain write failure takes the volume offline until reboot remounts it.

Inspect kernel/fs/nofs.asm, shell filesystem handlers, the ATA driver, and the initrd validator.

Timer & CPU

The PIT uses a 1,193,182 Hz input clock and divisor 11,932, producing roughly 100 IRQ0 ticks per second. Both tick and elapsed second counters are 64-bit. Seconds are derived from accumulated PIT input cycles rather than assuming an exactly 100 Hz rate.

The kernel’s tick-based delay uses interrupts and halt while waiting. It rejects disabled interrupts and invalid tick counts. uptime reads the counters; sysinfo also exposes actual keyboard IRQ and dropped-event counts.

CPU initialization first tests CPUID availability, then obtains vendor, family, model, stepping, and feature bits from the virtual CPU. Values displayed by cpu come from that hardware response.

Measure the current build

bench performs 100,000 actual physical frame allocation/free pairs and reports elapsed PIT ticks. The timer quantizes the measurement and includes interrupt and worker preemption time. A zero result means the work finished below tick resolution. Results describe the current emulated run, with no fixed throughput or physical hardware claim. The recorded build measurements include binary sizes and host/QMP timings; these timings include host and emulator overhead.

cpu
uptime
sysinfo
bench

Tasks & privilege

PIT preemption

The shell and two workers have real saved interrupt contexts. Each worker has its own reserved kernel stack. tasks on starts PIT-driven round robin with a two-tick quantum; tasks off stops the workers while the shell continues. ps reads actual state, work, switch, and IRQ tick counters.

All three tasks run in ring 0 and share the kernel address space. Boot checks verify cooperative switching and preemption of non-yielding workers, including register preservation and return to the shell.

tasks on
ps
tasks off
user demo
user spin

A real ring 3 transition

user demo enters CPL3 through IRETD with user code/data selectors and a TSS. Each execution gets a private page directory/table, code and stack frames. User addresses begin at 0x40000000, outside the kernel identity window. The embedded demo code is read-only; its stack has an absent guard page below it. Kernel pages stay supervisor-only.

INT 80h enters a dedicated TSS kernel trap stack. User IOPL is zero and the absent I/O bitmap denies port access. Syscall writes validate overflow, bounds, and every covered page before reading bytes.

Fault demonstrations

user fault attempts a kernel-memory read; user write attempts to modify read-only code; user stack accesses the guard page; user io attempts forbidden port I/O. These real exceptions terminate that user execution, restore the shell, and release its owned frames. user spin does visible user work until thirty PIT ticks have elapsed, then exits.

Inspect the scheduler, the ring 3 runtime, and user mode checks.

Static ELF32 programs

run NAME.elf loads a bundled program from the validated /initrd data, regardless of the current directory. The applications and their genuine ELF headers are generated with NASM from user/.

run hello.elf
run checks.elf
run fault.elf

hello.elf writes a message and exits. checks.elf checks writable data, zero-filled BSS, and validated cross-page syscall buffers. fault.elf attempts a supervisor-memory read and returns through the user fault handler.

The accepted subset

The loader accepts little-endian ELF32, System V ABI version 0, ET_EXEC, EM_386, and format version 1. Its bounded program table has one to four ordered PT_LOAD entries. File offsets and virtual addresses are 4 KiB aligned, alignment is exactly 4096, and segments cannot share pages.

All loaded memory fits in the 64 KiB user window beginning at 0x40000000. File bytes cannot exceed segment memory size, every file range is checked for bounds and overflow, and the entry point must be inside file-backed RX bytes. Only R, RX, and RW flags are accepted; writable mappings follow PF_W. Frames are zeroed before copying, leaving BSS zero-filled.

The complete metadata is checked before allocation or copying. Exit, faults, and load failure release owned user frames. The loader ignores section tables and physical-address fields; dynamic linking, relocations, PIE, TLS, argv, and the Linux syscall ABI are unsupported.

kernel/tasks/elf.asm implements the loader. test_elf.py checks the three real programs, fault recovery, frame cleanup, and thirty malformed metadata fixtures.

Build & test

Install NASM, QEMU, GNU Make, and Python 3. Build tools run on the host; the result is a raw BIOS disk image that QEMU boots.

git clone https://github.com/OthmaneBlial/noOS.git
cd noOS
make
make run

The boot image, NASM listing, and binaries are generated locally. A separate persistent volume at data/noos-data.img is created only when absent; make run attaches it as IDE slave alongside the boot image. Inspect Makefile and tests/ for the exact build and verification commands. A QEMU pass establishes virtual platform behavior; it is not a physical machine test.

What the tests inspect

make test runs QEMU checks for boot, VGA, keyboard, shell, memory, paging, initrd, persistent noFS, scheduler contexts, ring 3, the ELF subset, frame benchmark accounting, and hardware diagnostics. The memory matrix uses 16, 64, 128, and 256 MiB guests and compares the preserved E820 records with allocator accounting. The 256 MiB case checks that detected memory above the management ceiling stays outside the free pool.

The suite also inspects actual page directory and table entries, supervisor permissions, the absent null page, VGA cache flags, and pinned paging structures. Fault tests deliberately trigger invalid opcode, page fault, general protection, and divide error exceptions. Hardware tests check live PIT counter advancement, CPU data, and keyboard IRQ statistics.

Initrd tests read the actual two files, check missing files and directory errors, and reject six corrupt image fixtures: bad magic, excessive count, invalid data offset, invalid length, unterminated name, and duplicate name. See test_initrd.py.

The noFS suite closes and reopens the QEMU process to check persistence, inspects raw disk sectors, checks directory and slot limits, validates corrupt-bank fallback, and confirms that invalid volumes are left untouched. It rejects six structurally malformed metadata fixtures even when their checksums are valid, and refuses to display file data with a bad integrity checksum. See test_filesystem.py. These checks do not simulate every real power loss failure.

User tests inspect actual CPL3, the TSS kernel trap stack, private CR3, code and stack permissions, the guard page, denied I/O, real fault recovery, and restoration of allocated frame counts. Scheduling tests inspect advancing worker counters under PIT preemption.

ELF tests execute the real hello, fault, and data/BSS/check applications, verify cross-page syscall behavior and frame cleanup, and reject thirty malformed metadata fixtures. Frame benchmark checks preserve free and allocated frame counts while reporting actual elapsed PIT ticks.

See test_memory.py, test_paging.py, and test_hardware.py for assertions and scope.

GDB debugging

Use x86_64-elf-gdb, or another GDB build with i386 target support. Run make debug in one host terminal; QEMU’s -S option pauses the guest before execution. Connect from a second terminal.

x86_64-elf-gdb
set architecture i386
target remote 127.0.0.1:1234
hbreak *0x10000
continue
info registers
x/12i $pc

The hardware breakpoint stops at protected mode kernel entry. Flat NASM binaries do not carry ELF debug symbols; build/kernel.lst helps correlate instructions with source. stepi advances one instruction; x/16wx 0xB8000 inspects VGA memory.

Verified roadmap

Each milestone contains five equally weighted gates. Only a verified gate contributes to the total. The forty-gate checklist covers this defined implementation scope; even 100% does not establish production maturity or unrestricted platform support. This manual and the landing page read the same roadmap data.

Limits & contributing

noOS is a developing kernel. UEFI, x86-64, physical hardware compatibility and a future x86-64 path require their own implementation and evidence. ELF support is the explicitly bounded static subset above. Kernel tasks share one address space; user execution is synchronous, with no concurrent user scheduler or FPU context switching. The roadmap distinguishes completed work from planned work.

Keep runtime code in NASM Assembly, validate untrusted input, and include a focused test for nontrivial behavior. Report the exact checkout, QEMU command, observed output, and reproduction steps when filing a bug.

Completed milestones are tested, committed, and pushed to main. Roadmap gates increase only when the implementation is verified. Review the engineering roadmap, inspect the source repository, or open an issue.

noOS is available under the MIT license.