USB Mass Storage Issues with detecting USBMS Gadget in BIOS

[danifunker]

Greetings, we are implementing a project that leverages the circle framework and I believe I have identified some issues with the dwgadget implementation within Circle.

I know this functionality works fine with the Linux based mass storage driver, so I have reason to believe this is specific to Circle.

I altered the HandleSCSI function to include additional debug logging to help identify what commands may be causing issues.
in the file lib/usb/gadget/usbmsdgadget.cpp
I uncommented the #define MLOGNOTE(From,...) logging command
and added the following line under the class definition
void CUSBMSDGadget::HandleSCSICommand()
MLOGNOTE("HandleSCSICommand","CBWCB[0]=0x%x, CBWCB[1]=0x%x, CBWCB[2]=0x%x, CBWCB[3]=0x%x", m_CBW.CBWCB[0],m_CBW.CBWCB[1],m_CBW.CBWCB[2],m_CBW.CBWCB[3]);

I also enabled the USB_GADGET_DEBUG logs.

To test this, I imaged an SDcard with the file win98qi_v0.9.6_ALL_usb.img and then copied over the required files and output of the sample kernel of test/usb-msd-gadget (specifically in my case, kernel7.img). I am testing on Raspberry Pi Zero 2 W.

Issue 1: Many computer systems will not detect the USB Mass Storage during BIOS detection.

(higher priority)

Here are the logs from 3 boot sessions after I enabled the USB_GADGET_DEBUG logs.
I did have HandleSCSI additional logging enabled, but as the logs reveal the BIOS didn't get that far.

My cmdline.txt was logdev=ttyS1 loglevel=5 usbboost=true sounddev=sndi2s fast=true
I also tried with cmdline.txt as logdev=ttyS1 loglevel=5 sounddev=sndi2s and no difference was found in the logs.

logger: Circle 49.0.1 started on Raspberry Pi Zero 2 W 512MB
logger: Revision code is 902120, compiler has been GCC 14.2.1
00:00:00.66 timer: SpeedFactor is 1.51
00:00:00.68 sdhost: emmc1: sdhost-bcm2835 loaded
00:00:02.20 emmc: Capacity is 15193 MBytes
00:00:02.20 emmc: Found a valid version 3.0x SD card
00:00:02.90 kernel: Compile time: Jun 27 2025 11:43:11
00:00:07.24 dwgadget: IRQ (status 0x00001000)
00:00:07.24 dwgadget: USB reset
00:00:07.24 dwgadget: Set device address to 0
00:00:07.24 dwgadgetep: First in next EP sequence is 0
00:00:07.24 dwgadgetep: Dumping 0x10 bytes starting at 0x22FA8
00:00:07.24 dwgadgetep: 2FA8: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:09.92 dwgadget: IRQ (status 0x00002000)
00:00:09.92 dwgadget: Enumeration done
00:00:09.92 dwgadget: IRQ (status 0x00000800)
00:00:09.92 dwgadget: USB suspend
00:00:17.07 dwgadget: IRQ (status 0x00001000)
00:00:17.07 dwgadget: USB reset
00:00:17.07 dwgadget: Set device address to 0
00:00:17.07 dwgadgetep: First in next EP sequence is 0
00:00:17.07 dwgadgetep: Dumping 0x10 bytes starting at 0x22FA8
00:00:17.07 dwgadgetep: 2FA8: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:19.75 dwgadget: IRQ (status 0x00002000)
00:00:19.75 dwgadget: Enumeration done
00:00:19.75 dwgadget: IRQ (status 0x00000800)
00:00:19.75 dwgadget: USB suspend
00:00:25.33 dwgadget: IRQ (status 0x00001000)
00:00:25.33 dwgadget: USB reset
00:00:25.33 dwgadget: Set device address to 0
00:00:25.33 dwgadgetep: First in next EP sequence is 0
00:00:25.33 dwgadgetep: Dumping 0x10 bytes starting at 0x22FA8
00:00:25.33 dwgadgetep: 2FA8: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:28.01 dwgadget: IRQ (status 0x00002000)
00:00:28.01 dwgadget: Enumeration done
00:00:28.01 dwgadget: IRQ (status 0x00000800)
00:00:28.01 dwgadget: USB suspend

[rsta2]

The log looks mostly as expected, but the device does not receive any request from the host and goes to suspend instead. I will try to reproduce this here with the BIOS of a PC.

[rsta2]

I successfully tested the test/usb-msd-gadget with the BIOS of my PC Netbook. The drive is detected, but I had to remove the blinking of the Act LED, because the startup operation takes too long otherwise.

[danifunker]

Thanks for testing, are you able to boot into an OS as well? We are seeing major issues with Seabios enabled devices such as the ITX Llama, that is what the logs are from.

We have got this to work on other systems but I think the way how the dwgadget or dwgadgetendpoint is handling bus resets and handoff between bios session and boot. This doesn't happen with the Linux MSD gadget which I why I raised the issue.

[rsta2]

Unfortunately I do not have an OS, which I can boot on a PC from a SD card. I started the loading process and from the debug output I can see, that is loads something, but of course I will not really run. I think the time is critical, which the RPi needs to start into the application, which provides the MSD gadget function. When the RPi is powered via the USB, which is also used for data transfers, the RPi has only a short time to start until the boot selection window appears. Sometimes the time is too short, and there is no entry for the USB drive.

[danifunker]

On my PC (Itx llama), I'm able to use CTRL+ALT+DEL which does not restart the circle device. I know this isn't entirely a timing issue on the Llama due to that.

In my project we are using dwgadget/dwgadgetendpoint and have verified the ctrl+alt+del works in some scenarios but also doesn't get past the bios detection properly (sometimes in our project it detects in the bios but won't boot correctly due to resets).

If you have the opportunity to try win98qi usb it should boot, and used linux to boot with.

[rsta2]

I modified the test/usb-msd-gadget so that one can copy an disk image file to the SD card and it delivers the file contents like it would be written directly to the SD card, starting at sector 0. With this and with a disk image of FreeDOS I was able to test the boot process further and I also ran into an issue.

After selecting the boot option from the boot screen, it loads some sectors successfully and then instead of continuing the host sends an USB reset. Currently unfortunately I have no idea, why this happens.

See the log file attached. My comments are preceded with ###.

usb-msd-log.txt

[danifunker]

Thank you for testing this, this is similar to what we are seeing in my project, however I don't get the stack dump after trying to boot from our disc.

Is this something you are able to continue investigating?

[rsta2]

Currently I have no idea, how to continue.

[rsta2]

I tested now with a different PC (Thinkpad X240) and it works there without modifications to the Circle gadget source. I think you have to disable Secure Boot and enable the Compatibility System Module (CSM) so that it works. My previous PC did not support this and so it did not work. I assume there is no problem in Circle, it's just a feature (Secure Boot) of the PC.

[rsta2]

My apologies I was wrong. There was a problem in the Circle gadget code, so that it was not able to handle Enumeration Done interrupts properly, when they occurred in states other than StateResetDone. The problem has been fixed on the develop branch. With this booting works on my Netbook too, which didn't work before.

[danifunker]

I've applied this specific fix as a patch to my local environment, but noticed it is harder to get my BIOS to enumerate the device now. I've enabled USB_GADGET_DEBUG and the only indicators that anything is happening is when I restart my computer, that the mass storage device is logging a connection reset.

Here are my latest logs:

logger: Circle 49.0.1 started on Raspberry Pi Zero 2 W 512MB
logger: Revision code is 902120, compiler has been GCC 14.2.1
00:00:00.66 timer: SpeedFactor is 1.51
00:00:00.68 sdhost: emmc1: sdhost-bcm2835 loaded
00:00:02.20 emmc: Capacity is 15193 MBytes
00:00:02.20 emmc: Found a valid version 3.0x SD card
00:00:02.90 kernel: Compile time: Jul  3 2025 13:28:05
00:00:03.52 dwgadgetep: First in next EP sequence is 0
00:00:03.52 dwgadgetep: Dumping 0x10 bytes starting at 0x22F10
00:00:03.52 dwgadgetep: 2F10: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:15.57 dwgadgetep: First in next EP sequence is 0
00:00:15.57 dwgadgetep: Dumping 0x10 bytes starting at 0x22F10
00:00:15.57 dwgadgetep: 2F10: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:26.57 dwgadgetep: First in next EP sequence is 0
00:00:26.57 dwgadgetep: Dumping 0x10 bytes starting at 0x22F10
00:00:26.57 dwgadgetep: 2F10: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF

First start was at around 00:00:03.52

Next restart was at around 00:00:15.57 and the third start was at 00:00:26.57

[rsta2]

Are you sure, that you enabled USB_GADGET_DEBUG globally and rebuild everything? I'm missing at least the "dwgadget: USB reset" line, which must come before "dwgadgetep: First in next EP sequence is 0". Without the messages from "dwgadget" the log is not telling much.

[danifunker]

Thank you so much for the latest release. We've updated it in our project but still experiencing similar issues.

My build process was to edit the include/circle/sysconfig.h file, updated the USB_GADGET_VENDOR_ID, USB_GADGET_DEVICE_ID_BASE and set USB_GADGET_DEBUG in there as well, then ran make for RASSPI=3 using the GCC as per instructions.

I have built the latest usb-msd-gadget and tried booting 3 times from my retro PC using CTRL+ALT+DEL. My retro PC maintains power to the USB port during reboot.

Outside of these logs, I am able to see a lot of debug logs when I load Windows 98SE, I haven't included them since that part seems to be working.

logger: Circle 50 started on Raspberry Pi Zero 2 W 512MB
logger: Revision code is 902120, compiler has been GCC 14.3.1
00:00:00.66 timer: SpeedFactor is 1.51
00:00:00.68 sdhost: emmc1: sdhost-bcm2835 loaded
00:00:02.20 emmc: Capacity is 60906 MBytes
00:00:02.20 emmc: Found a valid version 3.0x SD card
00:00:02.90 kernel: Compile time: Aug 22 2025 11:20:30
00:00:11.86 dwgadget: IRQ (status 0x00001000)
00:00:11.86 dwgadget: USB reset
00:00:11.86 dwgadget: Set device address to 0
00:00:11.86 dwgadgetep: First in next EP sequence is 0
00:00:11.86 dwgadgetep: Dumping 0x10 bytes starting at 0x23118
00:00:11.86 dwgadgetep: 3118: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:18.32 dwgadget: IRQ (status 0x00002000)
00:00:18.32 dwgadget: Enumeration done
00:00:18.32 dwgadget: IRQ (status 0x00000800)
00:00:18.32 dwgadget: USB suspend
00:00:19.96 dwgadget: IRQ (status 0x00000800)
00:00:19.96 dwgadget: USB suspend
00:00:30.19 dwgadget: IRQ (status 0x00001000)
00:00:30.19 dwgadget: USB reset
00:00:30.19 dwgadget: Set device address to 0
00:00:30.19 dwgadgetep: First in next EP sequence is 0
00:00:30.19 dwgadgetep: Dumping 0x10 bytes starting at 0x23118
00:00:30.19 dwgadgetep: 3118: 01 00 FF FF FF FF FF FF-FF FF FF FF FF FF FF FF
00:00:36.64 dwgadget: IRQ (status 0x00002000)
00:00:36.64 dwgadget: Enumeration done
00:00:36.65 dwgadget: IRQ (status 0x00000800)
00:00:36.65 dwgadget: USB suspend
00:00:38.29 dwgadget: IRQ (status 0x00000800)
00:00:38.29 dwgadget: USB suspend

diff --git a/include/circle/sysconfig.h b/include/circle/sysconfig.h
index 566e6eb7..1de6ba35 100644
--- a/include/circle/sysconfig.h
+++ b/include/circle/sysconfig.h
@@ -329,7 +329,7 @@
 // define a new one.

 #ifndef USB_GADGET_VENDOR_ID
-#define USB_GADGET_VENDOR_ID           0x0000
+#define USB_GADGET_VENDOR_ID           0x04da
 #endif

 // USB_GADGET_DEVICE_ID_BASE is the base value for the assignment of
@@ -340,7 +340,7 @@
 // same USB Vendor ID!

 #ifndef USB_GADGET_DEVICE_ID_BASE
-#define USB_GADGET_DEVICE_ID_BASE      0x8001
+#define USB_GADGET_DEVICE_ID_BASE      0xa4a5
 #endif

 #ifndef USB_GADGET_DEVICE_ID_MIDI
@@ -355,6 +355,10 @@
 #define USB_GADGET_DEVICE_ID_MSD       (USB_GADGET_DEVICE_ID_BASE+2)
 #endif

+#ifndef USB_GADGET_DEBUG
+#define USB_GADGET_DEBUG
+#endif
+

[rsta2]

Thanks for the full log. With it I can analyze this now again. It will take some time.