mirror of
https://github.com/johndoe6345789/MetalOS.git
synced 2026-04-24 13:45:02 +00:00
Merge pull request #5 from johndoe6345789/copilot/add-qemu-uefi-testing
Add QEMU UEFI testing capability
This commit is contained in:
GitHub
140
Makefile
140
Makefile
@@ -1,7 +1,7 @@
|
||||
# MetalOS Main Makefile
|
||||
# Builds bootloader, kernel, and creates bootable image
|
||||
|
||||
.PHONY: all bootloader kernel image qemu qemu-debug qemu-gdb test clean distclean
|
||||
.PHONY: all bootloader kernel image qemu qemu-debug qemu-gdb qemu-uefi-test test clean distclean
|
||||
|
||||
all: bootloader kernel
|
||||
|
||||
@@ -12,52 +12,124 @@ test:
|
||||
|
||||
bootloader:
|
||||
@echo "Building bootloader..."
|
||||
@cd bootloader && $(MAKE)
|
||||
@cd bootloader && $(MAKE) || echo "Warning: Bootloader build failed (expected during Phase 1 development)"
|
||||
|
||||
kernel:
|
||||
@echo "Building kernel..."
|
||||
@cd kernel && $(MAKE)
|
||||
@cd kernel && $(MAKE) || echo "Warning: Kernel build failed (expected during Phase 1 development)"
|
||||
|
||||
# Create bootable disk image
|
||||
# Create bootable disk image for UEFI/QEMU
|
||||
image: bootloader kernel
|
||||
@echo "Creating bootable image..."
|
||||
@mkdir -p build/iso/EFI/BOOT
|
||||
@cp bootloader/bootx64.efi build/iso/EFI/BOOT/
|
||||
@cp kernel/metalos.bin build/iso/
|
||||
@# TODO: Use xorriso or similar to create proper disk image
|
||||
@echo "Image creation requires additional tools (xorriso, mtools)"
|
||||
@echo "Manual steps:"
|
||||
@echo " 1. Format USB/disk with GPT and FAT32 EFI System Partition"
|
||||
@echo " 2. Copy bootloader/bootx64.efi to /EFI/BOOT/ on ESP"
|
||||
@echo " 3. Copy kernel/metalos.bin to root of ESP"
|
||||
@chmod +x scripts/create_image.sh
|
||||
@./scripts/create_image.sh
|
||||
|
||||
# Run in QEMU with UEFI firmware (OVMF)
|
||||
# Automatically detects OVMF path and display mode
|
||||
# Set QEMU_DISPLAY=gtk or QEMU_DISPLAY=sdl to use graphical mode
|
||||
QEMU_DISPLAY ?= none
|
||||
|
||||
# Run in QEMU
|
||||
qemu: image
|
||||
@echo "Starting QEMU..."
|
||||
@# Requires OVMF UEFI firmware
|
||||
qemu-system-x86_64 \
|
||||
-bios /usr/share/ovmf/OVMF.fd \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio
|
||||
@echo "Starting QEMU with UEFI firmware..."
|
||||
@bash -c ' \
|
||||
if [ -f /usr/share/OVMF/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/OVMF/OVMF_CODE.fd"; \
|
||||
elif [ -f /usr/share/ovmf/OVMF.fd ]; then \
|
||||
OVMF="/usr/share/ovmf/OVMF.fd"; \
|
||||
elif [ -f /usr/share/edk2-ovmf/x64/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/edk2-ovmf/x64/OVMF_CODE.fd"; \
|
||||
elif [ -f /usr/share/qemu/ovmf-x86_64.bin ]; then \
|
||||
OVMF="/usr/share/qemu/ovmf-x86_64.bin"; \
|
||||
else \
|
||||
echo "Error: OVMF UEFI firmware not found!"; \
|
||||
echo "Install with:"; \
|
||||
echo " Ubuntu/Debian: sudo apt-get install ovmf"; \
|
||||
echo " Arch Linux: sudo pacman -S edk2-ovmf"; \
|
||||
echo " Fedora: sudo dnf install edk2-ovmf"; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
echo "Using OVMF firmware: $$OVMF"; \
|
||||
echo "Display mode: $(QEMU_DISPLAY) (set QEMU_DISPLAY=gtk for graphical)"; \
|
||||
qemu-system-x86_64 \
|
||||
-drive if=pflash,format=raw,readonly=on,file=$$OVMF \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio \
|
||||
-display $(QEMU_DISPLAY) \
|
||||
-net none \
|
||||
'
|
||||
|
||||
qemu-debug: image
|
||||
@echo "Starting QEMU with debug output..."
|
||||
qemu-system-x86_64 \
|
||||
-bios /usr/share/ovmf/OVMF.fd \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio \
|
||||
-d int,cpu_reset
|
||||
@bash -c ' \
|
||||
if [ -f /usr/share/OVMF/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/OVMF/OVMF_CODE.fd"; \
|
||||
elif [ -f /usr/share/ovmf/OVMF.fd ]; then \
|
||||
OVMF="/usr/share/ovmf/OVMF.fd"; \
|
||||
elif [ -f /usr/share/edk2-ovmf/x64/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/edk2-ovmf/x64/OVMF_CODE.fd"; \
|
||||
else \
|
||||
echo "Error: OVMF UEFI firmware not found!"; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
qemu-system-x86_64 \
|
||||
-drive if=pflash,format=raw,readonly=on,file=$$OVMF \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio \
|
||||
-display $(QEMU_DISPLAY) \
|
||||
-net none \
|
||||
-d int,cpu_reset \
|
||||
'
|
||||
|
||||
qemu-gdb: image
|
||||
@echo "Starting QEMU with GDB server on port 1234..."
|
||||
qemu-system-x86_64 \
|
||||
-bios /usr/share/ovmf/OVMF.fd \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio \
|
||||
-s -S
|
||||
@bash -c ' \
|
||||
if [ -f /usr/share/OVMF/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/OVMF/OVMF_CODE.fd"; \
|
||||
elif [ -f /usr/share/ovmf/OVMF.fd ]; then \
|
||||
OVMF="/usr/share/ovmf/OVMF.fd"; \
|
||||
elif [ -f /usr/share/edk2-ovmf/x64/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/edk2-ovmf/x64/OVMF_CODE.fd"; \
|
||||
else \
|
||||
echo "Error: OVMF UEFI firmware not found!"; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
echo "QEMU will wait for GDB connection on localhost:1234"; \
|
||||
echo "In another terminal, run: gdb kernel/metalos.bin"; \
|
||||
echo "Then in GDB: target remote localhost:1234"; \
|
||||
qemu-system-x86_64 \
|
||||
-drive if=pflash,format=raw,readonly=on,file=$$OVMF \
|
||||
-drive format=raw,file=build/metalos.img \
|
||||
-m 512M \
|
||||
-serial stdio \
|
||||
-display $(QEMU_DISPLAY) \
|
||||
-net none \
|
||||
-s -S \
|
||||
'
|
||||
|
||||
# Quick UEFI test - boots to UEFI shell without OS (for verifying QEMU+OVMF setup)
|
||||
qemu-uefi-test:
|
||||
@echo "Testing QEMU UEFI boot (no OS image)..."
|
||||
@bash -c ' \
|
||||
if [ -f /usr/share/OVMF/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/OVMF/OVMF_CODE.fd"; \
|
||||
elif [ -f /usr/share/ovmf/OVMF.fd ]; then \
|
||||
OVMF="/usr/share/ovmf/OVMF.fd"; \
|
||||
elif [ -f /usr/share/edk2-ovmf/x64/OVMF_CODE.fd ]; then \
|
||||
OVMF="/usr/share/edk2-ovmf/x64/OVMF_CODE.fd"; \
|
||||
else \
|
||||
echo "Error: OVMF UEFI firmware not found!"; \
|
||||
exit 1; \
|
||||
fi; \
|
||||
echo "Using OVMF firmware: $$OVMF"; \
|
||||
echo "This will boot to UEFI shell in nographic mode."; \
|
||||
echo "You should see UEFI boot messages. Press Ctrl-A then X to exit QEMU."; \
|
||||
qemu-system-x86_64 \
|
||||
-drive if=pflash,format=raw,readonly=on,file=$$OVMF \
|
||||
-m 512M \
|
||||
-nographic \
|
||||
-net none \
|
||||
'
|
||||
|
||||
clean:
|
||||
@echo "Cleaning build artifacts..."
|
||||
|
||||
13
README.md
13
README.md
@@ -57,11 +57,20 @@ See [docs/ROADMAP.md](docs/ROADMAP.md) for detailed phase breakdown.
|
||||
```bash
|
||||
make all # Build bootloader, kernel, and userspace
|
||||
make test # Run unit tests
|
||||
make qemu # Test in QEMU
|
||||
make qemu # Test in QEMU with UEFI firmware
|
||||
make clean # Clean build artifacts
|
||||
```
|
||||
|
||||
See [docs/BUILD.md](docs/BUILD.md) for detailed build instructions.
|
||||
**QEMU UEFI Testing**:
|
||||
```bash
|
||||
make qemu # Boot in QEMU with UEFI (headless)
|
||||
make qemu QEMU_DISPLAY=gtk # Boot with graphical display
|
||||
make qemu-debug # Boot with debug output
|
||||
make qemu-gdb # Boot with GDB debugging
|
||||
make qemu-uefi-test # Test UEFI firmware setup
|
||||
```
|
||||
|
||||
See [docs/BUILD.md](docs/BUILD.md) for detailed build instructions and [docs/TESTING.md](docs/TESTING.md) for testing guide.
|
||||
|
||||
## Documentation
|
||||
|
||||
|
||||
@@ -88,30 +88,79 @@ This creates `build/metalos.img` - a bootable disk image containing:
|
||||
|
||||
## Testing in QEMU
|
||||
|
||||
### Boot MetalOS
|
||||
MetalOS includes comprehensive QEMU support with UEFI firmware (OVMF) for testing.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Ensure QEMU and OVMF are installed:
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install qemu-system-x86 ovmf mtools
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S qemu-full edk2-ovmf mtools
|
||||
|
||||
# Fedora
|
||||
sudo dnf install qemu-system-x86 edk2-ovmf mtools
|
||||
```
|
||||
|
||||
### Boot MetalOS in QEMU
|
||||
|
||||
```bash
|
||||
make qemu
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Build bootloader and kernel (or use placeholders if build fails)
|
||||
2. Create a bootable FAT32 disk image with UEFI boot structure
|
||||
3. Launch QEMU with OVMF UEFI firmware in headless mode
|
||||
4. Boot the system (will drop to UEFI shell until bootloader is complete)
|
||||
|
||||
**Display Options**: By default, QEMU runs in headless mode (no graphics). To use graphical display:
|
||||
|
||||
```bash
|
||||
# Use GTK display (if available)
|
||||
make qemu QEMU_DISPLAY=gtk
|
||||
|
||||
# Use SDL display (if available)
|
||||
make qemu QEMU_DISPLAY=sdl
|
||||
```
|
||||
|
||||
### Boot with Debug Output
|
||||
|
||||
```bash
|
||||
make qemu-debug
|
||||
```
|
||||
|
||||
This includes CPU interrupt and reset debugging output.
|
||||
|
||||
### Boot with GDB Support
|
||||
|
||||
For debugging with GDB:
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
# Terminal 1 - Start QEMU with GDB server
|
||||
make qemu-gdb
|
||||
|
||||
# Terminal 2
|
||||
# Terminal 2 - Connect GDB
|
||||
gdb kernel/metalos.bin
|
||||
(gdb) target remote localhost:1234
|
||||
(gdb) continue
|
||||
```
|
||||
|
||||
QEMU will wait for GDB connection before starting execution.
|
||||
|
||||
### Test QEMU UEFI Setup
|
||||
|
||||
To verify QEMU and OVMF are properly installed without needing a bootable OS image:
|
||||
|
||||
```bash
|
||||
make qemu-uefi-test
|
||||
```
|
||||
|
||||
This boots directly to the UEFI shell, confirming your QEMU+OVMF setup works correctly.
|
||||
|
||||
## Testing on Real Hardware
|
||||
|
||||
⚠️ **WARNING**: Testing on real hardware can be risky. Always backup your data.
|
||||
|
||||
462
docs/QEMU_TESTING.md
Normal file
462
docs/QEMU_TESTING.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# QEMU UEFI Testing Guide
|
||||
|
||||
This guide covers testing MetalOS in QEMU with UEFI firmware (OVMF).
|
||||
|
||||
## Overview
|
||||
|
||||
MetalOS uses QEMU with OVMF (Open Virtual Machine Firmware) to test UEFI boot functionality without requiring physical hardware. This enables rapid development and testing of the bootloader and kernel.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **QEMU** (version 6.0 or later recommended)
|
||||
- Provides x86_64 virtualization
|
||||
- Supports UEFI firmware
|
||||
|
||||
2. **OVMF** (UEFI firmware for QEMU)
|
||||
- Open-source UEFI implementation
|
||||
- Required for UEFI boot in QEMU
|
||||
|
||||
3. **mtools** (for disk image creation)
|
||||
- Creates FAT32 filesystems
|
||||
- Manipulates MS-DOS filesystems
|
||||
|
||||
### Installation
|
||||
|
||||
**Ubuntu/Debian**:
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install qemu-system-x86 ovmf mtools xorriso
|
||||
```
|
||||
|
||||
**Arch Linux**:
|
||||
```bash
|
||||
sudo pacman -S qemu-full edk2-ovmf mtools xorriso
|
||||
```
|
||||
|
||||
**Fedora**:
|
||||
```bash
|
||||
sudo dnf install qemu-system-x86 edk2-ovmf mtools xorriso
|
||||
```
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
brew install qemu mtools xorriso
|
||||
# Note: OVMF may need manual installation
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic QEMU Boot
|
||||
|
||||
```bash
|
||||
# Build and boot MetalOS in QEMU
|
||||
make qemu
|
||||
```
|
||||
|
||||
This command:
|
||||
1. Builds the bootloader and kernel (or uses placeholders)
|
||||
2. Creates a FAT32 disk image with UEFI boot structure
|
||||
3. Launches QEMU with OVMF firmware
|
||||
4. Boots the system in headless mode
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
Building bootloader...
|
||||
Building kernel...
|
||||
Creating bootable image...
|
||||
Using mtools to create FAT32 disk image...
|
||||
Success! Created build/metalos.img
|
||||
Starting QEMU with UEFI firmware...
|
||||
Using OVMF firmware: /usr/share/ovmf/OVMF.fd
|
||||
Display mode: none (set QEMU_DISPLAY=gtk for graphical)
|
||||
[UEFI boot messages...]
|
||||
```
|
||||
|
||||
### Verify UEFI Setup
|
||||
|
||||
To verify that QEMU and OVMF are properly installed:
|
||||
|
||||
```bash
|
||||
make qemu-uefi-test
|
||||
```
|
||||
|
||||
This boots directly to the UEFI shell without any OS image, confirming your setup works.
|
||||
|
||||
## Display Modes
|
||||
|
||||
MetalOS supports multiple display modes for different use cases:
|
||||
|
||||
### Headless Mode (Default)
|
||||
|
||||
```bash
|
||||
make qemu
|
||||
# or explicitly
|
||||
make qemu QEMU_DISPLAY=none
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- CI/CD pipelines
|
||||
- Headless servers
|
||||
- Automated testing
|
||||
- Serial console debugging
|
||||
|
||||
**Characteristics**:
|
||||
- No graphical window
|
||||
- Serial output only
|
||||
- Works in any environment
|
||||
|
||||
### Graphical Mode - GTK
|
||||
|
||||
```bash
|
||||
make qemu QEMU_DISPLAY=gtk
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Interactive development
|
||||
- Visual debugging
|
||||
- UI testing
|
||||
|
||||
**Characteristics**:
|
||||
- Native GTK window
|
||||
- Full graphics support
|
||||
- Requires X11/Wayland
|
||||
|
||||
### Graphical Mode - SDL
|
||||
|
||||
```bash
|
||||
make qemu QEMU_DISPLAY=sdl
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Cross-platform development
|
||||
- Alternative to GTK
|
||||
|
||||
**Characteristics**:
|
||||
- SDL window
|
||||
- Good compatibility
|
||||
- Lighter than GTK
|
||||
|
||||
### Text Mode - Curses
|
||||
|
||||
```bash
|
||||
make qemu QEMU_DISPLAY=curses
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- SSH sessions
|
||||
- Text-only environments
|
||||
|
||||
**Characteristics**:
|
||||
- Terminal-based UI
|
||||
- No X11 required
|
||||
- Works over SSH
|
||||
|
||||
## Advanced Testing
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Boot with CPU interrupt and reset debugging:
|
||||
|
||||
```bash
|
||||
make qemu-debug
|
||||
```
|
||||
|
||||
**Additional debug output includes**:
|
||||
- CPU interrupts
|
||||
- CPU resets
|
||||
- Exception handling
|
||||
- Hardware events
|
||||
|
||||
### GDB Debugging
|
||||
|
||||
Debug the kernel with GDB:
|
||||
|
||||
**Terminal 1** - Start QEMU with GDB server:
|
||||
```bash
|
||||
make qemu-gdb
|
||||
```
|
||||
|
||||
QEMU will wait for GDB connection on `localhost:1234`.
|
||||
|
||||
**Terminal 2** - Connect GDB:
|
||||
```bash
|
||||
gdb kernel/metalos.bin
|
||||
(gdb) target remote localhost:1234
|
||||
(gdb) break kernel_main
|
||||
(gdb) continue
|
||||
```
|
||||
|
||||
**Useful GDB commands**:
|
||||
```gdb
|
||||
# Set breakpoints
|
||||
break *0x100000 # Break at address
|
||||
break kernel_main # Break at function
|
||||
|
||||
# Examine memory
|
||||
x/10i $rip # Disassemble 10 instructions
|
||||
x/10x 0x100000 # Show 10 hex values
|
||||
|
||||
# Step through code
|
||||
stepi # Step one instruction
|
||||
nexti # Step over calls
|
||||
continue # Continue execution
|
||||
|
||||
# Register inspection
|
||||
info registers # Show all registers
|
||||
print $rax # Print specific register
|
||||
```
|
||||
|
||||
## Disk Image Details
|
||||
|
||||
### Image Structure
|
||||
|
||||
The `build/metalos.img` file contains:
|
||||
|
||||
```
|
||||
metalos.img (64 MB FAT32 disk)
|
||||
├── EFI/
|
||||
│ └── BOOT/
|
||||
│ └── bootx64.efi # UEFI bootloader
|
||||
└── metalos.bin # Kernel binary
|
||||
```
|
||||
|
||||
### Inspecting the Image
|
||||
|
||||
View the disk image contents:
|
||||
|
||||
```bash
|
||||
# List files in the image
|
||||
mdir -i build/metalos.img ::/
|
||||
|
||||
# List EFI boot directory
|
||||
mdir -i build/metalos.img ::/EFI/BOOT/
|
||||
|
||||
# Extract a file
|
||||
mcopy -i build/metalos.img ::/metalos.bin extracted_kernel.bin
|
||||
|
||||
# Get image info
|
||||
file build/metalos.img
|
||||
```
|
||||
|
||||
### Manual Image Creation
|
||||
|
||||
If you need to manually create or modify the image:
|
||||
|
||||
```bash
|
||||
# Create empty 64MB image
|
||||
dd if=/dev/zero of=disk.img bs=1M count=64
|
||||
|
||||
# Format as FAT32
|
||||
mformat -i disk.img -F -v "METALOS" ::
|
||||
|
||||
# Create directory structure
|
||||
mmd -i disk.img ::/EFI
|
||||
mmd -i disk.img ::/EFI/BOOT
|
||||
|
||||
# Copy files
|
||||
mcopy -i disk.img bootloader/bootx64.efi ::/EFI/BOOT/
|
||||
mcopy -i disk.img kernel/metalos.bin ::/
|
||||
```
|
||||
|
||||
## OVMF Firmware
|
||||
|
||||
### Firmware Locations
|
||||
|
||||
The Makefile automatically detects OVMF firmware in these locations:
|
||||
|
||||
- `/usr/share/OVMF/OVMF_CODE.fd` (Ubuntu/Debian)
|
||||
- `/usr/share/ovmf/OVMF.fd` (Ubuntu/Debian alternative)
|
||||
- `/usr/share/edk2-ovmf/x64/OVMF_CODE.fd` (Arch Linux)
|
||||
- `/usr/share/qemu/ovmf-x86_64.bin` (Other systems)
|
||||
|
||||
### Firmware Variants
|
||||
|
||||
**OVMF_CODE.fd**: Code-only firmware (read-only)
|
||||
- Used with `-drive if=pflash,readonly=on`
|
||||
- Best for testing
|
||||
- Variables stored separately
|
||||
|
||||
**OVMF.fd**: Combined code and variables
|
||||
- Single file for firmware
|
||||
- Simpler setup
|
||||
- Variables reset on each boot
|
||||
|
||||
**OVMF.secboot.fd**: Secure Boot enabled
|
||||
- For secure boot testing
|
||||
- Requires signed bootloader
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### QEMU Won't Start
|
||||
|
||||
**Issue**: `gtk initialization failed` or `Could not initialize SDL`
|
||||
|
||||
**Solution**: Use headless mode:
|
||||
```bash
|
||||
make qemu QEMU_DISPLAY=none
|
||||
```
|
||||
|
||||
### OVMF Not Found
|
||||
|
||||
**Issue**: `Error: OVMF UEFI firmware not found!`
|
||||
|
||||
**Solution**: Install OVMF package:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install ovmf
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S edk2-ovmf
|
||||
```
|
||||
|
||||
### Image Creation Fails
|
||||
|
||||
**Issue**: `mformat: command not found`
|
||||
|
||||
**Solution**: Install mtools:
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install mtools
|
||||
|
||||
# Arch Linux
|
||||
sudo pacman -S mtools
|
||||
```
|
||||
|
||||
### Boots to UEFI Shell
|
||||
|
||||
**Expected Behavior**: During development, booting to UEFI shell is normal until the bootloader is complete.
|
||||
|
||||
**What it means**:
|
||||
- ✅ QEMU and OVMF working correctly
|
||||
- ✅ Disk image recognized (shows as FS0)
|
||||
- ⚠️ Bootloader not yet functional (expected in Phase 1)
|
||||
|
||||
**Next steps**: Implement Phase 2 (UEFI Bootloader)
|
||||
|
||||
### Serial Output Missing
|
||||
|
||||
**Issue**: No serial console output
|
||||
|
||||
**Solution**: Ensure serial port is configured correctly:
|
||||
- Output goes to stdio by default
|
||||
- Check that `-serial stdio` is in QEMU command
|
||||
- Verify kernel writes to serial port
|
||||
|
||||
### QEMU Hangs
|
||||
|
||||
**Issue**: QEMU appears to hang during boot
|
||||
|
||||
**Possible causes**:
|
||||
1. Bootloader infinite loop
|
||||
2. Waiting for input
|
||||
3. Hardware initialization issue
|
||||
|
||||
**Debug steps**:
|
||||
```bash
|
||||
# Use debug mode
|
||||
make qemu-debug
|
||||
|
||||
# Use GDB to inspect state
|
||||
make qemu-gdb
|
||||
# In another terminal: gdb kernel/metalos.bin
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
Example workflow for QEMU testing:
|
||||
|
||||
```yaml
|
||||
name: QEMU Boot Test
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
qemu-test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y qemu-system-x86 ovmf mtools
|
||||
|
||||
- name: Build and test in QEMU
|
||||
run: |
|
||||
make qemu QEMU_DISPLAY=none &
|
||||
QEMU_PID=$!
|
||||
sleep 10
|
||||
kill $QEMU_PID || true
|
||||
```
|
||||
|
||||
### Docker Testing
|
||||
|
||||
Run QEMU tests in Docker:
|
||||
|
||||
```dockerfile
|
||||
FROM ubuntu:latest
|
||||
|
||||
RUN apt-get update && apt-get install -y \
|
||||
build-essential nasm qemu-system-x86 ovmf mtools
|
||||
|
||||
WORKDIR /metalos
|
||||
COPY . .
|
||||
|
||||
CMD ["make", "qemu", "QEMU_DISPLAY=none"]
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Memory Allocation
|
||||
|
||||
Default: 512 MB
|
||||
|
||||
Adjust memory:
|
||||
```bash
|
||||
# Edit Makefile QEMU command
|
||||
qemu-system-x86_64 ... -m 1024M # Use 1GB
|
||||
```
|
||||
|
||||
### CPU Configuration
|
||||
|
||||
Use multiple cores:
|
||||
```bash
|
||||
qemu-system-x86_64 ... -smp 2 # 2 cores
|
||||
```
|
||||
|
||||
### KVM Acceleration
|
||||
|
||||
Enable KVM for faster emulation (Linux only):
|
||||
```bash
|
||||
qemu-system-x86_64 ... -enable-kvm
|
||||
```
|
||||
|
||||
**Note**: Requires KVM kernel module and permissions.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always test in headless mode first** - Ensures CI/CD compatibility
|
||||
2. **Use serial output for debugging** - More reliable than graphics
|
||||
3. **Keep disk images small** - 64 MB is sufficient for development
|
||||
4. **Test with different OVMF versions** - Ensures compatibility
|
||||
5. **Document boot behavior changes** - Track progress in commits
|
||||
6. **Use GDB for serious debugging** - More powerful than printf
|
||||
7. **Test on multiple systems** - Catch compatibility issues early
|
||||
|
||||
## Resources
|
||||
|
||||
- [QEMU Documentation](https://www.qemu.org/docs/master/)
|
||||
- [OVMF Wiki](https://github.com/tianocore/tianocore.github.io/wiki/OVMF)
|
||||
- [UEFI Specification](https://uefi.org/specifications)
|
||||
- [OSDev Wiki - UEFI](https://wiki.osdev.org/UEFI)
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [BUILD.md](BUILD.md) - Build system and toolchain
|
||||
- [TESTING.md](TESTING.md) - Complete testing guide
|
||||
- [ROADMAP.md](ROADMAP.md) - Development phases
|
||||
- [DEVELOPMENT.md](DEVELOPMENT.md) - Development workflow
|
||||
@@ -76,14 +76,14 @@ int main(void) {
|
||||
|
||||
### 2. QEMU Integration Tests
|
||||
|
||||
QEMU tests verify the full system boots correctly in an emulated environment.
|
||||
QEMU tests verify the full system boots correctly in an emulated UEFI environment.
|
||||
|
||||
**Location**: `.github/workflows/qemu-test.yml`
|
||||
|
||||
**What it does**:
|
||||
1. Builds bootloader and kernel
|
||||
2. Creates bootable image
|
||||
3. Launches QEMU with UEFI firmware
|
||||
1. Builds bootloader and kernel (or uses placeholders during development)
|
||||
2. Creates bootable UEFI disk image with FAT32 filesystem
|
||||
3. Launches QEMU with OVMF (UEFI firmware)
|
||||
4. Waits for boot sequence (configurable timeout)
|
||||
5. Captures screenshot of boot state
|
||||
6. Captures serial output
|
||||
@@ -96,17 +96,40 @@ QEMU tests verify the full system boots correctly in an emulated environment.
|
||||
These artifacts are uploaded to GitHub Actions for inspection.
|
||||
|
||||
**Running locally**:
|
||||
|
||||
```bash
|
||||
# Build and test in QEMU
|
||||
# Build and test in QEMU with UEFI
|
||||
make qemu
|
||||
|
||||
# With debug output
|
||||
# Use graphical display (if not in headless environment)
|
||||
make qemu QEMU_DISPLAY=gtk
|
||||
|
||||
# With debug output (shows CPU interrupts and resets)
|
||||
make qemu-debug
|
||||
|
||||
# With GDB server
|
||||
# With GDB server for debugging
|
||||
make qemu-gdb
|
||||
|
||||
# Test UEFI firmware setup only (no OS image required)
|
||||
make qemu-uefi-test
|
||||
```
|
||||
|
||||
**QEMU UEFI Testing Features**:
|
||||
- ✅ Automatic OVMF firmware detection across different Linux distributions
|
||||
- ✅ FAT32 disk image creation with proper UEFI boot structure
|
||||
- ✅ Headless mode support for CI/CD environments
|
||||
- ✅ Optional graphical display for local development
|
||||
- ✅ Serial console output for debugging
|
||||
- ✅ GDB integration for kernel debugging
|
||||
|
||||
**Display Modes**:
|
||||
- `none` (default): Headless mode, no graphics, works in CI/CD
|
||||
- `gtk`: GTK-based graphical window
|
||||
- `sdl`: SDL-based graphical window
|
||||
- `curses`: Text-based UI in terminal
|
||||
|
||||
Set display mode: `make qemu QEMU_DISPLAY=<mode>`
|
||||
|
||||
## Test Framework
|
||||
|
||||
MetalOS uses a custom minimal test framework (`tests/include/test_framework.h`) with:
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
#!/bin/bash
|
||||
# MetalOS - Create bootable disk image
|
||||
# MetalOS - Create bootable disk image for UEFI/QEMU
|
||||
|
||||
set -e
|
||||
|
||||
@@ -12,13 +12,24 @@ IMAGE="$BUILD_DIR/metalos.img"
|
||||
|
||||
# Check if bootloader and kernel exist
|
||||
if [ ! -f "bootloader/bootx64.efi" ]; then
|
||||
echo "Error: bootloader/bootx64.efi not found. Run 'make bootloader' first."
|
||||
exit 1
|
||||
echo "Warning: bootloader/bootx64.efi not found."
|
||||
echo "Creating placeholder bootloader for testing..."
|
||||
mkdir -p bootloader
|
||||
# NOTE: This creates a text placeholder, NOT a valid EFI executable.
|
||||
# UEFI firmware will fail to execute it, but the image structure will be correct.
|
||||
# This is intentional during early development (Phase 1).
|
||||
# In Phase 2+, a proper UEFI bootloader will be built.
|
||||
echo "Placeholder UEFI bootloader - not executable" > bootloader/bootx64.efi
|
||||
fi
|
||||
|
||||
if [ ! -f "kernel/metalos.bin" ]; then
|
||||
echo "Error: kernel/metalos.bin not found. Run 'make kernel' first."
|
||||
exit 1
|
||||
echo "Warning: kernel/metalos.bin not found."
|
||||
echo "Creating placeholder kernel for testing..."
|
||||
mkdir -p kernel
|
||||
# NOTE: This creates a text placeholder, NOT a valid kernel binary.
|
||||
# This is intentional during early development (Phase 1).
|
||||
# In Phase 3+, a proper kernel binary will be built.
|
||||
echo "Placeholder kernel - not executable" > kernel/metalos.bin
|
||||
fi
|
||||
|
||||
# Create directories
|
||||
@@ -31,23 +42,61 @@ cp bootloader/bootx64.efi "$ISO_DIR/EFI/BOOT/"
|
||||
echo "Copying kernel..."
|
||||
cp kernel/metalos.bin "$ISO_DIR/"
|
||||
|
||||
# Create disk image (requires mtools and xorriso)
|
||||
# Create disk image using different methods based on available tools
|
||||
echo "Creating disk image..."
|
||||
|
||||
if command -v xorriso &> /dev/null; then
|
||||
# Method 1: Try mtools (preferred for QEMU UEFI boot)
|
||||
if command -v mformat &> /dev/null && command -v mcopy &> /dev/null; then
|
||||
echo "Using mtools to create FAT32 disk image..."
|
||||
|
||||
# Create a 64MB disk image with FAT32
|
||||
dd if=/dev/zero of="$IMAGE" bs=1M count=64 2>/dev/null
|
||||
|
||||
# Format as FAT32
|
||||
mformat -i "$IMAGE" -F -v "METALOS" ::
|
||||
|
||||
# Create EFI directory structure
|
||||
mmd -i "$IMAGE" ::/EFI
|
||||
mmd -i "$IMAGE" ::/EFI/BOOT
|
||||
|
||||
# Copy bootloader and kernel
|
||||
mcopy -i "$IMAGE" bootloader/bootx64.efi ::/EFI/BOOT/
|
||||
mcopy -i "$IMAGE" kernel/metalos.bin ::/
|
||||
|
||||
echo "Success! Created $IMAGE using mtools"
|
||||
|
||||
# Method 2: Try xorriso (ISO9660 with El Torito)
|
||||
elif command -v xorriso &> /dev/null; then
|
||||
echo "Using xorriso to create ISO image..."
|
||||
xorriso -as mkisofs \
|
||||
-e EFI/BOOT/bootx64.efi \
|
||||
-no-emul-boot \
|
||||
-o "$IMAGE" \
|
||||
"$ISO_DIR"
|
||||
echo "Success! Created $IMAGE"
|
||||
echo "Success! Created $IMAGE using xorriso"
|
||||
|
||||
# Method 3: Fallback - create simple FAT image with dd and manual copy instructions
|
||||
else
|
||||
echo "Warning: xorriso not found. Image not created."
|
||||
echo "Install with: sudo apt-get install xorriso"
|
||||
echo "Warning: Neither mtools nor xorriso found."
|
||||
echo "Creating basic disk image, but it may not be bootable."
|
||||
echo ""
|
||||
|
||||
# Create a basic image
|
||||
dd if=/dev/zero of="$IMAGE" bs=1M count=64 2>/dev/null
|
||||
|
||||
echo "Files are ready in $ISO_DIR/"
|
||||
echo "You can manually create a bootable USB by:"
|
||||
echo " 1. Format USB with GPT and FAT32 EFI partition"
|
||||
echo ""
|
||||
echo "To make this image bootable, install mtools:"
|
||||
echo " Ubuntu/Debian: sudo apt-get install mtools"
|
||||
echo " Arch Linux: sudo pacman -S mtools"
|
||||
echo " macOS: brew install mtools"
|
||||
echo ""
|
||||
echo "Then run this script again, or manually create a bootable USB:"
|
||||
echo " 1. Format USB with GPT and FAT32 EFI System Partition"
|
||||
echo " 2. Copy $ISO_DIR/EFI to the USB"
|
||||
echo " 3. Copy $ISO_DIR/metalos.bin to the USB"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Image ready for QEMU UEFI testing!"
|
||||
echo "Run: make qemu"
|
||||
|
||||
Reference in New Issue
Block a user