Skip to content

Releases

BooleOS 0.23.0 - Phase 23: process memory release

Choose a tag to compare

@TheShannonDev TheShannonDev released this 02 Oct 22:59

BooleOS 0.23.0 - Phase 23: process memory release

Don't want to compile? Download booleos-0.23.0.zip: it has the bootable ISO, a blank disk image and a README.txt. All you need is QEMU; the exact command is in README.txt.

Changes

Added

  • A process's page directory and page tables are freed when it exits (Phase 23-B). Until now process_exit() released the user data pages (since Phase 21) but kept the page directory and every per-process page table, 3 to 4 pages per process, so each run, fork() and exec() that ended took memory out of the pool for good. The new vmm_destroy_directory() in kernel/memory/vmm.c does the whole teardown in one interrupt-off section:
    1. If the directory being freed is the one loaded in CR3, it loads the kernel directory first. That directory has the same PDE 0 and 1 (the identity map of 0–8 MB), so a process that is exiting itself keeps running on its static kernel stack until scheduler_yield(), and only loses its user mapping.
    2. For each PDE from 2 up with VMM_USER, it drops one reference to every present user page and frees the page table. A page still shared copy-on-write with another process stays allocated until its last holder lets go.
    3. It frees the directory page.
    • PDE 0 and 1 point at the two static kernel page tables, which every directory shares; they are never touched, and a PDE without VMM_USER is skipped. The kernel directory itself and 0 are refused.
    • There is no zombie state and no deferred reaper, because the kernel stack is a static per-slot array and nothing else needs to outlive the exit. process_exit() copies and zeroes cr3, frees the directory and marks the slot unused in the same section, so a second exit of the same process finds the slot unused and does nothing.
    • A process killed while blocked on waitpid, a pipe or an ATA command is never scheduled again, so nothing walks its freed directory.
  • selftest tests 33 and 34 (34 total, was 32): 30 fork()+exit cycles (each child forces a copy-on-write copy) and 20 exec()+exit cycles of cat must leave the free PMM page count exactly where it was.
  • pmm_free_page() of a page that is not allocated (already free, or out of range) prints pmm: ERROR free of a page that is not allocated (double free?): 0x... on the serial port. It used to return without a word. Nothing else changes in that case.
  • Documentation: "Freeing a process's address space" and "Double frees" in docs/memory.md, "Exit and the CR3 in use" in docs/scheduler.md, tests 33 and 34 in docs/testing.md.

Changed

  • fork() and exec() failure paths (ELF load, user stack, no free slot) free the half-built directory, its page tables and the pages already mapped. They leaked them before.
  • sys_kill() of the caller's own pid now leaves the CPU like sys_exit(). It used to return to user mode, which only worked because the directory leaked.
  • ROADMAP.md: Phase 23 and sub-phases 23-A to 23-C are marked done. The earlier note that Phase 23 would fix the heap/identity-map design was wrong: the fixed 256 KB kernel heap, the 192 KB limit on FAT16 programs that follows from it, and the way the kernel reaches physical frames only through the 0–8 MB identity map were not touched. That work has no phase scheduled and has to happen before the DOOM port (Phase 31). ROADMAP.md, PROGRESS.md and docs/memory.md say so now.
  • docs/kernel.md, docs/testing.md, docs/security.md and docs/pipes.md no longer describe the directory leak as present, and docs/kernel.md points at Phase 28 (not 23) for syscall deprecation.
  • tools/prev/ now holds the v0.22.1 snapshot (kernel + ramfs built from the v0.22.1 tag in a clean worktree), so the "previous release" GRUB entry of this version is v0.22.1.
  • kernel/version.h is 0.23.0, phase 23 "process memory release"; the README banner and phase table follow.

Known issues

  • Four older problems are recorded in docs/TODO.md and not fixed. The first, seen while validating this release: after killing selftest with Ctrl+C during its "file create" test, the kernel heap shrank by 44 bytes (229344 B to 229300 B) and stayed there; the cause is not known. The other three were found while doing this work: a process killed mid ATA command leaves a stale waiter pointer in kernel/drivers/ata.c (it can wake the wrong process if the slot is reused, and the ATA gate is never released if the process held it); a child reserved by fork() or SYS_EXEC_PIPE stays blocked forever if its parent is killed before making it ready; elf_load() would leak a frame if two segments of a program shared a page, which no program in the tree does.

Full history: CHANGELOG.md

BooleOS 0.22.1 - Patch: console output race fixed

Choose a tag to compare

@TheShannonDev TheShannonDev released this 02 Oct 22:19

BooleOS 0.22.1 - Phase 22: unlink()/rmdir() (patch: console output race fixed)

Don't want to compile? Download booleos-0.22.1.zip: it has the bootable ISO, a blank disk image and a README.txt. All you need is QEMU; the exact command is in README.txt.

Changes

Fixed

  • Console output race, found while validating Phase 22. Typing at the shell while a background run program kept printing corrupted the screen: characters lost or doubled, a command's name scrambled, and in the worst case what looked like a command running again by itself.
    • Cause: vga_putchar(), vga_clear() and vga_set_cursor() in kernel/drivers/vga.c read and wrote term_col, term_row and the VGA buffer with nothing stopping a preemption. Any process reaches them through SYS_WRITE (the shell's key echo included), SYS_CLEAR and SYS_GOTOXY. A timer tick landing mid-write left that shared state half-updated for whichever process ran next. A tick inside the roughly 2000-cell copy loop of vga_scroll() could tear a whole scroll, duplicating or dropping a line; that was the "command ran again by itself" symptom.
    • The shell's line buffer and the keyboard ring buffer were checked and are not involved: the first is private to each process and the second has one producer and one consumer.
    • Fix: the whole body of each of the three functions now runs between irq_save() and irq_restore(), the same pattern fat16.c uses. That is safe here because nothing in vga.c waits on an IRQ, unlike disk I/O.
    • Not changed: two processes that print at the same time still interleave their output line by line, and the echo of what you type mixes with another process's output. That is how a shared terminal behaves. The FAT16 buffers held across blocking disk writes (lock planned for Phase 29) are a separate problem and were not touched.

Added

  • selftest test 32 (32 tests in total, was 31): four children and the parent each write about 4000 bytes at once, which forces the race above. No syscall reads the screen back, so the test checks what it can: every child is reaped and an unrelated syscall still behaves normally afterwards.
  • A manual test in docs/testing.md: type a command while run selftest is still printing and check by eye that no line is duplicated or lost and no command runs twice.

Changed

  • kernel/version.h bumped to 0.22.1 (PATCH: no new phase, BOOLEOS_PHASE stays 22); the README banner follows.
  • docs/hal.md and PROGRESS.md describe the interrupt-off section in vga.c; the known issue about typing while a program prints is gone from docs/TODO.md.

Full history: CHANGELOG.md

BooleOS 0.22.0 - Phase 22: unlink()/rmdir()

Choose a tag to compare

@TheShannonDev TheShannonDev released this 28 Sep 23:30

BooleOS 0.22.0 - Phase 22: unlink()/rmdir()

Don't want to compile? Download booleos-0.22.0.zip: it has the bootable ISO, a blank disk image and a README.txt. All you need is QEMU; the exact command is in README.txt.

Changes

Added

  • unlink()/rmdir() (Phase 22). fat16_unlink()/fat16_rmdir() mark the dirent 0xE5 and free the cluster chain in every FAT copy, dirent first and then the FAT (a crash between the two loses space, never leaves a live entry pointing at freed clusters). rmdir refuses a non-empty directory (not recursive) and both refuse a file open in any live process or a directory that is any process's cwd, checked through a fat16_busy_fn callback so fat16.c stays free of process knowledge. SYS_UNLINK (35) and SYS_RMDIR (36); libnos wrappers nos_unlink()/nos_rmdir(). Freeing and allocating FAT clusters now run with interrupts off (disk I/O can't: ata_wait_irq() blocks on the IRQ with interrupts on).
  • selftest tests 25–31 (31 total, was 24): unlink() of a file and a second unlink() failing, unlink() refusing an open file then succeeding after close, rmdir() of an empty directory and a second rmdir() failing, rmdir() refusing a non-empty directory then succeeding once emptied, unlink()/rmdir() refusing the wrong kind and the root/./.., rmdir() refusing a directory that is a live process's cwd (its own included), and a counted cleanup that deletes every file and directory the suite created. The old [INFO] note about files left on disk is gone.
  • Documentation for the phase: a "Deleting files and directories" section in docs/filesystem.md (the delete steps, why the dirent is written before the FAT, the in-use checks, and the directory-sector race left open as Phase 29 debt, with a reproduced case: two run selftest at once can fail cleanup, though shared test names and the cwd refusal can cause that on their own, so it isn't proof of the race by itself); docs/syscalls.md rows 35/36; docs/sdk.md lists the new wrappers.
  • SECURITY.md (repository root, the file GitHub's Security tab shows): supported versions (only the latest tag, v0.21.0 at the time), how to report a vulnerability (email theshannondev@gmail.com, best effort, no SLA, no bounty, receipt of the report is confirmed), and a "Phase 21: Copy-on-write fork() hardening" section (per-page reference count, user_kptr_write() breaking copy-on-write before kernel writes, CR0.WP, known limits). The Phase 14 and Phase 19 material stays in docs/security.md and is linked, not copied.

Changed

  • sys_kill() now closes the killed process's fds and pipe ends before process_exit() (only sys_exit() did before), so unlink() no longer refuses a file forever just because the process that had it open was killed rather than exited.
  • Two known issues found while validating this phase, recorded and not fixed: two concurrent run selftest can fail the cleanup test (30/31, cause not isolated, see docs/filesystem.md); typing at the shell while a run program is still printing garbles the input (lost/doubled characters, a command re-running by itself — run doesn't wait for the program, so the shell's line reading and the program's output run at once), recorded in docs/TODO.md.
  • CLAUDE.md, "Regra de push": a scope line makes explicit that the section (including the doc-only exception) only decides what justifies a push to main; nightly always takes a push at the end of a finished unit of work or a session, documentation-only included. The one bullet that referred to nightly in parentheses now correctly says main.
  • docs/security.md: the short Phase 21 note became a full section, "Copy-on-write fork() and memory safety (Phase 21)", and the "Relevant files" block lists the Phase 21 files.
  • docs/syscalls.md row 25 no longer describes fork() as "not copy-on-write" (stale since Phase 21).
  • tools/prev/ now holds the v0.21.0 snapshot (kernel + ramfs built from the v0.21.0 tag in a clean worktree), so the "previous release" GRUB entry of this version is v0.21.0.

Full history: CHANGELOG.md

BooleOS 0.21.0 - Phase 21: Copy-on-write fork()

Choose a tag to compare

@TheShannonDev TheShannonDev released this 28 Sep 00:30

BooleOS 0.21.0 - Phase 21: Copy-on-write fork()

Don't want to compile? Download booleos-0.21.0.zip: it has the bootable ISO, a blank disk image and a README.txt. All you need is QEMU; the exact command is in README.txt.

Changes

Added

  • Copy-on-write fork() (Phase 21). process_fork() no longer copies the parent's pages. Each user page is mapped into the child at the same physical frame, a writable page becomes read-only with the new VMM_COW PTE bit (bit 9, one of the bits the CPU leaves to the OS) in both processes, and the frame's reference count goes up by one. The parent's TLB entry is flushed with invlpg right after its PTE changes. The whole pass runs with interrupts off. A page that was already read-only without VMM_COW stays read-only in both, and a write to it is still a genuine fault.
  • Per-page reference count in the PMM (pmm_refcount[], a uint16_t per page, 4 KB in .bss; PROCESS_MAX is 16, and a compile-time check fails the build if it ever reaches the type's limit). Every allocation starts at 1; pmm_page_ref() adds one, and pmm_free_page() now drops one and returns the page to the pool only at 0. A page mapped with no count (reserved with pmm_mark_used()) counts as having one owner, so sharing it can never make it look free. Allocation, reference and free run with interrupts off.
  • vmm_cow_break(): makes a copy-on-write page privately writable. The last owner gets the page back writable in place with no copy; any other owner gets a fresh copy and drops its reference to the shared one. The page-fault handler calls it for a write to a present page (exception_handler(), error code bits 0 and 1) and returns so the CPU retries the write; with no memory for the copy the fault takes the fatal path as before.
  • Kernel writes into user memory (copy_to_user(), SYS_GETARG) go through a new user_kptr_write() that breaks copy-on-write first. The kernel writes through physical addresses, so the read-only PTE alone would not stop it from writing into a frame another process still maps.
  • SYS_PAGEREF (34) / nos_pageref(addr): reference count of the page behind a user address (1 = private, N = shared by N processes), for tests.
  • kernel/irq.h: irq_save()/irq_restore(), moved out of process.c and shared with pmm.c/vmm.c.
  • selftest tests 22–24 (24 tests total): parent and child writes stay private in both orders, with the refcount at 2 after fork() and 1 after the first write; three generations share one page and the refcount goes 3 → 2 → 1 as the youngest and then the middle process exit without writing, with the page content intact; four children rewrite four shared pages for ~300 ms each under timer preemption, and the parent ends with its own content and a refcount of 1 on every page.
  • Documentation for the phase: a "Copy-on-write fork()" section in docs/memory.md (the VMM_COW bit, the reference count, what fork() and the page-fault handler do, CR0.WP, what process_exit() releases and what still leaks), SYS_PAGEREF in docs/syscalls.md, and updates to docs/scheduler.md, docs/security.md and docs/testing.md (tests 22 to 24, 24 tests in total).
  • .claude/skills/de-ai-writing/: project skill for rewriting text without the signs of AI writing catalogued in Wikipedia's "Signs of AI writing" guide (SKILL.md with the workflow, references/signs.md with the full catalogue and a fix for each sign). CLAUDE.md gains a section requiring public text (README, CHANGELOG, CONTRIBUTING, code comments, social posts, issue templates) to go through it; facts, numbers and claims stay unchanged. The optional scripts/check_ai_signs.py scanner was not added; the manual pass over references/signs.md is the fallback. Not yet run over the existing docs.
  • GitHub issue templates in .github/ISSUE_TEMPLATE/ (bug report, feature request, boot/compatibility report).
  • CONTRIBUTING.md: contribution guide with the pull request policy. PRs must be AI-generated, and the commit must prove it with a Co-Authored-By trailer naming the AI tool (Claude Code adds it automatically); PRs without the trailer are closed, and code that reads as hand-written despite it is sent back to be redone. It also lists what to read before opening a PR (CLAUDE.md, ROADMAP.md), the local build-and-boot expectation, and what kinds of contributions are welcome.

Changed

  • process_exit() now drops the exiting process's reference to each of its user pages, so a page is freed when no process maps it any more (the data-page part of ROADMAP 23-A/23-C, pulled into Phase 21). The page directory and page tables are still leaked (23-B). The release, clearing cr3 and marking the slot unused happen in one interrupt-off section, and a slot claimed by fork()/spawn starts with cr3 = 0, so killing a half-built process never walks the previous occupant's directory.
  • CR0.WP is set together with paging, so a ring-0 write through a read-only user PTE faults (and is resolved if it is copy-on-write) instead of writing into the shared frame.
  • vmm_map_user_page() is now a wrapper over vmm_map_user_page_flags(); new vmm_get_user_pte().
  • ROADMAP.md: Phase 26 gains sub-phase 26-E (USB HID keyboard driver) and the canonical input event, which was 26-E, becomes 26-F and is named Deflection; Phase 27 is split into 27-A Cathode (graphics API / framebuffer driver) and 27-B Raster (launcher/grid, the GUI delivered in the phase, on top of Cathode).
  • tools/prev/ now holds the v0.20.1 snapshot (kernel + ramfs built from the v0.20.1 tag), so the "previous release" GRUB entry of the next version is a real release.
  • ROADMAP.md: Phase 21 is marked closed; the data-page parts of 23-A and 23-C are marked done in Phase 21's work.
  • kernel/version.h bumped to 0.21.0, phase 21 "Copy-on-write fork()".

Fixed

  • make test-elf failed on whichever program it loaded last once selftest.elf grew (its new page-aligned test buffers): tools/test_elf_load.c never unmapped the pages and image buffers of earlier loads, and its thousands of fuzzing loads ran the host out of 32-bit mmap space. Each load is now released before the next one. The kernel's ELF loader was not involved.
  • CONTRIBUTING.md: removed a reference to a component (cathode_host, SDL2) that does not exist in the BooleOS kernel.
  • Repository links in README.md, docs/quickstart.md and docs/setup.md (releases page, source link, git clone URL) now point to github.com/BooleSystems/BooleOS; they still had the pre-relocation path.

Full history: CHANGELOG.md

BooleOS 0.20.1 - Phase 20 patch: the debug boot argument works

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:18

BooleOS 0.20.1 - Phase 20: Crash handler leads into Safe Mode (patch)

Don't want to compile? Download booleos-0.20.1.zip: it has the bootable ISO, a blank disk image and a quickstart. All you need is QEMU; the exact command is in quickstart.txt.

Changes

Added

  • ROADMAP.md: new sub-phase 26-E (canonical input_event_t unifying PS/2 and USB HID input), closing Phase 26.
  • Release tags for every version in this changelog: v0.2.0 through v0.16.0 were created retroactively (annotated, at the commit that closed each version, with the original commit date), joining the existing v0.0.1, v0.1.0 and v0.17.0–v0.20.0. All 26 tags v0.0.1–v0.20.0 now exist.
  • Retroactive release packages for v0.0.1–v0.20.0, each built from a clean checkout of its tag: the bootable ISO (named as the build produced it, nullos.iso), a blank FAT16 disk.img for the versions that have one (0.10.0 and later), a per-version README.txt that describes what that specific ISO does and how to run it in QEMU, the original docs of that version untouched, and an English translation of the docs of the Portuguese-language versions (0.0.1–0.10.0).

Changed

  • Project renamed from NullOS to BooleOS. The old name was too generic and already saturated on GitHub (several unrelated projects called "NullOS"). The new name references George Boole and Boolean algebra, the mathematical basis of every digital circuit.
    • Prose and UI text (boot banner, ASCII logo, fetch, GRUB entries, README, ROADMAP, docs/*.md, CLAUDE.md) now say "BooleOS".
    • Macros/prefixes NULLOS_* -> BOOLEOS_* (kernel/version.h, build env vars, @BOOLEOS_VERSION@ in tools/grub.cfg.in).
    • Build artifacts: nullos.elf -> booleos.elf, nullos.iso -> booleos.iso, /boot/prev-booleos.elf, release zip booleos-X.Y.Z.zip, FAT volume label BOOLEOS; user/lib/nullos.{c,h} -> user/lib/booleos.{c,h}; tools/prev/nullos.elf renamed only (the v0.20.0 snapshot content is untouched).
    • Deliberately unchanged: the nos_*/libnos/nosstdio API prefix, the repository links inside the docs (they still have to be pointed at the new repository location), C NULL and "null-terminated" terminology, and the historical entries of this changelog.
  • Repository relocated to the BooleSystems organization (github.com/BooleSystems/BooleOS); project history and tags were carried over.
  • Copyright and license attribution updated to reflect the current maintainer.
  • Project renamed from NullOS to BooleOS across code, docs, build artifacts and macros (see the rename entry above).
  • Git history rewritten for the move: author, committer and tagger identity, the copyright holder in LICENSE and the repository links in the historical docs were normalized. Every commit hash changed, so hashes quoted in older notes or issues no longer resolve; the commit messages, dates and tag names are unchanged in substance.
  • kernel/version.h bumped to 0.20.1 (PATCH: no new phase, only the debug boot argument fix below); the README banner follows.

Fixed

  • The debug boot argument of the "serial debug mode" GRUB entry did nothing. GRUB passed it and the kernel could read the command line, but no code ever looked for it, so that entry booted exactly like the default one. hal_boot_init() now sets a global flag, g_debug_boot, when the word debug is on the command line. While it is set, kmain writes extra [DEBUG] detail to the serial port only (nothing changes on screen): the command line and the bootloader's memory map region by region, the boot configuration values that decide Safe Mode (fail_count, threshold, safemode flag, pending crash), and one line per boot step (ATA, boot config, PMM, paging, heap, scheduler, FAT16, PCI, ramfs/shell) with the PIT tick count. No new subsystem, no allocation. Without the argument the boot output is unchanged. Docs: docs/setup.md ("Debug via serial"), docs/quickstart.md, docs/safemode.md.

Removed

  • kernel/main.c.save: an editor backup file that had been committed by mistake.
  • A stray Untagged tag (left over from a draft release) that did not correspond to any version.

Full history: CHANGELOG.md

BooleOS 0.20.0 - Phase 20: Crash handler leads into Safe Mode

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30

BooleOS 0.20.0 - Phase 20: Crash handler leads into Safe Mode

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.20.0-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.20.0-docs-original.zip: the docs of this version, exactly as they were

Changes

Added

  • A crash restarts into Safe Mode. An unhandled CPU exception used to end in
    a red screen and a hlt loop; now exception_handler() saves a crash record in
    the boot configuration sector (LBA 1, the same one as boot_fail_count), shows
    the red screen for ~3 s, and resets the machine (the 8042 pulse, then a triple
    fault if it does not answer within ~0.5 s counted on the raw PIT). The next
    boot goes straight to Safe Mode with a crash banner (system crashed: #PF Page Fault at EIP 0x...) and a new menu item "6. View last crash details" (exception,
    EIP, error code, CR2 and decoded flags for a page fault, uptime). The record
    (keys crash_pending, crash_type, crash_eip, crash_err, crash_cr2,
    crash_ticks) is acknowledged by "Reboot normally" and removed after the next
    complete normal boot, so entering and leaving Safe Mode never loses it. A crash
    that could not be saved (no disk yet, no config sector) halts with the screen
    readable, as before, instead of restarting. A second exception during the
    handling skips the dump and goes straight to the reset.
  • The save path depends on nothing that may be broken: polling-only ATA I/O
    (ata_crash_read_sector/ata_crash_write_sector, block_*_polled() in the HAL —
    no lock, no IRQ, no scheduler, bounded waits, soft reset of a channel left
    mid-command), a static buffer, no heap. New bootcfg_buf_* functions (the text
    store on an explicit buffer, hex numbers, bootcfg_remove()), timer_poll_delay_ms(),
    power_reboot_request(), exception_name().
  • A temporary serial-only trace of every step of the ATA probe()
    ([ATADBG], marked TEMP-DEBUG(ata-probe) in kernel/drivers/ata.c) stays in
    the kernel to catch the rare intermittent "no disk" at boot (see PROGRESS.md);
    it writes to the serial port only.
  • crash <de|pf|gpf> shell command, a debug tool that faults on purpose
    (#DE, a read of 0xDEADBEEF, #GP) so the whole pipeline can be tested repeatably
    with make run-reboot-test. Documented in docs/safemode.md.

Changed

  • Roadmap renumbered: the crash-handler phase took number 20, so every
    planned phase after it moved up by one (copy-on-write fork() is now 21,
    unlink() 22, memory release 23, e1000 24, AHCI 25, xHCI 26, framebuffer/GUI
    27, syscall deprecation 28, audit pass 2 29, polish 30, the DOOM port 31).
    References in ROADMAP.md, PROGRESS.md, the docs and code comments were
    updated; older CHANGELOG entries keep the numbers of their time.
  • power_reboot() was split: power_reboot_request() only pulses the reset line.
  • Documentation: docs/safemode.md (the crash handler, the record format, the
    flow, how to test), docs/kernel.md, docs/hal.md (the polled block I/O),
    docs/shell.md (crash), docs/testing.md (the manual crash test),
    docs/setup.md (make run-reboot-test for the crash test) and the README.

Full history: CHANGELOG.md

BooleOS 0.19.0 - Phase 19: SDK / app-development experience

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30

BooleOS 0.19.0 - Phase 19: SDK / app-development experience

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.19.0-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.19.0-docs-original.zip: the docs of this version, exactly as they were

Changes

Added

  • exec() runs programs from FAT16, not only from the ramfs baked into the
    ISO. The program is found with vfs_open() — the lookup every file open
    uses: the ramfs first (so a disk file can never shadow a system program),
    then FAT16 resolved against the caller's cwd, so run dir/prog.elf works. A
    FAT16 program is read from disk whole by its directory-entry size (at most
    192 KB) into a temporary heap buffer, loaded and freed; the ramfs path stays
    zero-copy. No change to the on-disk format.
  • SDK for writing programs from outside the kernel tree: sdk/hello.c (the
    template) and sdk/Makefile, which builds every *.c to build/<name>.elf
    reusing the system's own compiler flags, linker script (user/link.ld) and
    library sources, and make inject PROG=<name> to copy the result into
    build/disk.img without rebuilding the ISO. New guide docs/sdk.md for
    someone writing a program (rules, build, running it, the library, printf).
  • printf family in libnos (user/lib/nosstdio.c): printf, vprintf,
    sprintf, snprintf, vsnprintf with the standard libc names — %d %i %u %x %X %c %s %p %%, flags - 0 + space, width and precision (also *), h/hh/l.
    No floating point, no 64-bit, no #. A separate object linked only into the
    programs that use it.
  • make test-elf (tools/test_elf_load.c): a host-side test of the real
    kernel/elf.c on every built user program, plus truncation, header fuzzing and
    crafted hostile headers.
  • selftest: three new tests (exec of a program that exists only on FAT16;
    malformed, truncated and missing programs rejected; the printf family) —
    21 tests.

Changed

  • elf_load() takes the file size and no longer trusts the image: the program
    header table and every segment's file data are checked against it, segments
    must lie in [0x00800000, 0x02000000), and all checks use 64-bit arithmetic so
    a 32-bit field cannot wrap. All headers are validated before anything is
    mapped. This also closes the "elf_load never receives the file size / page_end
    overflow" item of the Phase 28 plan.

  • The kernel heap is grown to 256 KB when it is initialized, and heap_expand()
    takes exactly the physical page at heap_end (pmm_alloc_page_at(), new)
    instead of the lowest free one — the heap's virtual addresses are the
    identity-mapped physical ones (see Fixed). The heap can no longer grow once
    processes exist, a limit recorded in PROGRESS.md for Phase 22.

  • tools/Makefile: the user ELFs have the user target as an order-only
    prerequisite, so any target that needs them builds user/ first.

  • tools/prev/ holds the v0.18.0 build (the "previous release" GRUB entry of
    this version).

  • Documentation brought up to date for this phase: docs/testing.md (the 21-test
    selftest and make test-elf), docs/filesystem.md (exec() as a vfs_open()
    consumer and the shared-buffer hazard), docs/syscalls.md (SYS_EXEC /
    SYS_EXEC_PIPE name resolution), docs/security.md (the ELF loader does not
    trust the file), docs/shell.md (run a FAT16 program), docs/setup.md
    (make test-elf, the order-only rule) and the README (file list, docs list,
    make test-elf).

  • CLAUDE.md: a "Definition of Done" checklist (literal, not prose) at the top —
    what must be done in every subtask commit (a docs/TODO.md trace, a
    [Unreleased] CHANGELOG entry) and in the closing commit of a phase (the
    consolidated CHANGELOG entry as a blocking item, README, ROADMAP,
    version.h, TODO resolved into real docs, PROGRESS, syscall table, selftest),
    ending with "read this checklist item by item against the real state of the
    files"; plus the release conventions: every version merged into main gets an
    annotated vX.Y.Z tag, make snapshot is run on the tagged tree and
    tools/prev/ committed back to nightly, and a GitHub Release with a
    ready-to-run zip (bootable ISO, a blank disk image, a README with the QEMU
    command) is published — a version is not released with only the tag.

  • ROADMAP.md: a proposed phase "Crash handler leads into Safe Mode" is
    recorded (unnumbered, outside the priority order until it gets a place): a
    kernel crash saves its dump in the boot config sector, resets by itself and
    lands in Safe Mode with the reason and a "view last crash" item.

  • Documentation split by audience: the new docs/quickstart.md covers only
    "download a release zip, install QEMU, run one command" (no toolchain, no
    Docker, no compiling), and docs/setup.md is now developer-only. setup.md
    was re-checked against tools/Makefile and the scripts: it now states that the
    Makefile runs grub2-mkrescue (the Fedora name) and that the Docker script
    installs neither dosfstools nor python3 (both unverified), documents
    make disk, make snapshot, the exact make run flags (including -display sdl), the four-entry GRUB menu, that the debug boot argument is parsed but
    not acted on yet, and adds a "Branches and versions" section (main = last
    release with an annotated tag, nightly = daily work, the -nightly suffix,
    tools/prev/). README.md and docs/kernel.md now link the right document
    for each case.
    Follow-up: version numbers in the quickstart's explanatory text are now the
    placeholders vX.Y.Z (current) and vA.B.C (previous release) instead of
    hardcoded values; the QEMU installation section covers Linux, macOS (Homebrew,
    MacPorts) and Windows evenly; a new section explains running the ISO and disk
    image in other virtual machines (general requirements, plus step-by-step
    VirtualBox and VMware Workstation/Player, including the one-time raw-to-VDI/VMDK
    conversion — general guidance, not verified by the project); and setup.md now
    explains how to switch to the nightly branch to build the development
    version.

Fixed

  • A kernel page fault (#PF inside vmm_get_user_phys_from_dir) when the heap
    had to grow after a process existed. heap_expand() mapped heap_end — an
    address inside the identity-mapped 4–8 MB range — to the lowest free physical
    page, which repointed the kernel's view of the physical page at that address;
    if it held a process's page directory or page table, the kernel read another
    page's contents through it. Latent since the heap and processes shared that
    range; the first kmalloc large enough to grow the heap after boot (an
    exec() from FAT16) exposed it.
  • make run (or any target that needs the user programs) right after make clean failed with "No rule to make target ../build/user/init.elf"; it now builds
    user/ first.

Full history: CHANGELOG.md

BooleOS 0.18.0 - Phase 18: Safety/portability foundation (HAL, msg(ID), Safe Mode)

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30

BooleOS 0.18.0 - Phase 18: Safety/portability foundation (HAL, msg(ID), Safe Mode)

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.18.0-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.18.0-docs-original.zip: the docs of this version, exactly as they were

Changes

Added

  • Hardware abstraction layer (kernel/hal.h, kernel/hal.c,
    docs/hal.md): an arch-neutral interface over the existing drivers, as thin
    forwarding wrappers (the drivers were not rewritten).
    • Console: console_putc, console_puts, console_put_hex,
      console_put_dec, console_set_color, console_clear,
      console_set_cursor, console_color_t (CONSOLE_*).
    • Input: input_poll_key, input_poll_raw, input_flush.
    • Block device: block_read_sector, block_write_sector.
    • Power: power_reboot, power_shutdown (reachable through hal.h).
    • Boot info: hal_boot_init, boot_get_memory_map, boot_get_module,
      boot_get_info_region, boot_get_cmdline, boot_has_flag, backed by new
      Multiboot2 parsers (memory map, command line) in kernel/multiboot2.h.
      The kernel used to ignore the command line entirely (the debug word of the
      "serial debug mode" GRUB entry was never read).
  • msg(ID), a central table for all user-visible text (one English
    column; not a translation system): kernel/messages.h/.c for the kernel
    (boot log, errors, dumps, exception names, ps states) and
    user/lib/messages.h/.c for the shell, editor and cat (umsg_id_t,
    UMSG_*, linked only into those programs). msg() never returns NULL
    ("(?)" for a bad ID) and works from the exception handler. Output is
    unchanged. selftest/forktest and init/spintest are not migrated.
  • Safe Mode (docs/safemode.md), a recovery environment inside the same
    kernel binary that runs in ring 0 before the PMM, VMM, heap, scheduler,
    exec and syscalls exist:
    • a boot configuration store in one raw sector (LBA 1, inside FAT16's
      reserved region, read and written only through the HAL block I/O, magic
      line # nullos-config v1, empty defaults when the sector is invalid,
      guarded by the boot sector's reserved_sectors) — kernel/bootcfg.h/.c;
    • a boot failure counter (boot_fail_count): incremented right after the
      disk is up, reset on the first keyboard read; at
      BOOTCFG_FAIL_THRESHOLD (3) failed boots in a row, or with safemode on
      the boot command line, the kernel enters Safe Mode instead of booting;
    • a text UI (kernel/safemode.c, static buffers, no heap): reboot normally
      (resets the counter), a reboot submenu, disk info from the raw boot
      sector, and a sector hexdump; Safe Mode is left only by rebooting;
    • a restricted read-only shell (menu item 5, kernel/safeshell.c) that
      initializes the PMM, VMM, heap and FAT16 on demand, once per session, and
      offers help, ls, cat, pwd, cd, back calling FAT16 directly —
      no processes, no exec;
    • GRUB entries "NullOS (Safe Mode)" (safemode flag) and "NullOS
      v (previous release)", which boots the last release's kernel and
      ramfs kept together in the tracked tools/prev/; make snapshot records
      the current build there (run by hand after tagging a release, never
      automatically). tools/prev/ holds the v0.17.1 build.

Changed

  • Everything outside the drivers goes through the HAL: kmain, syscall.c,
    process.c, scheduler.c, exec.c, power.c, memory/{pmm,vmm,heap}.c,
    drivers/pci.c, all disk access in fs/fat16.c, and idt.c's exception
    handler and progress lines (the HAL console holds no state of its own, so
    this adds no risk there). Driver bring-up calls stay direct. kmain's
    Multiboot magic check goes through hal_boot_init().
  • ata_init() runs right after interrupts are enabled, before the PMM (it is
    still called once), so the boot log shows [ATA] before [PMM].
  • pmm_init() consumes the bootloader's real memory map instead of one fixed
    contiguous block: only usable regions are freed (rounded inward to pages,
    fragmented maps supported), the first 1 MB and 1–4 MB stay reserved, and
    kmain marks the ramfs module and the Multiboot2 info block used by their
    real addresses. The allocation ceiling is an explicit 8 MB (PMM_LIMIT_ADDR,
    2048 pages): the kernel touches physical pages through its 0–8 MB identity
    map, so nothing above it is handed out. This is a mitigation of a
    pre-existing bug recorded in PROGRESS.md (fix: Phase 22); [PMM] Total
    in the boot log now shows the allocatable 8192 KB (it used to show the old
    compile-time 32768 KB cap).
  • tools/make_disk.sh passes -R 8 to mkfs.vfat so sector 1 is explicitly
    outside FAT16 (existing disks already have it: 4 reserved sectors).
  • PROGRESS.md records two pre-existing problems found during this phase:
    the kernel writes to physical pages through the identity map without
    checking (elf.c, process.c; Phase 22), and edit with no file name
    cannot save (Ctrl+S reports the misleading "saved (no disk)").
  • kernel/version.h: 0.18.0, phase 18, "Safety/portability foundation".

Fixed

  • pmm_free_pages() over-reported by the total page count since Phase 2:
    pmm_used started at 0 while the bitmap started all-used, so releasing a
    region drove it negative (the old boot log showed Free: 61440KB for
    Total: 32768KB). It now starts at the total; boot free is 1024 pages
    (4096 KB), the real figure.

Full history: CHANGELOG.md

BooleOS 0.17.1 - Documentation patch: v0.17.0 closing gaps + ROADMAP restructuring

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30

BooleOS 0.17.1 - Documentation patch: v0.17.0 closing gaps + ROADMAP restructuring

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.17.1-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.17.1-docs-original.zip: the docs of this version, exactly as they were

Changes

Documentation only; no behavior change (kernel/version.h is 0.17.1, phase
still 17 / "Cleanup A").

Changed

  • docs/testing.md: the example selftest output still showed the old
    13/13 with 13 [PASS] lines and the old cleanup note; it now shows the
    real 18/18 output (including the Intel 440FX check, the two-process pipe,
    the 3-child waitpid and the 3-level mkdir/cd) and the current
    [INFO] cleanup text.
  • README.md: the "Build" section now lists make run-reboot-test (make run without -no-reboot, so reboot really restarts the guest) and
    make inject (copies a file into build/disk.img with mcopy without
    rebuilding the ISO; host-side only). The planned-phases range is 17–30.
  • ROADMAP.md: restructured the end of the plan. The separate "technical
    prerequisites for DOOM" phase (old Phase 30) is gone: lseek moved into
    Phase 29 (general polish, next to mv/cp), the deferred Windows test of
    docs/setup.md was added there too, and the DOOM engine port (old Phase
    31) is now Phase 30 (sub-phases 30-A..D). It needs only Phase 26 and a
    one-shot single-block memory reservation syscall (DOOM's Z_Zone allocator
    asks for one big block at startup), not a full userland malloc/free.
    The plan now covers Phases 17–30, with v1.0.0 right after Phase 30.
    PROGRESS.md range updated to match. Phase 23's "Independent of Phases
    17–22" now reads "Independent of the other planned phases".
  • Not part of this patch: the permanent "NullOS vX.Y.Z (anterior)" GRUB
    entry that CLAUDE.md requires at every merge into main was never
    implemented (neither in v0.16.0 nor v0.17.0). It is tracked for Phase
    18-B (Safe Mode and the 4-entry GRUB menu).

Full history: CHANGELOG.md

BooleOS 0.17.0 - Phase 17: Cleanup A (audit fixes, libnos/shell tools, test/build infrastructure)

Choose a tag to compare

@TheShannonDev TheShannonDev released this 25 Sep 22:30

BooleOS 0.17.0 - Phase 17: Cleanup A (audit fixes, libnos/shell tools, test/build infrastructure)

All you need to run it is QEMU; the exact command is in the README.txt inside the ISO package.

  • booleos-0.17.0-iso-img(originally-nullos).zip: the bootable ISO built from this tag (the image itself still says NullOS, because the project was renamed after this version), the blank disk image when this version has one, and a README.txt with the QEMU command and what this ISO does
  • booleos-0.17.0-docs-original.zip: the docs of this version, exactly as they were

Changes

Added

  • ROADMAP.md: granular phase table — one row per phase and
    sub-phase for completed Phases 0–16 (names taken from the README's
    completed-phases table, links to CHANGELOG versions and docs/
    files) and for planned Phases 17–31 including their sub-phases.
  • docs/TODO.md: header-only file for minimal "WIP: document X"
    stubs left during nightly development, resolved at each version's
    final polish (per the new CLAUDE.md documentation rule).
  • user/lib/nullos.c/h, user/shell.c, forktest.c, selftest.c,
    edit.c: libnos gained memcpy/memset/memmove/memcmp/strlen/
    strcmp/strncmp (standard libc names and signatures, so a call GCC
    emits by itself resolves) and nos_uitoa; the four per-program copies
    of strlen/uitoa, shell's strcmp/strncmp, selftest's st_bufeq
    and the inline zero/shift/copy loops in selftest and edit now call them.
  • user/selftest.c: new test "SYS_WRITE >128 bytes accumulates in a FAT16
    file" — writes 2100 bytes as two nos_write() calls (crossing the first
    2048-byte cluster) and reads them all back; the regression test for the
    chunked-write data loss. Suite is now 14 tests (st_big.txt is left on
    disk like the other test files).
  • pwd / SYS_GETCWD (30): fat16_get_path() rebuilds a cwd path from the
    cwd's cluster by walking up through .. (names in 8.3 uppercase).
    nos_getcwd(), shell pwd.
  • cat <file>: user/cat.c opens the file named by its argument and prints
    it; with no argument it still copies stdin (pipe sink). The shell's cat <file> launches it and waits. sys_exec_pipe() clears the global
    exec_arg so a piped/redirected cat never reads the argument left by an
    earlier plain exec().
  • cmd < file and cmd > file in the shell (run_redirected()): file fds
    through the existing SYS_EXEC_PIPE; > creates + truncates. External
    programs only, launched by name without arguments, not combinable with |.
  • kernel/power.c/h: power_reboot() (8042 reset, port 0x64 <- 0xFE) and
    power_shutdown() (PIIX4 PM base from PCI config 0x40, outw(base+4, 0x2000); prints "shutdown not supported on this hardware" when the PIIX4
    isn't in the PCI table). pci_find_device(). Syscalls SYS_REBOOT (31) and
    SYS_SHUTDOWN (32), nos_reboot()/nos_shutdown(), shell reboot/
    shutdown.
  • user/selftest.c: four new tests (18 total): a two-process pipeline
    (a fork()ed writer and cat launched with SYS_EXEC_PIPE, parent
    compares the output), waitpid with three children (each pid collected
    with the result that child reported, and gone afterwards), mkdir/cd
    three levels deep (pwd at every level, a file at the bottom, cd .. back
    to /), and a check for the Intel 440FX host bridge (8086:1237) next to
    the generic PCI count. The 440FX test is expected to fail once Phase 24
    moves QEMU to -machine q35 (see docs/TODO.md).
  • SYS_PCI_FIND (33) / nos_pci_find(vendor, device): 1 if a device with
    that ID is in the PCI table, 0 if not (pci_find_device() for userland).
  • tools/Makefile: make inject FILE=... [NAME=...] copies a file into the
    root of build/disk.img with mcopy, without rebuilding the ISO.
    Host-side only — the kernel still can't exec() from FAT16 (Phase 19).
  • tools/Makefile: make run-reboot-test runs QEMU without -no-reboot, so
    reboot really restarts the guest. run and debug keep -no-reboot on
    purpose (post-mortem state on a triple fault; it also turns a guest reset
    into a shutdown).

Changed

  • kernel/version.h: NULLOS_VERSION "0.17.0", NULLOS_PHASE "17",
    NULLOS_PHASE_DESC "Cleanup A".
  • user/shell.c: run has a single implementation, cmd_run(), shared by
    the foreground path and run_command(); it trims and validates the name.
  • ROADMAP.md: replaced the Phases 17–22 plan with the restructured
    Phases 17–31 sequence (Cleanup A, HAL + Safe Mode, SDK, COW fork,
    unlink/rmdir, process_exit() memory release, e1000, AHCI,
    xHCI, framebuffer/GUI, syscall deprecation, audit pass 2, polish,
    DOOM prerequisites, DOOM port / v1.0.0). Old Phases 17–22 renumbered
    to 20, 23, 24, 25, 26, 27, with a granular one-row-per-phase/sub-phase
    table (historical lettered phases as parent + child rows). No
    package-manager phase, by decision.
  • README.md: "Completed phases" table shows only whole phases (the old
    rows 2/2b and 3a/3b merged into one row each); the "planned phases" range
    is 17–31.
  • CLAUDE.md: new sections/rules for the nightly/main branch strategy,
    -nightly version suffix, sub-phases, HAL, centralized msg() text
    output, key=value system config file, and Safe Mode; serial-mirroring,
    exec()/fork() threading and docs-verification rules extended; Safe Mode
    rules name process_spawn_user.
  • PROGRESS.md: consolidated from 411 to ~150 lines (closed phases one
    line each, decisions tightened with links to docs/).
  • docs/: memory.md, filesystem.md, scheduler.md, pci.md,
    kernel.md, shell.md, pipes.md, testing.md, syscalls.md updated
    for everything above; docs/scheduler.md no longer describes the removed
    process_spawn().

Fixed

  • kernel/memory/pmm.c: pmm_init() computed the page count as
    (1024 + mem_upper) * 1024 / PAGE_SIZE, which overflows uint32_t
    for a huge mem_upper and wraps to a tiny total_pages, underflowing
    total_pages - 256. Now 256 + mem_upper / 4 (same value, no
    overflow), and freeing high memory is skipped with a warning when
    total_pages <= 256.

  • kernel/fs/fat16.c: fat16_init() now rejects a BPB with
    sectors_per_cluster == 0 (printing the reason) before it is used as
    a divisor, instead of dividing by zero.

  • kernel/process.c: next_pid++ (three places) now goes through
    alloc_pid(), which saves/restores EFLAGS around the increment
    instead of a bare cli/sti, since process_fork() calls it from
    inside its own cli section.

  • kernel/drivers/pci.c/pci.h: only the BARs a header type really
    has are read and printed (type 0: 6, type 1 PCI-PCI bridge: 2,
    type 2 CardBus: 1), with the multi-function bit (0x80) masked off
    first; the rest of bar[] stays 0.

  • kernel/memory/vmm.c/vmm.h: vmm_map_page() and
    vmm_map_user_page() now return int (0 = success, VMM_ERR_RANGE
    / VMM_ERR_NOMEM on failure) instead of failing silently as void;
    map_page_early() reports an exhausted page-table pool.
    vmm_map_user_page() also rejects virt < 0x800000 (the kernel's
    shared identity map) and frees a page-table page it can't use.
    Every call site checks the result: heap_expand() frees the page and
    returns 0; exec()'s user-stack loop prints an error and returns 0;
    elf_load() returns -1; process_fork() unwinds via its existing
    failed path. The three vmm_map_user_page sites also free the
    just-allocated physical page instead of leaking it.

  • kernel/keyboard.c, user/edit.c: Shift in the editor.
    The raw scancode path (SYS_READ_RAW) now carries a Shift bit
    (bit 9, next to Ctrl's bit 8), because the kernel consumes the Shift
    make/break scancodes itself and edit.c could never see them; the
    editor selects a new sc_map_shift[] table from it, so Shift+5 gives
    %, Shift+\ gives | and Shift+letter gives the capital.

  • kernel/fs/fat16.c: fat16_write_file() again refuses
    a directory entry (ATTR_DIRECTORY) — the Phase 15 switch to the
    shared dir_lookup() had dropped the old loop's directory skip — and
    no longer re-reads the dirent sector dir_lookup() just left in
    dir_buf. (The "duplicated dirent lookup" tech-debt item was already
    resolved by Phase 15; only these two leftovers remained.)

  • kernel/process.c, kernel/scheduler.c/h, kernel/process.h
    : process_spawn_user() now reserves its slot atomically
    (interrupts off via saved EFLAGS, slot marked PROCESS_BLOCKED, pid
    and waiting_for_pid reset in the same section), fills in every
    field, and only then publishes PROCESS_READY (or leaves it
    PROCESS_BLOCKED for start_blocked). This closes two races: two
    spawns picking the same free slot, and the scheduler running a slot
    whose esp/cr3 weren't built yet. New irq_save()/irq_restore()
    helpers, also used by alloc_pid().

  • kernel/fs/fat16.c, fat16.h, vfs.c, vfs.h, kernel/syscall.c:
    SYS_WRITE on a FAT16 fd lost data. sys_write() staged writes in
    128-byte chunks and each vfs_write() replaced the WHOLE file, so only
    the last chunk survived a write over 128 bytes. New fat16_write_at()
    (positional write: grows the chain, updates the dirent, data -> FAT ->
    dirent order) backs a stream vfs_write() that writes at fd->pos and
    advances it; the whole-file replace SYS_WRITE_FILE needs moved to
    vfs_write_all(), so the editor's save is unchanged.

  • user/shell.c: a bare edit or cat (no argument) printed command not found. nos_read() returns the line with its trailing newline, and the
    branches only match "name followed by a space or end of string". The
    shell now strips the trailing \n/\r right after reading the line.

  • Line editing echo (pre-existing): erasing a typed character did not
    erase it on the serial console. vga_putchar('\b') blanks the cell on
    screen, but its serial mirror sent a raw \b, which onl...

Read more