Create bootable USB/physical device image for real hardware deployment

[pbalduino]

Goal

Create a streamlined process to generate a bootable USB stick or physical device image, enabling MeniOS to run on real x86-64 hardware for testing and validation.

Context

MeniOS currently runs in QEMU using a disk image (menios.hdd) created via dd with GPT partitioning and Limine bootloader. The long-term objective is reliable boots on real hardware (README.md:5,20).

The current build system already creates a bootable disk image with:

• GPT partition table (BIOS boot partition + EFI system partition)
• Limine bootloader (both BIOS and UEFI support)
• FAT32 filesystem with kernel and userland tools
• All necessary boot files (limine.conf, BOOTX64.EFI)

However, there's no documented or automated way to transfer this image to a physical USB device for real hardware testing.

Current Image Creation (Makefile:794-851)

The build system creates menios.hdd with:

# Create 128MB disk image
dd if=/dev/zero bs=1M count=0 seek=128 of=menios.hdd

# Create GPT partitions
sgdisk menios.hdd -n 1:2048:4095 -t 1:ef02  # BIOS boot partition
sgdisk menios.hdd -n 2:4096 -t 2:ef00        # EFI system partition

# Format FAT32 filesystem
mformat -F -i menios.hdd@@2M

# Install Limine bootloader
limine bios-install menios.hdd

This image should theoretically be bootable on real hardware via:

sudo dd if=menios.hdd of=/dev/sdX bs=4M status=progress

Proposed Solution

1. Add make usb Target

Create a new Makefile target that:

1. Verifies the disk image exists (menios.hdd)
2. Lists available USB devices (safely)
3. Prompts for confirmation before writing
4. Uses dd to write the image to the specified device
5. Syncs and safely unmounts

Example implementation:

.PHONY: usb
usb: build
	@echo "=== MeniOS USB Creator ==="
	@echo ""
	@if [ ! -f $(IMAGE_NAME).hdd ]; then \
		echo "Error: $(IMAGE_NAME).hdd not found. Run 'make build' first."; \
		exit 1; \
	fi
	@echo "Available USB devices:"
	@lsblk -d -o NAME,SIZE,TYPE,TRAN | grep usb || echo "No USB devices detected"
	@echo ""
	@echo "WARNING: This will DESTROY all data on the target device!"
	@read -p "Enter device name (e.g., sdb): " DEVICE; \
	read -p "Write to /dev/$$DEVICE? [y/N]: " CONFIRM; \
	if [ "$$CONFIRM" = "y" ] || [ "$$CONFIRM" = "Y" ]; then \
		echo "Writing $(IMAGE_NAME).hdd to /dev/$$DEVICE..."; \
		sudo dd if=$(IMAGE_NAME).hdd of=/dev/$$DEVICE bs=4M status=progress conv=fsync; \
		sudo sync; \
		echo "Done! USB device is ready."; \
	else \
		echo "Aborted."; \
	fi

2. Documentation

Create docs/hardware/usb_boot.md with:

Creating a Bootable USB

# Build the disk image
make build

# Write to USB device (Linux)
make usb

# Or manually:
sudo dd if=menios.hdd of=/dev/sdX bs=4M status=progress
sudo sync

macOS Instructions

# Find USB device
diskutil list

# Unmount (don't eject)
diskutil unmountDisk /dev/diskN

# Write image
sudo dd if=menios.hdd of=/dev/rdiskN bs=4m
sudo sync

# Eject
diskutil eject /dev/diskN

Boot on Real Hardware

1. Insert USB drive
2. Boot into BIOS/UEFI settings (usually F2, Del, or F12)
3. Enable USB boot
4. Select the USB drive as boot device
5. Save and reboot

Troubleshooting

• Secure Boot: May need to disable in UEFI settings
• BIOS vs UEFI: Limine supports both; try toggling boot mode
• Legacy Boot: Ensure BIOS boot partition is present
• Serial Output: Connect serial cable to see kernel logs (default: COM1, 115200 baud)

3. Testing Checklist

Hardware to test on:

• Modern UEFI laptop (2015+)
• BIOS-only desktop (pre-2010)
• Hybrid UEFI/CSM system
• Secure Boot disabled system
• Various USB 2.0/3.0 drives

Boot validation:

• UEFI boot path works
• Legacy BIOS boot path works
• Kernel loads and initializes
• Serial console outputs correctly
• VGA/framebuffer displays properly
• Keyboard input works
• Can reach mosh shell prompt
• FAT32 filesystem is readable/writable
• Userland tools execute successfully

4. Known Limitations & Future Work

Current constraints:

• Single CPU core: SMP may need tuning for real hardware
• Limited drivers: No AHCI/SATA yet (uses Limine-loaded RAM disk)
• Framebuffer only: No GPU acceleration
• PS/2 keyboard: USB keyboard requires USB HID driver
• Serial debugging: Easiest way to debug boot issues

Future enhancements:

• USB keyboard/mouse support (Implement PS/2 mouse driver and input support #143 for PS/2 mouse)
• AHCI driver for real SATA disks
• Network card drivers (e1000, rtl8139)
• Better hardware detection and fallbacks
• Automated hardware testing in CI (if feasible)

Implementation Plan

1. Phase 1: Add basic make usb target with safety checks
2. Phase 2: Create documentation with step-by-step instructions
3. Phase 3: Test on multiple hardware configurations
4. Phase 4: Document hardware compatibility matrix
5. Phase 5: Add troubleshooting guide based on real issues

Success Criteria

• make usb successfully creates bootable USB drives
• Documentation covers Linux, macOS, and Windows (via Rufus/dd)
• MeniOS boots on at least one real hardware system
• Boot process is documented with screenshots/serial logs
• Known compatibility issues are documented
• Safe handling of dangerous operations (dd warnings)

Related Issues

• Refactor code structure to make it more organized #23 - Code structure refactoring (COMPLETE - provides clean foundation)
• Refactor monolithic Makefile into modular domain-focused structure #352 - Makefile modularization (this could be part of mk/runtime/run.mk or new mk/hardware/usb.mk)
• Implement PS/2 mouse driver and input support #143 - PS/2 Mouse Driver (hardware compatibility)
• Related roadmap: "Bring-up on real hardware" (README.md:20)

Priority

High - This is the current long-term objective according to the README. Real hardware testing is essential for validating:

• Boot process robustness
• Driver compatibility
• Performance characteristics
• Hardware initialization edge cases

Safety Considerations

CRITICAL: The dd command can destroy data if misused. The implementation MUST:

• ✅ Require explicit device name (no defaults)
• ✅ Show clear warnings before writing
• ✅ Require confirmation prompt
• ✅ Validate device exists and is a block device
• ✅ Prevent writing to system disk (detect mounted partitions)
• ✅ Use sync after writing to ensure data integrity