Phase T6: drop objcopy

#include "ld.h"
#include "elf_format.h"

#include <stdio.h>
#include <string.h>

static uint32_t align4(uint32_t x) { return (x + 3) & ~3u; }

/* Hardcodes exactly kernel/link.ld's layout - base address, section
 * order, and the _bss_start/_bss_end symbols entry.S relies on to zero
 * .bss (see docs/toolchain.md on why a general linker-script language
 * isn't implemented). */
void flat_assign_addresses(link_ctx_t *ctx, uint32_t base) {
    uint32_t addr = base;
    ctx->merged_addr[SEC_TEXT] = addr;
    addr = align4(addr + ctx->merged_size[SEC_TEXT]);
    ctx->merged_addr[SEC_RODATA] = addr;
    addr = align4(addr + ctx->merged_size[SEC_RODATA]);
    ctx->merged_addr[SEC_DATA] = addr;
    addr = align4(addr + ctx->merged_size[SEC_DATA]);
    ctx->merged_addr[SEC_BSS] = addr;
    uint32_t bss_end = addr + ctx->merged_size[SEC_BSS];

    out_symbol_t *s1 = &ctx->out_syms[ctx->n_out_syms++];
    safe_strcpy(s1->name, "_bss_start", MAX_NAME);
    s1->addr = ctx->merged_addr[SEC_BSS];
    s1->defined = 1;

    out_symbol_t *s2 = &ctx->out_syms[ctx->n_out_syms++];
    safe_strcpy(s2->name, "_bss_end", MAX_NAME);
    s2->addr = bss_end;
    s2->defined = 1;
}

typedef struct {
    char buf[1 << 16];
    uint32_t len;
} strtab_t;

static uint32_t strtab_add(strtab_t *st, const char *s) {
    if (st->len == 0) { st->buf[0] = '\0'; st->len = 1; }
    uint32_t off = st->len;
    size_t n = strlen(s) + 1;
    memcpy(st->buf + st->len, s, n);
    st->len += (uint32_t)n;
    return off;
}

static const char *SEC_NAMES[SEC_KIND_COUNT] = { ".text", ".rodata", ".data", ".bss" };

int write_flat_elf(link_ctx_t *ctx, const char *path, uint32_t base) {
    (void)base;

    static strtab_t strtab, shstrtab;
    memset(&strtab, 0, sizeof(strtab));
    memset(&shstrtab, 0, sizeof(shstrtab));

    /* section index plan: 0=NULL, 1..4=.text/.rodata/.data/.bss (only
     * those with nonzero size), then .symtab, .strtab, .shstrtab */
    int shidx[SEC_KIND_COUNT];

1	#pragma once
2	/* LD: linker. See docs/toolchain.md for exactly what's supported and
3	 * why. Native host tool (build infrastructure), not OS code.
4	 *
5	 * Two output modes, both sharing the same merge/resolve/relocate core
6	 * (main.c): `link_flat` (kernel/link.ld's single-load-address layout -
7	 * .text/.rodata/.data/.bss concatenated at a fixed base, for OBJCOPY to
8	 * turn into a flat kernel image) and `link_static_exec` (a minimal
9	 * static ELF32 executable the Linux kernel can run directly, for host
10	 * tools - one PT_LOAD segment, no dynamic linking). Neither mode
11	 * implements a general linker-script language: `link_flat`'s layout is
12	 * hardcoded to match kernel/link.ld exactly (see link_flat.c), since
13	 * that is the only layout this project's kernel ever needs. */
14	
15	#include <stdint.h>
16	#include <stddef.h>
17	
18	static inline void safe_strcpy(char *dst, const char *src, size_t dstsize) {
19	    size_t i = 0;
20	    for (; i + 1 < dstsize && src[i]; i++) dst[i] = src[i];
21	    dst[i] = '\0';
22	}
23	
24	#define MAX_INPUT_FILES 32
25	#define MAX_SECTIONS_PER_FILE 16
26	#define MAX_SYMS_PER_FILE 512
27	#define MAX_RELOCS_PER_FILE 512
28	#define MAX_NAME 128
29	
30	typedef enum { SEC_TEXT, SEC_RODATA, SEC_DATA, SEC_BSS, SEC_KIND_COUNT, SEC_KIND_OTHER } sec_kind_t;
31	
32	typedef struct {
33	    char name[MAX_NAME];
34	    sec_kind_t kind;    /* classified from the section name; SEC_KIND_OTHER is skipped (e.g. .symtab) */
35	    int is_nobits;         /* .bss: no file content, size still counts */
36	    uint32_t file_off;       /* offset of this section's bytes within in_file_t.data (PROGBITS only) */
37	    uint32_t size;
38	    uint32_t merged_off;      /* filled in during layout: offset within the OUTPUT section of this kind */
39	} in_section_t;
40	
41	typedef struct {
42	    char name[MAX_NAME];
43	    int defined;          /* 0 = extern/undefined in this file */
44	    int is_global;
45	    int section_idx;         /* index into this file's sections[], -1 if undefined */
46	    uint32_t value;             /* offset within that section, as given by the object file */
47	} in_symbol_t;
48	
49	typedef struct {
50	    int section_idx;    /* which of this file's sections the relocation patches */
51	    uint32_t offset;       /* byte offset within that section */
52	    int symbol_idx;          /* which of this file's symbols is referenced */
53	    int type;                  /* R_386_32 or R_386_PC32 */
54	} in_reloc_t;
55	
56	typedef struct {
57	    char filename[256];
58	    uint8_t *data;
59	    uint32_t data_len;
60	
61	    in_section_t sections[MAX_SECTIONS_PER_FILE];
62	    int n_sections;
63	    in_symbol_t syms[MAX_SYMS_PER_FILE];
64	    int n_syms;
65	    in_reloc_t relocs[MAX_RELOCS_PER_FILE];
66	    int n_relocs;
67	} in_file_t;
68	
69	/* Global (whole-link) symbol table entry - one per unique defined name
70	 * across all input files, with its final linked address filled in once
71	 * layout is decided. */
72	typedef struct {
73	    char name[MAX_NAME];
74	    uint32_t addr;
75	    int defined;
76	} out_symbol_t;
77	
78	#define MAX_OUT_SYMS 2048
79	
80	typedef struct {
81	    in_file_t files[MAX_INPUT_FILES];
82	    int n_files;
83	
84	    out_symbol_t out_syms[MAX_OUT_SYMS];
85	    int n_out_syms;
86	
87	    /* Merged section byte buffers - PROGBITS content only; .bss has no
88	     * bytes here, just a size (merged_size[SEC_BSS]). */
89	    uint8_t *merged_data[SEC_KIND_COUNT];
90	    uint32_t merged_size[SEC_KIND_COUNT];
91	    uint32_t merged_addr[SEC_KIND_COUNT]; /* filled in during layout */
92	} link_ctx_t;
93	
94	/* elf_reader.c */
95	int read_object(const char *path, in_file_t *out);
96	
97	/* main.c: shared merge/resolve/relocate core, used by both output modes */
98	out_symbol_t *find_out_sym(link_ctx_t *ctx, const char *name);
99	
100	/* link_flat.c / link_static_exec.c: each mode exposes an address-
101	 * assignment step (called before symbol resolution/relocation in
102	 * main.c, since both need final addresses) and a writer (called after). */
103	void flat_assign_addresses(link_ctx_t *ctx, uint32_t base);
104	int write_flat_elf(link_ctx_t *ctx, const char *path, uint32_t base);
105	
106	void static_exec_assign_addresses(link_ctx_t *ctx);
107	int write_static_exec_elf(link_ctx_t *ctx, const char *path);
108	

109	int main(int argc, char **argv) {
110	    const char *outpath = NULL;
111	    const char *inputs[MAX_INPUT_FILES];
112	    int n_inputs = 0;
113	    int flat_mode = 0;
114	    uint32_t flat_base = 0x10000;
115	
116	    for (int i = 1; i < argc; i++) {
117	        if (strcmp(argv[i], "-o") == 0 && i + 1 < argc) { outpath = argv[++i]; }
118	        else if (strcmp(argv[i], "-T") == 0 && i + 1 < argc) {
119	            /* Linker-script *presence* is the flat-mode switch; the
120	             * script's own contents are never read - link_flat.c
121	             * hardcodes the one layout this project's kernel needs
122	             * (see docs/toolchain.md). */
123	            flat_mode = 1;
124	            i++;
125	        }
126	        else if (strcmp(argv[i], "--flat-base") == 0 && i + 1 < argc) {
127	            flat_base = (uint32_t)strtoul(argv[++i], NULL, 0);
128	        }
129	        else if (strcmp(argv[i], "-m") == 0 && i + 1 < argc) { i++; /* -m elf_i386: accepted, always true */ }
130	        else if (strcmp(argv[i], "-nostdlib") == 0) { /* accepted, always true - no libc ever linked */ }
131	        else if (argv[i][0] == '-') { fprintf(stderr, "ld: unrecognized option '%s'\n", argv[i]); return 1; }
132	        else { if (n_inputs < MAX_INPUT_FILES) inputs[n_inputs++] = argv[i]; }
133	    }
134	    if (!outpath || n_inputs == 0) {
135	        fprintf(stderr, "usage: ld [-T <script>] [--flat-base 0xADDR] -o <out> <in.o>...\n");
136	        return 1;
137	    }
138	
139	    static link_ctx_t ctx;
140	    memset(&ctx, 0, sizeof(ctx));
141	    for (int i = 0; i < n_inputs; i++) {
142	        if (read_object(inputs[i], &ctx.files[ctx.n_files]) != 0) return 1;
143	        ctx.n_files++;
144	    }
145	
146	    merge_sections(&ctx);
147	
148	    if (flat_mode) {
149	        flat_assign_addresses(&ctx, flat_base);
150	    } else {
151	        static_exec_assign_addresses(&ctx);
152	    }
153	
154	    build_global_symbol_table(&ctx);
155	    apply_relocations(&ctx);
156	
157	    int rc = flat_mode ? write_flat_elf(&ctx, outpath, flat_base) : write_static_exec_elf(&ctx, outpath);
158	    return rc == 0 ? 0 : 1;

330	differs from GNU ld's output): the full `tests/toolchain/*.c` battery
331	linked by LD and run directly (matching Phase T4's expected exit codes);
332	the kernel linked by LD from a mix of nasm- and AS-assembled objects,
333	booted in QEMU to `SELFTEST PASS` and a working interactive shell
334	(scripting language, bytecode compiler+VM, tinyfs - via
335	`tools/qemu_type.py`); and `tools/mkfs_tinyfs` itself - `kernel/fs/tinyfs.c`,
336	`kernel/string.c`, and `tools/mkfs_tinyfs.c` compiled by `CC
337	--target=host`, assembled by AS, linked by LD in `link_static_exec` mode,
338	then actually run to format a real disk image, which then boots and
339	passes the full `tools/run_tests.sh` suite.
340	
341	That last check surfaced five real, previously-latent bugs - none of them
342	in LD itself, but in CC/AS paths LD's static_exec mode was the first
343	thing to actually exercise end-to-end:
344	
345	- **CC preprocessor**: `#include`'s per-depth path buffer
346	  (`static char paths[MAX_INCLUDE_DEPTH][600]`) was reused by every
347	  sibling include at the same nesting depth, and `token_t.file` stores
348	  that pointer directly (no copy) - a later sibling `#include`
349	  overwriting the buffer retroactively "changed" the filename recorded
350	  on every earlier token from the previous sibling. Fixed by giving each
351	  include its own permanently-allocated path. Also, macro-in-macro
352	  expansion only substituted one level deep (`TINYFS_DATA_BLOCK` ->
353	  `(TINYFS_INODE_BLOCK + ...)` left `TINYFS_INODE_BLOCK` unexpanded) -
354	  replaced with a proper recursive expander guarded against
355	  self-reference.
356	- **CC codegen - `_start`**: emitted unconditionally in every
357	  `--target=host` translation unit, so a multi-file host program
358	  (`mkfs_tinyfs.c` + `tinyfs.c` + `string.c`) got a `call main` baked into
359	  files that don't define `main`, which AS then couldn't resolve
360	  (there's no separate crt0.o in this toolchain). Now only emitted by the
361	  one unit that actually defines `main`. Relatedly, `_start` originally
362	  did a bare `call main` - `call` itself pushes a return address, so
363	  `argc` landed in the right cdecl slot by coincidence but `argv`
364	  received `argv[0]`'s string-pointer value instead of `&argv[0]`; fixed
365	  by loading argc/argv explicitly from `[esp]`/`[esp+4]` before the call.
366	- **CC codegen - top-level string/extern collection**: `walk_collect`
367	  recurses into `->next` (needed for statement sibling chains reached via
368	  `->list`), but the top-level driver in `codegen_emit` *also* iterates
369	  `n = n->next` while calling `walk_collect(n, prog)` on each node - so
370	  each call re-walked the entire remaining top-level chain, duplicating
371	  every string literal and extern once per remaining prefix.
372	- **CC codegen - static locals never allocated**: the `.data`/`.bss`
373	  emission loops only scanned `prog`'s top-level chain, but a `static`
374	  local variable is declared inside a function body's statement list -
375	  so `lea eax, [__static_N]` was emitted at every use site with no
376	  matching `global __static_N` / storage anywhere, an unresolvable
377	  symbol. Fixed by collecting static locals during the same recursive
378	  walk used for strings/externs.
379	- **CC codegen - function values didn't decay to a pointer**: a bare
380	  function name used as a value (`tinyfs_init(disk_block_read, ...)`,
381	  passing a callback) went through the same `ND_VAR` path as an ordinary
382	  global - compute its address, then *dereference* it - which read the
383	  function's own machine code bytes as if they were a stored pointer.
384	  Fixed by skipping the dereference for `TY_FUNC`-typed values.
385	- **CC codegen - no indirect calls**: calling *through* a function-pointer
386	  variable (`block_read(...)` where `block_read` is a `static
387	  tinyfs_block_read_fn`, assigned via `tinyfs_init`) always emitted a
388	  direct `call block_read` - a jump straight into the `.bss` bytes
389	  holding the pointer value, executed as instructions. The parser now
390	  detects when a call's callee resolves to a variable rather than a
391	  function symbol and marks the call indirect; codegen loads the stored
392	  pointer and emits `call eax`. AS gained the corresponding `call r/m32`
393	  (`FF /2`) encoding - previously only the direct relative form
394	  (`E8 rel32`) existed.
395	- **AS - 3-operand `imul` silently dropped its immediate**: the operand
396	  parser had a hard 2-operand ceiling (`ops[2]`, no comma check after the
397	  second operand), so `imul ecx, ecx, 4` (CC's array-indexing scale, e.g.
398	  `argv[1]`) parsed as `ecx, ecx` with `, 4` silently discarded, then
399	  encoded as the 2-operand register-multiply form (`ecx = ecx*ecx`
400	  instead of `ecx*4`). This is a general, silent miscompilation of any
401	  runtime-indexed array/pointer access with a non-constant-folded scale -
402	  it went undetected by `tests/toolchain/t04_pointers.c` because that
403	  test's array *writes* and *reads* both use the identical broken
404	  formula (self-cancelling: `nums[i] = i*2` stores at `base+i*i`, and
405	  `a[i]` in the summing loop reads back from `base+i*i` too), so the
406	  final sum still came out right despite the underlying addresses being
407	  wrong. It only surfaced when reading data written through a *different*
408	  mechanism using real offsets - the kernel-provided `argv[]` array.
409	  Fixed by extending `stmt_t.ops[]` to 3 slots and adding the proper
410	  `imul r32, r/m32, imm32` encoding (`0x69 /r id`, always full imm32 -
411	  same "no imm8 sign-extend optimization" convention the group1 ALU ops
412	  already use).
413	
414	## OBJCOPY
415	
416	Not yet built - Phase T6. Everything so far extracts the flat kernel
417	binary with GNU `objcopy -O binary` as an interim step.
418	
419	## Bootstrap

1	# Self-hosted toolchain: AS, CC, LD, OBJCOPY, HOSTCC
2	
3	## Context
4	
5	The OS build currently depends on `nasm`, `gcc`, `ld`, `objcopy`, and
6	`qemu-system-i386` as external infrastructure. The goal now is to replace
7	the first four with our own Claude-authored tools, written in C and
8	compiled by our own compiler (`CC`) - i.e. `CC` must be able to compile
9	itself. `qemu-system-i386` stays external (an emulator is out of scope;
10	it's the machine we run *on*, not part of the toolchain that builds for
11	it).
12	
13	Research done before this plan (see conversation) narrowed the scope
14	considerably:
15	- 32-bit static ELF binaries execute fine on this host, so `CC` needs only
16	  **one** code generator (x86-32) for both the freestanding kernel target
17	  and native host tools - no x86-64 path needed.
18	- Every inline-asm site in the kernel (12 call sites) reduces to just 7
19	  distinct operations: `inb`/`outb`/`inw`/`outw`, `lidt`, the GDT-flush
20	  sequence (`lgdt` + segment reload + far jump), and `hlt`. These become
21	  fixed compiler builtins instead of a general GCC-extended-asm parser.
22	- The preprocessor only needs `#include` (quote + angle, with the
23	  directory-relative-then-searchpath semantics `kernel/fs/tinyfs.c`
24	  already relies on to pick kernel vs. host `string.h`), `#pragma once`,
25	  and simple **object-like** `#define` (constants only - no function-like
26	  macros, no `#ifdef` anywhere in the codebase).
27	- `idt_stubs.S` is the only place using NASM's macro preprocessor
28	  (`%macro`/`%rep`/`%assign`/`%+`); hand-expanding its 32 stubs removes
29	  the need for `AS` to implement a macro layer at all. Every other `.S`
30	  file already uses only directives/mnemonics `AS` will support natively.
31	
32	Confirmed design decisions (from the user):
33	- **Compound literals / designated initializers** (used in `eval.c` and
34	  `codegen.c`): refactor those two files to avoid them rather than
35	  implementing the feature in `CC`. Mechanical, low-risk (both files are
36	  covered by `tools/run_tests.sh`), and removes real compiler complexity.
37	- **Bootstrap rigor**: full 3-stage, byte-identical verification (the
38	  GCC/LLVM-standard proof of self-hosting) - Stage0 (host gcc) builds
39	  Stage1; Stage1 recompiles the toolchain's own source to Stage2; Stage2
40	  recompiles it again to Stage3; Stage2 and Stage3 must match byte-for-
41	  byte.
42	- **Host tools**: `mkfs_tinyfs`/`tinyfs.c` become libc-free, using raw
43	  x86-32 Linux syscalls (`int 0x80`) via the same builtin mechanism as
44	  kernel port I/O. This means `LD` never needs dynamic linking (no
45	  `PT_DYNAMIC`/`.dynsym`/cooperating with `ld-linux.so`) - a static,
46	  single-`PT_LOAD` ELF is all it ever has to emit, for both the kernel
47	  and host tools.
48	
49	One external dependency is unavoidable and expected: host `gcc` (and
50	`nasm`/`ld`/`objcopy`) are needed exactly once, to build Stage0 from
51	source on a fresh checkout. Every rebuild after that - including
52	recompiling the toolchain itself - uses only our own tools. This is
53	identical to how GCC itself bootstraps on a new platform.
54	
55	## New repo layout
56	
57	```
58	toolchain/
59	  as/            AS: assembler (NASM-like subset, no macro preprocessor)
60	    lexer.c/.h  parser.c/.h  encode.c/.h  elf_writer.c/.h  bin_writer.c/.h  main.c
61	  cc/            CC: the C compiler
62	    lexer.c/.h  preprocessor.c/.h  parser.c/.h  ast.h
63	    codegen.c/.h        emits AS-syntax assembly text
64	    builtins.c/.h        the ~7 kernel builtins + the raw-syscall builtins
65	    main.c
66	  ld/            LD: linker
67	    elf_reader.c/.h  reloc.c/.h  link_flat.c/.h (kernel .link.ld-style layout)
68	    link_static_exec.c/.h (minimal static ELF32 executable for host tools)
69	    main.c
70	  objcopy/       OBJCOPY: ELF -> flat binary
71	    main.c
72	  include/       CC's own freestanding headers: stdint.h, stddef.h
73	docs/
74	  toolchain.md   AS instruction set, CC's C dialect + builtins, LD/OBJCOPY
75	                  behavior, bootstrap procedure
76	tests/toolchain/
77	  *.c fixtures + tests/expected/ for CC, exercised on both the host target
78	  and (for kernel-flavored fixtures) via QEMU boot
79	```
80	
81	`toolchain/*` tools are host-side build infrastructure, like
82	`tools/mkfs_tinyfs.c` today - not OS code, but (per this task) no longer
83	externally-sourced infrastructure either.
84	
85	## Phased plan
86	
87	Each phase ends in a concrete, automated verification checkpoint and a
88	commit, matching how the original 7 OS phases were built.
89	
90	**Phase T1 - AS (assembler)**
91	NASM-like syntax, scoped to exactly what the existing `.S` files use:
92	`BITS 16/32`, `ORG`, `EQU`, labels (incl. `.local` sub-labels), `section`,
93	`global`/`extern`, `db`/`dw`/`dd`/`dq`, `times`, `align`, and the specific
94	mnemonic/operand forms present in `boot/boot.S`, `boot/stage2.S`,
95	`kernel/entry.S`, `kernel/idt_stubs.S` (enumerated in `docs/toolchain.md`
96	before coding). Two output modes: `-f bin` (flat) and `-f elf32`
97	(relocatable object, for `entry.S`/`idt_stubs.S` which link with C code).
98	First hand-expand `idt_stubs.S`'s `%macro`/`%rep` into 32 explicit stub
99	blocks (no behavior change, verified by `tools/run_tests.sh` still
100	passing under the *old* nasm-based build before touching `AS` itself).
101	Verify: assemble all four `.S` files with `AS` and diff the output
102	byte-for-byte against `nasm`'s output for the same (now-macro-free)
103	sources.
104	
105	**Phase T2 - CC front end**
106	`toolchain/include/{stdint,stddef}.h` (hand-rolled, small - just the
107	typedefs the kernel actually uses: `uint8/16/32_t`, `int32_t`, `size_t`,
108	`NULL`). `toolchain/cc/preprocessor.c`: `#include` with the same quote-
109	then-searchpath resolution GCC gave us for free (must preserve the
110	`kernel/fs/tinyfs.c` trick), `#pragma once` (dedup by resolved path),
111	object-like `#define` with recursive constant substitution. Lexer +
112	recursive-descent parser for the documented C subset (types, control
113	flow, operators, `sizeof`, casts, `__attribute__((packed))` recognized
114	and applied to struct layout, function calls) - documented in
115	`docs/toolchain.md` as the "tinyC dialect" up front, before coding.
116	Verify: parse-only (no codegen yet) every `.c`/`.h` file in `kernel/` and
117	`tools/` without error, after the Phase T3 kernel-source refactor lands
118	(see below) - this is the acceptance bar for "the dialect covers what we
119	actually write."
120	
121	**Phase T3 - Kernel source adaptation**
122	Refactor `kernel/lang/script/eval.c`'s ~22 compound literals into small
123	constructor helpers (`mkint`/`mkstr`) and `kernel/lang/compiler/codegen.c`'s
124	designated-initializer `BINOP_TABLE` into an explicit function. Replace
125	all 12 inline-asm call sites (`ata.c`, `serial.c`, `keyboard.c`,
126	`shell.c`, `idt.c`, `gdt.c`) with calls to the fixed builtins Phase T4
127	will implement. Add `strchr` to `kernel/string.h`/`.c` (needed by the
128	libc-free `mkfs_tinyfs` rewrite). Rewrite `tools/mkfs_tinyfs.c`'s file
129	I/O to raw syscalls instead of `fopen`/`fread`/`fwrite`/`fseek`/`fclose`/
130	`exit`/`perror`. Verify: `tools/run_tests.sh` still green, built the old
131	way (gcc/nasm/ld/objcopy) - proves the refactor is behavior-preserving
132	before the new toolchain is even in the loop.
133	
134	**Phase T4 - CC codegen + builtins**
135	Naive, non-optimizing codegen (every intermediate value spills to the
136	stack - same pragmatic spirit as the bytecode VM's design): x86-32,
137	cdecl-ish calling convention, no floating point (unused anywhere in this
138	codebase). Emits `AS`-syntax assembly text (mirrors `gcc -S | as`).
139	`builtins.c` implements the ~7 kernel primitives (`__builtin_inb` etc.,
140	mapped 1:1 to what the removed inline-asm sites did) and the raw-syscall
141	builtins (`__sys_open/read/write/lseek/close/exit`, `int 0x80`, matching
142	Linux x86-32 syscall numbers/calling convention) for host tools. Two
143	target modes selected by a flag: `--target=kernel` (freestanding, no
144	runtime) and `--target=host` (adds a `_start` that calls `main` then
145	`__sys_exit`s). Verify: a growing `tests/toolchain/*.c` battery -
146	arithmetic, control flow, functions/recursion, structs, pointers, arrays,
147	each builtin - compiled via `CC`+`AS`, run directly (host target) or
148	booted in QEMU (kernel target, reusing the `tools/run_tests.sh`/serial-log
149	pattern) with expected-output fixtures.
150	
151	**Phase T5 - LD (linker)**
152	Parses ELF32 relocatable objects, resolves symbols across multiple inputs
153	and the two relocation types our object code actually produces
154	(`R_386_32` for absolute data like `isr_stub_table`, `R_386_PC32` for
155	relative calls/jumps to extern symbols like `kmain`/`isr_handler`). Two
156	output modes: `link_flat` (the kernel's `link.ld`-style single-load-
157	address layout - `.text`/`.rodata`/`.data`/`.bss` concatenated at a fixed
158	base) and `link_static_exec` (minimal static ELF32 executable: one
159	`PT_LOAD`, entry point, no dynamic section - for host tools). Verify:
160	link the same objects the GNU-toolchain build produces; can't byte-diff
161	ELF output directly (metaddata/padding differ), so verify functionally -
162	both the kernel image and `mkfs_tinyfs` built via `LD` boot/run
163	identically to the GNU-linked versions (`tools/run_tests.sh` green either
164	way).
165	
166	**Phase T6 - OBJCOPY**
167	Parses ELF32, extracts `PROGBITS` loadable sections in address order into
168	a flat binary - matching `objcopy -O binary`'s semantics for the simple
169	single-segment layout `LD`'s `link_flat` mode produces. Verify: byte-for-
170	byte diff against GNU `objcopy -O binary` on the same ELF input.
171	
172	**Phase T7 - Full switch-over**
173	Makefile's `AS`/`CC`/`LD`/`OBJCOPY`/`HOSTCC` variables point at the newly
174	built tool binaries (`HOSTCC` = `CC --target=host`). Rebuild the entire
175	OS - boot loader, kernel, `mkfs_tinyfs` - using only our own tools, with
176	host gcc/nasm/ld/objcopy no longer invoked anywhere in the OS build path
177	(only used to have built the toolchain itself, one directory up).
178	Verify: `tools/run_tests.sh` green against the fully self-tool-built disk
179	image.
180	
181	**Phase T8 - Self-hosting bootstrap**
182	Stage1 = Phase T7's `CC`/`AS`/`LD`/`OBJCOPY` (built by host gcc). Use
183	Stage1 to compile `toolchain/{as,cc,ld,objcopy}`'s own source ->
184	Stage2. Use Stage2 to compile the same source again -> Stage3. Verify:
185	Stage2 and Stage3 binaries are byte-identical (`cmp`), for all four
186	tools - the fixed-point proof that `CC` genuinely self-hosts, not just
187	"happened to compile once under host gcc's tolerance for our code."
188	`make` thereafter builds everything (OS + toolchain) with Stage2/3.
189	
190	**Phase T9 - Docs + cleanup**
191	`docs/toolchain.md` finalized (instruction set, C dialect + builtin
192	list, linker/objcopy behavior, the 3-stage bootstrap procedure and how to
193	re-run it). README's toolchain-requirements section updated: host
194	gcc/nasm/ld/objcopy are a one-time bootstrap dependency, not a build
195	dependency. Final full-repo `tools/run_tests.sh` pass plus the Stage2==
196	Stage3 check, both green.
197	
198	## Verification strategy
199	
200	Every phase has a concrete, automated pass/fail gate before moving on:
201	byte-diff against the reference tool (T1, T6), parse/compile of the real
202	codebase (T2, T3), a growing fixture battery through the new pipeline
203	(T4), functional QEMU/serial-log equivalence (T5, T7, reusing
204	`tools/run_tests.sh`'s existing pattern), and byte-identical fixed-point
205	bootstrap (T8). No phase is considered done without its gate passing.
206	
207	## Sequencing note
208	
209	This is a large, multi-week-scale undertaking by the standards of the
210	project so far - each phase (especially T2/T4/T5) is comparable in size
211	to one of the original 7 OS-build phases. Work proceeds phase by phase
212	with a commit at the end of each, same cadence as before.
213