# HDGL Self-Bootloader - Compilation & Boot Instructions

## Overview
This HDGL bootloader is a self-replicating firmware that boots from disk,
loads HDGL runtime, and executes HDGL bytecode programs.

## Files Generated

1. hdgl_self_bootloader.hdg (9001 bytes)
   - Main HDGL bootloader source
   - Self-replication engine
   - Omega runtime initialization
   - Default user program

2. boot_sector.bin (254 bytes)
   - MBR-compatible boot sector
   - Jump to HDGL stub
   - Signature: 0x55AA

## Compilation Steps

### Step 1: Assemble Boot Sector (if needed)
```bash
# For x86 real mode boot
nasm -f bin boot_sector_stub.asm -o boot_sector.bin

# Or use pre-generated binary
cp boot_sector.bin boot_sector.bin
```

### Step 2: Create Storage Layout
The HDGL runtime expects the following storage layout:

```
Sector 0-1:  Bootloader (boot_sector.bin)
Sector 2-5:  HDGL Runtime Core (hdgl_runtime_core.hdg)
Sector 6-9:  HDGL Bootloader Source (hdgl_self_bootloader.hdg)
Sector 10+:  Code Storage / Runtime Data
```

### Step 3: Assemble HDGL Code to Assembly
Use the self-hosting compiler:

```bash
# Compile the self-hosting runtime first
clang-cl hdgl_self_hosting_runtime_final.c -o hdgl_self_hosting.exe

# Execute it on the bootloader source
hdgl_self_hosting.exe hdgl_self_bootloader.hdg
```

This generates: hdgl_self_bootloader.s (x86 assembly)

### Step 4: Assemble Generated Assembly
```bash
nasm -f bin hdgl_self_bootloader.s -o hdgl_bootloader.bin
```

## Booting the HDGL Self-Bootloader

### Method 1: QEMU (Simulation)
```bash
qemu-system-i386 -fda hdgl_self_bootloader.bin -boot a
```

### Method 2: VirtualBox
1. Create new VM with DOS/BIOS support
2. Mount hdgl_self_bootloader.bin as floppy
3. Boot VM

### Method 3: Real Hardware
1. Write to MBR: `dd if=boot_sector.bin of=/dev/sdX bs=512 count=1`
2. Write HDGL code to sectors 2-9
3. Reboot system

## Expected Behavior

### On Boot:
1. BIOS loads sector 0 to 0x7C00
2. HDGL stub initializes execution environment
3. Omega runtime loads from storage sectors
4. Glyph tree created: root -> cpu, memory, storage
5. Default program executes:
   ```
   HDGL Self-Bootloader v1.0
   Initializing Omega Runtime...
   Omega Runtime Initialized
   Glyph Tree: CPU, MEM, STORAGE
   Self-Replication: ENABLED
   Waiting for input...
   ```

### User Interaction:
- Press 'R' to trigger self-replication
- Self-replication:
  1. Reads current HDGL code
  2. Analyzes and optimizes
  3. Writes back with modifications
  4. Persists to storage

## Storage Persistence

The self-replication engine:
- Writes modified code back to sectors 2-5
- Updates MBR with new bootloader signature
- Creates backup copies
- Preserves essential boot signatures

## HDGL Runtime Architecture

### Omega Glyph Tree:
```
ROOT (id=0)
├── CPU (state=CONFIGURED)
│   └── discovered
│   └── executed
├── MEMORY (state=READY)
│   └── discovered
│   └── ready
└── STORAGE (state=CONFIGURED)
    └── discovered
    └── mounted
```

### Glyph Operations:
- **glyph**: Create new glyph with attributes
- **branch**: Create parent-child relationship
- **recurse**: Traverse glyph tree
- **mutate**: Change glyph state
- **execute**: Run glyph code

## Self-Replication Details

The replication engine:
1. **Read Current**: Load HDGL code from storage
2. **Analyze**: Detect existing glyphs and structure
3. **Optimize**: Apply mutation rules (constant folding, dead code)
4. **Modify**: Add timestamps, increment version
5. **Write Back**: Overwrite with new version
6. **Persist**: Update MBR and create backups

## Verification

Check if bootloader is working:

```bash
# Mount and check sectors
dd if=hdgl_self_bootloader.bin bs=512 skip=1 count=1 | less

# Should show: HDGL Self-Bootloader source code
```

## Security Notes

- Bootloader includes checksum verification
- Signature protection on critical sections
- Backup creation prevents data loss
- Self-modification can be detected via hash comparison

## Advanced Usage

### Custom User Programs

Create your own HDGL program:

```hdgl
# user_program.hdg
glyph my_app
    class = APPLICATION
    state = INIT
end

entry run_my_app
    display "My HDGL Application"
    create glyph custom_feature
        class = CUSTOM
        state = CONFIGURED
    end
    recurse custom_feature
        mutate discovered
    end
end
```

Compile and execute:
```bash
hdgl_self_hosting.exe user_program.hdg
```

### Integration with Existing Systems

The HDGL bootloader can coexist with existing BIOS:
- Only takes control during early boot
- Can hand off to OS after initialization
- Self-replicates but preserves essential boot data

## Troubleshooting

### Bootloader doesn't load
- Check MBR signature: should be 0x55AA
- Verify sector layout matches expected
- Ensure HDGL runtime is in correct sectors

### Self-replication fails
- Check storage permissions
- Verify sector 0-1 contains valid bootloader
- Ensure sufficient free space for backups

### Runtime crashes
- Check Omega glyph allocation (max 256 glyphs)
- Verify storage I/O operations
- Review mutation callbacks

## Next Steps

1. Test in QEMU first
2. Verify self-replication works
3. Create custom HDGL applications
4. Integrate with real hardware (if desired)
5. Explore advanced mutation rules

## References

- HDGL Self-Host Compiler: hdgl_self_hosting_compiler.hdgl
- HDGL Runtime v3: hdgl_runtime_v3.c
- Original Firmware: firmware.hdgl
- Self-Bootloader: hdgl_self_bootloader.hdg
