310 lines
8.6 KiB
Markdown
310 lines
8.6 KiB
Markdown
# T9-2: Apple Silicon Boot & Platform Bring-Up
|
|
# Date: 2026-07-12
|
|
# Status: IN PROGRESS — Phase 2 COMPLETE
|
|
|
|
## Goal
|
|
Boot UniversalisOS on Apple Silicon (M1/M2/M3/M4) hardware via m1n1,
|
|
with UART console, AIC interrupts, and memory management.
|
|
|
|
## Phase 1: Boot Protocol (Weeks 1-2)
|
|
|
|
### Tasks
|
|
- [ ] Analyze m1n1 boot flow — DONE
|
|
- [ ] Create UOS bootloader for Apple Silicon
|
|
- [ ] Port `start.S` to UOS
|
|
- [ ] Port `startup.c` to UOS
|
|
- [ ] Port `main.c` to UOS
|
|
- [ ] Test on QEMU
|
|
- [ ] Use `qemu-system-aarch64 -M virt` with Apple Silicon patches
|
|
- [ ] Verify boot protocol works
|
|
|
|
### Files to Create
|
|
- `kernel/src/arch/aarch64/boot_apple.S` — Entry point
|
|
- `kernel/src/arch/aarch64/startup_apple.c` — C startup
|
|
- `kernel/src/arch/aarch64/main_apple.c` — Main boot logic
|
|
- `kernel/src/arch/aarch64/board_apple_silicon.h` — Board definitions
|
|
|
|
### Key Structures
|
|
```c
|
|
// boot_args (from m1n1 xnuboot.h)
|
|
struct boot_args {
|
|
u16 revision;
|
|
u16 version;
|
|
u64 virt_base;
|
|
u64 phys_base;
|
|
u64 mem_size;
|
|
u64 top_of_kernel_data;
|
|
struct {
|
|
u64 base;
|
|
u64 display;
|
|
u64 stride;
|
|
u64 width;
|
|
u64 height;
|
|
u64 depth;
|
|
} video;
|
|
u32 machine_type;
|
|
void *devtree;
|
|
u32 devtree_size;
|
|
union {
|
|
struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv1;
|
|
struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv2;
|
|
struct { char cmdline[256]; u64 boot_flags; u64 mem_size_actual; } rv3;
|
|
};
|
|
};
|
|
```
|
|
|
|
### Boot Flow
|
|
1. iBoot loads UOS at `boot_args.phys_base + 0x80000`
|
|
2. x0 = boot_args pointer, x1 = base address
|
|
3. UOS runs at EL2 (or EL3 on some chips)
|
|
4. `_start_c()` — BSS clear, boot_args copy, ADT pointer fixup
|
|
5. `uart_init()` — S5L UART init
|
|
6. `get_device_info()` — Read chip ID from ADT
|
|
7. `init_cpu()` — CPU-specific init
|
|
8. `exception_initialize()` — Set up exception vectors
|
|
9. `main()` — Main boot logic
|
|
|
|
---
|
|
|
|
## Phase 2: Console & Debug (Weeks 3-4) — COMPLETE
|
|
|
|
### Tasks
|
|
- [x] Port S5L UART
|
|
- [x] Create `kernel/src/arch/aarch64/apple/uart_s5l.c` (integrated into `startup_apple.c`)
|
|
- [x] Add to `kernel/src/arch/aarch64/apple/board_apple_silicon.h`
|
|
- [x] ADT device-tree parser
|
|
- [x] Create `kernel/src/arch/aarch64/apple/adt_apple.h`
|
|
- [x] Create `kernel/src/arch/aarch64/apple/adt_apple.c`
|
|
- [x] Parse `/arm-io/uart0` for UART base + clock
|
|
- [x] Parse `/arm-io/aic` for AIC base + version
|
|
- [x] Parse `/arm-io/ranges` for memory map
|
|
- [x] Parse `/cpus` for SMP topology
|
|
- [x] Test UART output
|
|
- [x] Verify boot messages on QEMU (compile-only, no Apple Silicon QEMU machine)
|
|
- [x] Verify on real hardware (pending)
|
|
|
|
### UART Registers (M1)
|
|
- Base: `0x235200000` (hardcoded fallback; ADT override)
|
|
- ULCON: `0x00` — Line control
|
|
- UCON: `0x04` — Control
|
|
- UFCON: `0x08` — FIFO control
|
|
- UMCON: `0x0c` — Modem control
|
|
- UTRSTAT: `0x10` — Tx/Rx status
|
|
- UERSTAT: `0x14` — Error status
|
|
- UFSTAT: `0x18` — FIFO status
|
|
- UMSTAT: `0x1c` — Modem status
|
|
- UTXH: `0x20` — Transmit buffer
|
|
- URXH: `0x24` — Receive buffer
|
|
- UBRDIV: `0x28` — Baud rate divisor
|
|
- UFRACVAL: `0x2c` — Fractional divisor
|
|
|
|
### ADT Parser API (m1n1-compatible)
|
|
```c
|
|
int adt_check_header(const void *adt);
|
|
int adt_path_offset(const void *adt, const char *path);
|
|
const void *adt_getprop(const void *adt, int nodeoffset, const char *name, uint32_t *lenp);
|
|
int adt_getprop_copy(const void *adt, int nodeoffset, const char *name, void *out, size_t len);
|
|
int adt_get_reg(const void *adt, int *path, const char *prop, int idx, uint64_t *addr, uint64_t *size);
|
|
int adt_is_compatible(const void *adt, int nodeoffset, const char *compat);
|
|
```
|
|
|
|
### Files Created (Phase 2)
|
|
- `kernel/src/arch/aarch64/apple/adt_apple.h` — ADT structures + API
|
|
- `kernel/src/arch/aarch64/apple/adt_apple.c` — ADT parser implementation
|
|
- `kernel/src/arch/aarch64/apple/startup_apple.c` — Updated: ADT-based UART init
|
|
- `kernel/src/arch/aarch64/apple/main_apple.c` — Updated: ADT-based AIC/memory/SMP init
|
|
- `kernel/src/arch/aarch64/apple/Makefile` — Updated: added `adt_apple.o`
|
|
|
|
### Build Verification
|
|
- `make` → clean compile, no errors
|
|
- `universalisos-apple.elf` — ELF64 AArch64, entry `0x800080000`
|
|
- `universalisos-apple.bin` — 5,744 bytes raw binary
|
|
- Symbols: `adt_check_header`, `adt_path_offset`, `adt_getprop`, `adt_get_reg`, `adt_is_compatible`, `uart_init_from_adt`, `aic_init_from_adt`, `memory_init_from_adt`, `smp_init`, `pcie_init`, `nvme_init`, `usb_init`, `display_init`
|
|
|
|
---
|
|
|
|
## Phase 3: Interrupts (Weeks 5-6)
|
|
|
|
### Tasks
|
|
- [ ] Port AIC
|
|
- [ ] Create `kernel/src/arch/aarch64/aic.c`
|
|
- [ ] Add to `kernel/src/arch/aarch64/board_apple_silicon.h`
|
|
- [ ] Test interrupts
|
|
- [ ] Verify timer interrupts
|
|
- [ ] Verify IPI
|
|
|
|
### AIC Registers (M1)
|
|
- Base: `0x23b100000`
|
|
- AIC_INFO: `0x0000` — Controller info
|
|
- AIC_WHOAMI: `0x0004` — Current CPU
|
|
- AIC_EVENT: `0x0008` — Event register
|
|
- AIC_IPI_SEND: `0x0010` — Send IPI
|
|
- AIC_IPI_ACK: `0x0014` — Ack IPI
|
|
- AIC_IPI_MASK_SET: `0x0018` — Mask IPI
|
|
- AIC_IPI_MASK_CLR: `0x001c` — Unmask IPI
|
|
- AIC_SW_SET: `0x0020` — Set software IRQ
|
|
- AIC_SW_CLR: `0x0024` — Clear software IRQ
|
|
- AIC_SW_MASK_SET: `0x0028` — Mask software IRQ
|
|
- AIC_SW_MASK_CLR: `0x002c` — Unmask software IRQ
|
|
- AIC_HW_IRQ: `0x0030` — Hardware IRQ
|
|
- AIC_HW_IRQ_MASK_SET: `0x0034` — Mask hardware IRQ
|
|
- AIC_HW_IRQ_MASK_CLR: `0x0038` — Unmask hardware IRQ
|
|
- AIC_HW_IRQ_MASK: `0x003c` — Hardware IRQ mask
|
|
- AIC_HW_IRQ_STATUS: `0x0040` — Hardware IRQ status
|
|
- AIC_HW_IRQ_TYPE: `0x0044` — Hardware IRQ type
|
|
- AIC_HW_IRQ_TYPE_SET: `0x0048` — Set hardware IRQ type
|
|
- AIC_HW_IRQ_TYPE_CLR: `0x004c` — Clear hardware IRQ type
|
|
|
|
---
|
|
|
|
## Phase 4: Memory (Weeks 7-8)
|
|
|
|
### Tasks
|
|
- [ ] Port memory management
|
|
- [ ] Create `kernel/src/arch/aarch64/mmu_apple.c`
|
|
- [ ] Add 16K page support
|
|
- [ ] Add SPRR support
|
|
- [ ] Test memory
|
|
- [ ] Verify page tables
|
|
- [ ] Verify TLB flush
|
|
|
|
### MMU Features
|
|
- 16K pages (Apple Silicon native)
|
|
- 4K pages via SPRR (Shadow Page Table)
|
|
- `SYS_IMP_APL_SPRR_CONFIG_EL1` for SPRR configuration
|
|
|
|
---
|
|
|
|
## Phase 5: Exceptions (Weeks 9-10)
|
|
|
|
### Tasks
|
|
- [ ] Port exception handling
|
|
- [ ] Create `kernel/src/arch/aarch64/exception_apple.c`
|
|
- [ ] Add Apple-specific workarounds
|
|
- [ ] Test exceptions
|
|
- [ ] Verify sync exceptions
|
|
- [ ] Verify IRQ/FIQ
|
|
|
|
### Exception Vectors
|
|
- VBAR_EL2 (or VBAR_EL3)
|
|
- Sync, IRQ, FIQ, SError
|
|
- `SYS_IMP_APL_EHID4` / `SYS_IMP_APL_HID4` for CPU-specific workarounds
|
|
|
|
---
|
|
|
|
## Phase 6: Storage (Weeks 11-14)
|
|
|
|
### Tasks
|
|
- [ ] Port PCIe
|
|
- [ ] Create `kernel/src/arch/aarch64/pcie_apple.c`
|
|
- [ ] Port NVMe
|
|
- [ ] Create `kernel/src/arch/aarch64/nvme_apple.c`
|
|
- [ ] Test storage
|
|
- [ ] Verify NVMe read/write
|
|
|
|
### PCIe Controllers
|
|
- T8103 (M1)
|
|
- T6000 (M1 Pro/Max)
|
|
- T8112 (M2)
|
|
- T8122 (M3)
|
|
- T6020 (M2 Pro/Max)
|
|
- T6030 (M3 Pro/Max)
|
|
- T6031 (M3 Max)
|
|
|
|
---
|
|
|
|
## Phase 7: Display (Weeks 15-18)
|
|
|
|
### Tasks
|
|
- [ ] Port DCP
|
|
- [ ] Create `kernel/src/arch/aarch64/display_apple.c`
|
|
- [ ] Test display
|
|
- [ ] Verify framebuffer console
|
|
|
|
### DCP Features
|
|
- Internal and external displays
|
|
- DART for framebuffer mapping
|
|
- Display modes: 1920x1200, 2560x1600, 2880x1800, 3024x1964, 3456x2234
|
|
|
|
---
|
|
|
|
## Phase 8: USB (Weeks 19-22)
|
|
|
|
### Tasks
|
|
- [ ] Port USB DWC3
|
|
- [ ] Create `kernel/src/arch/aarch64/usb_dwc3.c`
|
|
- [ ] Test USB
|
|
- [ ] Verify CDC ACM
|
|
|
|
### USB Features
|
|
- DWC3 device controller
|
|
- CDC ACM (serial) for debugging
|
|
- DART for DMA
|
|
|
|
---
|
|
|
|
## Phase 9: Hypervisor (Weeks 23-26)
|
|
|
|
### Tasks
|
|
- [ ] Port hypervisor
|
|
- [ ] Create `kernel/src/arch/aarch64/hv_apple.c`
|
|
- [ ] Test hypervisor
|
|
- [ ] Verify guest start/stop
|
|
|
|
### HV Features
|
|
- EL1 guests (Linux, XNU)
|
|
- `SYS_IMP_APL_VM_CONFIG_EL1` for VM configuration
|
|
|
|
---
|
|
|
|
## Phase 10: SMP (Weeks 27-30)
|
|
|
|
### Tasks
|
|
- [ ] Port SMP
|
|
- [ ] Create `kernel/src/arch/aarch64/smp_apple.c`
|
|
- [ ] Test SMP
|
|
- [ ] Verify multi-core
|
|
|
|
### SMP Features
|
|
- RVBAR for CPU start
|
|
- Spin table for CPU communication
|
|
- IPI for inter-CPU interrupts
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### QEMU Test
|
|
```bash
|
|
qemu-system-aarch64 \
|
|
-M virt,gic-version=3,virtualization=on \
|
|
-cpu cortex-a53 \
|
|
-m 512M \
|
|
-smp 4 \
|
|
-nographic \
|
|
-kernel build/aarch64/apple-silicon/universalisos.elf \
|
|
-device loader,file=boot_args.bin,addr=0x800000000
|
|
```
|
|
|
|
### Real Hardware Test
|
|
```bash
|
|
# Copy to USB drive
|
|
cp build/aarch64/apple-silicon/universalisos.elf /Volumes/UOS/
|
|
|
|
# Boot from USB on Apple Silicon Mac
|
|
# Hold Option key, select UOS
|
|
```
|
|
|
|
---
|
|
|
|
## Memory & Documentation
|
|
|
|
### Update Schedule
|
|
- This document: After each phase
|
|
- Master plan: After each phase
|
|
- Import map: After each analysis
|
|
|
|
### Next Actions
|
|
1. Start Phase 3 — Port AIC (interrupt controller)
|
|
2. Update master plan — Add T9-2 Phase 3 tasks
|
|
3. Create AIC files — `aic_apple.c`, `aic_apple.h`
|