hachem.wtf
aboutsummaryrefslogtreecommitdiff
path: root/docs/internals.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/internals.md')
-rw-r--r--docs/internals.md76
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.