From 7684f3df95eddc3dd6836c4ed8eb8401222ae316 Mon Sep 17 00:00:00 2001 From: hachem Date: Fri, 16 Oct 2026 19:15:31 +0200 Subject: chore: documentation --- README.md | 45 ++----- docs/README.md | 17 --- docs/getting-started.md | 107 ---------------- docs/internals.md | 76 ------------ docs/language.md | 318 ------------------------------------------------ docs/targets.md | 77 ------------ 6 files changed, 9 insertions(+), 631 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/getting-started.md delete mode 100644 docs/internals.md delete mode 100644 docs/language.md delete mode 100644 docs/targets.md diff --git a/README.md b/README.md index 419c6e5..1f7d161 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # hdass -hachem's dumb assembly super-set, pronounced "hd ass", or "headass"...depends on how you feel that day. +hachem's dumb assembly super-set, pronounced "hd ass", or "headass" depending on your mood. -the entire point of this project is to provide a middle ground between c and assembly. if we think about why we still write assembly today, it's usually because we need direct control over what the cpu is doing. we want control over the exact instructions being executed, the memory, the stack and everything else that higher-level programming languages normally abstract away. the thing is, not every program written in assembly actually needs that control. sometimes you want to write something close to the machine without having to manuall deal with every tiny detail yourself. you still want registers, explicit control over memory and a good understanding of what your program is doing, but you don't necessarily need to manually express everything as individual assembly instructions. +the entire point of this project is to provide a middle ground between c and assembly because if we think about why we still write assembly today, it's usually because we need direct control over what the cpu is doing. we want control over the exact instructions being executed, the memory, the stack and everything else that higher level programming languages like c normally abstract away. the thing is, not every program written in assembly actually needs allat. sometimes you want to write something close to the machine without having to manuall deal with every tiny detail yourself. this is where this piece of shit comes in. -this is where this piece of shit comes in. it's not quite high-level enough to be a c-like language, but it's also not low-level enough to be as annoying to write as raw assembly. the goal is to sit somewhere in between, keeping the parts of assembly that make it useful while making the parts that don't need to be painful a little nicer to work with. hdass transpiles into multiple flavours of assembly, currently nasm and fasm (masm is planned), rather than directly producing machine code. the idea is to provide a single language for writing low-level programs while allowing the backend to translate code into the assembler syntax you want to target. you're still ultimately producing assembly, and you're never particularly far away from the code that gets assembled. the goal isn't to hide the machine from you or turn assembly into c. there are already plenty of high-level languages that do that. hdass just fills the gap between the two, where you might want some more convenience whilst writing assembly without taking away the reason you wanted to work close to the machine in the first place. +it's not quite high level enough to be a c like language, but it's also not low level enough to be as annoying to write as raw assembly. the goal is to sit somewhere in between, keeping the parts of assembly that make it useful while making the parts that don't need to be painful less of unlubricated dildo levels of pain. hdass transpiles into multiple flavours of assembly, currently nasm and fasm (masm is planned unfortunately), rather than directly producing machine code. the idea is to provide a single language for writing low level programs while allowing the backend to translate code into the assembler syntax you want to target, totally not because i didn't want to make an assembler manually. you're still ultimately producing assembly, and you're never particularly far away from the code that gets assembled. ## examples here's a simple "hello, world!" world program written using hdass' syntax: @@ -31,34 +31,24 @@ proc main } ``` -the program still directly controls the registers used for the system calls. nothing is hiding what the program is doing. more examples can be found in [examples/](examples/). +more shit can be found in [examples/](examples/). -## documentation -the docs live in [docs/](docs/): - -- [getting started](docs/getting-started.md) — build the compiler, write and run a first program on x86-64 and aarch64. -- [language reference](docs/language.md) — directives, declarations, statements, control flow, memory, floats, raw instructions and extensions. -- [targets](docs/targets.md) — architectures and assemblers, what each supports, and the per-architecture syscall abis. -- [internals](docs/internals.md) — the compiler pipeline and how to add a backend or architecture. +## docs +> some day lmao ## building -the build is driven by [meson](https://mesonbuild.com/). configure a build directory and compile the compiler: +the build is with by meson: ```bash meson setup build meson compile -C build ``` -this produces the `hdass` binary at `build/hdass`. the default build turns on the address and undefined-behaviour sanitizers; for an optimised build without them, configure a separate directory: +this produces the `hdass` binary at `build/hdass`. the default build turns on the address and undefined-behaviour sanitizers, for an optimised build without them, configure a separate directory: ```bash meson setup build-release --buildtype=release -Db_sanitize=none meson compile -C build-release ``` -to run the unit tests: -```bash -meson test -C build -``` -if [cppcheck](https://cppcheck.sourceforge.io/) is installed, `ninja -C build cppcheck` runs static analysis over the sources. -hdass emits x86-64 assembly, so to actually assemble and run its output you need an x86-64 linux toolchain. the bundled docker environment provides a consistent one on any host, including apple silicon, where the amd64 image runs under emulation. the image is a debian base with `nasm`, `fasm`, `ld` (binutils), a c toolchain and meson/ninja preinstalled. +hdass emits x86-64 assembly, so to actually assemble and run its output you need an x86-64 linux toolchain. since it's a pain in the ass to actually use, i bundled a docker environment. start the container (this builds the image the first time): ```bash @@ -79,23 +69,6 @@ ld -e main hello.o -o hello ./hello ``` -hdass targets nasm by default; pass `-t fasm` to emit fasm instead, which assembles in a single step: -```bash -./build-linux/hdass -t fasm examples/hello_world.hdass -o hello.asm -fasm hello.asm hello.o -ld -e main hello.o -o hello -``` - -to transpile, assemble, link and run every program in [examples/](examples/) and check its output, use the end-to-end test script (also from inside the container): -```bash -meson setup build-linux && meson compile -C build-linux && ./scripts/test_examples.sh -``` - -or, from the host, run the whole suite (unit tests plus the example tests) in one shot, bringing the container up if needed: -```bash -./scripts/docker_test.sh -``` - to build, assemble, link and run a single program in the container: ```bash ./scripts/run.sh examples/circle.hdass diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index c36bd26..0000000 --- a/docs/README.md +++ /dev/null @@ -1,17 +0,0 @@ -# hdass documentation - -hdass is a small superset of assembly: you keep registers, memory and explicit -control flow, and write the repetitive parts (moves, arithmetic, loops, branches) -more compactly. it transpiles to x86-64 (nasm or fasm) or aarch64 (gnu as). - -- [getting started](getting-started.md) — build the compiler, then write and run - a first program on both x86-64 and aarch64. -- [language reference](language.md) — the full syntax: declarations, statements, - control flow, memory, floating point, raw instructions and extensions. -- [targets](targets.md) — the architecture and assembler axes, what each target - supports, the portable register model, and the per-architecture syscall abis. -- [internals](internals.md) — the `lex → parse → analyze → emit` pipeline and how - to add a new assembler backend or architecture. - -working programs live in [examples/](../examples/) (x86-64) and -[examples/arm64/](../examples/arm64/). diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 6781c0f..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,107 +0,0 @@ -# getting started - -## build the compiler - -hdass builds with [meson](https://mesonbuild.com/): - -```bash -meson setup build -meson compile -C build -``` - -that produces `build/hdass`. it has two options you need: `-o ` writes the -output (default stdout), and `-t ` picks the assembler and architecture -(`nasm` by default, `fasm`, or `arm64`). `build/hdass --help` lists the rest. - -hdass only *transpiles*: it emits assembly text, which you assemble and link -yourself. the examples target linux, so you need an x86-64 (and -for aarch64, an aarch64) linux toolchain. the bundled -[docker image](../README.md#building) has `nasm`, `fasm`, an aarch64 -cross-assembler and `qemu`; the commands below run inside it: - -```bash -docker compose up -d -docker compose exec hdass bash -``` - -## a first program (x86-64) - -put this in `hello.hdass`: - -```hdass -[entry: main] - -const SYS_WRITE = 1 -const SYS_EXIT = 60 -const STDOUT = 1 - -data message = "Hello, hdass!\n" - -proc main -{ - rax = SYS_WRITE // write(STDOUT, message, message.len) - rdi = STDOUT - rsi = message - rdx = message.len - syscall - - rax = SYS_EXIT // exit(0) - rdi = 0 - syscall -} -``` - -transpile, assemble, link and run: - -```bash -./build/hdass hello.hdass -o hello.asm -nasm -f elf64 hello.asm -o hello.o -ld -e main hello.o -o hello -./hello -``` - -it prints `Hello, hdass!`. `[entry: main]` exports `main` and drops its `ret`, so -the procedure ends the program itself with the exit syscall; `ld -e main` uses it -as the start symbol. swap `-t fasm` and `fasm hello.asm hello.o` to use fasm -instead — the machine code is the same. - -## running on aarch64 - -the same source model runs on arm, but the syscall abi differs (numbers and -argument registers), so this program is aarch64-specific. written with the -[`logical_registers`](targets.md#the-portable-register-model) extension so the -registers read the same on both architectures: - -```hdass -[entry: main] -[enable: logical_registers] - -const SYS_EXIT = 93 // AArch64 Linux exit - -proc main -{ - r1 = 42 // x0 = exit code - r9 = SYS_EXIT // x8 = syscall number - syscall // svc #0 -} -``` - -build it for aarch64 and run it under qemu: - -```bash -./build/hdass -t arm64 exit.hdass -o exit.s -aarch64-linux-gnu-as exit.s -o exit.o -aarch64-linux-gnu-ld -e main exit.o -o exit -qemu-aarch64 ./exit # exits 42 -``` - -`r1` maps to `x0` and `r9` to `x8`, `syscall` becomes `svc #0`. see -[targets](targets.md) for the register mapping and the abi tables. - -## next - -- the whole language: [language reference](language.md). -- what runs where and why programs still carry per-architecture abi details: - [targets](targets.md). -- more programs to read: [examples/](../examples/) and - [examples/arm64/](../examples/arm64/), each runnable with the steps above. 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_` 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`. -3. pick an assembler `Backend` (gnu as suits most non-x86 targets — reuse - `gas_backend` or write one), add `generate_`, 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. diff --git a/docs/language.md b/docs/language.md deleted file mode 100644 index 8c10eb4..0000000 --- a/docs/language.md +++ /dev/null @@ -1,318 +0,0 @@ -# hdass language reference - -this is the language reference. hdass transpiles to x86-64 (nasm or fasm, `-t nasm`/`-t fasm`) and aarch64 (`-t arm64`); for which target supports what, the portable [`logical_registers`](#logical_registers) model, and the per-architecture syscall abis, see [targets](targets.md). new here? start with [getting started](getting-started.md). pipeline: `lex → parse → analyze → emit`. - -the examples below use x86-64 register names. the output isn't tied to an os, but the examples and toolchain here target linux (elf, `ld`). - -## a first program - -```hdass -[entry: main] - -const SYS_WRITE = 1 -const SYS_EXIT = 60 -const STDOUT = 1 - -data message = "type shi.\n" - -proc main -{ - rax = SYS_WRITE - rdi = STDOUT - rsi = message - rdx = message.len - syscall - - rax = SYS_EXIT - rdi = 0 - syscall -} -``` - -writes `type shi.` to stdout and exits. - -## comments - -```hdass -rax = 1 // line -/* block */ -``` - -## directives - -top-level `[key: value]` (or bare `[key]`), configuring the whole program. - -| directive | meaning | -| --- | --- | -| `[bits: 64]` / `[bits: 32]` / `[bits: 16]` | target bitness. default 64. | -| `[entry: NAME]` | makes procedure `NAME` the entry point. | -| `[enable: NAME]` | turns on an [extension](#extensions). | -| `[format: bin]` / `[format: elf]` | output a flat binary instead of an elf object. default elf. | -| `[org: 0x7C00]` | set the load address of a flat binary. | -| `[boot]` | pad a flat binary to 510 bytes and append the `0xAA55` boot signature. | - -the last three build a raw binary instead of a linked elf, enough for an x86 -boot sector. in `bin` format there are no sections or exported symbols, and code -comes first so execution starts at the origin. unknown keys, a bad `bits` value, -and unknown extensions are errors. - -## constants and data - -`const` names a constant integer expression — integer literals, character literals, other constants, a leading `-`, and `+` `-` `*` `/`. integers are decimal, `0x` hex, or `0b` binary (these forms work anywhere an integer does). `data` puts a string in `.data`; the name is its address and `.len` is its length in bytes. - -```hdass -const STDOUT = 1 -const MASK = 0xFF -const AREA = 8 * 6 // 48 -data message = "type shi.\n" // message -> address, message.len -> 10 -``` - -## enums and structs - -both describe compile-time values reached with `Name.member`, which folds to an integer. - -`enum` names a set of constants numbered from 0: - -```hdass -enum Status -{ - Ok, // 0 - Warn, // 1 - Fail // 2 -} - -rax = Status.Fail // mov rax, 2 -``` - -`struct` describes a packed memory layout (no padding). fields are `name` or `name: size`, where size defaults to `qword`. `Name.field` is the field's byte offset, and `Name.size` is the total size. - -```hdass -struct Point -{ - x // qword, offset 0 - y // qword, offset 8 - flag: byte // offset 16 -} - -rsi += Point.y // add rsi, 8 -rax = Point.size // mov rax, 17 -``` - -a struct is layout only — it allocates nothing. pair it with a `stack` buffer sized by `Name.size` and pointer arithmetic (see [examples/records.hdass](../examples/records.hdass)). - -## procedures - -`proc` groups a body. parameters name registers — `value` below is `rdi`. - -```hdass -proc print_number(value: rdi) -{ - rax = value -} -``` - -each procedure ends with `ret`, except the entry point. `[entry: NAME]` exports `NAME` with `global` and drops its `ret`, so it must end the program itself (an exit syscall). link with `ld -e NAME`. - -## registers - -written by their architecture names — `rax`–`rdi`, `rbp`, `rsp`, `r8`–`r15` — and their sub-registers (`al`, `ax`, `eax`, `dl`, …), which imply a store's size. the [`logical_registers`](#logical_registers) extension adds `r1`–`r14`. the segment registers (`cs ds es fs gs ss`) and control registers (`cr0 cr2 cr3 cr4`) are also recognised, for systems code that sets up segments or switches cpu modes. - -## statements - -```hdass -rax = SYS_WRITE // mov -rcx -= 1 // += -= *= /= %= -> add sub imul idiv (idiv) -rax = rbx * rcx // + - * / % in a value; / % and their = forms use rax:rdx -rdx = buffer + 31 // address math -loop: // label -goto loop -if rcx != 0 // == != < <= > >= ; guards the next statement or a { block } - goto loop -while rcx != 0 // same condition; repeats the next statement or { block } - rcx -= 1 -syscall -print_number(r12) // call; args go into the callee's parameter registers -stack buf[Point.size] // stack buffer (size is any constant); buf is its base address -``` - -## control flow (`if` / `else` / `while`) - -`if ` guards either the single next statement or a `{ }` block, and an optional `else` takes its own statement or block. `else if` chains because the `else` body is itself a statement. comparisons are `==` `!=` `<` `<=` `>` `>=`; a float compare needs an `xmm` register on the left (see [floating point](#floating-point)). - -```hdass -if rax > rbx -{ - rdi = 1 - goto done -} -else if rax == rbx - rdi = 0 -else - rdi = -1 -``` - -`while ` runs its statement or `{ }` block for as long as the condition holds, testing it before each pass. it is the same condition as `if`, and desugars to a label, the test, the body, and a jump back — the `loop:`/`goto` you would write by hand. use `goto` to break out early. - -```hdass -rbx = 0 -while rcx > 0 -{ - rbx += rcx - rcx -= 1 -} -``` - -an optional `.name` right after `while` names the loop's generated labels, so they read as `.name` (top) and `.name_end` (exit) instead of the anonymous `.while_N` — handy for finding a loop in the emitted assembly. give nested loops distinct names. - -```hdass -while .countdown rcx > 0 // emits `.countdown:` … `jmp .countdown` … `.countdown_end:` - rcx -= 1 -``` - -a **conditional select** picks one of two register values without a branch: `dst = a if else b`. it lowers to `csel` on aarch64 (one instruction) and `cmov` on x86 (a default move plus a conditional move, arranged so `dst` may safely alias either source). both sources must be registers. - -```hdass -r3 = r1 if r1 > r2 else r2 // r3 = max(r1, r2), branchless -``` - -## dereference (`^`) - -`^reg` is the memory at the address in `reg` — nasm's `[reg]`. on the left of `=` it stores there. the store width comes from the value operand, so a sized sub-register picks the size: - -```hdass -^rsi = rdx // mov [rsi], rdx (qword) -^rsi = dl // mov [rsi], dl (byte) -^rsi = eax // mov [rsi], eax (dword) -``` - -a leading size keyword sets the width explicitly. it down-converts a full register to the matching sub-register, and gives an immediate a width nasm would otherwise reject: - -```hdass -^byte rsi = rdx // mov byte [rsi], dl (rdx -> its low byte) -^word rsi = rax // mov word [rsi], ax -^dword rsi = r12 // mov dword [rsi], r12d -^byte rsi = '0' // mov byte [rsi], '0' -^byte rsi = 10 // mov byte [rsi], 10 -``` - -`^reg` is also a value — it loads from that address. a size keyword loads a narrower value and zero-extends it into the target: - -```hdass -rax = ^rsi // mov rax, [rsi] -rbx = ^byte rsi // movzx rbx, byte [rsi] -rcx = ^dword rsi // mov ecx, [rsi] (32-bit load zero-extends) -rdx = ^rsi + 4 // load, then add 4 -``` - -`^signed` before the size sign-extends instead, so a narrower value keeps its sign in the full register. it needs a `byte`, `word`, or `dword` size (a full-width load has nothing to extend): - -```hdass -rax = ^signed byte rsi // movsx rax, byte [rsi] -rbx = ^signed word rsi // movsx rbx, word [rsi] -rcx = ^signed dword rsi // movsxd rcx, dword [rsi] -``` - -## raw instructions - -any statement that isn't an assignment, label, call or keyword is emitted as a bare instruction: a mnemonic and its operands, written in hdass's own operand syntax. this is the escape hatch for everything outside the assignment and control-flow model: `int`, `hlt`, `cli`/`sti`, `lgdt`, port i/o, the mode switch. operands are the usual registers, immediates, constants and `^memory`, and share the mnemonic's line. - -```hdass -cli -int 0x10 -out 0x64, al -lgdt ^gdt // lgdt [gdt] -cr0 = eax // an ordinary move; segment/control regs work with `=` too -hlt -``` - -mnemonics pass straight through, so a typo is reported by the assembler. operands render through the same path as everywhere else, so an instruction is as portable as the rest of the language, though the mnemonics themselves are architecture-specific. - -## expressions - -assignment values and `if` operands: registers, integers, chars (`'0'`), constants, data names, member access (`data.len`), and `+` `-` `*` `/` `%`. operators are left-associative and each right-hand operand must be a single term, so `a * b + c` works but `a + b * c` (a nested right operand) doesn't yet. - -a leading `-` negates a term (`rax = -5`, `rbx = rax + -3`, `const OFFSET = -8`). it only applies to values that fold to a constant, so it emits a negative immediate; negating a register (`-rbx`) is not supported. - -## extensions - -### logical_registers - -uniform names for the general-purpose registers, so you don't juggle the irregular `rax`/`rbx`/`rsi`/… spellings. `r1`–`r14` map to: - -| `r1` | `r2` | `r3` | `r4` | `r5` | `r6` | `r7` | `r8` | `r9` | `r10` | `r11` | `r12` | `r13` | `r14` | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| rax | rbx | rcx | rdx | rsi | rdi | r8 | r9 | r10 | r11 | r12 | r13 | r14 | r15 | - -`rsp`/`rbp` and the instruction pointer keep their own names. - -```hdass -r1 = 5 // mov rax, 5 -r4 = r10 // mov rdx, r11 -r6 += r1 // add rdi, rax -``` - -a `.8`/`.16`/`.32`/`.64` suffix selects the width, mapping to the sub-register: - -```hdass -r1.8 // al -r1.16 // ax -r1.32 // eax -r1.64 // rax -^byte rsi = r4 // mov byte [rsi], dl (r4 -> rdx -> dl) -``` - -arch `r8`–`r15` share the `rN` spelling, so with the extension on a bare `r8` is the *logical* register (which is arch `r9`). reach arch `r8`–`r15` through logical `r7`–`r14`. architecture names like `rax` and `rsi` still work everywhere. - -## floating point - -floating-point values live in the sse registers `xmm0`–`xmm15` (double precision). float literals like `3.14` are placed in `.data` and loaded for you. - -```hdass -xmm0 = 3.5 // movsd from a .data slot -xmm0 *= xmm1 // += -= *= /= -> addsd subsd mulsd divsd -``` - -an `=` between a float register and a general-purpose register converts: - -```hdass -xmm0 = rax // int -> float (cvtsi2sd) -rbx = xmm0 // float -> int, truncating (cvttsd2si) -``` - -`^` loads and stores floats too, so float state can live in memory (a `stack` buffer or struct): - -```hdass -^rsi = xmm0 // movsd [rsi], xmm0 -xmm1 = ^rsi // movsd xmm1, [rsi] -``` - -`if` compares floats too, when the left side is an `xmm` register (`ucomisd`): - -```hdass -if xmm0 > 4.0 - goto escaped -``` - -see [examples/mandelbrot.hdass](../examples/mandelbrot.hdass) for a float program. not yet supported: mixing floats and ints in one expression, and printing floats. - -## building a program - -```bash -hdass program.hdass -o program.asm # nasm (default) -nasm -f elf64 program.asm -o program.o -ld -e main program.o -o program -./program -``` - -or target fasm with `-t fasm`, which assembles in one step: - -```bash -hdass -t fasm program.hdass -o program.asm -fasm program.asm program.o -ld -e main program.o -o program -``` - -for `-t arm64` and the full toolchain (including the aarch64 cross-assembler and qemu), see [getting started](getting-started.md); the [readme](../README.md) has the docker setup. - -## some stinkies -clobbering is your responsibility: `syscall` trashes `rcx` and `r11`, while a callee can trash any registers it touches, so nothing is saved automatically. `examples/fibonacci.hdass`, for example, keeps its counter in `r15` for this reason. register widths must also match, meaning something like `rax = r1.8` would become `mov rax, al`, which will not assemble. division clobbers extra registers: `/` `%` and their `=` forms use `idiv` through `rax:rdx`, so both are overwritten regardless of the destination. the divisor can be anything — a register, a constant, or an immediate — but an immediate or an `rax`/`rdx` divisor is first copied into `r11`, so those also clobber `r11`. labels and procedures become plain assembler symbols, so avoid names the target assembler reserves: `loop`, for instance, is an instruction mnemonic that fasm rejects as a label (nasm allows it). finally, the entry procedure has no `ret`; it should end with an exit syscall. diff --git a/docs/targets.md b/docs/targets.md deleted file mode 100644 index 70259ea..0000000 --- a/docs/targets.md +++ /dev/null @@ -1,77 +0,0 @@ -# targets - -hdass separates two things that assemblers usually tangle together: - -- the **architecture** — which instructions exist and how registers work; -- the **assembler syntax** — how those instructions are written to a file. - -a target is a pairing of the two, chosen with `-t`: - -| `-t` | architecture | assembler | notes | -| --- | --- | --- | --- | -| `nasm` (default) | x86-64 | nasm | intel syntax, `nasm -f elf64` | -| `fasm` | x86-64 | fasm | intel syntax, `fasm` (one step) | -| `arm64` | aarch64 | gnu as | `aarch64-linux-gnu-as` | - -for x86-64, `nasm` and `fasm` emit the **same instruction bodies** and differ only -in framing (file header, sections, constant and data syntax). `arm64` is a -separate instruction selector: different registers, three-operand arithmetic, -`ldr`/`str` memory, `cmp`+`b.cond` branches and `svc #0` syscalls. - -`masm` (x86-64) and a 32-bit `arm` target are planned. - -## what each architecture supports - -the language is the same; not every construct lowers on every architecture yet. - -| feature | x86-64 | aarch64 | -| --- | --- | --- | -| moves, arithmetic (`+ - * /`), compound assignment | ✅ | ✅ | -| `if` / `else` / `while`, `goto`, labels | ✅ | ✅ | -| conditional select (`a if c else b`) | ✅ `cmov` | ✅ `csel` | -| calls, `syscall` | ✅ | ✅ | -| memory load/store (`^`), sized and signed | ✅ | partial (`ldr`/`str`) | -| raw instruction statement | ✅ | ✅ | -| modulo (`%`), division remainder | ✅ | ❌ not yet | -| floating point (`xmm`) | ✅ | ❌ not yet | -| `stack` buffers | ✅ | ❌ not yet | -| bare-metal directives (`format`, `org`, `boot`, `bits 16`) | ✅ | — (x86/bios concept) | - -unsupported constructs emit a `; TODO` comment instead of incorrect instructions. - -## the portable register model - -architecture-native register names (`rax` on x86-64, `x0` on aarch64) lock a -program to one architecture. to write for both, enable -[`logical_registers`](language.md#logical_registers): `r1`–`r14` are the -general-purpose registers, mapped per target. - -| logical | `r1` | `r2` | `r3` | `r4` | `r5` | `r6` | `r7` | `r8` | `r9` | `r10` | … | -| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | -| x86-64 | rax | rbx | rcx | rdx | rsi | rdi | r8 | r9 | r10 | r11 | … | -| aarch64 | x0 | x1 | x2 | x3 | x4 | x5 | x6 | x7 | x8 | x9 | … | - -aarch64 is simply `rN → x(N-1)`. the raw [instruction statement](language.md#raw-instructions) -is architecture-locked too: its mnemonics are whatever you write. - -## syscall abis differ - -even with logical registers, a *syscall* is not portable: linux uses different -call numbers, argument registers and trap instructions per architecture. so a -program still carries architecture-specific abi constants. - -| | x86-64 | aarch64 | -| --- | --- | --- | -| syscall number in | `rax` (logical `r1`) | `x8` (logical `r9`) | -| arguments in | `rdi rsi rdx r10 r8 r9` | `x0 x1 x2 x3 x4 x5` | -| trap (`syscall`) | `syscall` | `svc #0` | -| `exit` number | `60` | `93` | -| `write` number | `1` | `64` | - -c works the same way: portable source, per-platform syscalls. - -## os independence - -the emitted instructions aren't tied to an os; only the syscall numbers and the -`[entry]`/link convention are. the examples and toolchain here target linux (elf, -`ld`, and `qemu-aarch64` for arm); see [getting started](getting-started.md). -- cgit v1.3