Repository navigation
Releases
BooleOS 0.23.0 - Phase 23: process memory release
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 eachrun,fork()andexec()that ended took memory out of the pool for good. The newvmm_destroy_directory()inkernel/memory/vmm.cdoes the whole teardown in one interrupt-off section:- 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. - 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. - 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_USERis 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 zeroescr3, 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.
- 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
- selftest tests 33 and 34 (34 total, was 32): 30
fork()+exit cycles (each child forces a copy-on-write copy) and 20exec()+exit cycles ofcatmust 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) printspmm: 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" indocs/scheduler.md, tests 33 and 34 indocs/testing.md.
Changed
fork()andexec()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 likesys_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.mdanddocs/memory.mdsay so now. docs/kernel.md,docs/testing.md,docs/security.mdanddocs/pipes.mdno longer describe the directory leak as present, anddocs/kernel.mdpoints at Phase 28 (not 23) for syscall deprecation.tools/prev/now holds the v0.22.1 snapshot (kernel + ramfs built from thev0.22.1tag in a clean worktree), so the "previous release" GRUB entry of this version is v0.22.1.kernel/version.his0.23.0, phase23"process memory release"; the README banner and phase table follow.
Known issues
- Four older problems are recorded in
docs/TODO.mdand not fixed. The first, seen while validating this release: after killingselftestwith 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 inkernel/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 byfork()orSYS_EXEC_PIPEstays 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
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
runprogram 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()andvga_set_cursor()inkernel/drivers/vga.cread and wroteterm_col,term_rowand the VGA buffer with nothing stopping a preemption. Any process reaches them throughSYS_WRITE(the shell's key echo included),SYS_CLEARandSYS_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 ofvga_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()andirq_restore(), the same patternfat16.cuses. That is safe here because nothing invga.cwaits 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.
- Cause:
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 whilerun selftestis still printing and check by eye that no line is duplicated or lost and no command runs twice.
Changed
kernel/version.hbumped to0.22.1(PATCH: no new phase,BOOLEOS_PHASEstays22); the README banner follows.docs/hal.mdandPROGRESS.mddescribe the interrupt-off section invga.c; the known issue about typing while a program prints is gone fromdocs/TODO.md.
Full history: CHANGELOG.md
BooleOS 0.22.0 - Phase 22: unlink()/rmdir()
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 dirent0xE5and 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).rmdirrefuses 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 afat16_busy_fncallback sofat16.cstays free of process knowledge.SYS_UNLINK(35) andSYS_RMDIR(36); libnos wrappersnos_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 secondunlink()failing,unlink()refusing an open file then succeeding after close,rmdir()of an empty directory and a secondrmdir()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: tworun selftestat 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.mdrows 35/36;docs/sdk.mdlists the new wrappers. SECURITY.md(repository root, the file GitHub's Security tab shows): supported versions (only the latest tag,v0.21.0at the time), how to report a vulnerability (emailtheshannondev@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 indocs/security.mdand is linked, not copied.
Changed
sys_kill()now closes the killed process's fds and pipe ends beforeprocess_exit()(onlysys_exit()did before), sounlink()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 selftestcan fail the cleanup test (30/31, cause not isolated, seedocs/filesystem.md); typing at the shell while arunprogram is still printing garbles the input (lost/doubled characters, a command re-running by itself —rundoesn't wait for the program, so the shell's line reading and the program's output run at once), recorded indocs/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 tomain;nightlyalways takes a push at the end of a finished unit of work or a session, documentation-only included. The one bullet that referred tonightlyin parentheses now correctly saysmain.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.mdrow 25 no longer describesfork()as "not copy-on-write" (stale since Phase 21).tools/prev/now holds the v0.21.0 snapshot (kernel + ramfs built from thev0.21.0tag 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()
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 newVMM_COWPTE 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 withinvlpgright after its PTE changes. The whole pass runs with interrupts off. A page that was already read-only withoutVMM_COWstays read-only in both, and a write to it is still a genuine fault. - Per-page reference count in the PMM (
pmm_refcount[], auint16_tper page, 4 KB in.bss;PROCESS_MAXis 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, andpmm_free_page()now drops one and returns the page to the pool only at 0. A page mapped with no count (reserved withpmm_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 newuser_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 ofprocess.cand shared withpmm.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(theVMM_COWbit, the reference count, whatfork()and the page-fault handler do,CR0.WP, whatprocess_exit()releases and what still leaks),SYS_PAGEREFindocs/syscalls.md, and updates todocs/scheduler.md,docs/security.mdanddocs/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.mdwith the workflow,references/signs.mdwith the full catalogue and a fix for each sign).CLAUDE.mdgains 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 optionalscripts/check_ai_signs.pyscanner was not added; the manual pass overreferences/signs.mdis 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 aCo-Authored-Bytrailer 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, clearingcr3and marking the slot unused happen in one interrupt-off section, and a slot claimed byfork()/spawn starts withcr3 = 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 overvmm_map_user_page_flags(); newvmm_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 thev0.20.1tag), 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.hbumped to0.21.0, phase21"Copy-on-write fork()".
Fixed
make test-elffailed on whichever program it loaded last onceselftest.elfgrew (its new page-aligned test buffers):tools/test_elf_load.cnever unmapped the pages and image buffers of earlier loads, and its thousands of fuzzing loads ran the host out of 32-bitmmapspace. 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.mdanddocs/setup.md(releases page, source link,git cloneURL) now point togithub.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
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_tunifying PS/2 and USB HID input), closing Phase 26. - Release tags for every version in this changelog:
v0.2.0throughv0.16.0were created retroactively (annotated, at the commit that closed each version, with the original commit date), joining the existingv0.0.1,v0.1.0andv0.17.0–v0.20.0. All 26 tagsv0.0.1–v0.20.0now 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 FAT16disk.imgfor the versions that have one (0.10.0 and later), a per-versionREADME.txtthat 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@intools/grub.cfg.in). - Build artifacts:
nullos.elf->booleos.elf,nullos.iso->booleos.iso,/boot/prev-booleos.elf, release zipbooleos-X.Y.Z.zip, FAT volume labelBOOLEOS;user/lib/nullos.{c,h}->user/lib/booleos.{c,h};tools/prev/nullos.elfrenamed only (the v0.20.0 snapshot content is untouched). - Deliberately unchanged: the
nos_*/libnos/nosstdioAPI prefix, the repository links inside the docs (they still have to be pointed at the new repository location), CNULLand "null-terminated" terminology, and the historical entries of this changelog.
- Prose and UI text (boot banner, ASCII logo,
- 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
LICENSEand 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.hbumped to0.20.1(PATCH: no new phase, only thedebugboot argument fix below); the README banner follows.
Fixed
- The
debugboot 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 worddebugis on the command line. While it is set,kmainwrites 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,safemodeflag, 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
Untaggedtag (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
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 aREADME.txtwith the QEMU command and what this ISO doesbooleos-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 ahltloop; nowexception_handler()saves a crash record in
the boot configuration sector (LBA 1, the same one asboot_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
(keyscrash_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. Newbootcfg_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], markedTEMP-DEBUG(ata-probe)inkernel/drivers/ata.c) stays in
the kernel to catch the rare intermittent "no disk" at boot (seePROGRESS.md);
it writes to the serial port only. crash <de|pf|gpf>shell command, a debug tool that faults on purpose
(#DE, a read of0xDEADBEEF, #GP) so the whole pipeline can be tested repeatably
withmake run-reboot-test. Documented indocs/safemode.md.
Changed
- Roadmap renumbered: the crash-handler phase took number 20, so every
planned phase after it moved up by one (copy-on-writefork()is now 21,
unlink()22, memory release 23,e100024, AHCI 25, xHCI 26, framebuffer/GUI
27, syscall deprecation 28, audit pass 2 29, polish 30, the DOOM port 31).
References inROADMAP.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-testfor the crash test) and the README.
Full history: CHANGELOG.md
BooleOS 0.19.0 - Phase 19: SDK / app-development experience
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 aREADME.txtwith the QEMU command and what this ISO doesbooleos-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 withvfs_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, sorun dir/prog.elfworks. 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) andsdk/Makefile, which builds every*.ctobuild/<name>.elf
reusing the system's own compiler flags, linker script (user/link.ld) and
library sources, andmake inject PROG=<name>to copy the result into
build/disk.imgwithout rebuilding the ISO. New guidedocs/sdk.mdfor
someone writing a program (rules, build, running it, the library,printf). printffamily in libnos (user/lib/nosstdio.c):printf,vprintf,
sprintf,snprintf,vsnprintfwith 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.con 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_loadnever 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 atheap_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 inPROGRESS.mdfor Phase 22. -
tools/Makefile: the user ELFs have theusertarget as an order-only
prerequisite, so any target that needs them buildsuser/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 andmake test-elf),docs/filesystem.md(exec()as avfs_open()
consumer and the shared-buffer hazard),docs/syscalls.md(SYS_EXEC/
SYS_EXEC_PIPEname resolution),docs/security.md(the ELF loader does not
trust the file),docs/shell.md(runa 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 (adocs/TODO.mdtrace, 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 intomaingets an
annotatedvX.Y.Ztag,make snapshotis run on the tagged tree and
tools/prev/committed back tonightly, 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.mdcovers only
"download a release zip, install QEMU, run one command" (no toolchain, no
Docker, no compiling), anddocs/setup.mdis now developer-only.setup.md
was re-checked againsttools/Makefileand the scripts: it now states that the
Makefile runsgrub2-mkrescue(the Fedora name) and that the Docker script
installs neitherdosfstoolsnorpython3(both unverified), documents
make disk,make snapshot, the exactmake runflags (including-display sdl), the four-entry GRUB menu, that thedebugboot 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-nightlysuffix,
tools/prev/).README.mdanddocs/kernel.mdnow link the right document
for each case.
Follow-up: version numbers in the quickstart's explanatory text are now the
placeholdersvX.Y.Z(current) andvA.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); andsetup.mdnow
explains how to switch to thenightlybranch to build the development
version.
Fixed
- A kernel page fault (
#PFinsidevmm_get_user_phys_from_dir) when the heap
had to grow after a process existed.heap_expand()mappedheap_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 firstkmalloclarge enough to grow the heap after boot (an
exec()from FAT16) exposed it. make run(or any target that needs the user programs) right aftermake cleanfailed 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)
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 aREADME.txtwith the QEMU command and what this ISO doesbooleos-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 throughhal.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) inkernel/multiboot2.h.
The kernel used to ignore the command line entirely (thedebugword of the
"serial debug mode" GRUB entry was never read).
- Console:
msg(ID), a central table for all user-visible text (one English
column; not a translation system):kernel/messages.h/.cfor the kernel
(boot log, errors, dumps, exception names,psstates) and
user/lib/messages.h/.cfor the shell, editor andcat(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/forktestandinit/spintestare 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,
execand 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'sreserved_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 withsafemodeon
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
offershelp,ls,cat,pwd,cd,backcalling FAT16 directly —
no processes, noexec; - GRUB entries "NullOS (Safe Mode)" (
safemodeflag) and "NullOS
v (previous release)", which boots the last release's kernel and
ramfs kept together in the trackedtools/prev/;make snapshotrecords
the current build there (run by hand after tagging a release, never
automatically).tools/prev/holds the v0.17.1 build.
- a boot configuration store in one raw sector (LBA 1, inside FAT16's
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 infs/fat16.c, andidt.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 throughhal_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
kmainmarks 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 inPROGRESS.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.shpasses-R 8tomkfs.vfatso sector 1 is explicitly
outside FAT16 (existing disks already have it: 4 reserved sectors).PROGRESS.mdrecords 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), andeditwith no file name
cannot save (Ctrl+S reports the misleading "saved (no disk)").kernel/version.h:0.18.0, phase18, "Safety/portability foundation".
Fixed
pmm_free_pages()over-reported by the total page count since Phase 2:
pmm_usedstarted at 0 while the bitmap started all-used, so releasing a
region drove it negative (the old boot log showedFree: 61440KBfor
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
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 aREADME.txtwith the QEMU command and what this ISO doesbooleos-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/13with 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-childwaitpidand the 3-levelmkdir/cd) and the current
[INFO] cleanuptext.README.md: the "Build" section now listsmake run-reboot-test(make runwithout-no-reboot, sorebootreally restarts the guest) and
make inject(copies a file intobuild/disk.imgwithmcopywithout
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:lseekmoved into
Phase 29 (general polish, next tomv/cp), the deferred Windows test of
docs/setup.mdwas 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 userlandmalloc/free.
The plan now covers Phases 17–30, with v1.0.0 right after Phase 30.
PROGRESS.mdrange 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 intomainwas 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)
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 aREADME.txtwith the QEMU command and what this ISO doesbooleos-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 anddocs/
files) and for planned Phases 17–31 including their sub-phases.docs/TODO.md: header-only file for minimal "WIP: document X"
stubs left duringnightlydevelopment, 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 gainedmemcpy/memset/memmove/memcmp/strlen/
strcmp/strncmp(standard libc names and signatures, so a call GCC
emits by itself resolves) andnos_uitoa; the four per-program copies
ofstrlen/uitoa, shell'sstrcmp/strncmp, selftest'sst_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 twonos_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.txtis 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(), shellpwd.cat <file>:user/cat.copens the file named by its argument and prints
it; with no argument it still copies stdin (pipe sink). The shell'scat <file>launches it and waits.sys_exec_pipe()clears the global
exec_argso a piped/redirectedcatnever reads the argument left by an
earlier plainexec().cmd < fileandcmd > filein the shell (run_redirected()): file fds
through the existingSYS_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(). SyscallsSYS_REBOOT(31) and
SYS_SHUTDOWN(32),nos_reboot()/nos_shutdown(), shellreboot/
shutdown.user/selftest.c: four new tests (18 total): a two-process pipeline
(afork()ed writer andcatlaunched withSYS_EXEC_PIPE, parent
compares the output),waitpidwith 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(seedocs/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 ofbuild/disk.imgwithmcopy, without rebuilding the ISO.
Host-side only — the kernel still can'texec()from FAT16 (Phase 19).tools/Makefile:make run-reboot-testruns QEMU without-no-reboot, so
rebootreally restarts the guest.runanddebugkeep-no-rebooton
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:runhas a single implementation,cmd_run(), shared by
the foreground path andrun_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 thenightly/mainbranch strategy,
-nightlyversion suffix, sub-phases, HAL, centralizedmsg()text
output, key=value system config file, and Safe Mode; serial-mirroring,
exec()/fork() threading and docs-verification rules extended; Safe Mode
rules nameprocess_spawn_user.PROGRESS.md: consolidated from 411 to ~150 lines (closed phases one
line each, decisions tightened with links todocs/).docs/:memory.md,filesystem.md,scheduler.md,pci.md,
kernel.md,shell.md,pipes.md,testing.md,syscalls.mdupdated
for everything above;docs/scheduler.mdno 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 overflowsuint32_t
for a hugemem_upperand wraps to a tinytotal_pages, underflowing
total_pages - 256. Now256 + 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, sinceprocess_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 ofbar[]stays 0. -
kernel/memory/vmm.c/vmm.h:vmm_map_page()and
vmm_map_user_page()now returnint(0 = success,VMM_ERR_RANGE
/VMM_ERR_NOMEMon failure) instead of failing silently asvoid;
map_page_early()reports an exhausted page-table pool.
vmm_map_user_page()also rejectsvirt < 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
failedpath. The threevmm_map_user_pagesites 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 andedit.ccould never see them; the
editor selects a newsc_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
shareddir_lookup()had dropped the old loop's directory skip — and
no longer re-reads the dirent sectordir_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 markedPROCESS_BLOCKED, pid
andwaiting_for_pidreset in the same section), fills in every
field, and only then publishesPROCESS_READY(or leaves it
PROCESS_BLOCKEDforstart_blocked). This closes two races: two
spawns picking the same free slot, and the scheduler running a slot
whoseesp/cr3weren't built yet. Newirq_save()/irq_restore()
helpers, also used byalloc_pid(). -
kernel/fs/fat16.c,fat16.h,vfs.c,vfs.h,kernel/syscall.c:
SYS_WRITEon a FAT16 fd lost data.sys_write()staged writes in
128-byte chunks and eachvfs_write()replaced the WHOLE file, so only
the last chunk survived a write over 128 bytes. Newfat16_write_at()
(positional write: grows the chain, updates the dirent, data -> FAT ->
dirent order) backs a streamvfs_write()that writes atfd->posand
advances it; the whole-file replaceSYS_WRITE_FILEneeds moved to
vfs_write_all(), so the editor's save is unchanged. -
user/shell.c: a bareeditorcat(no argument) printedcommand 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/\rright 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...