linx-linux

name	linx-linux
description	Linx Linux bring-up and runtime stabilization workflow. Use when debugging initramfs smoke/full boot failures, symbolizing trap loops, bisecting Linux+QEMU regressions, or validating kernel-side call/ret and block-target legality behavior.

Linx Linux

Overview

Use this skill for Linux runtime bring-up on Linx, from trap triage through stable smoke/full boot gates.

Required runtime gates

python3 /Users/zhoubot/linx-isa/kernel/linux/tools/linxisa/initramfs/smoke.py
python3 /Users/zhoubot/linx-isa/kernel/linux/tools/linxisa/initramfs/full_boot.py
python3 /Users/zhoubot/linx-isa/kernel/linux/tools/linxisa/busybox_rootfs/boot.py
python3 /Users/zhoubot/linx-isa/tools/bringup/check_linx_virt_defconfig_spec.py --defconfig /Users/zhoubot/linx-isa/kernel/linux/arch/linx/configs/linx_v150_defconfig --report-out /Users/zhoubot/linx-isa/docs/bringup/gates/linxisa_virt_defconfig_audit.json

For the merged direct-kernel recovery lane, these wrappers are firmwareless by default. If you override QEMU_EXTRA_ARGS, preserve -bios none unless you are explicitly testing a firmware artifact.

Treat every runtime wrapper as fail-closed: guest success markers never override a QEMU timeout or nonzero process exit. A strict published result must name the exact KERNEL, INITRD or rootfs image, and QEMU binary and retain their SHA-256 provenance. If a legacy wrapper only prints a transcript, keep that result diagnostic until a machine-readable provenance record accompanies it.

Promoted vmlinux provenance

• Build a kernel intended for promoted runtime evidence with tools/bringup/run_linux_vmlinux_build_clean.sh --fresh --target vmlinux. A successful build must produce and self-verify <out-dir>/vmlinux.provenance.json.
• Before promotion, verify that report with tools/bringup/linux_vmlinux_provenance.py verify and require a clean source, a fresh generation, the exact pinned Linux HEAD, and the expected Clang and ld.lld SHA-256 values.
• The report must bind the Linux source state, build argv, config, compiler, linker, make/host tools, build helper, and resulting vmlinux. A directory ownership or deletion marker is not artifact provenance.
• A parent workload or release manifest must record the SHA-256 of the verified provenance report. Without that binding, runtime output is diagnostic even when the guest passes.

Deterministic smoke repro

• For early boot triage, prefer the pinned vmlinux + initramfs smoke form so you can move the boot boundary without rebuilding QEMU each iteration:

TIMEOUT=20 LINX_DISABLE_TIMER_IRQ=1 SKIP_BUILD=1 \
QEMU=/Users/zhoubot/linx-isa/emulator/qemu/build/qemu-system-linx64 \
python3 /Users/zhoubot/linx-isa/kernel/linux/tools/linxisa/initramfs/smoke.py

• Keep the matching kernel rebuild command alongside it:

bash /Users/zhoubot/linx-isa/tools/bringup/run_linux_vmlinux_build_clean.sh \
  --linux-root /Users/zhoubot/linx-isa/kernel/linux \
  --out-dir /Users/zhoubot/linx-isa/kernel/linux/build-linx-fixed \
  --clang /Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang \
  --gmake /opt/homebrew/bin/gmake \
  --target vmlinux --fresh

• Reproduce the current BusyBox rootfs lane with the clean helper path and explicit firmwareless boot when you need a rootfs-specific verdict instead of an initramfs-only boundary:

QEMU="$(bash /Users/zhoubot/linx-isa/tools/bringup/run_qemu_build_clean.sh \
  --qemu-root /Users/zhoubot/linx-isa/emulator/qemu \
  --out-dir /tmp/linx-qemu-clean-build \
  --target qemu-system-linx64)" \
SKIP_BUILD=1 QEMU="$QEMU" QEMU_EXTRA_ARGS='-bios none' \
python3 /Users/zhoubot/linx-isa/kernel/linux/tools/linxisa/busybox_rootfs/boot.py

• If the active arch/linx tree was replaced from a recovered authoritative patch and the clean build helper falls into Kconfig restart prompts, seed the build explicitly from the checked-in Linx defconfig before trying vmlinux:

cd /Users/zhoubot/linx-isa/kernel/linux
PATH=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin:$PATH \
/opt/homebrew/bin/gmake \
  O=/Users/zhoubot/linx-isa/kernel/linux/build-linx-fixed \
  ARCH=linx \
  LLVM=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/ \
  'CC=/Users/zhoubot/linx-isa/compiler/llvm/build-linxisa-clang/bin/clang --target=linx64-unknown-linux-gnu -fintegrated-as' \
  HOSTCC=/usr/bin/clang HOSTCXX=/usr/bin/clang++ \
  linx_v150_defconfig olddefconfig

Trap triage

1. capture first repeated trap tuple (pc, cause, context),
2. identify whether the PC belongs to the kernel or a user PIE; for a PIE, subtract the mapped load base before symbolizing the matching user ELF,
3. disassemble neighborhood,
4. classify failure (target legality, ABI/call-ret, translation/fault),
5. bisect Linux/QEMU SHAs when needed.

When a user trap contains an implausibly small address after paired loads, also inspect T/U-hand queue age across the producer and every consumer. A multi-def instruction gives its destinations one instruction index but still pushes them in operand order; compiler queue allocation must therefore include same-instruction DefOpNo order. Two later consumers both reading t#1 or u#1 can be a compiler depth-assignment bug even when each instruction's standalone QEMU semantics is correct.

Cross-stack checks

• kernel call/ret path matches contract,
• dynamic targets are legal block starts,
• regression rerun includes strict AVS system/runtime checks,
• timer IRQ behavior remains enabled in strict closure unless explicitly waived.
• treat /chosen/bootargs string corruption separately from later parser bugs: if the command line bytes are already wrong before parse_args(), fix the DT property read/import path first.
• Do not rely on a previously built build-linx-fixed/vmlinux after replacing arch/linx from a recovered patch. Rebuild from current source first; if the rebuild does not complete, treat runtime smoke results from the stale image as non-authoritative.

Recovery-forward-port note

• When the Linux port is sourced from an older recovered patch, expect two independent classes of failures:
  • source/API drift against current kernel headers and MM helpers,
  • old Linx asm surface (b.attr, old block-head macros, unfused symbolic BSTART CALL, %tpcrel_hi/%tpcrel_lo) that depends on compiler-side compatibility.
• Separate those two before debugging runtime behavior: refresh the in-repo clang binary first when assembler/parser changes were made, then resume kernel source forward-porting.
• When the clean rebuild stops in the repeated SelectionDAGISel::isOrEquivalentToAdd crash family, use the generated /var/folders/.../*.sh Clang crash repro first. If removing the quoted cc1 vectorizer flags makes the repro pass, prefer an object-scoped kernel workaround (CFLAGS_<obj>.o += -fno-vectorize -fno-slp-vectorize) before widening backend changes. Current verified progression moved through the earlier fs/nfs, fs/lockd, and lib/random32.o blockers and now stops later at lib/hexdump.o.

Timer and BI-state diagnostics

• Distinguish signal-path success from timer-path success: ctx_ri_step_trap_smoke.py validates trap-resume (BI=1 + restore); ctx_tq_irq_smoke.py validates timer-interrupt coverage.
• When diagnosing state corruption, use QEMU debug dump mode (LINX_CPU_DUMP_DEBUG=1) and inspect EBARG/BSTATE plus debug SSR (DBCR/DBVR/DWCR/DWVR) before and after trap return.
• Do not mark timer PASS if the only evidence is mismatch==0 with irq0_delta==0; that is a non-covered path.

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 kernel/runtime contract needed for stable closure,
  • new mandatory runtime gate/repro command/env,
  • new recurring trap/timer triage sequence.
• 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-linux
  • 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 linux-bringup and Linux-facing call/ret parity checks.

References

• references/runtime_triage.md