The Runtime

The entry point is not _start but a hand-written assembly trampoline that zeroes .bss, sets up the stack pointer from AT_RANDOM in the auxiliary vector, and calls main. The trampoline is small enough to inline in the binary — 16 bytes of ARM32 instructions.

.globl _start
_start:
    ldr sp, =stack_top
    bl main
    mov r7, #1
    svc #0

All I/O goes through svc #0 with the syscall number in r7. The runtime provides thin wrappers for read, write, exit, mmap, open, and close. No buffering, no errno — just the raw kernel ABI.

Commands

cat

Reads a file via open/read/write and dumps it to stdout. The buffer is 4kB (one page), allocated with mmap at startup and reused across calls. Error handling checks the return value of open and prints a syscall-based error message.

int cmd_cat(const char *path) {
    long fd = sys_open(path, 0, 0);
    if (fd < 0) return 1;
    long n;
    while ((n = sys_read(fd, buf, 4096)) > 0)
        sys_write(1, buf, n);
    sys_close(fd);
    return 0;
}

hexdump

Like cat but prints a hex+ASCII side-by-side view. Each line shows the offset, sixteen hex bytes, and the printable characters. The implementation reuses cat’s read loop and formats directly into the write buffer to avoid a second copy.

sysinfo

Calls sys_sysinfo() and prints the result: uptime, total RAM, free RAM, process count, and load averages. The sysinfo struct is defined locally since there’s no <sys/sysinfo.h>.

ls

Reads a directory via open (O_RDONLY|O_DIRECTORY) and getdents64. The struct linux_dirent64 is defined manually; the command iterates entries, skips . and .., and prints each name. This one touches more of the kernel ABI than the others — getdents64 is a less common syscall that most libc-free experiments overlook.

Why This Works

Each command is a self-contained demonstration of a specific kernel interface exercised from a minimal runtime. Together they show that a useful userspace — file I/O, directory traversal, system introspection — needs nothing more than the syscall interface and a willingness to define your own struct layouts. The entire runtime is ~300 lines of C and asm, and each command is under 50 lines. There is no startup overhead, no dynamic linker, no PT_INTERP segment.

Front-End

The lexer and parser are a single-pass recursive descent parser. The grammar is expression-oriented — everything returns a value, including blocks and conditionals. Types are inferred bottom-up; there is no type checker pass, just a typeof() that walks the AST at parse time.

typedef enum {
    NODE_INT, NODE_IDENT, NODE_BINOP,
    NODE_BLOCK, NODE_CALL, NODE_IF,
} node_kind;

typedef struct node {
    node_kind kind;
    struct node *kids[3];
    int ival;
    char *sval;
} node;

Middle-End: Rewrites

The middle-end applies a fixed set of tree rewrites before codegen: constant folding, dead-branch elimination, and tail-call identification. Each rewrite is a recursive walk that returns a (possibly new) node. The passes are cheap enough that we run them to fixpoint — typically two iterations exhaust all opportunities.

ARM32 Code Generation

The back-end walks the AST and emits instructions into a fixed-size buffer. Registers are allocated on the fly with a simple linear-scan scheme: the first four available registers (r0–r3) serve as the working set, and anything beyond that spills to the stack.

static void emit(node *n) {
    switch (n->kind) {
    case NODE_INT:
        emit_mov_imm(n->ival);
        break;
    case NODE_BINOP:
        emit(n->kids[0]);
        push();
        emit(n->kids[1]);
        pop_into_r1();
        switch (n->ival) {
        case '+': emit_add(); break;
        case '-': emit_sub(); break;
        case '*': emit_mul(); break;
        }
        break;
    case NODE_CALL:
        for (int i = 0; n->kids[i]; i++)
            emit(n->kids[i]);
        emit_bl(n->sval);
        break;
    }
}

Each emit_* function writes 2–4 bytes into the buffer and advances the cursor. The final buffer is a valid .text segment that can be mprotected to PROT_EXEC and called directly.

uint8_t *buf = mmap(NULL, 4096, PROT_READ|PROT_WRITE,
                     MAP_PRIVATE|MAP_ANONYMOUS, -1, 0);
// ... emit into buf ...
mprotect(buf, 4096, PROT_EXEC);
int (*fn)(int) = (int (*)(int))buf;
fn(42);

Syscall Wrappers

The runtime library replaces the C standard library with direct Linux syscalls via SVC instructions. Each wrapper follows the AAPCS calling convention — arguments in r0–r3, syscall number in r7, SVC #0 to trap, return value in r0.

// _exit(0)  →  mov r0, #0; mov r7, #1; svc #0
static void emit_syscall(int n) {
    emit_mov_imm(7, n);   // r7 = syscall number
    emit_svc(0);           // svc #0
}

The linker stub resolves symbolic calls like print_int to the corresponding syscall (write to stdout), so user code never needs to know the syscall table.

Status

The front-end handles the core language. The ARM32 code generator produces correct output for integer arithmetic, conditionals, and function calls. The syscall wrappers cover exit, write, read, and mmap. The missing pieces — structs, floats, a proper register allocator — are standard compiler engineering that builds on the pipeline already in place.

Raw Socket Setup

Raw sockets on Linux require CAP_NET_RAW (or root). The call is straightforward — socket(AF_PACKET, SOCK_RAW, htons(ETH_P_IP)) — which delivers every IP frame that reaches the interface.

int sock = socket(AF_PACKET, SOCK_RAW, htons(ETH_P_IP));
if (sock < 0) {
    perror("socket");
    return 1;
}

The socket is placed into promiscuous mode via PACKET_ADD_MEMBERSHIP with PACKET_MR_PROMISC. This tells the NIC to forward all frames, not just those addressed to our MAC, so we see traffic from other hosts on the same broadcast domain.

Packet Capture Loop

The capture thread reads from the raw socket into a fixed 64kB buffer and hands the buffer to a parser running in a second thread. The split keeps the capture side lossless — if the parser lags, the kernel buffer fills and drops packets in the NIC ring, not in userspace.

for (;;) {
    ssize_t n = recvfrom(sock, buf, sizeof(buf), 0, NULL, NULL);
    if (n < 0) break;
    parse_frame(buf, n);
}

TCP Header Parsing

parse_frame walks the protocol stack: Ethernet header → IP header → TCP header. Each step checks the relevant length field before advancing.

void parse_frame(uint8_t *buf, size_t len) {
    struct ethhdr *eth = (struct ethhdr *)buf;
    if (ntohs(eth->h_proto) != ETH_P_IP) return;

    struct iphdr *ip = (struct iphdr *)(buf + sizeof(struct ethhdr));
    size_t ip_hlen = ip->ihl * 4;
    if (ip->protocol != IPPROTO_TCP) return;

    struct tcphdr *tcp = (struct tcphdr *)((uint8_t *)ip + ip_hlen);
    // extract src_port, dst_port, seq, ack, flags
    // update connection table
}

Connection Tracking

The parser maintains a hash table of active connections keyed by the 4-tuple (src_ip, src_port, dst_ip, dst_port). Each entry tracks byte counts, packet counts, the current TCP state (from flags), and a rough RTT measured from SYN/SYN-ACK timing. Expired entries — those with no activity for 60 seconds — are evicted on every tenth iteration to keep the table bounded.

Real-Time Display

A curses-based UI refreshes the connection table once per second, printing per-connection bandwidth as a bar chart and flags as human-readable state:

192.168.1.20:44012 → 10.0.0.1:443  (ESTABLISHED)  1.2 MB   ████████░░
192.168.1.20:44013 → 10.0.0.1:443  (ESTABLISHED)  340 kB   ██░░░░░░░░
192.168.1.30:22   → 10.0.0.2:53041 (ESTABLISHED)  4.1 MB   ██████████

Packet capture at 60% with TCP header parsing already gives a useful picture of what crosses the wire. The missing pieces — reassembly, deeper protocol dissection, and a filter language — are natural extensions once the core loop is solid.