diff options
| author | hachem <im@hachem.wtf> | 2026-10-16 19:15:31 +0200 |
|---|---|---|
| committer | hachem <im@hachem.wtf> | 2026-10-16 19:15:31 +0200 |
| commit | 7684f3df95eddc3dd6836c4ed8eb8401222ae316 (patch) | |
| tree | c4ecfa118fdb72c692cb1086f0404c2b18c5753b /docs/internals.md | |
| parent | 62636576bce8e8121a3d70f63547fae40a52f697 (diff) | |
Diffstat (limited to 'docs/internals.md')
| -rw-r--r-- | docs/internals.md | 76 |
1 files changed, 0 insertions, 76 deletions
diff --git a/docs/internals.md b/docs/internals.md deleted file mode 100644 index f219a8f..0000000 --- a/docs/internals.md +++ /dev/null @@ -1,76 +0,0 @@ -# internals - -hdass is a straight pipeline: `lex → parse → analyze → emit`. each stage is one -pair of files under [`src/`](../src). - -| stage | files | does | -| --- | --- | --- | -| cli | `main.c`, `args.c` | parse arguments, pick a target, drive the pipeline | -| lex | `lexer.c` | source text → a stream of tokens | -| parse | `parser.c`, `ast.c` | tokens → an ast (`struct Program` of procs and declarations) | -| analyze | `sema.c` | check the ast: undefined names, entry point, constant/reference rules | -| emit | `codegen.c` | ast → assembly text for the chosen target | -| support | `diag.c`, `file.c` | caret diagnostics, file reading | - -the ast is mostly architecture-neutral (assignments, control flow, `^` memory, -calls, a raw instruction), so almost all of hdass is shared. the architecture -lives entirely in code generation. - -## two seams in codegen - -code generation is split along the same two axes as a [target](targets.md): - -- **`struct Arch`** — instruction selection. one hook, `emit_proc`, turns a - procedure's statements into that architecture's instructions (its register - model, mnemonics, stack frames). `x86_arch` and `aarch64_arch` implement it. -- **`struct Backend`** — assembler syntax. framing hooks (`prologue`, `constant`, - `data_section`, `string_data`, `float_slot`, `text_section`, `global`, - `boot_signature`) write the file structure around the instructions. - `nasm_backend`, `fasm_backend` and `gas_backend` implement it. - -`generate(program, out, arch, backend)` orchestrates the two. a public entry -point is just a pairing: - -```c -void generate_nasm(struct Program* program, FILE* out) -{ - generate(program, out, &x86_arch, &nasm_backend); -} -``` - -so `nasm` and `fasm` reuse one x86 instruction selector with different framing, -and `arm64` pairs its own selector with gnu as. - -## adding an assembler backend - -to emit a new *syntax* for an existing architecture (say masm for x86-64): - -1. write the framing functions (`masm_prologue`, `masm_constant`, …) and gather - them into a `static const struct Backend masm_backend`. -2. add `generate_masm` that pairs `x86_arch` with it. -3. wire a `-t masm` name in `args.c` and dispatch to it in `main.c`. - -only the framing differs; the instruction bodies come from `x86_arch` unchanged. - -## adding an architecture - -to emit a new *instruction set* (the larger job): - -1. write an `emit_proc_<arch>` and the helpers it needs — a register mapping, an - operand renderer, and lowerings for each statement kind. the aarch64 selector - is the template: it maps logical `rN → x(N-1)`, renders `#immediate` operands, - and lowers assignment/arithmetic/branch/call/syscall. -2. gather it into a `static const struct Arch <arch>_arch`. -3. pick an assembler `Backend` (gnu as suits most non-x86 targets — reuse - `gas_backend` or write one), add `generate_<arch>`, and wire a `-t` name. - -unsupported statement kinds should emit a `; TODO` comment instead of incorrect -instructions, the convention the existing selectors already use for gaps. - -## building and checking - -meson drives the build; see [getting started](getting-started.md). the test suite -(`build/tests`) covers the lexer, parser, sema and codegen for every target. if -`cppcheck` is installed, `ninja -C build cppcheck` runs static analysis. the -scripts under [`scripts/`](../scripts) assemble and run every example end to end -in docker. |
