nulsl-libc/docs/architecture.md

Architecture

nulsl-libc is a from-scratch, C17, static-only libc for Linux, built for Null Linux's 32 MB target. This document explains how the pieces fit together. The short version: the kernel is the API, everything else is a wrapper, and nothing is allowed to make the process bigger than it needs to be.

Why static-only

A dynamically linked process carries the dynamic linker (ld.so) and its relocation machinery in memory for its entire lifetime. On a 32 MB budget that is pure overhead. nulsl-libc therefore builds only libc.a, links every program with -nostdlib -static, and ships its own crt0.o as the process entry point. There is no PT_INTERP in anything we build, and there is nothing to load.

This is also the project guideline: "If it's small, if it's lean, you have ZERO reason to link with libC at ALL. Linux specific syscalls can do you well." — so the libc itself goes straight to the kernel.

The syscall layer

┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│  stdio.c     │   │  stdlib.c    │   │  unistd.c    │
│  puts, putchar│  │  exit, atoi  │   │  read, write │
└──────┬───────┘   └──────┬───────┘   └──────┬───────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          ▼
                 ┌─────────────────┐
                 │   syscall.c     │   <-- the ONLY file that executes
                 │  raw syscall()  │       the `syscall` instruction
                 └────────┬────────┘
                          ▼
                   ┌────────────┐
                   │   Linux    │
                   │   kernel   │
                   └────────────┘

• src/syscall.c — variadic syscall(long number, ...), the only architecture-specific C code. On error the kernel returns -errno; syscall() translates that to the libc convention (-1 + errno).
• src/unistd.c, src/stdio.c, src/stdlib.c — wrappers and the hand-rolled pieces (string core in src/string.c).
• src/crt/crt0.S — _start, the process entry point. Sets up a valid frame, calls main(argc, argv), hands the return value to exit(). Kept out of libc.a on purpose: archive members are only extracted when referenced, and nothing references _start.

Modules

Module	Real today	Stubbed (roadmap)
src/string.c	strlen, strcmp, strncmp, strcpy, strncpy,	—
	memcpy, memmove, memset, memcmp
src/unistd.c	read, write, close, getpid, _exit	unlink
src/stdio.c	puts, putchar, fflush (trivially), FILE stubs	printf, fopen/fread/...
src/stdlib.c	exit, abort, atoi	malloc/calloc/realloc,
		free, strtol
src/syscall.c	raw syscall() (x86_64)	other architectures
src/crt/crt0.S	_start (x86_64)	other architectures

Stub convention

A function that is not implemented yet must:

1. be declared in the public header with its standard signature;
2. return its documented error value (-1, NULL, EOF, 0...);
3. set errno = ENOSYS;
4. carry a /* TODO: ... */ comment naming what it needs.

This keeps every stub link-clean and its failure mode explicit — programs fail loudly with a clear errno instead of silently misbehaving.

Conventions

• C17 only. -std=c17 is forced everywhere; configure refuses non-C17 compilers.
• Freestanding. Everything is compiled with -ffreestanding -fno-builtin, so the compiler never injects its own memcpy/strlen and the code you read is the code that runs.
• errno is a plain global for now (single-threaded). If threads ever land, it becomes a TLS slot behind the same header.
• FILE is a struct with one int fd until a buffering layer exists (src/internal.h owns the definition; the public header only forward- declares it).
• No dependencies. No libtool, no glibc, no kernel UAPI headers — the few syscall numbers we need live in include/sys/syscall.h.

Build layout

Makefile            driver (committed): make release / make debug / ...
configure.ac        autotools source (C17 enforced, static-only)
autogen.sh          autoreconf -i
bin/release/        out-of-tree build, CFLAGS='-O2'
bin/debug/          out-of-tree build, CFLAGS='-O0 -g'
include/            public headers (nothing but declarations)
src/                implementations (headers live elsewhere)
src/crt/crt0.S      process entry point (separate object)
benchmarks/         make bench — must stay lean
tests/              make check — smoke test links -nostdlib -static

The repository root is never configured in-tree: configure.ac refuses it so the driver Makefile cannot be clobbered. Release is always -O2.

Roadmap

• brk()-based allocator (malloc/calloc/realloc/free)
• printf engine
• open()/close()/read()/write() file I/O and a small buffering layer
• environ, getenv
• strtol with full base/errno semantics
• more architectures under src/arch/
• signals (only then: a real abort())