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.
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.
Check the image and USB
- 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.
- 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.
- 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.
- 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.
- 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.
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 itsfsN:mapping and launch\EFI\BOOT\BOOTX64.EFI. Mapping numbers vary; inspect them rather than assumingfs0:. - 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.
Find your symptom
| What you see | What to check next |
|---|---|
| USB is absent from the boot menu | Verify 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 firmware | Check 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 DOS64 | Note 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 animating | Record 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 frozen | Stop 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 work | Try 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: drive | Firmware 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 stop | The 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. |
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.
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.
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.
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.