packages /

llvm 0.1.0

Bindings to LLVM's C API (LLVM 23), for the Auk compiler's back end: build IR, verify and print it, optimize it, emit object files and bitcode, link modules,...

files / README.md 5.3 kB · 88 lines

# llvm

Bindings to LLVM's C API (LLVM 23), for the Auk compiler's back end: build IR, verify and
print it, optimize it, emit object files and bitcode, link modules, add debug info, and run code
in memory with ORC LLJIT. They are generated from a list, not written by hand.

**Effects:** `ffi`. **Links:** LLVM 23's shared library (`auk run`/`test` `dlopen` it, `auk build`
links it), found with `llvm-config --libdir`: on macOS Homebrew's (`brew install llvm@23`;
its llvm-config is `/opt/homebrew/opt/llvm@23/bin/llvm-config`), on Linux `llvm-config-23`'s
(apt.llvm.org's `llvm-23-dev`). Set `LLVM_CONFIG` to use another LLVM 23.

```auk
let c = llvm.ir.context_create()
let m = llvm.ir.module_create_with_name_in_context("demo", c)
let i64 = llvm.ir.int64_type_in_context(c)
let f = llvm.ir.add_function(m, "add", llvm.ir.function_type(i64, [i64, i64], 0))
let b = llvm.builder.create_builder_in_context(c)
llvm.builder.position_builder_at_end(b, llvm.values.append_basic_block_in_context(c, f, "entry"))
let sum = llvm.builder.build_add(b, llvm.values.get_param(f, 0), llvm.values.get_param(f, 1), "sum")
let _ = llvm.builder.build_ret(b, sum)
llvm.kit.verify(m)?
print(llvm.ir.print_module_to_string(m))

let tm = llvm.kit.host_machine(llvm.kit.Level.Default)?   // for this computer
llvm.kit.set_target(m, tm)
let jt = llvm.kit.jit()?                      // ORC LLJIT
llvm.kit.add_object(jt, llvm.kit.emit(tm, m, false)?)?
print(llvm.kit.call_ii_i(llvm.kit.lookup(jt, "add")?, 40, 2))   // 42
```

`example/` does the same, then writes `add.o` and `add.bc`, links the object with `cc` into an
executable and runs it (`cd example && raft install && auk run src/main.auk`).

## Names and types

- `LLVMFooBar` is `llvm.<area>.foo_bar` (`LLVMBuildICmp` → `llvm.builder.build_icmp`,
  `LLVMOrcLLJITLookup` → `llvm.orc.orc_lljit_lookup`). Areas: `ir` (context, module, types,
  attributes, verify, print), `values` (constants, globals, functions, blocks, instructions),
  `builder`, `debug` (DIBuilder), `target` (targets, target machines, object files), `orc`
  (LLJIT, errors), `bitcode` (memory buffers, bitcode, linker), `passes`.
- Each `LLVMFooRef` is its own type `llvm.Foo` (`llvm.Value`, `llvm.Type`, `llvm.OrcLLJIT`, ...),
  so a type can't be passed as a value. A result that may be NULL is `T?` (`get_first_function`,
  `is_a_function`, `get_named_function`, every `LLVMErrorRef`); so is a parameter that takes
  NULL (`set_initializer(g, none)`, `set_current_debug_location2(b, none)`).
- `LLVMBool` and enums are `int`. The enum values the compiler uses are constants:
  `LLVMIntSLT` → `llvm.INT_SLT`, `LLVMPrivateLinkage` → `llvm.PRIVATE_LINKAGE`.
- `const char *` is `str`. A string with a length (`const char *Name, size_t NameLen`) takes the
  `str` alone, and an array with a count (`LLVMValueRef *Args, unsigned NumArgs`) takes a list
  alone: `build_call2(b, fty, f, [x, y], "r")`.
- Strings LLVM hands over (`LLVMPrintModuleToString`, `char **ErrorMessage`) are copied and
  disposed of. Out-parameters are `var`: `var m: llvm.Module? = none`,
  `parse_bitcode_in_context2(c, buf, &m)`.
- Callbacks and pointers to C structs are `ffi.Ptr` (pass `ffi.null`, or lay the struct out with
  `ffi.alloc`/`write_*`, as `llvm.kit.define` does for `LLVMOrcCSymbolMapPair`). A handle goes in and out of C memory
  through a cast: `extern fn entry_ptr(e: llvm.OrcSymbolStringPoolEntry): ffi.Ptr = "(void *)"`.

## `llvm.kit` (by hand)

`init_native()` (AArch64 and x86), `check(e: llvm.Error?): ()!`, `host_machine(level)`,
`set_target(m, tm)`, `verify(m)`, `run_passes(m, "default<O2>", tm)`, `emit(tm, m, asm)`:
`[int]`, `bitcode(m)`, `parse_bitcode(c, bytes)`, `take_bytes(buffer)`, and ORC: `jit()`,
`define(jit, [(name, address)])` (absolute symbols), `add_object(jit, obj)`,
`lookup(jit, name): ffi.Ptr`, `close(jit)`. JIT code is called through an `extern fn` with a
function-pointer prototype, address first: `call_ii_i(f, a, b)` is
`"int64_t (*)(int64_t, int64_t)"`; declare one per signature you call.

`llvm.codegen` is a piece of the Rust back end (`Gen::bin`, `truth`, `bool8`, `cstr_addr` from
`src/mir/llvm/codegen.rs`) ported to Auk, with a test that JIT-compiles and calls the result.

## Regenerating

```
python3 packages/llvm/gen/gen.py            # writes src/{lib,ir,values,builder,debug,target,orc,bitcode,passes}.auk
python3 packages/llvm/gen/gen.py --check    # LLVM names src/ (the Rust back end) uses but bind.txt lacks
python3 packages/llvm/gen/gen.py --survey   # how much of the whole C API the FFI can express
```

`gen/bind.txt` is the list: every LLVM function, `Ref` type and enum value the Rust back end uses
(`src/mir/llvm/*.rs`, `src/build.rs`), plus a few for the helpers and tests. Signatures come from
`/opt/homebrew/opt/llvm@23/include/llvm-c`. `kit.auk`, `codegen.auk` and `proof.auk` are
hand-written; `gen/lib_head.auk` is the top of `lib.auk`.

Bound: 211 functions (ir 40, values 54, builder 56, debug 10, target 24, orc 16, bitcode 8,
passes 3), 21 types, 57 constants. Of the names `src/` uses, only three structs aren't bound as
such: `LLVMOrcCSymbolMapPair`, `LLVMJITEvaluatedSymbol` and `LLVMJITSymbolFlags` travel by value
inside an array, so `kit.define` lays them out by hand. Across the whole C API, 1062 of 1066
functions bind (`--survey`); the rest take `const char **` (`LLVMParseCommandLineOptions`,
`LLVMRunFunctionAsMain`) or MCJIT's options struct.