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