Arch porting guide

Hot-path design per architecture: traps, context switch, uaccess, interrupt controllers β€” source: docs/architecture/riscv64.md / aarch64.md

Β§1riscv64: the trap path

  • Origin detection: the sscratch/tp swap β€” kernel mode has sscratch=0 and tp=Task; user mode the reverse (early boots fall back to sstatus.SPP while tp=hartid<0x1000).
  • A 288-byte PtRegs repr(C): x1–x31 in order + status/badaddr/cause/orig_a0 (syscall rollback).
  • Kernel traps switch to a per-CPU interrupt stack (16KB/CPU); user traps take the kernel stack from ti_kernel_sp (task+0x08).
  • The big-lock protocol: entry takes the kernel big lock with amoswap.d.aq, exit releases with amoswap.d.rl; before exit sc.d clears any LR/SC reservation (preventing cross-context leaks) + fence iorw,iorw.
  • Hard-coded task offsets (flags 0x00 / preempt 0x04 / kernel_sp 0x08 / user_sp 0x10 / cpu 0x18 / state 0x20 / pid 0x24).

Context switch (Linux order)

fpu_save_for_switch   # save f0-f31+fcsr only if FS==DIRTY, set OFF
set_prev β†’ switch_mm  # sfence.vma before and after satp (ASID=0, not embedded)
__switch_to           # ra/sp/s0-s11/SUM, tp=next
restore_fpu           # enable only if fs != OFF

uaccess

  • SUM-bit brackets (Rust + assembly implementations, returning the uncopied byte count); an .ex_table insn,fixup exception table.
  • Three-phase copy: aligned bytes β†’ an 8Γ— unrolled 64B/iteration word copy with shifts (threshold WORD_COPY_MIN=71) β†’ tail bytes.

ASID / TLB / IPI

  • Sv39 9-bit ASIDs: 0=kernel, 1=reserved, 2–511 user; an atomic bitmap with CAS retry, linear scan on exhaustion; the flush family all/asid/page/range/kernel.
  • IPIs: 0=reschedule, 1=halt, received via SSIP.

Β§2x86_64: the three hot-path levers

  • FSGSBASE: rdfsbase/wrfsbase instead of the FS/GS MSR pair β€” measured 393 ns/switch.
  • Lazy FPU: xsaveopt moved into the #NM handler (the kernel binary verified free of compiler FP).
  • PCID: CPUID-gated enable, per-mm tags + invlpg shootdowns (armed only on CPUs reporting the bit β€” the "arm everywhere" #GP bug is fixed).
  • Combined: lat_ctx -s64 2 4.97β†’2.07 Β΅s (βˆ’58%).

x86_64 specifics

  • SMAP (divergence D-18): CR4.SMAP enabled; usercopy uses pushfq/orq/popfq AC brackets instead of STAC/CLAC β€” which unconditionally #UD under QEMU TCG (established by paired trials); ~55 ns per bracket; SMAP-VIOL beacons silent across the suite.
  • Syscall face: MSR entry; SYSRET eligibility falls back to iret on TF|RF; a dirty EFLAGS.DF entering the kernel once reversed rep movsb (fixed); CR0.WP set from the earliest boot.
  • Userspace W^X: NX mappings, PT_GNU_STACK, READ_IMPLIES_EXEC.

Β§3aarch64: porting notes

  • Per-task state: TPIDR_EL0 is the task TLS state (user-writable, no set-tls syscall; saved/installed at the __switch_to commit point, inherited on fork, double-cleared on exec) β€” losing it killed the first fork.
  • FPSIMD: prebuilt libraries' NEON dirties user FP during syscalls β€” EL0 vector traps capture live registers into thread.user_fpsimd and reinstall before eret; signal frames read from that buffer.
  • The SVC semantics difference: after SVC, ELR points past the instruction (ecall stays on it) β€” the syscall path never advances PC, ERESTARTSYS rewinds pcβˆ’=4.
  • GICv3: with DS=1, GICD_CTLR bit1 = Grp1NS enable; IGROUPR at 0x0080; ICC_SGI1R encoding; the virtual timer PPI 11 = INTID 27; PL011 RX needs both RX|receive-timeout interrupts armed; unblocking takes both legs (the GIC CPU interface + clearing PSTATE.DAIF.I).
  • Memory map: PAGE_OFFSET=0xffff_c000_0000_0000, TASK_SIZE=256GB (a 1TiB constant once pushed the mmap base outside the walker subtree), TCR_EL1.IPS=44-bit (the 32-bit default turns β‰₯4GB translations into address-size aborts instead of translation faults).
  • The ASID fix: NEXT_ASID monotonic without an in-use check β†’ permanent None after 254 mms, everything falling to ASID 0 with full flushes; ported riscv64's bitmap over a 256-entry pool.

Current edges (stated plainly)

  • A 1/9 boot flake (the trap frame lands exactly past the linear-map end β€” a kernel-stack-top problem, under investigation).
  • LTP-on-aarch64 not started (cross-build + serial-fed smoke subset laid down).
  • debug= boot flags unavailable (the EL2 trampoline destroys the DTB pointer before cmdline parsing) β€” compile-time feature gating instead.

Β§4Checklist for a new port

  1. Boot protocol and early mapping (the three-stage page-table pages before memblock).
  2. Trap entry: origin detection, PtRegs, per-CPU interrupt stacks, the big-lock aq/rl pair, LR/SC (or equivalent) cleanup.
  3. The context-switch order (FPU state, address-space switch + TLB caveats).
  4. uaccess (SUM/AC-class mechanisms + the exception table).
  5. Interrupt controller + timer (Sstc / APIC timer / GICv3 PPIs).
  6. Per-CPU areas and the tp/TPIDR-class registers.
  7. Integration with INV-LOCK-7 (per-mm PTE locks) and D-17 (the MMIO arena, no identity window).