|
|
@@ -5,6 +5,36 @@ x86 assembly. Single-author project (~7,000 SLOC, no external runtime; the
|
|
|
kernel has no libc, while ring-3 commands may link the in-tree `libc.a`).
|
|
|
Targets i586 (first-gen Pentium); runs under QEMU or on real hardware.
|
|
|
|
|
|
+## Source tree
|
|
|
+
|
|
|
+| Directory | Contents |
|
|
|
+|-----------|----------|
|
|
|
+| `boot/` | `boot.S` (boot sector, `linker.ld`), `mbr.S`/`mbr.ld`, `vesa_stage.S` (linked first into `kernel.elf`), `boot/efi/` (UEFI loader) |
|
|
|
+| `kernel/` | The kernel, its drivers and services, `kernel.ld`, `ap_tramp.*`, `kexec_tramp.S`, `irqret.inc`; host tests `ccmp_test.c`, `touchpad_gesture_test.c` |
|
|
|
+| `common/` | Freestanding code linked into both kernel and userland: `inflate.c/h`, `font_8x16.c/h` |
|
|
|
+| `include/` | ABI headers shared by boot, kernel, userland and host tools: `syscall.h`, `wm_abi.h`, `version.h`, `bootinfo.h`, `phys.h`, `rootfs.h`, `wifi_cfg.h`, `rtl8821a_tbl.h` |
|
|
|
+| `user/` | `ucmd_lib.h` (the ring-3 syscall wrappers) and `ucmd.ld` |
|
|
|
+| `user/apps/<name>/` | One ring-3 program per directory: entry file `ucmd_<name>.c` plus private modules (`browser/` holds `browser.c`, `browser_html.c`, `js_*.c`, `svg_raster.c`; `chat/` holds `chat_login.c`; `gallery/` holds the real `gallery.c` behind the `ucmd_gallery.c` launcher; `hello/` has its own `hello.ld`) |
|
|
|
+| `user/lib/<lib>/` | Ring-3 libraries: `libc`, `ngui`, `ufont`, `img`, `tls` (crypto incl. `wpa_crypto.c`), `uhttp`, `ujson`, `uwm` (`uwm_lib.c`), `wifi` (`wifi_store.c`, `wpa.c`); host tests live next to their library |
|
|
|
+| `tools/` | Host tools (`mkpack.c`, `mkrootfs.c`, `mkrtwtbl.c`, `kexec_send.c`, `netkexec_send.c`, `netmonitor.c`, `flash.sh`) and the QMP test scripts |
|
|
|
+| `host/` | Linux SDL3 browser harness |
|
|
|
+
|
|
|
+The top-level `Makefile` builds everything. Objects go to `build/`
|
|
|
+(mirroring the source paths, with `-MMD` header dependencies); the images and
|
|
|
+the files the workflows use (`kernel.elf`, `kernel.bin`, `boot.bin`,
|
|
|
+`mbr.bin`, `floppy.img`, `usb.img`, `usb-efi.img`, `BOOTX64.EFI`, `cmds.pack`,
|
|
|
+`cmds_pack_gz.bin`, `rootfs*.bin`, `cmds.img`, `root.img`, `browser.elf`,
|
|
|
+`gallery.elf`, the host tools and test binaries) stay at the top level.
|
|
|
+Include paths: the kernel sees `include/`, `common/`, `kernel/`; ring-3 code
|
|
|
+sees `include/`, `common/`, `user/` and every `user/lib/*` (plus the libc
|
|
|
+headers unless an object clears `XFLAGS`). The kernel never includes a
|
|
|
+userland header; `user/apps/term/ucmd_term.c` is the one ring-3 file that
|
|
|
+uses kernel headers (`IO_KEY_*`, `VFS_PATH_MAX`) and gets `-Ikernel`.
|
|
|
+Per-object flags (`OPT`, `XFLAGS`) are target-specific variables on the
|
|
|
+`.o`; make does not track flag changes, so delete the object (or
|
|
|
+`make clean`) after editing one. The kernel link order is
|
|
|
+`KERNEL_LINK_ORDER` and is part of the image layout.
|
|
|
+
|
|
|
## Documentation site (`docs/`)
|
|
|
|
|
|
`docs/` is the static architecture site: hand-written HTML5, one shared
|
|
|
@@ -211,7 +241,7 @@ and `make net-dev`/`kernel-net-dev` reload over the network. `bootlog save
|
|
|
(~0.35-0.4 s after the kernel starts on QEMU's USB image).
|
|
|
4. `mbr.S` — MBR (USB/HDD boot); loads the active partition's boot sector
|
|
|
(partition 1 at LBA 63).
|
|
|
-5. **UEFI (`efi/`)** — an x86-64 PE32+ `BOOTX64.EFI` loads from the ESP. It
|
|
|
+5. **UEFI (`boot/efi/`)** — an x86-64 PE32+ `BOOTX64.EFI` loads from the ESP. It
|
|
|
picks a GOP mode, converts `GetMemoryMap` into the E820 map at `0x1000`,
|
|
|
stages `kernel.bin` below 4 GB, allocates a loader-data buffer below the
|
|
|
512 MB identity window (above the low 1 MB) for the embedded gz rootfs
|
|
|
@@ -324,7 +354,7 @@ it to `0x7E00`. The kernel region itself only has one wall (`_end` below
|
|
|
Process stacks (≥ `0x900000`) come from the frame allocator, with an 8-stack
|
|
|
fallback pool (a static BSS array; no fixed address).
|
|
|
- **UEFI boot**: `bootinfo.h` (the `0x500` block and its checksum/accessors),
|
|
|
- `efi/efi.h` (minimal UEFI types and table/protocol layouts), `efi/main.c`
|
|
|
+ `boot/efi/efi.h` (minimal UEFI types and table/protocol layouts), `boot/efi/main.c`
|
|
|
(GOP mode choice, `GetMemoryMap` → E820, kernel staging below 4 GB and
|
|
|
rootfs pack in loader-data pages below 512 MB, boot-info/framebuffer
|
|
|
blocks, `ExitBootServices`). The loader prefers the raw installed image:
|
|
|
@@ -333,9 +363,9 @@ it to `0x7E00`. The kernel region itself only has one wall (`_end` below
|
|
|
the kernel from P1 and the NBROOT1 gzip pack from P2. The kernel and pack
|
|
|
embedded in `BOOTX64.EFI` are only a fallback when the disk image is
|
|
|
missing or invalid, so `install`/`net-install` update both boot paths
|
|
|
- without rewriting the ESP. `efi/tramp.S` +
|
|
|
- `efi/tramp.ld` (the `0x800` long-mode exit, kernel copy and jump) and
|
|
|
- `efi/payload.S` (embeds `kernel.bin`, `cmds_pack_gz.bin` and the trampoline
|
|
|
+ without rewriting the ESP. `boot/efi/tramp.S` +
|
|
|
+ `boot/efi/tramp.ld` (the `0x800` long-mode exit, kernel copy and jump) and
|
|
|
+ `boot/efi/payload.S` (embeds `kernel.bin`, `cmds_pack_gz.bin` and the trampoline
|
|
|
in `BOOTX64.EFI`). The legacy `vesa_stage.S` writes the same v2 boot info
|
|
|
(with `pack_addr`/`pack_size`); `vga.c`/`panic.c` honour the RGBX flag and
|
|
|
skip the VBE-only ATI CRTC reset / NVIDIA stolen-VRAM alias under EFI;
|
|
|
@@ -1176,16 +1206,16 @@ it to `0x7E00`. The kernel region itself only has one wall (`_end` below
|
|
|
zeroed but pages appended by `SYS_MEM_GROW` are not (decoders initialize
|
|
|
what they use), which keeps large image arenas fast to map. The reaper
|
|
|
frees it with the rest of the process and `top` counts its pages. Ring-3
|
|
|
- commands use `libc/malloc.c` (malloc/free/heap_reset), which owns this
|
|
|
- arena; the `SYS_MEM_*` calls are the libc backend (`libc/ucmd_mem.c`) and
|
|
|
+ commands use `user/lib/libc/malloc.c` (malloc/free/heap_reset), which owns this
|
|
|
+ arena; the `SYS_MEM_*` calls are the libc backend (`user/lib/libc/ucmd_mem.c`) and
|
|
|
are not called by application code. The canvas mapping at
|
|
|
`USER_GFX_BASE` (`0x50000000`) and the WM mappings are separate.
|
|
|
-- **Ring-3 libc**: `libc/include/` (stddef/stdint/stdarg/stdlib/string/ctype/
|
|
|
+- **Ring-3 libc**: `user/lib/libc/include/` (stddef/stdint/stdarg/stdlib/string/ctype/
|
|
|
assert/ucmd_heap, setjmp/errno/stdio/math/time/sys/time/sys/types, float/
|
|
|
- limits/inttypes/alloca), `libc/malloc.c`, `libc/string.c`, `libc/strdup.c`,
|
|
|
- `libc/stdlib.c`, `libc/ucmd_mem.c`, `libc/setjmp.S`, `libc/errno.c`,
|
|
|
- `libc/div64.c`, `libc/dtoa.c`, `libc/stdio.c`, `libc/stdio_file.c`,
|
|
|
- `libc/math.c`, `libc/time.c`, linked as `libc.a` only into commands that
|
|
|
+ limits/inttypes/alloca), `user/lib/libc/malloc.c`, `user/lib/libc/string.c`, `user/lib/libc/strdup.c`,
|
|
|
+ `user/lib/libc/stdlib.c`, `user/lib/libc/ucmd_mem.c`, `user/lib/libc/setjmp.S`, `user/lib/libc/errno.c`,
|
|
|
+ `user/lib/libc/div64.c`, `user/lib/libc/dtoa.c`, `user/lib/libc/stdio.c`, `user/lib/libc/stdio_file.c`,
|
|
|
+ `user/lib/libc/math.c`, `user/lib/libc/time.c`, linked as `libc.a` only into commands that
|
|
|
reference it. `malloc` is a boundary-tag first-fit allocator with
|
|
|
immediate coalescing: 16-byte aligned, `calloc` zeroes, `realloc` grows in
|
|
|
place when the next block is free, and the heap maps 64 KB lazily then
|
|
|
@@ -1215,8 +1245,9 @@ it to `0x7E00`. The kernel region itself only has one wall (`_end` below
|
|
|
`/ramfs`. The
|
|
|
shell finds them through PATH (`/ramfs/bin` by default), loads the whole
|
|
|
ELF through the VFS and spawns it as a ring-3 process; `hello` is just
|
|
|
- `bin/hello`. New command: add `ucmd_<name>.c` to UCMDS — the pack, the
|
|
|
- mount and the PATH listing pick it up automatically. `SYS_SPAWN` still
|
|
|
+ `bin/hello`. New command: create `user/apps/<name>/ucmd_<name>.c` and add
|
|
|
+ `<name>` to UCMDS — the pack, the mount and the PATH listing pick it up
|
|
|
+ automatically (a command that links libraries also needs an `.elf` rule). `SYS_SPAWN` still
|
|
|
loads ELFs from any VFS mount, so commands can also live on `/share` or a
|
|
|
FAT disk (`path /share/bin`, or an absolute path). They talk to the kernel through
|
|
|
`int 0x80` (`syscall.h`: putstr/ticks/sleep/exit, the whole-file service in
|
|
|
@@ -2578,7 +2609,7 @@ and the WM falls back to polling (`io_keyboard_irq_masked()`).
|
|
|
|
|
|
27. Ring-3 stdio/time/math limits: `FILE` is read-only and whole-file
|
|
|
(4 MB cap); there is no `open/read/write/lseek`/fd layer yet, and
|
|
|
- `stdin` is EOF. The TODO is in `libc/stdio_file.c`; writable files and
|
|
|
+ `stdin` is EOF. The TODO is in `user/lib/libc/stdio_file.c`; writable files and
|
|
|
streaming need kernel `SYS_OPEN/READ/WRITE/LSEEK/CLOSE` plus offset
|
|
|
`fs_ops`. `time` is UTC-only, `time_t` is 64-bit, and the RTC range is
|
|
|
1970-2069; there is no timezone database. `math` is an x87
|