Wikis > USB Subsystem > Troubleshooting

Troubleshooting the USB Drivers

Check these things first

  • Make sure you have installed the USB drivers using the WarpIn package with all the default package selections and settings, that you have allowed the installer to overwrite and unlock all existing files, and you have allowed it to modify your CONFIG.SYS.
  • Make sure all the USB drivers are installed in the standard location (\os2\boot) and that there are no other USB drivers installed in other locations on your boot disk.
  • Make sure all of the USB drivers are the same version and make sure that your CONFIG.SYS is loading the correct drivers. You should not mix versions since the drivers are designed to work together and changes in some drivers might not be compatible with older versions of other drivers.
    • USBEHCD.SYS, USBOHCD.SYS, USBUHCD.SYS, USBXHCD.SYS, and USBD.SYS are a matched set and must all be the same version. (Your system may not use all of these drivers.)
    • USBHID.SYS, USBKBD.SYS, and USBMOUSE.SYS are a matched set and must all be the same version. These must also be the same version as the Host Controller drivers and USBD.
    • USBRESMG.SYS and USBCALLS.DLL are a matched set and must be the same version. There are many different versions of USBRESMG.SYS and USBCALLS.DLL distributed with various other packages. If you are having problems with the USBCALLS interface, make sure that you are not using mismatched versions. Beware of other versions of USBCALLS.DLL in your LIBPATH or current directory. You can use any pair of USBRESMG.SYS/USBCALLS.DLL you want, however if you open a ticket, you MUST be using the versions in the official Arca Noae distribution. If you are unsure about which version to use, use the one from the Arca Noae distribution. It attempts to unify all the various versions and should work in all cases.
  • Make sure you are not using any switches on any of the USB drivers (except USBMSD.ADD). No switches are necessary and some switches can make the drivers not work properly.
  • Make sure you do not have tracing enabled for the USB drivers. Tracing is generally not supported on version 12.x drivers.
  • If you have a very old version of the libusbcalls RPM package installed, and you update the libusbcalls RPM package, and then you get missing file errors when booting, simply reinstall the USB WarpIN package to replace the missing files.
  • If you are having problems with MSD type devices, and you are running eCS and have the eCenter USB widget installed, try uninstalling the eCenter USB widget to see if that is causing your problems. The eCenter USB widget is known to cause problems with MSD type devices. To eliminate the eCenter USB widget as a cause of the problems, you must completely uninstall it, including its DLL. Note that the AN Removable Media widget that comes with ArcaOS does not┬áhave these problems and is OK to use.

Notes on the xHCI preview

Slight differences in reliability have been reported with different xHCI controllers.Your results using the xHCI preview may vary accordingly. Be sure to read the limitations section in the ReadMe.

Known issues:

  1. Isochronous transfers are not implemented. Streaming audio/video won’t work for xHCI connected devices.
  2. Sometimes trying to simultaneously operate more than one xHCI connected Mass Storage Device (MSD) doesn’t work.
  3. Sometimes one xHCI connected device interferes with another device connected to the same xHCI controller, causing one of the devices to stop working.

Driver Order in CONFIG.SYS

The order of the USB base drivers in CONFIG.SYS changed from version 11.x to version 12.x. The old version 11.x drivers required USBD.SYS to come after the HC drivers:


For the 12.x drivers, USBD.SYS should come first:


USB MSD Disk Interoperability

In order to use MSD type memory sticks or disks with ArcaOS, the media must be partitioned and contain LVM information. This type of media is compatible with other operating systems. However, some other systems (Windows, for example) can create media that is not partitioned and does not have LVM information on it. Please see the Preparing USB MSD Disks page for information on how to make your USB memory stick or USB disk compatible.

Known Issues

  • Sometimes the keyboard doesn’t work during bootup. For example, you cannot press ENTER when there are errors in the config.sys that require you to press ENTER. OS/2 relies on the system’s BIOS to provide all necessary services (disk, keyboard, video, etc.) while it loads and runs itself and its own drivers. If the BIOS stops providing a particular service such as USB keyboard emulation before the USB drivers are loaded and running, then you get this problem. Everyone blames the USB drivers even though they are not even running yet. This is a BIOS issue, not a USB driver issue. You can work around this problem by adding PAUSEONERROR=NO to your CONFIG.SYS, so that the kernel won’t stop and wait for you to press ENTER if there is an error.

Opening a Ticket

Before opening a ticket, make sure your issue is not already listed in the Known Issues section above.

If you open a ticket, a TestLog log file is always required. You can save a lot of time by attaching the TestLog log file to your ticket when you open it, rather than waiting for the developer to ask for it. Always make sure you capture the TestLog log file when the problem exists.

Unless specifically requested, don’t provide comparisons or reports from different operating systems. The ArcaOS, and OS/2 USB stack is completely different than USB on other systems. It has a different architecture, different implementation, and it operates differently. Any comparisons with or reports from some other OS just don’t provide any useful information. Also, any results, IDs, reports, etc. produced by Windows, for example, are known to be frequently wrong and cannot be trusted to be accurate. In general, unsolicited reports of how something works on another system like Windows can interfere with and discourage work on your problem.

Normally the developer will not want a trace file, and you should not have tracing enabled for the USB drivers. If the developer does want a trace file, be sure to follow the developer’s instructions for creating one exactly.

This page contains instructions for creating a TestLog log file and a formatted trace file.

Uninstalling the USB widget from the eCS eCenter

  1. Right click on the USB widget in the eCenter and select “Delete widget”.
  2. Close the eCenter
  3. Open a command window and navigate to “\ecs\system\ewps\plugins\xcenter” on your boot disk.
  4. Rename, move, or delete USBSHOLD.DLL so that it cannot be loaded.

Capturing A TestLog log file

If you don’t already have the current version of the TestLog program, you can download it here: Get TestLog

Open a command window and execute the testlog command

testlog generic

Attach the created log file to your ticket. Do not ZIP the log file.

Capturing a Startup Trace file

A startup trace file is for a problem that occurs on startup, rather than for a problem that occurs after the system has been running for a while.

To create a startup trace file, do the following:

1) Add the following line to your config.sys. Note the NOWRAP keyword which is what makes this a startup trace.


2) Add the appropriate “TRACE=ON <trace code>” line to your config.sys. The developer will tell you the correct trace codes to use.

Trace codes for USB drivers:

  • 0x00e0 224 UHCI
  • 0x00e1 225 OHCI
  • 0x00e2 226 EHCI
  • 0x00e3 227 USBD
  • 0x00e4 228 ALL HID
  • 0x00e5 229 USBCOM
  • 0x00ee 238 USBAUDIO
  • 0x00ef 239 USBMSD

3) Reboot to enable tracing.

4) To capture the trace dump, open a command window and type:


From the file menu choose Save Formatted… and save the trace to a file of your choice.

5) Attach file you created to your ticket.

Capturing a Runtime Trace file

A runtime trace file is for problems that occur after the system is up and running. It is not for problems that occur at startup.

To create a runtime trace file, do the following:

1) Add the following line to your config.sys. Note the WRAP keyword which is what makes this a runtime trace.


2) Reboot to enable tracing.

3) Open a command window and type the TRACE command that the developer gave you and then type “TRACE /C”.

4) Cause the problem to occur.

5) To capture the trace dump, go back to the command window and type:


6) From the file menu choose Save Formatted… and save the trace to a file of your choice.

Creating a Trap Dump

Please see How to get a Trap Dump.

This entry last updated: by David Azarewicz