Skip to content

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

Choose a tag to compare

@TheShannonDev TheShannonDev released this 28 Sep 00:30
· 21 commits to main since this release

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