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.

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.