fix: don't expose eMMC as USB mass storage when no image is mounted#741
Open
MagnaCapax wants to merge 1 commit intosipeed:mainfrom
Open
fix: don't expose eMMC as USB mass storage when no image is mounted#741MagnaCapax wants to merge 1 commit intosipeed:mainfrom
MagnaCapax wants to merge 1 commit intosipeed:mainfrom
Conversation
When /boot/usb.disk0 exists but is empty (the default state), the USB gadget init script (S03usbdev) sets /dev/mmcblk0p3 as the mass storage backing file. This exposes the NanoKVM's raw eMMC partition (~162MB, ext4/exfat) as a USB disk to the host computer. On Legacy BIOS systems, the BIOS attempts to boot from this device, reads invalid data (no MBR), and enters a HLT loop — completely hanging the system with no keyboard input accepted. The only recovery is a physical power cycle. Similarly, the Go server (image.go) re-mounts /dev/mmcblk0p3 whenever an ISO image is unmounted, re-exposing the eMMC partition. Changes: S03usbdev: Flip the empty-file check so that when usb.disk0 is empty, no backing file is set. The mass_storage device (with removable=1) reports "no media inserted" — which BIOS handles safely by skipping to the next boot device. When usb.disk0 contains a path, that path is used as before. image.go: Remove the imageNone constant (/dev/mmcblk0p3). When unmounting an image (empty request), the device stays unmounted instead of falling back to the eMMC partition. GetMountedImage retains backward compatibility by treating mmcblk0p3 as "no image" for devices that haven't rebooted yet. No changes needed to virtual-device.go — with this fix, toggling "Virtual Disk" ON creates the mass_storage gadget with no media (correct behavior), and users mount ISOs through the existing UI. Refs: sipeed#633, sipeed#385, sipeed#438, sipeed#187
MagnaCapax
force-pushed
the
fix/mass-storage-default-backing
branch
from
a5244e4 to
9d37427
Compare
winstar0070
added a commit
to Stella-IT/NanoKVM
that referenced
this pull request
Feb 12, 2026
When usb.disk0 is empty, no backing file is set instead of defaulting to /dev/mmcblk0p3. This prevents Legacy BIOS systems from hanging during boot when the raw eMMC partition was exposed as a USB disk. Cherry-picked from: sipeed#741 Original author: MagnaCapax
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When
/boot/usb.disk0exists but is empty (the default out-of-box state), the NanoKVM exposes its raw eMMC partition (/dev/mmcblk0p3) as a USB mass storage device. This causes Legacy BIOS systems to hang during boot — the BIOS attempts to boot from the device, reads invalid data (no MBR signature), and enters a HLT loop. The system becomes completely unresponsive; no keyboard input is accepted, and the only recovery is a physical power cycle.This affects any NanoKVM connected to a Legacy BIOS system in its default configuration — a zero-config out-of-box bug.
The same behavior occurs when an ISO image is unmounted via the web UI:
image.gore-mounts/dev/mmcblk0p3as the "no image" fallback, re-exposing the eMMC.Changes
kvmapp/system/init.d/S03usbdev/boot/usb.disk0is empty, do not set a backing file forlun.0/fileremovable=1) reports "no media inserted"usb.disk0contains a path, that path is used as before (no behavior change)server/service/storage/image.goimageNoneconstant (/dev/mmcblk0p3)req.File), the device stays unmounted instead of falling back to the eMMC partitionGetMountedImageretains backward compatibility by still treatingmmcblk0p3as "no image" for devices that haven't rebooted after the updateserver/service/vm/virtual-device.go(no changes needed)S03usbdevfix, toggling "Virtual Disk" ON correctly creates the mass_storage gadget with no media. Users then mount ISOs through the existing UI.Root Cause
Three code paths wrote
/dev/mmcblk0p3to the USB gadget's backing file:S03usbdev(line 116):echo /dev/mmcblk0p3 > functions/mass_storage.disk0/lun.0/file— when the gate file is emptyimage.go(line 114):image = imageNone— when unmounting an ISOvirtual-device.go(line 35):touch /boot/usb.disk0— creates the empty gate file that triggers (1)The eMMC partition contains a Linux ext4/exfat filesystem with no MBR. When Legacy BIOS reads sector 0 and finds no
0x55AAboot signature, some implementations (notably ASRock) enter a HLT loop instead of trying the next boot device.Testing
Workaround tested in production (2026-01-30) on ASRock DeskMini A300 (Legacy BIOS P3.70, Ryzen 5 3400G) with NanoKVM (Image v1.4.0 / App 2.3.4):
/boot/usb.disk0on NanoKVM → only HID + RNDIS functions present → BIOS proceeds normally through boot order → system boots successfully.The code changes in this PR implement the same logic as the workaround (empty gate file = no backing file) but at the correct code level, preserving the virtual USB disk feature for users who mount actual ISO images.
Related Issues
Fixes #633
Refs #385, #438, #187