boot-analysis

What this skill does

# Boot Sequence Analysis for Breenix

Analyze and optimize the kernel boot process from bootloader to kernel ready.

## Purpose

Understanding the boot sequence is critical for debugging initialization issues, optimizing boot time, and ensuring proper subsystem ordering. This skill provides tools for analyzing boot logs, verifying checkpoint progression, and identifying boot failures.

## When to Use

- **Boot failures**: Kernel hangs or crashes during initialization
- **Initialization order issues**: Subsystems initialized in wrong order
- **Boot time optimization**: Reducing time from bootloader to ready
- **Checkpoint verification**: Confirming all subsystems initialize correctly
- **Boot regression analysis**: New code breaks boot sequence
- **Understanding boot flow**: Learning how kernel initialization works

## Breenix Boot Sequence

### Phase 1: Bootloader Handoff

**What happens**:
- Bootloader (bootloader crate) loads kernel
- Sets up initial page tables
- Provides memory map
- Transfers control to kernel entry point

**Entry point**: `kernel/src/main.rs` `kernel_main()`

**Initial state**:
```rust
// CPU in Long Mode (64-bit)
// Interrupts disabled
// Paging enabled (bootloader setup)
// Stack ready
// Physical memory mapped at offset
```

**Typical log output**:
```
[Bootloader messages]
Loading kernel...
Jumping to kernel entry point...
```

### Phase 2: Early Initialization

**Subsystems initialized** (in order):

**1. Logger**
```
[ INFO] Breenix OS starting...
```
- Serial output configured
- Framebuffer initialized
- Log level set

**2. GDT (Global Descriptor Table)**
```
[ INFO] GDT initialized
```
- Kernel/user code segments
- Kernel/user data segments
- TSS (Task State Segment)

**3. IDT (Interrupt Descriptor Table)**
```
[ INFO] IDT initialized
```
- Exception handlers (divide by zero, page fault, etc.)
- Interrupt handlers (timer, keyboard)
- Double fault handler with IST stack

**4. PIC (Programmable Interrupt Controller)**
```
[ INFO] PIC initialized
```
- Remapped to avoid conflicts
- All interrupts masked initially

### Phase 3: Memory Subsystem

**5. Frame Allocator**
```
[ INFO] Physical memory: 94 MiB usable
[DEBUG] Frame allocator initialized
```
- Reads bootloader memory map
- Identifies usable regions
- Initializes frame tracking

**6. Heap Allocator**
```
[ INFO] Heap: 1024 KiB
```
- Sets up kernel heap
- Enables dynamic allocation
- #[global_allocator] now functional

**7. Virtual Memory**
```
[DEBUG] Page table initialized
```
- Kernel page table setup
- Higher-half kernel mapping
- Recursive mapping if used

**8. Kernel Stacks**
```
[DEBUG] Kernel stack allocator initialized
```
- Stack bitmap allocator
- Guard pages configured
- IST stacks for exceptions

### Phase 4: Device Drivers

**9. Timer (PIT)**
```
[ INFO] Timer initialized at 100 Hz
```
- Configures Programmable Interval Timer
- Sets interrupt frequency
- Starts tick counting

**10. RTC (Real-Time Clock)**
```
[ INFO] RTC initialized: 2025-10-23 12:34:56 UTC
```
- Reads hardware clock
- Caches boot time
- Enables wall-clock time APIs

**11. Serial Input**
```
[ INFO] Serial input interrupts enabled
```
- UART receive interrupts
- Input buffer ready
- Command processing available

**12. Keyboard**
```
[ INFO] Keyboard initialized
```
- PS/2 keyboard driver
- Scancode processing
- Key event generation

### Phase 5: System Infrastructure

**13. Interrupts Enabled**
```
[ INFO] Enabling interrupts...
```
- Unmasks timer interrupt
- Unmasks keyboard interrupt
- System becomes responsive

**14. System Calls**
```
[ INFO] System call infrastructure initialized
```
- INT 0x80 handler registered
- Syscall dispatcher ready
- SWAPGS configured

**15. Threading**
```
[ INFO] Threading subsystem initialized
```
- Scheduler initialized
- Idle thread created
- Context switch infrastructure ready

**16. Process Management**
```
[ INFO] Process management initialized
```
- Process manager ready
- PID allocation working
- Fork/exec infrastructure initialized

### Phase 6: Testing (if enabled)

**17. POST (Power-On Self Test)**
```
[ INFO] Running POST tests...
=== Memory Test ===
✅ MEMORY TEST COMPLETE
...
🎯 KERNEL_POST_TESTS_COMPLETE 🎯
```
- Validates subsystems
- Runs self-checks
- Confirms kernel health

**18. Userspace Tests (if configured)**
```
RING3_SMOKE: creating hello_time userspace process
[ INFO] Process created: PID 1
USERSPACE OUTPUT: Hello from userspace!
```
- Creates test processes
- Verifies userspace execution
- Tests system calls

### Phase 7: Kernel Ready

**Final state**:
```
[ INFO] Kernel initialization complete
[ INFO] System ready
```
- All subsystems operational
- Ready for interactive use or more tests
- Idle loop or wait for input

## Boot Analysis Techniques

### Technique 1: Extract Boot Timeline

**Using log-analysis skill:**

```bash
# Get all initialization messages in order
grep "initialized\|INITIALIZED\|Initializing" logs/breenix_20251023_*.log

# Or more comprehensive
grep -E "INFO|WARN|ERROR" logs/latest.log | less
```

**Expected sequence**:
1. GDT initialized
2. IDT initialized
3. PIC initialized
4. Physical memory info
5. Timer initialized
6. RTC initialized
7. Interrupts enabled
8. Threading initialized
9. Process management initialized

### Technique 2: Find Boot Checkpoint Failures

**Identify last successful checkpoint:**

```bash
# Find last "initialized" message
grep "initialized" logs/breenix_*.log | tail -10

# Or find last successful operation
grep "SUCCESS\|✅\|complete" logs/breenix_*.log | tail -10
```

**If boot hangs**:
- Last checkpoint shows how far boot progressed
- Next subsystem is where hang occurs
- Focus debugging on that subsystem

### Technique 3: Compare Boot Sequences

**Working vs broken boot:**

```bash
# Extract initialization sequence
grep "initialized\|Initializing" working.log > working_boot.txt
grep "initialized\|Initializing" broken.log > broken_boot.txt

# Compare
diff -u working_boot.txt broken_boot.txt
```

**Look for**:
- Missing initialization steps
- Different initialization order
- New error messages
- Stops at different point

### Technique 4: Time Boot Stages

**Add timing checkpoints:**

```rust
let start = kernel::time::get_monotonic_ms();

// Initialize subsystem
gdt::init();

let elapsed = kernel::time::get_monotonic_ms() - start;
log::info!("GDT initialization took {}ms", elapsed);
```

**Analyze timing:**
- Which stages are slow?
- Where can we optimize?
- Any unexpected delays?

### Technique 5: Verify Subsystem Dependencies

**Check initialization order:**

```rust
// Memory must be initialized before heap
assert!(frame_allocator.is_initialized());
heap::init(); // Safe now

// GDT must be before IDT
gdt::init();
idt::init(); // Can reference GDT segments

// Interrupts must be off during sensitive operations
assert!(!are_enabled());
```

## Common Boot Issues

### Issue 1: Boot Hang

**Symptoms**:
- Kernel boots partway then stops
- No error message, just hangs
- Some subsystems initialized, others not

**Diagnosis**:
```bash
# Find last successful operation
grep "initialized\|complete" logs/latest.log | tail -1

# Check if interrupts were enabled prematurely
grep "Enabling interrupts" logs/latest.log

# Look for infinite loops
grep "WARN\|ERROR" logs/latest.log
```

**Common causes**:
1. **Interrupts enabled too early**
   - Timer interrupt fires before handler ready
   - Solution: Ensure all handlers registered before enabling

2. **Deadlock during initialization**
   - Lock acquired, never released
   - Solution: Check lock usage during boot

3. **Infinite loop in subsystem init**
   - Waiting for condition that never happens
   - Solution: Add timeouts or debug why condition fails

**Fix patterns**:
```rust
// Add checkpoint logging
log::info!("About to initialize subsystem X");
subsystem_x::init();
log::info!("Subsystem X initialized successfully");

// If hangs between checkpoints, focus on subsystem_x::init()
```

### Issue 2: Boot Panic

**Symptoms**:
```
PANIC: [messa