bMETAL / DOS64

Boot and hardware help

Boot troubleshooting

Work from the downloaded image to the firmware, then to the last visible boot step. A successful QEMU boot is a useful comparison, not proof that a laptop is supported.

Experimental system: use disposable USB media and keep important data off test devices. If a laptop becomes unusually hot or unresponsive, stop the test. A forced power-off may lose pending writes or damage the test filesystem.

Confirmed requirements: an x86-64 CPU, 64-bit UEFI with GOP graphics, and Secure Boot disabled for the unsigned image. USB storage and input depend on supported hardware. The checks below are diagnostic suggestions unless explicitly described as requirements; they are not confirmed fixes for a particular laptop.

01

Check the image and USB

  1. Download the whole-disk IMG from Download image. It is not an ISO, and copying the file onto an existing USB filesystem does not make it bootable.
  2. Before writing it, compare its size and SHA-256 with the values on the download page. On Linux, run this in the download directory:
sha256sum bmetal-dos64-usb.img

If the hash differs for a freshly downloaded, unused image, download it again before continuing. Booting without snapshot mode or adding files changes the image; that modified copy will no longer match the published checksum.

  1. Use an image writer in raw/disk-image mode. Select the verified whole USB device, not one partition. Writing the image erases the selected device; check its model and capacity first.
  2. Let the writer finish and verify the write if it offers that option, then safely eject. Keep all three image partitions intact; do not accept a host OS prompt to format them.
  3. If writing or booting remains unreliable, try a different spare USB drive and a direct laptop USB port instead of a dock or hub. Change one thing at a time and record the result.

On a larger USB drive, the supplied partitions retain their original sizes. Unused space after them is expected, not evidence of a failed write.

02

UEFI and Secure Boot

  • Select the USB device's UEFI entry in the one-time boot menu. Legacy BIOS/CSM boot is not provided. A 64-bit CPU alone does not guarantee 64-bit UEFI firmware.
  • The published EFI application is unsigned. A firmware message such as Security Violation can indicate signature enforcement: check Secure Boot before diagnosing the kernel.
  • The boot partition should contain EFI\BOOT\BOOTX64.EFI. If firmware opens a UEFI shell instead, and a mapped FAT volume exposes that file, you can select its fsN: mapping and launch \EFI\BOOT\BOOTX64.EFI. Mapping numbers vary; inspect them rather than assuming fs0:.
  • Firmware seeing the USB device does not guarantee DOS64 can use it after the UEFI handoff. DOS64 then relies on its own graphics, input, and storage support.
Before changing firmware: record the original settings. Secure Boot changes can trigger disk-encryption recovery on your installed OS; have its recovery key available first. Do not clear Secure Boot keys or change SATA/RAID settings for this guide. Restore your normal settings after testing.
03

Find your symptom

Observations and next checks, not hardware-specific diagnoses
What you seeWhat to check next
USB is absent from the boot menuVerify the raw image write, UEFI boot mode, and a direct port. Try another spare USB drive. Confirm that the machine has 64-bit UEFI.
Security error or immediate return to firmwareCheck Secure Boot and the EFI file path above. Photograph the exact firmware message; an immediate return alone does not identify the cause.
Blank screen after selecting DOS64Note whether any DOS64 banner appeared. GOP graphics are required. Compare the same pristine download in QEMU; if serial capture is available, check whether boot continued without visible output.
Loading stops; top-right disk stops animatingRecord the last text, elapsed time, and whether the keyboard or caret still responds. The indicator updates as DOS64 code runs; it is not an independent hardware watchdog. A still disk at an idle shell is normal. During loading, a stopped indicator does not identify which driver or operation stalled.
Fan speeds up and everything appears frozenStop if the machine becomes unusually hot. Increased fan speed does not identify the cause. On the next controlled test, remove nonessential USB devices and capture the screen or serial output rather than repeatedly waiting on an unresponsive system.
Shell appears but keyboard or touchpad does not workTry a basic wired USB keyboard or mouse connected directly. USB boot-HID devices and an i8042 keyboard fallback are supported paths, but built-in laptop devices are not guaranteed. Firmware-menu input working does not prove DOS64 input support.
Storage unavailable or no C: driveFirmware can load the EFI application even when DOS64 cannot later access the USB storage. Keep the image partitions intact; try a different direct port or spare USB drive. Do not format internal disks to solve this.
System-check output appears, then seems to stopThe published image runs syscheck.exe from AUTOEXEC.BAT. Include its last output in the report: reaching it is different from freezing before the shell startup sequence.
04

Compare with QEMU

Use a pristine image, QEMU, and OVMF on Linux. This variant of the normal boot command uses standard VGA for GOP, keeps guest disk writes in a temporary snapshot, and captures COM1 output to a host file. Run it from the image directory. Adjust the OVMF path for your distribution.

qemu-system-x86_64 -m 1G -vga std \
  -device qemu-xhci \
  -device usb-kbd -device usb-mouse \
  -drive if=none,id=dos64,file=bmetal-dos64-usb.img,format=raw,snapshot=on \
  -device usb-storage,drive=dos64,removable=on \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
  -boot order=c -display gtk -serial file:dos64-serial.log

Type in the guest window. Close QEMU before inspecting or copying the image. Guest changes, including its on-disk boot log, are discarded when QEMU exits; the host file dos64-serial.log remains. Use a new log filename for each test to preserve previous results.

  • Cannot open OVMF: locate your distribution's installed x86-64 OVMF firmware and correct the path. Do not substitute legacy BIOS firmware.
  • GTK display unavailable: use an installed QEMU graphical backend. A display-backend startup error occurs on the host, before DOS64 boots.
  • Guest has not initialized the display: first confirm OVMF loaded and keep -vga std. Save serial output if the screen remains blank; this message alone is not a kernel diagnosis.

If QEMU boots and the laptop does not, include both results in the report. That narrows the comparison to different environments; it does not prove that the image supports the laptop.

05

Collect boot logs

Photograph the screen first

Capture the complete screen, especially the last message and any failure code. Note whether the disk indicator or caret moves and whether input responds. A photograph is useful even when no log file exists.

On the USB data volume

DOS64 can save boot diagnostics to C:\LOG.TXT once storage is mounted and file logging starts. After the test is stopped and the USB drive is safely reconnected to another OS, look on the 100 MiB system data volume, not the EFI boot partition. Copy the file before another boot and check whether it contains the failed attempt.

No log does not mean no failure: an early hang can occur before the buffered boot messages reach the USB drive. A missing, old, or incomplete log is possible, especially if storage failed or power was forcibly removed.

Serial output

The QEMU command above captures COM1 without relying on guest storage. On physical hardware, capture is only practical when a usable COM1 UART and suitable equipment are available; the serial configuration is 115200 baud, 8 data bits, no parity, 1 stop bit. A USB-to-serial adapter plugged into the DOS64 laptop is not automatically a COM1 output port. Do not assume a modern laptop exposes one.

06

Report a boot problem

Include this information when reporting the problem to the project maintainer through your existing contact channel. A public issue tracker is not linked here yet.

Image filename and published build date:
SHA-256 of the pristine download:
Laptop / motherboard model and CPU:
UEFI firmware version:
UEFI boot entry used; Secure Boot state:
USB drive model and capacity; image-writing tool:
Direct USB port or hub/dock:
Last visible message or failure code:
Time until the apparent freeze:
Disk indicator / caret movement; keyboard response:
QEMU result with the same download:
Results after changing one device or port:
Attachments: full-screen photo, LOG.TXT and/or serial log if available

Review logs and photographs before sharing. Remove private filenames, device serial numbers, or other identifying information you do not want to publish. Do not send passwords or recovery keys. A stopped animation alone is not enough to assign a cause; preserve the surrounding evidence.