--- name: linx-compiler description: Linx compiler/backend workflow for LLVM and compile gates. Use when implementing or debugging Linx codegen/MC behavior, enforcing call/ret lowering contracts, running compile coverage suites, or validating object/relocation correctness. --- # Linx Compiler ## Overview Use this skill for all compiler-side work centered on `compiler/llvm` and AVS compile gates. ## Focus areas - Target backend changes (TableGen/ISel/MC/asm/disasm). - ABI and call/ret lowering correctness. - Compile-only gate stability and coverage. ## Canonical checks ```bash python3 /Users/zhoubot/linx-isa/tools/isa/gen_c_codec.py --spec /Users/zhoubot/linx-isa/isa/v0.57/linxisa-v0.57.json --out-dir /tmp/linxisa-llvm-codec-check diff -q /tmp/linxisa-llvm-codec-check/linxisa_opcodes.h /Users/zhoubot/linx-isa/compiler/llvm/llvm/lib/Target/LinxISA/MCTargetDesc/linxisa_opcodes.h diff -q /tmp/linxisa-llvm-codec-check/linxisa_opcodes.c /Users/zhoubot/linx-isa/compiler/llvm/llvm/lib/Target/LinxISA/MCTargetDesc/linxisa_opcodes.c cd /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests && CLANG=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang TARGET=linx64-linx-none-elf OUT_DIR=/Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/out-linx64 ./run.sh python3 /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/analyze_coverage.py --out-dir /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/out-linx64 --fail-under 100 cd /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests && CLANG=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang TARGET=linx32-linx-none-elf OUT_DIR=/Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/out-linx32 ./run.sh python3 /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/analyze_coverage.py --out-dir /Users/zhoubot/linx-isa/avs/compiler/linx-llvm/tests/out-linx32 --fail-under 100 ``` The codec parity check is the source-of-truth proof that LLVM MC tables are generated from the live v0.57 ISA catalog. The coverage denominator must be derived from `isa/v0.57/linxisa-v0.57.json`, not carried forward from retired profiles closure counts. Coverage must include all active v0.57 scalar CAS/DMA forms and the tile/PTO deltas (`TPREFETCH`, dense TMA `0..8`, unique named `CUBE` forms, and the 111-operation PTO map where PTOAS/MC surfaces overlap). Coverage conclusions require a fresh `run.sh` using Clang rebuilt from the current `compiler/llvm` HEAD; if the binary's reported VCS revision is stale, classify existing analyzer output as provenance/audit evidence rather than a source defect. v0.57 is the sole active ISA release. Treat v0.57 as a regression comparison only; do not accept legacy v0.57 selectors, aliases, or block-template spellings in active MC coverage unless they are explicitly present in the v0.57 golden catalog. Treat `plain_c_reachable_contract.json` as a demonstrated plain-C non-regression baseline, not an exhaustive denominator for everything C can reach. Keep pure C/C++, intrinsic-directed C, inline assembly, and MC coverage as separate lanes. Add a new C/IR target to an independently reviewed inventory as a gap before implementation; only replayed object disassembly may close it. Never use total ISA mnemonic breadth as the plain-C reachability denominator. ## Toolchain lane policy - Pin lane defaults to in-repo binaries: - `CLANG=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang` - `LLD=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/ld.lld` - Use external toolchain paths only in external lane or explicit override. - In reports, include lane + compiler path provenance so gate outcomes are reproducible. ## Call/ret compile contract - enforce call-header adjacency, - preserve `FENTRY + FRET.STK` normal path, - keep `FENTRY + FEXIT` tail-transfer path legal, - preserve relocation/template checks. ## SIMT recurrence contract - Treat generic loop-carried recurrences as order-dependent. Only recurrence kinds with an explicitly supported `v.rd*` reduction plan may use grouped multi-lane lowering. - In auto layout, lower a generic recurrence with `LB0=1` scalar replay. An explicit grouped request must reject with a stable legality reason rather than emitting independent per-lane recurrence states. - Recurrence carrier loads/stores synthesized by the compiler are memory traffic even when the source IR has no load or store. A body containing synthesized `.brg` accesses must use `MSEQ`/`MPAR`, never tile-only `VSEQ`/`VPAR`. - Gate constant-trip recurrences with both assembly and runtime evidence: lock the recurrence update token as the stored value, require zero-offset carrier access in scalar replay, and compare auto-mode output with scalar mode. ## Workflow 1. Implement backend change. 2. Add lit/FileCheck coverage. 3. Rebuild the actual in-repo `clang` binary when the change touches the assembler/parser/MC path, not just `llvm-mc`: ```bash ninja -C /Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang clang -j10 ``` 4. Validate both standalone MC and integrated-assembler surfaces when the change affects assembly syntax, reloc spelling, or expression parsing. Do not treat `llvm-mc` success as sufficient proof for `.S` files compiled through Clang: ```bash /Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/llvm-mc -triple=linx64 -filetype=obj /tmp/probe.s -o /tmp/probe.o /Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang -target linx64-linx-none-elf -c /tmp/probe.s -o /tmp/probe-clang.o ``` 5. For recurring kernel-forward-port crashes in `SelectionDAGISel::isOrEquivalentToAdd`, first use the emitted Clang crash repro script from `/var/folders/.../*.sh` and remove the quoted `"-vectorize-loops"` / `"-vectorize-slp"` cc1 flags in that reproducer. If the repro then passes, treat the failure as a candidate for an object-scoped kernel workaround (`CFLAGS_.o += -fno-vectorize -fno-slp-vectorize`) before widening LLVM backend changes. 6. When a Linx runtime trap maps into compiler-rt `__atomic_*` helpers, inspect the linked object before changing workload code. Current Linx lowering can route C11 atomics used inside compiler-rt (`__c11_atomic_*`) back to the same public `__atomic_*` symbols, producing self-recursion such as `__atomic_load_1 -> __atomic_load_1`. A valid bring-up fallback must compile `compiler-rt/lib/builtins/atomic.c` for `linx64-unknown-linux-musl` and show no `__atomic_*` or `__c11` self-recursive relocations in `llvm-objdump -r`; disassembly should show direct load/store bodies for `__atomic_load_{1,2,4,8}` until native Linx atomic lowering is implemented. 7. Keep active compatibility MC coverage out of `legacy-*` naming. Historical baselines may stay archived, but any still-supported syntax/reloc surface should live under normal compatibility-oriented test names. 8. Keep `TPREFETCH` parser/MC encoding adjacent to `TLOAD`/`TSTORE`, but model it as destination-free: no tile destination operand and no result queue publication. 9. Keep TMA selector coverage dense over `0..8`; reject holes, aliases, and stale selector spellings. Keep named CUBE TableGen/block-template entries one-to-one with v0.57 architectural identities. 10. Run both linx64 and linx32 compile/coverage gates. 11. Confirm no cross-stack call/ret regressions. 12. Handoff gate evidence to integration owner before repin. ## Skill evolve loop (mandatory closeout) - At closeout, decide `skill-evolve: update` or `skill-evolve: no-update`. - Update this skill only for material reusable findings: - new backend contract/call-ret rule tied to v0.57 closure, - new mandatory compile gate/repro command/env, - new recurring compiler triage pattern that changed debug order. - Skip updates for minor optimization, wording cleanup, or one-off local workaround. - If update is needed, validate with: - `python3 /Users/zhoubot/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/zhoubot/linx-isa/skills/linx-skills/linx-compiler` - `python3 /Users/zhoubot/linx-isa/skills/linx-skills/scripts/check_skill_change_scope.py --repo-root /Users/zhoubot/linx-isa/skills/linx-skills --base origin/main` ## Included scope This consolidated skill absorbs prior `llvm-backend` and compiler-side `call-ret-parity` workflows. ## References - `references/compiler_checks.md`