# qbe.mbt API Documentation (doc)

This directory provides API documentation for each MoonBit package in the qbe.mbt compilation backend, based on each package's `pkg.generated.mbti` (generated by `moon info`) and source code comments.

[中文版本 (Chinese Version)](zh/README.md)

## Package Overview

Packages are listed in compilation pipeline order:

| Phase | Package | API Doc | Description |
| --- | --- | --- | --- |
| Data Structures | `types` | [types.md](types.md) | SSA IR: `Fn`/`Blk`/`Ins`/`Phi`/`Jump`/`Con`/`Tmp` etc. |
| Utilities | `util` | [util.md](util.md) | Error types, string interning, output, sorting |
| Lexing | `lexer` | [lexer.md](lexer.md) | IL text → token sequence |
| Parsing | `parser` | [parser.md](parser.md) | Token sequence → `Fn`/`Dat`/`Typ` |
| CFG Analysis | `cfg` | [cfg.md](cfg.md) | Predecessors, dominators, dominance frontiers, loops, aliasing |
| SSA Construction | `ssa` | [ssa.md](ssa.md) | Use chains, phi insertion, memopt/loadopt/copy |
| Constant Folding | `fold` | [fold.md](fold.md) | Constant instruction evaluation |
| Wasm ABI | `abi_wasm` | [abi_wasm.md](abi_wasm.md) | Wasm calling convention: Par/Arg→Nop, Call simplification |
| Wasm Instruction Selection | `isel_wasm` | [isel_wasm.md](isel_wasm.md) | Wasm op mapping, address mode decomposition, CFG→structured control flow |
| Wasm Assembly Output | `emit_wasm` | [emit_wasm.md](emit_wasm.md) | WAT text format output |
| ABI Processing | `abi` | [abi.md](abi.md) | Platform-specific ABI for parameters/return values |
| Instruction Selection | `isel` | [isel.md](isel.md) | amd64 instruction pattern selection |
| Liveness Analysis | `live` | [live.md](live.md) | in/out live sets |
| Register Spilling | `spill` | [spill.md](spill.md) | Stack spilling under register pressure |
| Register Allocation | `rega` | [rega.md](rega.md) | Virtual → physical registers |
| Assembly Output | `emit` | [emit.md](emit.md) | Render GAS assembly |
| RISC-V ABI | `abi_rv64` | [abi_rv64.md](abi_rv64.md) | rv64 calling convention: A0-A7/FA0-FA7 parameters and returns |
| RISC-V Instruction Selection | `isel_rv64` | [isel_rv64.md](isel_rv64.md) | rv64 instruction mapping, compare+branch merging |
| RISC-V Assembly Output | `emit_rv64` | [emit_rv64.md](emit_rv64.md) | RISC-V GAS text output |
| CLI Entry | `cmd/main` | [cmd_main.md](cmd_main.md) | Command-line arguments and pipeline orchestration |

## Pipeline Overview

```
            ┌──────┐  ┌───────┐
   src.ssa ─►│lexer │─►│parser │─┐
            └──────┘  └───────┘ │
                                  ▼
                              ┌─────┐
                              │types│  Fn/Dat/Typ
                              └─────┘
                                  │
   ┌──────────────────────────────┼──────────────────────────────┐
   │                                ▼                              │
   │  cfg.fillrpo/preds/dom/fron/loop/alias                        │
   │                                │                              │
   │                                ▼                              │
   │           ssa.filluse → ssa.memopt → ssa.phiins → renblk     │
   │                                │                              │
   │                                ▼                              │
   │           ssa.loadopt → ssa.copy → fold.fold                  │
   │                                │                              │
   │                                ▼                              │
   │                          abi.abi                              │
   │                                │                              │
   │                                ▼                              │
   │                          isel.isel                           │
   │                                │                              │
   │                                ▼                              │
   │           live.filllive → spill.fillcost → spill.spill        │
   │                                │                              │
   │                                ▼                              │
   │           rega.rega → cfg.simpljmp                           │
   │                                │                              │
   └────────────────────────────────┼─────────────────────────────┘
                                    ▼
                              emit.emitfn
                                    │
                                    ▼
                               out.s (GAS assembly)
```

### Wasm Pipeline

```
            ┌──────┐  ┌───────┐
   src.ssa ─►│lexer │─►│parser │─┐
            └──────┘  └───────┘ │
                                  ▼
                              ┌─────┐
                              │types│  Fn/Dat/Typ
                              └─────┘
                                  │
   ┌──────────────────────────────┼──────────────────────────────┐
   │                                ▼                              │
   │  cfg.fillrpo/preds/dom/fron/loop/alias                        │
   │                                │                              │
   │                                ▼                              │
   │           ssa.filluse → ssa.memopt → ssa.phiins → renblk     │
   │                                │                              │
   │                                ▼                              │
   │           ssa.loadopt → ssa.copy → fold.fold                  │
   │                                │                              │
   │                                ▼                              │
   │                       abi_wasm.abi_wasm                       │
   │                                │                              │
   │                                ▼                              │
   │                      isel_wasm.isel_wasm                      │
   │                                │                              │
   │                                ▼                              │
   │              [skip spill/rega — wasm has no physical regs]    │
   │                                │                              │
   └────────────────────────────────┼─────────────────────────────┘
                                    ▼
                              emit_wasm.emit_fn
                                    │
                                    ▼
                               out.wat (WAT text)
```

Each stage with a `-d*` flag outputs an IL-form snapshot to stderr in debug mode; see [cmd_main.md](cmd_main.md) for the flag table.

## Project Links

- Overview: [README.mbt.md](../README.mbt.md)
- Demo examples: [demo/](../demo/README.md)
- Regression tests: [test/](../test/)
- Coding conventions: [AGENTS.md](../AGENTS.md)

### RISC-V 64 Pipeline

```
parse → fillrpo → fillpreds → filluse → memopt
      → filldom → fillfron → filllive(false) → phiins → renblk → filluse → ssacheck
      → fillloop → fillalias → loadopt → filluse → ssacheck
      → copy → filluse → fold
      → abi_rv64 → fillpreds → filluse
      → isel_rv64
      → init_rv64_target()   ← switch TargetCfg (register layout)
      → fillrpo → filllive → fillcost → spill → rega
      → fillrpo → simpljmp → fillrpo → fillpreds
      → emit_rv64
```

rv64 shares the same `spill`/`rega` with amd64: target differences are switched at runtime via `types.target_cfg` (see [types.md](types.md) TargetCfg section).
The rv64 backend currently has no differential reference validation; `data` segment and floating-point constant rodata output are pending.