Source Tree Reference

Source tree reference

Every source file in the NyxOS repository, with its purpose and size. Kernel line counts are from the v5.9.112 tree (the folder layout is unchanged since); the user/ tree gained the TinyCC port (user/tcc/, ~47 000 lines) in the v6.1–v6.4 Phase 2 work — see Toolchain.

Tree	Files	Lines
kernel/	148	109 213
user/ (excl. tcc/)	~70	~7 150
user/tcc/	~60	47 034

Important

The kernel source was reorganised into subject subfolders around v5.9.95 — kernel/*.c no longer sits flat. Objects still build flat into kernel/ (VPATH resolves each .c/.h/.asm from its folder), and quoted #includes are relative to the including file's own folder, e.g. gui/apps/selene_win.c includes "../../core/kernel.h". This page documents the current layout; older releases had everything under kernel/.

Note

kernel/fs/initramfs_data.h (71 663 lines) is a generated CPIO blob and, since v5.9.101, is no longer tracked in git — a clean checkout regenerates it via make. The image/*_vectors.h and crypto/x509_testchain.h headers are generate-once test fixtures that are tracked. Excluding the generated blob, the kernel is roughly 37 500 lines of hand-written code.

See also: Architecture, Building, Contributing, Kernel-Data-Structures

---

kernel/

Top level holds only the build glue.

File	Lines	Purpose
Makefile	—	VPATH over the subfolders; flat .o output; -Wall -Wextra -Wshadow, warning-clean
linker.ld	51	Section layout; load base 0x100000; captures -mcmodel=large .ldata/.lbss

kernel/core/ — boot, CPU setup, kernel entry (8061 lines)

File	Lines	Purpose
kernel.c	3294	kernel_main(), the kernel shell and all 104 builtins
kernel.h	1236	Types, constants, process_t, extern declarations, KERNEL_VERSION
syscall.c	1353	61-entry syscall dispatch, per-process fd table, user-copy helpers
smp.c	579	AP bringup, per-CPU state, TLB shootdown IPIs
smp.h	115	cpu_info_t, MAX_CPUS
isr_stubs.asm	497	Exception and IRQ entry stubs, AP stubs
boot.asm	164	Multiboot 1 + 2 headers, protected → long mode, 128 KB boot stack
isr.c	126	Exception dispatch, ring-3 fault → signal, panic
gdt.c	120	GDT, per-CPU TSS descriptors, ltr
trampoline.asm	109	Real-mode AP stub, embedded as a flat binary
switch.asm	87	Context switch
irq.c	86	IRQ handler registration, masking, EOI
stubs.asm	83	Assorted assembly helpers
spinlock.h	73	Test-and-set spinlocks
idt.c	56	IDT construction, gate installation
timer.c	51	PIT at 1000 Hz
umoddi3.c	32	64-bit division helper GCC emits calls to without libgcc

kernel/mm/ — memory management (1396 lines)

File	Lines	Purpose
paging.c	667	4-level paging, demand paging, COW, vm_handle_fault, PHYS_ADDR_MASK
memory.c	276	Bitmap physical allocator, multiboot2 memory map, kmalloc routing
mmap.c	257	User VMAs — anonymous and file-backed mmap/munmap/mprotect
slab.c	103	Fixed-size caches, 8 B–1024 B, free-list corruption check
heap.c	60	16 MB kernel heap, first-fit with walk-time coalescing
slab.h	33	SLAB_MAX_OBJ

kernel/proc/ — processes (2290 lines)

File	Lines	Purpose
process.c	1330	Process table, weighted round-robin scheduler, fork, clone, reaping
signal.c	318	POSIX-subset signals, delivery, sigreturn trampoline
shared_libc.c	230	The prelinked libc.so mapped into every process; dlopen/dlsym
elf.c	201	ELF64 loader
pipe.c	133	Anonymous pipes with reference-counted ends
elf.h	78	ELF structures and constants

kernel/fs/ — filesystem (74 290 lines, mostly generated)

File	Lines	Purpose
initramfs_data.h	71663	Generated, untracked — the CPIO archive as a C byte array
ext2.c	1197	Read/write EXT2 with a write-through sector cache
vfs.c	1184	Node pool, mount table, /proc and /dev generation, rename
ext2.h	150	On-disk structures
initramfs.c	73	CPIO newc unpacking
initramfs.h	23

kernel/net/ — networking (2231 lines)

File	Lines	Purpose
tcp.c	534	State machine, retransmission, listen/accept, in-order recv gate
net.c	386	BSD socket layer, 32 slots, echo services
http.c	257	HTTP/1.1 client, redirect Location, clamped request builder
ip.c	189	IPv4 send/receive, checksums, routing
dhcp.c	169	DISCOVER → OFFER → REQUEST → ACK
dns.c	169	A-record resolver
arp.c	143	16-entry ARP cache
icmp.c	143	Echo request/reply
udp.c	89	Datagrams and port listeners
tcp.h	75	tcp_conn_t, flags, states, RTO constants
ethernet.c	43	Frame construction and demultiplexing
http.h	26	http_response_t with location
dns.h	8

kernel/crypto/ — cryptographic primitives (3352 lines)

File	Lines	Purpose
p384.c	352	secp384r1 arithmetic, ECDSA-P384 verify
p256.c	326	secp256r1 arithmetic, ECDSA-P256 verify
x509_testchain.h	326	Test-vector chain for chaintest
der.c	314	DER/ASN.1 reader, hardened X.509 date parser
rsa.c	312	PKCS#1 v1.5 (SHA-256 and SHA-512) + PSS verification
aes_gcm.c	291	AES-128-GCM seal/open
x509.c	273	Chain verification, SAN and validity checks
curve25519.c	219	X25519
sha256.c	184	SHA-256, HMAC, PBKDF2
sha512.c	172	SHA-512, SHA-384
csprng.c	159	HMAC_DRBG-SHA256 with RDSEED/RDRAND seeding
x509_roots.h	149	Five pinned trust anchors
der.h	68
sha256.h	32	PBKDF2_ITERATIONS = 10000
aes_gcm.h / rsa.h / p256.h / p384.h / csprng.h / curve25519.h / x509.h / sha512.h	14–32	Headers

kernel/crypto/tls/ — TLS 1.2 (981 lines)

File	Lines	Purpose
tls.c	816	Handshake, key schedule, record layer, SKE dispatch for all 5 sig schemes
tls_prf.c	110	TLS 1.2 PRF, P_SHA256
tls.h	38
tls_prf.h	17

kernel/image/ — image decoders (3352 lines)

File	Lines	Purpose
jpeg_vectors.h	1320	Test vectors for jpegtest
gif_vectors.h	438	Test vectors for giftest
jpeg.c	405	Baseline JPEG — Huffman, IDCT, YCbCr, fancy upsampling
inflate.c	345	DEFLATE (RFC 1951) + zlib (RFC 1950)
gif.c	307	GIF87a/89a, LZW, interlace, animation, NETSCAPE loop count
png.c	273	PNG decoder, all five scanline filters
bmp.c	156	BMP — 24/32-bit and 8-bit palette, both row orders
gif.h	30	gif_anim_t, gif_frame_t, loop_count
png.h / jpeg.h / bmp.h / inflate.h / image.h	12–18	Headers, and the shared image_t

kernel/drivers/ — device drivers (2995 lines across five subfolders)

drivers/video/ (1199)

File	Lines	Purpose
fb.c	370	Framebuffer primitives, double buffering, clip region
screen.c	350	Text-mode console
font.c	338	IBM VGA 8×16 ROM font, 256 glyphs
vbe.c	122	Bochs VBE mode setting
font.h	19

drivers/misc/ (605)

File	Lines	Purpose
apic.c	214	Local APIC + I/O APIC
ata.c	112	ATA PIO driver
apic.h	101	APIC register and flag definitions
rtc.c	82	CMOS real-time clock
serial.c	40	Serial console
ata.h / rtc.h	27–29	Headers

drivers/input/ (510)

File	Lines	Purpose
keyboard.c	380	PS/2 keyboard, US/ES layouts, raw key-event ring
mouse.c	130	PS/2 mouse, 3-byte packets, wheel

drivers/audio/ (438)

File	Lines	Purpose
sb16.c	291	Sound Blaster 16 — DSP, DMA, mixer
sb16.h	76	Ports and commands
speaker.c	43	PC speaker via PIT channel 2
speaker.h	28

drivers/net/ (243)

File	Lines	Purpose
rtl8139.c	243	The only NIC driver — PCI Ethernet

kernel/gui/ — compositor, apps, games (9384 lines across three subfolders)

gui/core/ (3239)

File	Lines	Purpose
compositor.c	2576	Window manager — z-order, workspaces, taskbar, Start menu, icons, snapping
bootsplash.c	207	Boot animation, 23-step progress bar
gui.c	144	The gui demo command
compositor.h	111	window_t and the application contract
theme.h	79	The Nightfall palette — every colour as a named role
wallpaper_win.c	70	Wallpaper colour picker
nyx_logo.h	29	Crescent-moon ASCII art
bootsplash.h / wallpaper_win.h	8–15	Headers

gui/apps/ (4988)

File	Lines	Purpose
selene_win.c	2098	Selene, the web browser — HTML layout, forms, tables, lists, entities
fileman_win.c	913	File manager
terminal_win.c	441	Terminal emulator, CSI parser, scrollback
editor_win.c	351	GUI text editor
paint_win.c	259	Paint
calc_win.c	201	Calculator
soundtest_win.c	199	Sound test
imageview_win.c	152	Image viewer
taskman_win.c	108	Task manager
*_win.h	16–54	Per-app headers

gui/games/ (1157)

File	Lines	Purpose
minesweeper_win.c	382	Minesweeper
tetris_win.c	228	Tetris
snake_win.c	154	Snake
games_win.c	138	The Games folder shelf
pong_win.c	126	Pong
*_win.h	17–44	Per-game headers

kernel/auth/ — accounts (830 lines)

File	Lines	Purpose
auth.c	457	PBKDF2 credential store on EXT2, random salts
login.c	340	Framebuffer login and create-account panel
login.h	17	LOGIN_MAX_ATTEMPTS = 3
auth.h	16	AUTH_MIN_PASS = 4

kernel/doom_src/

The third-party doomgeneric engine sources, excluded from warning sweeps and dead-code audits.

---

user/

Unchanged by the reorg — still flat. Full program descriptions in Userspace and Command-Reference.

Runtime

File	Lines	Purpose
syscall.h	640	Every syscall wrapper, shared structs, all flag constants (a __TINYC__ path for syscall6)
libc.c	738	The freestanding C library — grown compiler-complete in Phase 2 (stdio, ctype, strtod, …)
libc.h	146	Its public surface
crt0.asm	38	Entry point, argc/argv/envp, __sigreturn trampoline, [abs] operands
nyxrt.c	41	Nyx C runtime
nyxrt.h	51	Nyx C types and ABI
libdemo.c	29	Demonstration shared library for dlopen

Toolchain — user/tcc/

The vendored TinyCC 0.9.27 port (~47 034 lines), cross-compiled with host GCC into /tcc.elf, the in-OS C compiler. Only the x86-64/ELF backend is used; the other targets ship but are unbuilt. Full detail in Toolchain.

File	Lines	Purpose
tccgen.c	7 386	Code generator — the front-end's type/expression engine
tccpp.c	3 903	Preprocessor and lexer
tccelf.c	3 079	ELF object/executable writer + static linker (the static-PLT fix lives here)
x86_64-gen.c	2 258	x86-64 machine-code emitter
libtcc.c	1 981	The compiler driver library
tcc.c	371	The main() command-line front-end
nyxshim/	~500	Host-header-free shims (config.h, nyxshim.c, freestanding <stdio.h> etc.)
i386-asm.c, tccasm.c, tccrun.c, elf.h, …	—	Assembler, run stubs (unused), and shared headers

Shell and interactive

File	Lines	Purpose
sh.c	1042	The userspace shell — pipelines, redirection, job control, globbing, quoting
edit.c	221	Full-screen nano-style editor
less.c	134	Pager, also built as more
top.c	67	Live process monitor

Coreutils

cat wc ls cp mv rm mkdir touch grep head tail sort find stat echo upper which clear env date sleep uname whoami free pmap — 11–67 lines each.

Network tools

File	Lines	Purpose
wget.c	285	HTTP client with its own DNS-over-UDP resolver
nc.c	99	Netcat, full-duplex over poll()

DOOM

File	Lines	Purpose
doom_userlibc.c	633	The libc surface the DOOM engine expects
doomgeneric_nyxos.c	116	Platform hooks — fbpresent, getkeyevent
doom_nullsound.c	71	Null sound backend

Tests and demos

init.c (601, the syscall regression suite), threads.c (120), ps.c kill.c, and the reproducers pstorm bigread netstorm vfsfill stacktest vmtest munmaptest mprotecttest dltest fdleak fsx sockdemo srvdemo udpdemo polldemo keyevtest fbtest alarmdemo sigrec segv fault args spin hello hello_nyx. See Userspace for what each proves.

---

Other trees

Path	Contents
tools/mkinitramfs.py	Generates fs/initramfs_data.h from the user/ tree (deterministic)
docs/	The project website — index.html, style.css, script.js
iso/	GRUB staging directory for grub-mkrescue
.github/	Issue templates, PR template, workflows, Dependabot

Root files

File	Purpose
AGENTS.md	The authoritative development log and release table
README.md	Project overview
CONTRIBUTING.md	Coding standards and workflow — see Contributing
SECURITY.md	Vulnerability reporting policy
build.ps1 / run.ps1	Build through WSL, then launch QEMU — see Building
ext2-test.img	The EXT2 data disk, mounted at /mnt
doom1.wad	DOOM shareware data

---

Largest hand-written files

The ten files most worth knowing before making a change (excluding generated blobs and test vectors).

Rank	File	Lines
1	core/kernel.c	3294
2	gui/core/compositor.c	2576
3	gui/apps/selene_win.c	2098
4	core/syscall.c	1353
5	proc/process.c	1330
6	core/kernel.h	1236
7	fs/ext2.c	1197
8	fs/vfs.c	1184
9	user/sh.c	1042
10	crypto/tls/tls.c	816

See also

• Architecture — how these files relate, and the folder-structure diagram
• Building — how they are compiled and linked (VPATH, warning flags)
• Kernel-Data-Structures — the structures they define
• Contributing — coding standards

External resources

• NyxOS repository — GitHub