# Pactor64 — Raspberry Pi 5 ARM64 Port TODO

## Phase 2: Interrupts + Timer (GIC-400 + ARM Generic Timer)

- [ ] Create `kernel/gic.c` + `kernel/gic.h`
  - [ ] GIC-400 distributor init (GICD_CTLR at 0xFF841000)
  - [ ] GIC-400 CPU interface init (GICC_CTLR at 0xFF842000)
  - [ ] Enable specific IRQs (timer = IRQ 27/30, UART = IRQ 33)
  - [ ] IRQ acknowledge + EOI functions
- [ ] Create `kernel/timer.c` + `kernel/timer.h`
  - [ ] Read CNTFRQ_EL0 (timer frequency, ~54MHz on Pi 5)
  - [ ] Configure CNTP_TVAL_EL0 for 100Hz tick
  - [ ] Enable timer via CNTP_CTL_EL0
  - [ ] Timer IRQ handler (PPI 14, IRQ 30 on GIC)
  - [ ] `timer_ticks` counter, `uptime` command
- [ ] Create `kernel/vectors.S`
  - [ ] Exception vector table (16 entries × 128 bytes)
  - [ ] Sync handler (for SVC, data abort, instruction abort)
  - [ ] IRQ handler (save/restore all registers X0-X30)
  - [ ] FIQ / SError stubs
  - [ ] Set VBAR_EL1 to vector table address
- [ ] Update `kernel/entry.S`
  - [ ] Configure SCR_EL3 (if running from EL3)
  - [ ] Set VBAR_EL1
  - [ ] Enable IRQ routing (DAIF.I = 0)
  - [ ] Configure GIC + timer before kernel_main
- [ ] Update `kernel/main.c`
  - [ ] Add `ticks` command
  - [ ] Add `uptime` command
  - [ ] Timer ISR increments counter
- [ ] Test on Pi 5: timer ticks increment, uptime works

## Phase 3: Memory Management (MMU + Translation Tables)

- [ ] Create `kernel/mmu.c` + `kernel/mmu.h`
  - [ ] Parse firmware memory map (ATAGS or DTB at x0)
  - [ ] Create translation tables for TTBR1_EL1 (kernel space)
  - [ ] Identity-map kernel region (0x80000, 2MB block)
  - [ ] Map peripheral MMIO region (0xFE000000+)
  - [ ] Map GIC region (0xFF840000+)
  - [ ] Configure MAIR_EL1 (memory attributes)
  - [ ] Configure TCR_EL1 (granule size, VA range)
  - [ ] Enable MMU (SCTLR_EL1.M = 1)
- [ ] Create `kernel/pmm.c` + `kernel/pmm.h`
  - [ ] Bitmap-based physical page allocator
  - [ ] Parse DTB/ATAGS for available memory regions
  - [ ] `pmm_alloc_page()` / `pmm_free_page()`
- [ ] Create `kernel/heap.c` or integrate into main
  - [ ] Simple bump allocator or free-list allocator
  - [ ] `kmalloc()` / `kfree()`
- [ ] Test: malloc works, memory info command

## Phase 4: Syscalls + Userspace (EL0)

- [ ] Create `kernel/syscall.c` + `kernel/syscall.h`
  - [ ] SVC handler (read ESR_EL1 for SVC number from X8)
  - [ ] Syscall dispatch table (Linux ARM64 compatible numbers)
  - [ ] Implement: sys_write(64), sys_read(63), sys_exit(93), sys_brk(214)
- [ ] Create `kernel/syscall_entry.S`
  - [ ] SVC entry: save all registers (X0-X30, SP_EL0, SPSR_EL1, ELR_EL1)
  - [ ] Switch to kernel stack (from SP_EL1)
  - [ ] Call syscall_dispatch
  - [ ] Restore registers + ERET to EL0
- [ ] Create `kernel/elf.c` (port from x86-64)
  - [ ] ELF64 header validation (AArch64 machine type)
  - [ ] Load PT_LOAD segments
  - [ ] Return entry point
- [ ] Create userspace entry (`libc/start.S`)
  - [ ] `_start` at EL0, set up user stack, call main
  - [ ] SVC #0 for syscalls
- [ ] Port `libc/start.c` (printf, malloc, strings)
  - [ ] Replace x86 `syscall` instruction with ARM `svc #0`
  - [ ] Use X8 for syscall number (Linux ARM64 ABI)
- [ ] Create `userspace.ld` (load at 0x400000)
- [ ] Cross-compile hello.elf for AArch64
- [ ] Test: hello.elf runs in EL0, prints via SVC

## Phase 5: Storage + Filesystem + Applications

- [ ] Create `kernel/emmc.c` + `kernel/emmc.h`
  - [ ] EMMC2 controller driver (BCM2712 SD card interface)
  - [ ] Initialize SD card (CMD0, CMD8, ACMD41, CMD2, CMD3, CMD7, CMD17)
  - [ ] Read sectors (single + multi-block)
  - [ ] Write sectors
- [ ] Integrate ext2 filesystem (port from x86-64)
  - [ ] Connect ext2 block_read callback to EMMC driver
  - [ ] Mount SD card partition
  - [ ] Read files from ext2
- [ ] Create `mkcard.sh`
  - [ ] Create FAT32 boot partition (firmware + kernel)
  - [ ] Create ext2 data partition (applications)
  - [ ] Copy firmware files + kernel8.img + config.txt
- [ ] Port ELF loader to load from filesystem
  - [ ] `load <filename>` command
  - [ ] `execute <filename>` command
- [ ] Recompile applications for AArch64
  - [ ] fibonacci.c, primes.c, ascii.c, matrix.c, guess.c, sort.c
  - [ ] hello.elf
  - [ ] Update Makefile cross-compilation targets
- [ ] Build embedded application registry (same as x86-64)
- [ ] Test: execute fibonacci on Pi 5

## Phase 6: Embedded Features

- [ ] GPIO driver (`kernel/gpio.c`)
  - [ ] GPIO function select (FSEL registers)
  - [ ] GPIO set/clear/read
  - [ ] LED blink test
  - [ ] Button input
- [ ] I2C driver (`kernel/i2c.c`)
  - [ ] BSC (Broadcom Serial Controller) at 0xFE804000 (I2C1)
  - [ ] Init, start, stop, read, write
  - [ ] Sensor reading (e.g., BME280 temperature/humidity)
- [ ] SPI driver (`kernel/spi.c`)
  - [ ] BCM2712 SPI master
  - [ ] Init, transfer
- [ ] Framebuffer (`kernel/fb.c`)
  - [ ] Mailbox interface to VideoCore GPU (0xFE00B880)
  - [ ] Allocate framebuffer via mailbox property tags
  - [ ] Pixel drawing, basic text rendering
  - [ ] Replace serial-only output with HDMI display
- [ ] Network (`kernel/net.c`)
  - [ ] Ethernet via PCIe/USB (Pi 5 uses different NIC than Pi 4)
  - [ ] Or USB CDC Ethernet for simpler approach
- [ ] PWM (`kernel/pwm.c`)
  - [ ] Servo/motor control
  - [ ] Audio output
- [ ] Watchdog (`kernel/watchdog.c`)
  - [ ] Hardware watchdog timer
  - [ ] System reset on hang

## Cross-Cutting Tasks

- [ ] Add regression test framework (same pattern as x86-64)
- [ ] Add memory protection (page permissions for EL0 vs EL1)
- [ ] Add SMP support (bring up cores 1-3)
- [ ] Add spinlocks / mutexes for multi-core
- [ ] Add DMA support for fast SD card / peripheral transfers
- [ ] Power management (clock gating, sleep states)
- [ ] Documentation: hardware register map, boot sequence, API reference
- [ ] Create CI/build script for automated testing