******************************************************************
*** WARNING: This software is provived without any warranties. ***
***          It has not been proven to be free of defects.     ***
***          Any use is at the user's own risk!                ***
******************************************************************
  
"CMD", "VIA", "INTEL", "ETEQ", "OPTI", "SIS", "NEC", "ALI", "ACER", 
"AMD", "IBM", "USB", "OS/2", "EHCI", "OHCI", "UHCI"
are trade marks of their respective owners.

Updates to the host controller drivers USBUHCD.SYS,USBOHCD.SYS,USBEHCD.SYS (and USBD.SYS)

Prerequisites: these drivers will ONLY work on >= Warp4,Fixpak13. This is the minimum requirement.
Because of known kernel defects, you will however need to use kernel versions 10.104a or 10.105.
eComStation meets this requirement out of the box.
Replacement kernels can also be received from here:
www.os2site.com/sw/upgrades/kernel

Note: these drivers DO NOT work with Warp3, no matter what fixpack

If you get a message on boot saying that "KEE could not be loaded" or such you will know that your kernel is not up-to-date.
You can also execute: pstat.exe /F | find "KEE" from a commandline.
If it returns without displaying anything, your kernel is not up-to-date. If it instead returns with: "KEE   KEE.DLD"
then you have a working kernel.


1.) the base of these driver updates is the latest IBM sources.
    Unfortunately these do not reflect versions 10.162 of the IBM provided drivers. The DDK sources seem
    to got stuck in stage "work in progress"

2.) Parameters supported by these drivers:
USBUHCD.SYS,USBOHCD.SYS,USBEHCD.SYS,USBD.SYS: /V: give some information on bootup (also supported by 10.162 drivers)
USBUHCD.SYS,USBOHCD.SYS,USBEHCD.SYS: /FS: on shutdown, put the HC into reset instead of just letting it execute
                                          this is supposed to solve some problems on next bootup
                                          (also supported by 10.162 drivers)
USBEHCD.SYS                          /S:x (where x=1,2,4,8,16,32,64), according to Robert Lalla, lower values are
                                          supposed to improve throughput. Technically, it will set
                                          "Interrupt Threshold Control", see EHCI spec
                                          (x=1: raise interrupt every 1ms frame,
                                          x=64: raise interrupt every 64th 1ms frame), this parameter might need
                                          some experimentation for optimal throughput/latency

There are still some improvements to be made but hopefully these drivers fix some of the problems you might have
experienced with the IBM provided drivers (host controllers and therefore some USB ports being unusuable, hangs on
bootup, etc.).

Make sure you back up your existing drivers ! These drivers come without any warranty whatsoever. If they don't work
for you, revert back to your backed up drivers.


Post bugs to:
http://svn.netlabs.org/usb/report
ALWAYS state WHAT VERSION of the driver you were using when the trap occurred ! If possible, please add a valid email address
to the CC field so that you will get email notifications when the bug report is updated by me.

I'd be especially interested in reports on older systems (also without ACPI.PSD) and on systems using ACPI.PSD.
These drivers SHOULD work with OS2APIC.PSD and also with ACPI.PSD.
As time permits, I will try and solve the problems.

Please provide as much info as you can:
1.) Did it work with the IBM supplied 10.162 drivers ? Also try combinations of IBM drivers and these drivers
2.) Kernel version: run "bldlevel OS2KRNL" from the root directory
3.) how many CPUs / CPU cores ?
4.) ACPI.PSD ? What switches ?
5.) What type of USB ? UHCI ? OHCI ? EHCI ? Output of "pci.exe -D" is very helpful:
    http://hobbes.nmsu.edu/download/pub/os2/util/misc/pci104vka.zip
    Please run pci.exe with the "-D" flag: this gives detailed pci config space info for each PCI device !!!!
    If you have eCS 2.0, you can instead use:
    \ecs\install\DETECTEI\pciscan.exe
6.) USB relevant parts in Config.sys, in particular, order and number of driver instances: USBD.SYS and USB(I|O|E)HCD.SYS
7.) if trap or hang: describe as good as you can: when exactly does it hang ? Can you check by hitting
    Alt-F2 when boot blob in upper left corner shows up and note down last driver that loaded successfully ?
    What driver / daemon program would load after the last successfully loaded driver ?
    If trap in USB(I|O|E)HCD.SYS: note down trap screen, CS:IP, SS:BP and AX,BX,CX,DX,ES,DS are especially important
    Or, even easier: take a picture of the trap screen and attach to bug report


Important note: do NOT use the USB widget from eCenter/XCenter (part of eWorkplace/XWorkplace) in order to control USB devices.
This widget is badly broken and its use can lead to all kinds of ill effects, including non functional USB or a complete system hang.
I suggest to revert back to the original daemon program that handles USB devices attaches/detaches.
This is \ecs\boot\USBMSDD.EXE.
Here is a piece of REXX code to create a program object in the startup folder:

/* REXX script */
if RxFuncAdd('SysLoadFuncs','REXXUTIL','SysLoadFuncs') then do
   rc = SysLoadFuncs()
end
bootDrive = SysBootDrive()
class='WPProgram'
title='USB-Monitor V1.2'
location='<WP_START>'
app='EXENAME='bootDrive'\ecs\boot\usbmsdd.exe'
startupdir='STARTUPDIR='bootDrive'\ecs\boot'
parameters='PARAMETERS='bootDrive'\ecs\boot\usbmsdd.ini'
icon='ICONFILE='bootDrive'\os2\boot\usbmon.ico'
iconpos='ICONPOS=0,0'
open='OPEN=RUNNING'
minimized='MINIMIZED=YES'
progtype='PROGTYPE=WINDOWABLEVIO'
autoclose='NOAUTOCLOSE=NO'
objectid='OBJECTID=<USB_MON>'
rc = SysCreateObject(class,title,location,app';'startupdir';'parameters';'icon';'iconpos';'open';'minimized';'progtype';'autoclose';'objectid';','R')
if rc==0 then
   ret = 0
else
   ret = 1
return ret

Save this to a file with extension .cmd and execute from a commandline. Of course you can modify the title and/or object id to whatever you like.


Lars Erdmann


HOW TO SET UP DUMPING+TRACING
For setting up a dump partition you can also have a look at:
http://newsgroups.derkeiler.com/Archive/Comp/comp.os.os2.bugs/2007-09/msg00032.html

Setting up a dump partition
1.) Create a partition > the physical size of your memory and give it a
drive letter, say X: (for what follows).
Note: if you use LVM, for whatever reason that partition needs to be "compatible"
and "boot". After creating it, you should however remove it from boot manager.
2.) Get http://www.os2site.com/sw/drivers/filesystem/dumpfs.zip
3.) Copy udumpfs.dll to \os2\dll, copy dumpfs.ifs to \os2\boot, save
\os2dump and copy os2dump.hd to \os2dump
4.) add "IFS=C:\OS2\BOOT\DUMPFS.IFS" to config.sys (C: being your boot
drive). You might need to shift around this statement. I seem to remember it
has to be the last IFS
5.) add "TRAPDUMP=R0,X:" to config.sys (without quotes)
6.) reboot
7.) do a "format X: /FS:DUMPFS" to format the dump partition
8.) reboot

Now you are basically set up to do a dump.

In order to also do a trace (for this, there is no necessity for dumping to work)
you also need to set up tracing.The trace codes are:
USBUHCD.SYS: the trace code is 224 (0xE0)
USBOHCD.SYS: the trace code is 225 (0xE1)
USBEHCD.SYS: the trace code is 226 (0xE2)

9.) add "TRACEBUF=512 /M=NW,Q,NDTI /D=ALL" to config.sys
10.) add "TRACE=ON 226" to config.sys (or "TRACE=ON 225,226" for tracing multiple drivers etc.)
11.) reboot

Now, when the system reboots and hangs, hit Ctrl-Alt-NumLock-NumLock to
initiate a system dump. Let the system dump finish.

12.) reboot, make sure you boot from a maintenance partition, CD-ROM or
alternate config.sys (without USB) so that it does not hang again
13.) Now you will need pmdf.exe to extract the trace info from the system
dump: do a "\os2\pdpsi\pmdf.exe" to open the dump formatter
14.) Do a file open on X:\ and select the dump file
15.) You can now enter commands in the command line at the very bottom of
the pmdf window. Enter ".ts c:\trace.raw" to save the trace buffer to file
"c:\trace.raw". I will need this file to have a look at the trace info. 

16.) For tracing to work, it's not necessary to take a dump if your system boots ok.
In case your system boots fine, after your system is up you can run "tracefmt.exe" to have the tracing info displayed.
Do a "file"->"safe formatted ..." to have the trace info saved in ASCII format. Attach this file
to your bug report.