docs(asm): document symbol operands ("s") + checkpoint
Adds a 'Symbol inputs — "s" = fn' section to docs/inline-assembly.md (direct bl/call, portability, the export-vs-callconv linkage point) and logs the symbol-operand + round-trip work in CHECKPOINT-ASM.
This commit is contained in:
@@ -55,6 +55,44 @@ does.
|
||||
"{rdi}" = fd // pinned to a specific register (x86_64 rdi)
|
||||
```
|
||||
|
||||
### Symbol inputs — `"s" = fn`
|
||||
|
||||
A `"s"` input feeds a **function or global symbol** (not a runtime value).
|
||||
In the template, `%[name]` expands to the symbol's **platform-mangled
|
||||
name**, so you can branch or call straight to it:
|
||||
|
||||
```sx
|
||||
cb :: (n: i64) -> i64 export "cb" { return n + 1; }
|
||||
|
||||
trampoline :: (n: i64) -> i64 {
|
||||
return asm volatile {
|
||||
#string ASM
|
||||
mov x0, %[arg]
|
||||
bl %[fn] // DIRECT call — `bl _cb` on macOS, `bl cb` on Linux
|
||||
mov %[res], x0
|
||||
ASM,
|
||||
[res] "=r" -> i64,
|
||||
[arg] "r" = n,
|
||||
[fn] "s" = cb, // symbol operand
|
||||
clobbers(.x0, .x30, .memory),
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Two reasons to prefer this over passing a function *pointer* in a plain
|
||||
`"r"` register and using an indirect `blr`/`call *`:
|
||||
|
||||
- **One fewer indirection** — a direct PC-relative branch, no pointer
|
||||
load into a register, and a predictable (non-indirect) branch.
|
||||
- **Portable** — the backend emits the correctly-mangled name, so you
|
||||
don't hardcode the macOS leading underscore.
|
||||
|
||||
The callee needs a stable, externally-linked symbol — i.e. `export`
|
||||
(which also gives it the C ABI). A plain or `callconv(.c)`-only function
|
||||
is `internal` and gets dead-code-eliminated, so the symbol won't link.
|
||||
(A global-scope `asm { … }` routine has no operand list, so it can't use
|
||||
a symbol operand — it references the literal symbol in its text.)
|
||||
|
||||
### Value outputs — `-> Type`
|
||||
|
||||
`-> Type` produces a value that becomes (part of) the block's result:
|
||||
|
||||
Reference in New Issue
Block a user