ARM64 parity WIP + planning doc

.github/workflows/arm64-boot.yml

@@ -0,0 +1,92 @@
+name: ARM64 Boot Test
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build-and-boot-arm64:
+    name: Build and Boot ARM64 Kernel
+    runs-on: ubuntu-24.04-arm64
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Rust nightly
+        uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: rust-src, llvm-tools-preview
+
+      - name: Verify Rust setup
+        run: |
+          rustc -Vv
+          cargo -Vv
+          rustup component list --installed
+
+      - name: Install QEMU for ARM64
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y qemu-system-arm
+          qemu-system-aarch64 --version
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: ~/.cargo/registry
+          key: ${{ runner.os }}-arm64-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo build
+        uses: actions/cache@v4
+        with:
+          path: target
+          key: ${{ runner.os }}-arm64-cargo-build-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Build ARM64 kernel
+        run: |
+          cargo build --release \
+            --target aarch64-breenix.json \
+            -Z build-std=core,alloc \
+            -p kernel \
+            --bin kernel-aarch64
+
+      - name: Verify kernel binary
+        run: |
+          ls -la target/aarch64-breenix/release/kernel-aarch64
+          file target/aarch64-breenix/release/kernel-aarch64
+
+      - name: Boot ARM64 kernel in QEMU
+        run: |
+          timeout 30 qemu-system-aarch64 \
+            -M virt \
+            -cpu cortex-a72 \
+            -m 512M \
+            -nographic \
+            -kernel target/aarch64-breenix/release/kernel-aarch64 \
+            2>&1 | tee arm64-boot.log &
+          QEMU_PID=$!
+
+          # Wait for boot or timeout
+          for i in $(seq 1 30); do
+            if grep -q "Hello from ARM64" arm64-boot.log 2>/dev/null; then
+              echo "SUCCESS: ARM64 kernel booted successfully!"
+              kill $QEMU_PID 2>/dev/null || true
+              exit 0
+            fi
+            sleep 1
+          done
+
+          echo "TIMEOUT: Kernel did not print expected message"
+          kill $QEMU_PID 2>/dev/null || true
+          echo "=== Boot log ==="
+          cat arm64-boot.log
+          exit 1
+
+      - name: Upload boot log
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: arm64-boot-log-${{ github.run_number }}
+          path: arm64-boot.log
+          if-no-files-found: ignore
+          retention-days: 7

AGENTS.md

@@ -61,43 +61,9 @@ ls -t logs/*.log | head -1 | xargs less
 
 ## Development Workflow
 
-### Agent-Based Development (MANDATORY)
+### Agent-Based Development
 
-**The main conversation is for ORCHESTRATION ONLY.** Never execute tests, run builds, or perform iterative debugging directly in the top-level session. This burns token context and leads to session exhaustion.
-
-**ALWAYS dispatch to agents:**
-- Build verification and compilation checks
-- GDB debugging sessions (via gdb_chat.py)
-- Code exploration and codebase research
-- Any task that may require multiple iterations or produce verbose output
-
-**The orchestrator session should only:**
-- Plan and decompose work into agent-dispatchable tasks
-- Review agent reports and synthesize findings
-- Make high-level decisions based on agent results
-- Coordinate multiple parallel agent investigations
-- Communicate summaries and next steps to the user
-
-**Anti-pattern (NEVER DO THIS):**
-```
-# DON'T run kernel directly - ALWAYS use GDB
-cargo run --release --bin qemu-uefi
-cargo run -p xtask -- boot-stages
-# DON'T grep through large outputs in main session
-cat target/output.txt | grep ...
-```
-
-**Correct pattern:**
-```
-# DO use GDB for kernel debugging
-printf 'break kernel::kernel_main\ncontinue\ninfo registers\nquit\n' | python3 breenix-gdb-chat/scripts/gdb_chat.py
-
-# DO dispatch to an agent for GDB sessions
-Task(subagent_type="general-purpose", prompt="Use gdb_chat.py to debug the
-clock_gettime syscall. Set breakpoint, examine registers, report findings.")
-```
-
-When a debugging task requires multiple iterations, dispatch it ONCE to an agent with comprehensive instructions. The agent will iterate internally and return a summary. If more investigation is needed, dispatch another agent - don't bring the iteration into the main session.
+Use agents when it’s helpful for long or iterative investigations, but it is no longer mandatory to route all work through agents. The main session may run commands, do code exploration, or perform debugging directly as needed.
 
 ### Feature Branches (REQUIRED)
 Never push directly to main. Always:

aarch64-breenix.json

@@ -0,0 +1,27 @@
+{
+  "llvm-target": "aarch64-unknown-none-softfloat",
+  "data-layout": "e-m:e-p270:32:32-p271:32:32-p272:64:64-i8:8:32-i16:16:32-i64:64-i128:128-n32:64-S128-Fn32",
+  "arch": "aarch64",
+  "target-endian": "little",
+  "target-pointer-width": "64",
+  "target-c-int-width": "32",
+  "os": "none",
+  "executables": true,
+  "linker-flavor": "gnu-lld",
+  "linker": "rust-lld",
+  "panic-strategy": "abort",
+  "disable-redzone": true,
+  "features": "+v8a,+strict-align",
+  "max-atomic-width": 128,
+  "relocation-model": "static",
+  "code-model": "small",
+  "pre-link-args": {
+    "gnu-lld": [
+      "-Tkernel/src/arch_impl/aarch64/linker.ld",
+      "--fix-cortex-a53-843419"
+    ]
+  },
+  "stack-probes": {
+    "kind": "none"
+  }
+}

docker/qemu-aarch64/Dockerfile

@@ -0,0 +1,15 @@
+# Dockerfile for running Breenix ARM64 tests in isolated QEMU
+# Uses qemu-system-aarch64 for ARM64 kernel testing
+
+FROM ubuntu:24.04
+
+# Install QEMU ARM64 emulator
+RUN apt-get update && apt-get install -y \
+    qemu-system-arm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create working directory
+WORKDIR /breenix
+
+# Default command - will be overridden
+CMD ["qemu-system-aarch64", "--version"]

docker/qemu-aarch64/run-arm64-boot.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+# Run ARM64 kernel boot test in Docker
+# Usage: ./run-arm64-boot.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BREENIX_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Find the ARM64 kernel binary
+KERNEL_BIN="$BREENIX_ROOT/target/aarch64-unknown-none/release/kernel-aarch64"
+if [ ! -f "$KERNEL_BIN" ]; then
+    echo "Error: ARM64 kernel not found. Build with:"
+    echo "  cargo build --release --target aarch64-unknown-none --features testing -p kernel --bin kernel-aarch64"
+    exit 1
+fi
+
+echo "Running ARM64 boot test in Docker..."
+echo "Kernel: $KERNEL_BIN"
+
+# Create output directory
+OUTPUT_DIR="/tmp/breenix_arm64_boot"
+rm -rf "$OUTPUT_DIR"
+mkdir -p "$OUTPUT_DIR"
+
+# Build Docker image if needed
+docker build -q -t breenix-qemu-aarch64 "$SCRIPT_DIR" > /dev/null
+
+# Run QEMU in Docker
+# Using virt machine with:
+# - 512MB RAM
+# - 1 CPU
+# - PL011 UART for serial output
+# - No graphics
+docker run --rm \
+    -v "$KERNEL_BIN:/breenix/kernel.elf:ro" \
+    -v "$OUTPUT_DIR:/output" \
+    breenix-qemu-aarch64 \
+    timeout 30 qemu-system-aarch64 \
+        -machine virt \
+        -cpu cortex-a72 \
+        -m 512 \
+        -kernel /breenix/kernel.elf \
+        -nographic \
+        -serial file:/output/serial.txt \
+        -d guest_errors,unimp \
+        -D /output/qemu_debug.txt \
+        -no-reboot \
+    &
+QEMU_PID=$!
+
+# Wait for output or timeout
+echo "Waiting for kernel output (30s timeout)..."
+FOUND=false
+for i in $(seq 1 30); do
+    if [ -f "$OUTPUT_DIR/serial.txt" ]; then
+        if grep -q "Breenix" "$OUTPUT_DIR/serial.txt" 2>/dev/null || \
+           grep -q "kernel_main" "$OUTPUT_DIR/serial.txt" 2>/dev/null || \
+           grep -q "Hello" "$OUTPUT_DIR/serial.txt" 2>/dev/null; then
+            FOUND=true
+            break
+        fi
+    fi
+    sleep 1
+done
+
+# Cleanup
+docker kill $(docker ps -q --filter ancestor=breenix-qemu-aarch64) 2>/dev/null || true
+
+# Check results
+echo ""
+echo "========================================="
+if $FOUND; then
+    echo "ARM64 BOOT: PASS"
+    echo "Kernel produced output!"
+    echo ""
+    echo "Serial output:"
+    cat "$OUTPUT_DIR/serial.txt" 2>/dev/null | head -50
+else
+    echo "ARM64 BOOT: FAIL/TIMEOUT"
+    echo ""
+    echo "Serial output (if any):"
+    cat "$OUTPUT_DIR/serial.txt" 2>/dev/null | head -20 || echo "(no output)"
+    echo ""
+    echo "QEMU debug log:"
+    cat "$OUTPUT_DIR/qemu_debug.txt" 2>/dev/null | head -20 || echo "(no debug log)"
+    exit 1
+fi
+echo "========================================="

docker/qemu/Dockerfile.aarch64

@@ -0,0 +1,20 @@
+# Dockerfile for running Breenix ARM64 tests in isolated QEMU
+# Uses qemu-system-aarch64 with virt machine
+
+FROM ubuntu:24.04
+
+# Install QEMU ARM64 with display support
+RUN apt-get update && apt-get install -y \
+    qemu-system-arm \
+    # X11 and SDL support for graphical display
+    libsdl2-2.0-0 \
+    libgtk-3-0 \
+    libvte-2.91-0 \
+    x11-apps \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create working directory
+WORKDIR /breenix
+
+# Default command - will be overridden
+CMD ["qemu-system-aarch64", "--version"]