From 18b4dd0f6139e824ca3b27851354b13f0e6d8384 Mon Sep 17 00:00:00 2001 From: Maksymilian Wilczynski Date: Fri, 22 May 2026 09:08:05 +0200 Subject: [PATCH] readme enhancement --- readme.md | 67 +++++++++++++++---------------------------------------- 1 file changed, 18 insertions(+), 49 deletions(-) diff --git a/readme.md b/readme.md index f8b51ce..e98bb98 100644 --- a/readme.md +++ b/readme.md @@ -1,8 +1,8 @@ # NT-Lite -- an x86-64 kernel -## The Monster From ~~Redmond~~ Cracow +“Not only is UNIX dead, it’s starting to smell really bad.” - Rob Pike -Boots. Runs processes. Loads drivers. Plays video. Runs Doom. Has opinions. +“UNIX has three operations: read, write, and lie through ioctl.” ## what is it? @@ -54,29 +54,9 @@ Single address space for the whole system. No separate kernel/user page tables. Kernel lives in the higher half. User processes only see what they are explicitly given. Kernel pages are supervisor-only so user-mode code cannot touch them. User pages are isolated from each other through the allocator and process creation path, not by hardware address-space separation. One rogue pointer can't crash the kernel but it might corrupt other processes. But what are the chances? -Is this how a serious modern OS should isolate processes? No. - +Is this how a serious modern OS should isolate processes? No. Is it very convenient while building? Absolutely. -### boot chain - -Bootloader loads config, pulls in the core images, sets up the higher-half mapping, then jumps to `KernelMain`. - -From there: - -```text -HAL init -interrupts -paging -scheduler -boot drivers -filesystems -runtime drivers -self-tests -init.exe -shell -``` - ### execution model NT-Lite has a Windows-flavored execution model, but a simplified one. @@ -104,8 +84,6 @@ The important bit: interrupt -> DPC -> IoCompleteRequest -> APC -> alertable wait/user callback ``` -That is a real path, not a TODO scribbled in the margin. - ### I/O and filesystems Everything goes through the VFS. Disk access, filesystem parsing, path resolution, and process personalities are separate layers instead of one giant bowl of sadness. @@ -144,7 +122,7 @@ Currently shipping: ```text AHCI interrupt-driven SATA IDE PIO/DMA -FAT32 filesystem driver with VFAT long filename support +FAT32 filesystem driver with VFAT and all ``` ### processes, threads, and syscalls @@ -191,8 +169,6 @@ if (s == SYS_STATUS_PENDING) If the request completes by user APC, the alertable wait returns `SYS_STATUS_USER_APC`, the callback runs in user mode, and the original execution continues afterward. -That sentence used to be science fiction. Now it is boring. Excellent. - ## paths ```text @@ -204,9 +180,8 @@ That sentence used to be science fiction. Now it is boring. Excellent. "/1/apps/video.exe" -> volume 1 ``` -Volumes `0`-`7` are available. A volume only works if a filesystem is registered on it. The Win32 personality translates drive letters to volume numbers, while the POSIX personality maps volumes onto a tree. - -`0:/` is a mounted namespace, not a Windows path. It merely enjoys cosplay. +Volumes `0`-`7` are available. A volume only works if a filesystem is registered on it (duh). +The Win32 personality translates drive letters to volume numbers, while the POSIX personality maps volumes onto a tree. ## how to build @@ -247,20 +222,14 @@ apps/ video.exe ``` -## known truths - -- FAT32 works well enough to save `.doomrc` properly. -- Doom runs. -- Video playback works. -- Async file I/O exists. -- Process isolation is not strong. -- This is not production software. -- This is absolutely the wrong way to spend a weekend. - ## screenshots ![video.exe running bink video 2](image.png) +## TODO + +todo + ## faq Q: Why? @@ -269,29 +238,29 @@ A: Learning. Fun. Spite. Q: Does it run Doom? A: `doom.exe` -Q: Does Doom save its config correctly? -A: Yes. `.doomrc`, not cursed `.DOO` nonsense. VFAT forever! +Q: Can you read and write files? +A: As far as I'm aware. Q: Does it have async I/O? -A: Yes. Events, IOSBs, user APC callbacks, cancellation. Very suspiciously serious. +A: You didn't read the features list? Q: Is the Win32 layer real? -A: Real enough to load binaries that expect it. Not real enough to run Notepad. +A: Depends how you frame it. Some apps will run, most will not. Q: Are processes isolated? A: No. But IPC is free. Q: How often does it crash? -A: Less often than before, which is how civilizations begin. +A: Less often than before. Q: Can it recover from a crash? -A: Usually. Unless the kernel shat itself. +A: Yes. Unless the kernel faulted. Q: Is this finished? A: No. And it never will be. Q: Will it corrupt my data? -A: It should not. +A: It shouldn't. Q: Why is the path syntax so weird? A: It makes sense to me. @@ -300,7 +269,7 @@ Q: Why are the logs so verbose? A: How else do I debug it? Q: What should I read first? -A: This document. Then the scheduler. Then whatever hurt you last. +A: This document. Q: Can I use this in production? A: Don't.