Refine headers and eliminate dead code

.gitignore

@@ -1,8 +1,8 @@
 *.o
+*.dSYM/
+*.ext4
 /kbox
 tests/unit/test-runner
-rootfs.ext4
-alpine.ext4
 deps/
 lkl-x86_64/
 lkl-aarch64/

Makefile

@@ -9,7 +9,7 @@ BUILD    ?= debug
 
 CFLAGS  += -std=gnu11 -D_GNU_SOURCE -Wall -Wextra -Wpedantic -Wshadow
 CFLAGS  += -Wno-unused-parameter
-CFLAGS  += -Iinclude
+CFLAGS  += -Iinclude -Isrc
 
 ifeq ($(BUILD),release)
   CFLAGS  += -O2 -DNDEBUG
@@ -44,7 +44,6 @@ endif
 SRC_DIR  = src
 SRCS     = $(SRC_DIR)/main.c \
            $(SRC_DIR)/cli.c \
-           $(SRC_DIR)/util.c \
            $(SRC_DIR)/syscall-nr.c \
            $(SRC_DIR)/lkl-wrap.c \
            $(SRC_DIR)/fd-table.c \
@@ -90,8 +89,7 @@ TEST_SUPPORT_SRCS = $(SRC_DIR)/fd-table.c \
                     $(SRC_DIR)/path.c \
                     $(SRC_DIR)/identity.c \
                     $(SRC_DIR)/syscall-nr.c \
-                    $(SRC_DIR)/elf.c \
-                    $(SRC_DIR)/util.c
+                    $(SRC_DIR)/elf.c
 
 TEST_OBJS    = $(TEST_SRCS:.c=.o) $(TEST_SUPPORT_SRCS:.c=.o)
 TEST_TARGET  = tests/unit/test-runner
@@ -228,14 +226,14 @@ clean:
 # Auto-generate with gcc -MM if needed; keep it simple for now.
 $(SRC_DIR)/main.o: include/kbox/cli.h include/kbox/image.h
 $(SRC_DIR)/cli.o: include/kbox/cli.h
-$(SRC_DIR)/probe.o: include/kbox/probe.h include/kbox/seccomp-defs.h
-$(SRC_DIR)/image.o: include/kbox/image.h include/kbox/lkl-wrap.h include/kbox/mount.h include/kbox/net.h include/kbox/identity.h include/kbox/probe.h include/kbox/seccomp.h
-$(SRC_DIR)/shadow-fd.o: include/kbox/shadow-fd.h include/kbox/lkl-wrap.h include/kbox/syscall-nr.h
-$(SRC_DIR)/seccomp-dispatch.o: include/kbox/seccomp.h include/kbox/seccomp-defs.h include/kbox/fd-table.h include/kbox/lkl-wrap.h include/kbox/procmem.h include/kbox/path.h include/kbox/identity.h include/kbox/shadow-fd.h include/kbox/net.h
-$(SRC_DIR)/seccomp-supervisor.o: include/kbox/seccomp.h include/kbox/seccomp-defs.h include/kbox/syscall-nr.h
-$(SRC_DIR)/seccomp-bpf.o: include/kbox/seccomp.h include/kbox/seccomp-defs.h include/kbox/syscall-nr.h
-$(SRC_DIR)/seccomp-notify.o: include/kbox/seccomp.h include/kbox/seccomp-defs.h
-$(SRC_DIR)/net-slirp.o: include/kbox/net.h include/kbox/lkl-wrap.h include/kbox/syscall-nr.h
-$(SRC_DIR)/web-telemetry.o: include/kbox/web.h include/kbox/lkl-wrap.h include/kbox/syscall-nr.h
-$(SRC_DIR)/web-events.o: include/kbox/web.h
-$(SRC_DIR)/web-server.o: include/kbox/web.h include/kbox/fd-table.h include/kbox/lkl-wrap.h include/kbox/syscall-nr.h
+$(SRC_DIR)/probe.o: include/kbox/probe.h src/seccomp-defs.h
+$(SRC_DIR)/image.o: include/kbox/image.h include/kbox/mount.h include/kbox/identity.h include/kbox/probe.h src/lkl-wrap.h src/net.h src/seccomp.h src/shadow-fd.h
+$(SRC_DIR)/shadow-fd.o: src/shadow-fd.h src/lkl-wrap.h src/syscall-nr.h
+$(SRC_DIR)/seccomp-dispatch.o: src/seccomp.h src/seccomp-defs.h src/fd-table.h src/lkl-wrap.h src/procmem.h include/kbox/path.h include/kbox/identity.h src/shadow-fd.h src/net.h
+$(SRC_DIR)/seccomp-supervisor.o: src/seccomp.h src/seccomp-defs.h src/syscall-nr.h
+$(SRC_DIR)/seccomp-bpf.o: src/seccomp.h src/seccomp-defs.h src/syscall-nr.h
+$(SRC_DIR)/seccomp-notify.o: src/seccomp.h src/seccomp-defs.h
+$(SRC_DIR)/net-slirp.o: src/net.h src/lkl-wrap.h src/syscall-nr.h
+$(SRC_DIR)/web-telemetry.o: src/web.h src/lkl-wrap.h src/syscall-nr.h
+$(SRC_DIR)/web-events.o: src/web.h
+$(SRC_DIR)/web-server.o: src/web.h src/fd-table.h src/lkl-wrap.h src/syscall-nr.h

include/kbox/cli.h

@@ -1,22 +1,18 @@
 /* SPDX-License-Identifier: MIT */
+
 #ifndef KBOX_CLI_H
 #define KBOX_CLI_H
 
 #include <stdbool.h>
 #include "kbox/mount.h"
 
-/*
- * CLI argument structures and parsing.
- *
- * Replaces Rust's clap derive macros with getopt_long.
- */
+/* CLI argument structures and parsing. */
 
 #define KBOX_MAX_BIND_MOUNTS 32
 #define KBOX_MAX_MOUNT_OPTS 16
 
 enum kbox_mode {
     KBOX_MODE_IMAGE,
-    /* KBOX_MODE_HOST deferred to post-MVP */
 };
 
 struct kbox_image_args {
@@ -27,8 +23,7 @@ struct kbox_image_args {
     unsigned part;        /* -p: partition number (0 = whole disk) */
     const char *work_dir; /* -w: working directory (default: /) */
     const char *command;  /* -c: command to execute (default: /bin/sh) */
-    const char
-        *cmdline; /* -k: kernel cmdline (default: mem=1024M loglevel=4) */
+    const char *cmdline;  /* -k: cmdline (default: mem=1024M loglevel=4) */
     const char *mount_opts[KBOX_MAX_MOUNT_OPTS];
     int mount_opt_count;
     const char *bind_mounts[KBOX_MAX_BIND_MOUNTS];
@@ -54,8 +49,7 @@ struct kbox_args {
     };
 };
 
-/*
- * Parse command-line arguments.
+/* Parse command-line arguments.
  * Returns 0 on success, -1 on error (message printed to stderr).
  */
 int kbox_parse_args(int argc, char *argv[], struct kbox_args *out);

include/kbox/elf.h

@@ -5,20 +5,17 @@
 #include <stddef.h>
 #include <stdint.h>
 
-/*
- * ELF interpreter (PT_INTERP) parsing.
+/* ELF interpreter (PT_INTERP) parsing.
  *
- * Pure computation on a byte buffer -- no file I/O.
+ * Pure computation on a byte buffer; no file I/O.
  * Used to detect dynamically linked binaries before execve.
  */
 
-/*
- * Parse the PT_INTERP segment from an ELF header buffer.
- *
- * buf:      at least 64 bytes of the ELF file header + program headers
- * buf_len:  length of buf
- * out:      buffer to write the interpreter path (NUL-terminated)
- * out_size: size of out buffer
+/* Parse the PT_INTERP segment from an ELF header buffer.
+ * @buf:      at least 64 bytes of the ELF file header + program headers
+ * @buf_len:  length of buf
+ * @out:      buffer to write the interpreter path (NUL-terminated)
+ * @out_size: size of out buffer
  *
  * Returns the length of the interpreter path on success (not including NUL),
  * 0 if no PT_INTERP segment (static binary), or -1 on malformed ELF.
@@ -28,13 +25,11 @@ int kbox_parse_elf_interp(const unsigned char *buf,
                           char *out,
                           size_t out_size);
 
-/*
- * Like kbox_parse_elf_interp, but also returns the file offset and
- * size of the PT_INTERP segment data.  Needed for in-place patching
- * of the interpreter path (e.g. rewriting to /proc/self/fd/N).
- *
- * offset_out: filled with the file offset (p_offset) of the interp string
- * filesz_out: filled with p_filesz of the PT_INTERP segment
+/* Like kbox_parse_elf_interp, but also returns the file offset and size of the
+ * PT_INTERP segment data. Needed for in-place patching of the interpreter path
+ * (e.g. rewriting to /proc/self/fd/N).
+ * @offset_out: filled with the file offset (p_offset) of the interp string
+ * @filesz_out: filled with p_filesz of the PT_INTERP segment
  *
  * Both outputs are only written when the return value is > 0.
  */

include/kbox/identity.h

@@ -1,4 +1,5 @@
 /* SPDX-License-Identifier: MIT */
+
 #ifndef KBOX_IDENTITY_H
 #define KBOX_IDENTITY_H
 
@@ -8,37 +9,31 @@
 
 struct kbox_sysnrs; /* forward declaration */
 
-/*
- * Identity management and permission normalization.
+/* Identity management and permission normalization.
  *
- * kbox can fake identity (uid/gid) inside the guest and normalize
- * displayed permissions to match realistic Linux defaults.
+ * kbox can fake identity (uid/gid) inside the guest and normalize displayed
+ * permissions to match realistic Linux defaults.
  */
 
-/*
- * Normalized permission entry for well-known paths.
- * Returns true if the path has a normalized permission, filling
- * out mode/uid/gid.
+/* Normalized permission entry for well-known paths.
+ * Returns true if path has a normalized permission, filling out mode/uid/gid.
  */
 bool kbox_normalized_permissions(const char *path,
                                  uint32_t *mode,
                                  uint32_t *uid,
                                  uint32_t *gid);
 
-/*
- * Simple hash of a username for generating consistent UIDs.
+/* Simple hash of a username for generating consistent UIDs.
  * Used by normalized_permissions for /home/<user>.
  */
 uint32_t kbox_hash_username(const char *name);
 
-/*
- * Parse a "UID:GID" identity specification.
+/* Parse a "UID:GID" identity specification.
  * Returns 0 on success, -1 on parse error.
  */
 int kbox_parse_change_id(const char *spec, uid_t *uid, gid_t *gid);
 
-/*
- * Apply guest identity inside LKL.
+/* Apply guest identity inside LKL.
  * If root_id is true, sets uid=0 gid=0.
  * If override_uid/gid >= 0, uses those.
  * Otherwise passthrough (no change).

include/kbox/image.h

@@ -1,11 +1,11 @@
 /* SPDX-License-Identifier: MIT */
+
 #ifndef KBOX_IMAGE_H
 #define KBOX_IMAGE_H
 
 #include "kbox/cli.h"
 
-/*
- * Image mode lifecycle.
+/* Image mode lifecycle.
  *
  * 1. Open the image file
  * 2. Register it as an LKL block device
@@ -18,8 +18,7 @@
  * 9. Run the supervisor loop
  */
 
-/*
- * Run image mode with the given arguments.
+/* Run image mode with the given arguments.
  * Returns 0 on success, -1 on error (message printed to stderr).
  */
 int kbox_run_image(const struct kbox_image_args *args);

include/kbox/mount.h

@@ -2,13 +2,12 @@
 #ifndef KBOX_MOUNT_H
 #define KBOX_MOUNT_H
 
-#include "kbox/syscall-nr.h"
+struct kbox_sysnrs; /* forward declaration */
 
-/*
- * Mount profile application.
+/* Mount profile application.
  *
- * Sets up recommended filesystems (proc, sysfs, devtmpfs, tmpfs)
- * and applies user-specified bind mounts.
+ * Sets up recommended filesystems (proc, sysfs, devtmpfs, tmpfs) and applies
+ * user-specified bind mounts.
  */
 
 enum kbox_mount_profile {
@@ -21,14 +20,12 @@ struct kbox_bind_spec {
     char target[4096];
 };
 
-/*
- * Parse a bind mount specification "SRC:DST".
+/* Parse a bind mount specification "SRC:DST".
  * Returns 0 on success, -1 on parse error.
  */
 int kbox_parse_bind_spec(const char *spec, struct kbox_bind_spec *out);
 
-/*
- * Apply mounts according to the given profile.
+/* Apply mounts according to the given profile.
  *   KBOX_MOUNT_FULL:    proc, sysfs, devtmpfs, devpts, tmpfs
  *   KBOX_MOUNT_MINIMAL: proc, tmpfs only
  * Assumes we are already chroot'd.
@@ -37,8 +34,7 @@ int kbox_parse_bind_spec(const char *spec, struct kbox_bind_spec *out);
 int kbox_apply_recommended_mounts(const struct kbox_sysnrs *s,
                                   enum kbox_mount_profile profile);
 
-/*
- * Apply bind mounts.
+/* Apply bind mounts.
  * Returns 0 on success, -1 on error.
  */
 int kbox_apply_bind_mounts(const struct kbox_sysnrs *s,