# Architecture Reference

## Key Constants

| Constant | Value | Defined in |
|---|---|---|
| `STACKP_VALUE` | `0x14FEA0` | `lifter/core/Includes.h` |
| Stack reserve min | `0x1000` | `lifter/memory/MemoryPolicySetup.hpp` (`configureDefaultMemoryPolicy`) |
| Stack reserve max | `0x100000` | `lifter/memory/MemoryPolicySetup.hpp` (`configureDefaultMemoryPolicy`) |

## Pipeline Order

| # | Function | File | Purpose |
|---|---|---|---|
| 1 | `createRuntimeImageContext` | `lifter/core/RuntimeImageContext.hpp` | Validates PE headers, builds `RuntimeImageContext` |
| 2 | `createConfiguredLifterForRuntime` | `lifter/core/LifterStages.hpp` | Calls `loadFile`, parses PE exports, auto-outlines export addresses |
| 3 | `configureDefaultMemoryPolicy` | `lifter/memory/MemoryPolicySetup.hpp` | Sets `memoryPolicy` (SYMBOLIC default, CONCRETE for PE sections + stack), clamps `stackReserve` to `[0x1000, 0x100000]` |
| 4 | `prepareRuntimePagedMemory` | `lifter/core/LifterPipelineStages.hpp` | Marks `pageMap` intervals for mapped memory regions |
| 5 | `runSignatureStage` | `lifter/core/LifterPipelineStages.hpp` | Signature-based analysis |
| 6 | Lift loop | `lifter/core/LiftDriver.hpp` | Main lifting of instructions to LLVM IR |
| 7 | `run_opts` | `lifter/core/MergenPB.hpp` | Fixpoint optimization (see below) |

## run_opts Fixpoint Loop

```
loop {
    O1 pipeline
    GEPLoadPass
    ReplaceTruncWithLoadPass
    PromotePseudoStackPass
    PromotePseudoMemory
} until instruction count stabilizes (delta == 0)

Final O2 pipeline (runs once after fixpoint)
```

Termination: the loop compares instruction count before and after each iteration. When the count stops changing, the fixpoint is reached.

## Custom Pass Summary

| Pass | Filters on | Produces | Description |
|---|---|---|---|
| `GEPLoadPass` | `memory`-base GEPs where: `getPointerOperand() == mem`, `!isSymbolic`, `address_to_mapped_address != 0`, `isIntegerTy()`, `readMemory` succeeds | Constant integer values folded from PE image | Folds constant loads from the PE image through `memory`-base GEPs |
| `ReplaceTruncWithLoadPass` | `trunc(load wide, ptr)` patterns | `load narrow, ptr` | Rewrites wide-load-then-truncate into narrow load; valid on little-endian |
| `PromotePseudoStackPass` | `memory`-base GEPs in `[STACKP_VALUE - reserve, STACKP_VALUE + reserve]` via `isStackAddress()` | `stackmemory` alloca GEPs | Replaces pseudo-stack memory accesses with real stack alloca operations |
| `PromotePseudoMemory` | Remaining `memory`-base GEPs (not handled by above passes) | `inttoptr` | Converts leftover pseudo-memory GEPs to raw pointer operations |

Pass order matters: GEPLoadPass must run before PromotePseudoMemory, otherwise concrete PE loads get converted to `inttoptr` and are lost.

## InlinePolicy

- **CRTP framework**: default policy inlines everything.
- **Outline set**: `addAddress(va)` registers a VA for outlining (i.e., not inlined).
- **Check site**: `Semantics_ControlFlow.ipp:202` — when a call target is constant-resolved, the inline policy is consulted.
- **CLI**: `--outline <addrs>` accepts comma-separated hex addresses, parsed in `Utils.cpp`, stored in `ParseResult::outlineAddresses`.
- **PE export auto-outline**: export addresses are automatically added to the outline set in `createConfiguredLifterForRuntime`. Forwarded exports are filtered out by checking if the RVA falls within the export directory range.

## Control-Flow Recognition

The lift loop recognizes several `ret`/`jmp` shapes beyond a plain return or branch and emits structured IR for them instead of falling through to `solvePath`.

### Real return vs ROP/continuation return

`lift_ret` (`Semantics_ControlFlow.ipp`) classifies the return on entry:

- If RSP folds to the constant `STACKP_VALUE`, this is a return from the outermost (entry) frame. Emit a clean `ret rax` via `emitResolvedFunctionReturn` and stop the lift loop.
- Otherwise the return is treated as a ROP/continuation return: pop the return target, advance RSP by `ptrSize` (plus the immediate for `ret imm16`), and try to resolve the popped target via `solvePath`. If that fails, the `UnresolvedRetChain` diagnostic is recorded and the block is degraded to a `ret rax` to keep the IR well-formed.

### Ret-to-IAT chain (Themida-virt)

Themida-virt and similar protectors rewrite each `call [rip+IAT]` site as a VM-staged `push target; ret`, where `target` was loaded from the IAT by an upstream VM handler. The original code's semantics consume two stack slots: `ret` pops the IAT slot into RIP (calling the import), then the import's own `ret` pops the continuation address.

When the popped target is a constant in `importMap`, `lift_ret` collapses both pops into one structural emission:

1. Read the next stack slot (`[RSP+ptrSize]`); if it is also a constant, treat it as the continuation VA `contVA`.
2. Advance RSP by another `ptrSize` so it reflects both pops (the import's return + the original ret). Emitted as `ret-chain-cont-rsp-...` in the IR.
3. Emit `call @<import>` with an empty `volatileRegs` set so the lifter does not clobber caller-saved GPRs across the external call -- VM dispatchers preserve their own caller-saved state across import calls in the real binary.
4. Emit `br contBB`, queue `contVA` for lifting if not already visited, record the site in `chainedImportRetSites` so the unresolved-ret diagnostic is suppressed for this address, and stop the per-instruction lift loop for the current block.

Without the RSP advance in step 2, the continuation block sees RSP off by one slot (entry RSP + 8 instead of + 16). For `example2` the post-O2 IR shows only SSA-renumbering churn across the fix because no `[rsp+N]` read in the continuation flows to a visible computation, but the invariant still holds and is gated by the `ret_to_iat_chain_advances_rsp_by_two_slots` microtest.

### Direct vs indirect jumps

`lift_jmp` discriminates on `instruction.types[0]`: `Immediate8`/`Immediate16`/`Immediate32`/`Immediate64` are direct (RIP-relative) jumps, everything else is indirect. For direct jumps the immediate is sign-extended and added to RIP to form the absolute target. Both forms then go through `solvePath`; if the path solver cannot resolve the target, the `UnresolvedIndirectJump` diagnostic is recorded (no inline `std::cout` print -- the diagnostics framework persists it to `output_diagnostics.json`).

### Operand-type quirks

Iced classifies operand types by the bytes the instruction actually accesses, not by physical register/memory width. SSE handlers that gate on `Register128`/`Memory128` only must also accept `Register64`/`Memory64` for instructions whose semantics read fewer bytes than the encoding nominally allows. PUNPCKLQDQ is the canonical example: the encoding is `xmm/m128` but only the low 64 bits of the source are read, so Iced reports `Register64`/`Memory64`. The `sse_memory_form_handlers_do_not_fall_through_to_not_implemented` microtest gates this for `pand`/`por`/`pxor` to catch future Iced reclassifications before they silently reach a `not_implemented; ret` lowering.


## Memory Subsystem

### FileReader

CRTP base with concrete implementations `x86FileReader` and `x86_64FileReader`.

| Method | Returns | Failure value |
|---|---|---|
| `RvaToFileOffset` | file offset | `0` |
| `readMemory` | `bool` | `false` |
| `address_to_mapped_address` | mapped address | `0` |

### MemoryPolicy

| Region | Policy |
|---|---|
| Default | SYMBOLIC |
| PE sections | CONCRETE |
| Stack | CONCRETE |

Set by `configureDefaultMemoryPolicy` in `lifter/memory/MemoryPolicySetup.hpp`.

### pageMap

`std::map<uint64_t, uint64_t>` — interval map of paged memory regions.

- `markMemPaged(start, end)` — inserts an interval.
- `isMemPaged` — uses `upper_bound` then decrements iterator to check containment.

### stackReserve

Set by `configureDefaultMemoryPolicy`, clamped to `[0x1000, 0x100000]`. Consumed by:
- `PromotePseudoStackPass` — defines the stack address window around `STACKP_VALUE`
- `prepareRuntimePagedMemory` — marks the stack region in `pageMap`

## PE Parsing

- Header types come from the **linuxpe** library.
- `RvaToFileOffset` returns `0` on failure — callers must check before using the offset.
- Export directory is parsed in `createConfiguredLifterForRuntime`; forwarded exports are detected by checking if the export RVA falls within the export directory VA range.
- `RuntimeImageContext` is validated in `createRuntimeImageContext` (step 1 of the pipeline).