# Amiberry X86 Jit

> Amiberry X86 Jit is an Agent Skill for testing & quality published in the BlitterStudio/amiberry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Reference workflow for Amiberry x86-64 JIT debugging and fixes. Use for x86 or x86-64 JIT allocator failures, RIP-relative `±2GB` distance bugs, PIE or ASLR allocation issues, high-natmem/direct-mode bugs, `PC_P` pointer-width regressions, `MAP_32BIT` or `VirtualAlloc` fallback bugs, runtime JIT disable or interpreter fallback bugs, and regressions in files such as `src/jit/x86/compemu_support_x86.cpp` and `src/jit/x86/compemu_x86.h`.

- Skill name: `amiberry-x86-jit`
- Category: [Testing & Quality](https://www.openparable.com/skill/testing-quality/1)
- Source: https://github.com/BlitterStudio/amiberry/blob/HEAD/.agents/skills/amiberry-x86-jit/SKILL.md
- Repository: BlitterStudio/amiberry (929 GitHub stars when collected)

## SKILL.md

# Amiberry x86-64 JIT — Allocation And RIP-Relative Reference

## Scope

- Use this skill for x86/x86-64 JIT issues in `src/jit/x86/`.
- Use `amiberry-arm64-jit` instead for `src/jit/arm/` codegen and ARM64 flag handling.
- Load [references/address-space-and-failures.md](references/address-space-and-failures.md) when you need the recent allocator fixes, invariants, or symbol names.

## Core Problem Shape

The main x86-64 failure mode is not "allocation failed" in the generic sense. It is "allocation succeeded at an address that the JIT cannot safely reference" or "a pointer-width value was routed through a 32-bit virtual-register path."

x86-64 JIT code uses RIP-relative addressing to reach globals and nearby code/data. That means:

- Low address does not automatically mean safe address.
- The correct check is distance from the actual base used by the JIT path, not distance from an arbitrary `.data` symbol.
- Pool allocations are dangerous because they can bypass later code-cache range checks.

High natmem above 4GB is supported. Do not treat it as a reason to disable JIT or broadly fall back to interpreter mode; the goal is to keep direct compiled performance unless a real special memory bank requires helper paths.

## Non-Negotiable Invariants

- Any allocation used by RIP-relative helpers must be within safe range of the effective JIT anchor.
- Under PIE or high ASLR, validate against the real base chosen by the allocator path:
  - `vm_acquire_anchor` when already established
  - otherwise the first cache base or fallback anchor used by the current code path
- Linux and Windows last-resort allocation paths both need distance validation.
- If allocation failure disables JIT at runtime, keep `cache_enabled`, `currprefs.cachesize`, and `changed_prefs.cachesize` in sync.
- If block compilation fails after partial setup, clean the block state with `invalidate_block(bi)` and clear stale tags with `flush_icache_hard(3)`.
- `PC_P` (vreg 16) is the only pointer-width virtual register. All Dn/An/temp non-`PC_P` vregs are 32-bit M68K values.
- `set_const()` must mask non-`PC_P` values to 32 bits; any host pointer copied into a non-`PC_P` vreg must be materialized with a 64-bit register path or represented as a 32-bit displacement plus a pointer-width `PC_P`/`R_MEMSTART` add.
- Constant `PC_P` copies in `mov_l_rr()` must not use the generic `mov_l_ri()` shortcut, because that truncates when copied into a non-`PC_P` destination.
- `R_MEMSTART` holds `natmem_offset` on x86-64 and is the base for direct high-natmem loads/stores.
- `jit_n_addr_unsafe` can mean "high natmem needs pointer-clean codegen"; `jit_n_addr_bank_unsafe` means "a real bank requires helper paths." Do not collapse these two cases.

## Investigation Workflow

1. Identify whether the failure is in code-cache allocation, pool allocation, or a later block-compilation path.
2. Inspect the active anchor used by `jit_vm_acquire()`.
3. Check whether the allocator is validating distance after every fallback, not just the primary path.
4. Verify whether a helper or fallback returns success on an address that is valid to the OS but invalid for RIP-relative codegen.
5. If JIT is disabled on failure, trace whether later prefs-apply paths can silently re-enable it.
6. For high-natmem regressions, verify whether the failing path is truncating `PC_P`, `natmem_offset`, `regs.pc_p`, or cache/tag pointers through 32-bit stores, loads, adds, or `isconst` shortcuts.
7. Separate correctness fallbacks from performance fallbacks: real `S_N_ADDR` banks can use helpers, but high natmem alone should still compile normal blocks.

## Linux x86-64 Allocator Rules

- Prefer a VMA-aware near-address search such as `find_nearest_gap()` before blind probing.
- Adaptive probe stride is safer than a hardcoded large stride; tiny pool allocations can fit into holes that a 2MB walk will skip.
- `UAE_VM_32BIT` / `MAP_32BIT` is a strategy, not a proof. A returned pointer can still be out of safe range under PIE layouts.
- If a `MAP_32BIT` allocation is returned but rejected by range checks, consider the next fallback instead of disabling JIT immediately.

## macOS x86-64 Allocator Rules

- Darwin can ignore advisory `mmap()` address hints and return a valid mapping far from the requested anchor.
- Use exact near-address allocation for x86-64 JIT buffers that need RIP-relative reach; do not accept a hinted result unless it is range-checked.
- Intel macOS JIT builds need non-PIE `__TEXT` fixed at 4GB plus a small `__PAGEZERO` on the x86_64 slice; this keeps globals near low 32-bit JIT buffers while making fallback space allocatable.
- `veccode`, `popallspace`, block pools, and the JIT cache all need to stay within the same ±2GB anchor discipline.

## Windows x86-64 Allocator Rules

- Treat the Windows path the same way conceptually: search near the active base first, then validate every fallback.
- Unanchored `VirtualAlloc(NULL, ...)` is not safe unless the result is range-checked and freed on failure.
- Remember that lazy block or pool allocators may bypass any post-hoc code-cache validation done elsewhere.

## Common Review Traps

- Range-checking against `&data_anchor` even though the effective base is `vm_acquire_anchor` or the compiled cache.
- Trying unanchored allocation only when `MAP_32BIT` fails, but not when it succeeds and is then rejected as too far away.
- Clearing only `currprefs.cachesize` when disabling JIT, allowing a later prefs apply to re-enable the broken path.
- Forgetting to move new helper definitions above first use, breaking x86 CI with simple declaration-order errors.
- Returning early from `compile_block()` without invalidating partially initialized state.
- Routing constant `PC_P` through `mov_l_ri()` or `set_const()` for a non-`PC_P` temp.
- Using `readreg_offset(PC_P, ...)` when the logical value, including deferred offsets, is needed.
- Treating `jit_n_addr_unsafe` as a blanket interpreter/helper fallback when `jit_n_addr_bank_unsafe` is false.
- Leaving one-off investigation logs such as H3 diagnostics in generic memory paths.

## Verification

- Test x86-64 Linux with PIE or aggressive ASLR and sustained Workbench usage.
- Test x86-64 Windows fallback paths if code changed under `_WIN32`.
- Confirm normal JIT behavior when allocations succeed.
- Confirm graceful interpreter fallback when allocations fail.
- Change an unrelated preference after runtime JIT disable and verify the failing JIT path does not come back.
- Run a high-natmem SysInfo/Workbench smoke test and check for no H3/software failure/CPU-halt markers.
- Confirm performance is at JIT levels, not interpreter-level MIPS, after high-natmem fixes.

---

Source: https://www.openparable.com/skill/testing-quality/amiberry-x86-jit (OpenParable). Cite the canonical URL above.
