******************************************************************
*** 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", "Windows"
are trade marks of their respective owners.

Updates to the USB drivers


NOTE: usbcalls.dll (and usbcalls.sys) is now installed to directory \OS2\DLL (in line with the ArcaNoae package).
Please remove any usbcalls.dll/usbcalls.sym from the \ECS\DLL directory !

NOTE: usbcalls.dll might be in use by the system in which case it cannot be overwritten. You need to unlock the DLL
      from memory:
      from a command line, switch to directory \os2\dll and issue "unlock usbcalls.dll" before you attempt to overwrite
      the file. The "unlock" utility is part of every eCS installation and can be found in the \ecs\bin directory
      (or can be found on Hobbes).
      Alternatively, if you have EMX installed you can also issue: "emxupd -d usbcalls.dll" which will delete the DLL.
      You can then unzip the package which will recreate the DLL.



WARNINGS:
1) use of HPFS386.IFS: if you use HPFS386.IFS, avoid ejecting a stick from the commandline
   while the current drive letter/current directory is pointing to the stick you attempt
   to eject. Change to some other drive first before you do the eject. Otherwise, you will
   experience a trap in HPFS386.IFS.
2) if you want to wipe a large floppy stick with DFSee in order to create partitions under
   OS/2, it's a good idea to eject the stick after the wipe and to run a "rediscover prm"
   (lvm.exe /rediscoverprm) before you use lvm/minilvm to create partitions and format those.

-----------------------------------------------------------------------------------------------------------------------
changes in 10.208:
USBEHCD:
1) if TD allocation failed for an isochronous request the protection spinlock would not
   be released which would lead to a system hang (thanks Wim Brul)
2) QH was wrongly deallocated when creation of TD list or attachal of TD list would fail
   for new request
3) QH "endpoint zero in use" flag would not be reset if creation of TD list would fail
   for a new endpoint zero request
USBOHCD,USBUHCD:
1) change code to be analogue to that of USBEHCD
USBD:
1) back out change done between 10.999 and 10.200:
   do NOT cancel requests against a stalled endpoint, this will hopefully avoid the hangs
   that people are experiencing when using certain USB devices (those that on error will fail
   with a stalled endpoint) (thanks Martin Vieregg)
2) do NOT cancel requests against default address on a device attach (this is properly done
   on device detach if necessary)




changes in 10.207:
USBD:
1) reenable suspend/resume notification to USBMSD.ADD
2) changes so that the remove wakeup capability (mouse/keyboard ability to wake up a suspended system)
   is properly enabled

USBEHCD,USBOHCD,USBUHCD:
1) changes to suspend/resume code

USBMSD:
1) rework suspend/resume code in the IDC APMService call as well as in ExecuteUSBIO (set up and start a command),
   FinishUSBIO (command termination handling) and MSDCheckForService and MSDDetachDevice
  (update all these to deal with device port disconnect and reconnect on suspend/resume)
2) add tracing for suspend/resume
3) change function ProcessStatus to NOT fill uncompleted data transfer buffers with zero, if the transfer
   was not fully completed, the driver will retry the operation anyways
4) another fix to DevHelp_PageListToLin handling, only handle one scatter/gather list element at a time
   
USBHID:
1) for the /S switch, do not create a UConv object via "KernCreateUConvObject16" but let function "KernStrFromUcs16"
   create one dynamically (let the system find out which code page is in use)

USBCALLS:
1) correct case of export names for REXX functions RXUSBIRQREAD,RXUSBIRQWRITE,RXUSBCTRLTRANSFER,RXUSBDATATRANSFER

USBCOM:
1) change driver to skip any COMx and LPTx device names declared by other drivers such as COM.SYS, PSCOM.SYS and also
RDRHELP.200. The latter is part of IBM Lan Server and declares virtual devices. USBCOM.SYS would not correctly skip the
COMx device names declared by RDRHELP.200 (also exports NET$RDR$ device name) when creating a unique COMx device name.





changes in 10.206:
USBMSD:
1) leaving interrupts (globally) enabled when using DevHelp_PhysToVirt and DevHelp_PageListToLin as under
   the given conditions it is not necessary to (globally) disable and reenable them, this was done in order to
   minimize impact on devices needing a timely interrupt response (like audio devices, for example)
2) added additional tracing in order to catch problems with transmission requests not being fully
   executed (only part of the requested sectors being transferred)
3) fix a bug on computing number of successfully transferred sectors (need to use 32-bit division
   instead of 16-bit division). This would lead to endless attempts to reissue the transmission
   command if the overall amount to transfer was exactly 64 kBytes (which is also the absolute limit
   an ADD will ever be requested to transmit in one shot)
4) some minor changes and code cleanup of things that would never be executed as they would never work
   anyways
5) for people having problems opening a OpenOffice supported document from a FAT32 stick: these latest
   changes also fix the problem where older USBMSD versions would always return with error:
   "invalid parameter" on an attempt to open the document (however, copying the document from the FAT32 stick
   to a hard drive and opening it from there would work).
   I don't know why this error now went away but I assume that the fixes also fixed a problem with EA support
   (if /EAS switch is specified for FAT32.IFS).




changes in 10.205:
USBMSD:
1) fixed a serious bug that under specific conditions could lead to clipped or corrupted files.
   Unfortunately, the file size might even have been reported correctly after a write
   and no indication of an error was given to the user.
   The DDK code that this driver builds upon is unfortunately older than
   the final 10.162 version of USBMSD.ADD delivered by IBM, therefore I don't know
   if that error also exists in 10.162 or not.
2) increased buffer range for /BUFFER: switch for USB 1.x only systems / USB 1.x devices
3) prevent executing a command while another command is still in progress, this typically
   leads to problems with device detection if many are already plugged in on bootup





changes in 10.204:
USBEHCD.SYS,USBOHCD.SYS: back out changes done in 10.203, powering off ports leads
to a hang on the next boot on many systems, also EHCI BIOS handover restored to what
it was before

USBMSD:
1) on device attach, dynamically adapt the number of times to call "TEST_UNIT_READY"
   when waiting for a device to become ready,
   this should improve device attach for USB disks that might take a very long time
   until they finally become ready (spinning up the disk etc.)
2) completely rework the LOCK/UNLOCK/EJECT handling: do not issue commands
   for USB sticks/USB hard disks but instead return immediately indicating success
   (many of these devices do not properly support these commands), also
   DO NOT call IORBDone ("command processed" notification to OS2DASD.DMD/OS2CDROM.DMD)
   while a command is still executing !
3) move all segment locking from INIT_COMPLETE to INIT, the DMDs will issue IORB commands
    to the ADD already before INIT_COMPLETE
4) allow to wipe a large floppy formatted stick with DFSee and then to use lvm/minilvm to
   partition the stick under OS/2 and format the partition(s)
5) fix a trap on unplugging and/or replugging a device while a transfer is still in progress

USBEHCD,USBOHCD,USBUHCD,USBD:
1) cosmetic fix to context hook stubs: make sure that DS is set on function entry
    (should not be necessary but won't hurt either ...)

USBETHR.OS2:
1) to the better or worse: added the USB ethernet driver
   (this driver is limited to Kawasaki LSI KL5KUSB101 chip)




changes in 10.203:
USBMOUSE.SYS, USBKBD.SYS:
1) fixed a problem with /V switch (even without /V, startup message would be shown on bootup)

USBMSD:
1) update OS2CDROM.DMD callback processing so that multiple USB CD-ROM devices can actually be handled
2) skip "GetMaxLUN" command for protocol type "BulkOnly" devices if their subclass is not also "SCSI"
    ("GetMaxLUN" hangs for many devices and will prevent device attachal)
3) successfully finish the device attach phase even if no media is inserted in the CD-ROM drive
    (allows you to boot with CD-ROM drive attached but no media yet inserted)
4) implement "command queueing" (wait for issued command to finish before sending next) in order to prevent
   erroneous device behaviour
5) reduce the number of occasions where a MSD reset is driven and prevent recursive MSD resets

USBEHCD.SYS:
1) increase timeouts for BIOS handover

USBEHCD.SYS, USBOHCD.SYS:
1) for /FS switch specified, power off all ports before host controller reset



changes in 10.202:
USBD.SYS:
1) fix a trap on device attach (handling of unexpected error condition)
2) fix a potential problem when allocation of memory structure to manage
   newly inserted device fails



changes in 10.201:
USBD.SYS:
1) replace a blocking delay between Master and Companion controller
   enumeration phases with a timer routine triggered phase invocation
   this is to fix a problem on some systems that will completely
   block on bootup with the old approach of using a blocking delay

USBMSD.ADD:
1) add additional tracing
2) fix a trap on system start when tracing is enabled through config.sys
3) set default sense if requested by DMD for those cases where
   no command invocation takes place and therefore
   no sense info is generated
4) floppy drives: on processing sense data, only set "MEDIUM INSERTED" flag
   if the sense data indicates that media change has taken place
   this prevents a system block if you invoke "Lock" on a diskette drive
   that has no media inserted
5) floppy drives: change handling of lock command so that you will get a sensible
    error text instead of no visual feedback at all in case no media is inserted
6) floppy drives: chain in a "TEST_UNIT_READY" command
    (done by issuing a IOCC_UNIT_STATUS / IOCM_GET_UNIT_STATUS request)
   before any read/write transfer command if no disk insertion has yet been detected,
   this is for floppy drives that expect a TEST_UNIT_READY command
   in order to determine if media is inserted or not (drives without changeline support)
7) floppy drives: reject a read/write command for as long as no medium has yet been inserted
   this is to prevent endless looping for floppy access when opening the drives folder
   in XWorkplace

USBUHCD.SYS,USBOHCD.SYS,USBEHCD.SYS
1) fixed a trap for isochronous transfer buffer handling (properly serialize adding/removing buffers)



changes in 10.200:
USBD.SYS:
1) changes to support old and/or small USB sticks
2) serialize HC reset: reset master (EHCI) controllers first,
    then reset companion (UHCI,OHCI) controllers,
    delay resetting of HCs until most/all of the RUN statements
    in config.sys have been executed
    this is hopefully solving some device attachal problems
    for devices already attached on bootup
3) changes in controlling use of default address (address 0)


USBHID.SYS, USBD.SYS:
1) fixes to clearing a stalled pipe

USBEHCD.SYS, USBOHCD.SYS, USBUHCD.SYS:
1) increase timeout for setting device address (for slow devices)
2) per device, serialize access to endpoint zero
3) increase host controller reset time when /FS switch is used

USBEHCD.SYS, USBOHCD.SYS
1) remove port power on on host controller reset, this is supposed
   to get rid of problems where devices will not properly be detected
   if already plugged in on bootup

USBMSD.ADD:
1) changes to support old and/or small USB sticks
2) only use "MODE SENSE (10), flexible disk page" command on USB floppy drives,
    apparently many new USB sticks do not or do not properly support this command
    (and in the scope of USBMSD.ADD it's only relevant to floppy drives anyway)

USBAUDIO.SYS:
1) changes to make volume/bass/treble setting work
2) added initial tracing support (major trace code: 238)

USBCALLS.DLL:
1) added missing exports for REXX functions
"RxUsbDeviceClearFeature"
"RxUsbInterfaceClearFeature"
"RxUsbEndpintClearFeature"
"RxUsbEndpointClearHalt"



changes in 10.199:
USBMSD.ADD:
1) make drives > 65536*255*63 sectors (500 GB) work
2) do changes in 1) also for virtualized large floppy media (Windows formatted USB sticks)
3) increase timeouts for drives that take very long to resume from sleep
4) change device attach to closer match the Windows way of doing things
5) do not send REQUEST_SENSE after each TEST_UNIT_READY command
    in order to reduce the number of commands sent

USBD.SYS (,USBxHCD.SYS):
1) deal with external hubs sending more status change pipe data then they should
   (gleaned from the Linux implementation)

USBPRT.SYS:
1) change the way stalled pipes are cleared (clear transmission error to get device operational again)

USBCALLS.DLL (,USBRESMG.SYS):
1) latest updates to the interface functions (C and REXX interface)
     
-----------------------------------------------------------------------------------------------------------------------     

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

USBHID.SYS                            /V: give some information on bootup (also supported by 10.162 drivers)
                                      /S: show HID devices names (for mice and keyboards) in OS/2 HW manager

USBPRT.SYS                            /V: give some information on bootup (also supported by 10.162 drivers)
                                      /L: do all dynamic memory allocation in lower physical 16 MB (normally not necessary)
                                      /LPT : set driver name as printer name (by default name is $USBPRT) 


USBCOM.SYS                            /V: give some information on bootup (also supported by 10.162 drivers)
                                      /L: do all dynamic memory allocation in lower physical 16 MB (normally not necessary)

USBAUDIO.SYS                          /V: give some information on bootup (also supported by 10.162 drivers)
                                      /L: do all dynamic memory allocation in lower physical 16 MB (normally not necessary)


USBMSD.ADD                            /V: give some information on bootup (also supported by 10.162 drivers)
                                      /REMOVABLES:x  : specify that you intend to use up to x USB removable devices (memory sticks)
                                      /FLOPPIES:x    : specify that you intend to use up to x USB floppy drives
                                      /CDS:x         : specify that you intend to use up to x USB CD-ROMs
                                      /OPTICALS:x    : specify that you intend to use up to x USB optical drives
                                      /MAX_FLOPPY    : specify that you intend to use LS-120/LS-240 USB drives
                                      /A_USAGE:n     : n=0->do not attempt to assign drive letter A: to first floppy
                                                     : n=1->assign drive letter A: to first floppy in any case
                                                     : n=2->assign drive letter A: to first floppy but only
                                                       if no other driver (IBM1FLPY.ADD for example) is using drive letter A:
                                      /BUFFER:x      : specify max transfer buffer size in bytes (min:8192 bytes, max:61440 bytes)
                                                       it is recommended to not specify this switch unless using a USB 1.x only system
                                                       or using USB 1.x MSD devices
                                      /FIXED_DISKS:, /REMOVABLE_AS_FLOPPY, /CHS, /MS10_OFF switches removed !
                                      They are no longer needed with the contained driver.

Note: use of USBCDROM.ADD is NOT necessary to use a CD-ROM !
       You can achieve the same functionality by specifying /CDS:x switch for USBMSD.ADD.

USBMOUSE.SYS                          /V: give some information on bootup (also supported by 10.162 drivers)

USBKBD.SYS                            /V: give some information on bootup (also supported by 10.162 drivers)

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.

-----------------------------------------------------------------------------------------------------------------------

Important note: if you have problems using the USB widget from eCenter/XCenter (part of eWorkplace/XWorkplace):
You can 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.

-----------------------------------------------------------------------------------------------------------------------

Enabling Tracing and taking a trace
Many of the USB drivers support tracing. This means that operational data that allows offline error diagnosis is saved to a piece of memory
called trace buffer. Then this memory can be read, the contents formatted and saved away as a file.
The following drivers have these major trace codes:
USBUHCD.SYS:  224
USBOHCD.SYS:  225
USBEHCD.SYS:  226
USBAUDIO.SYS: 238
USBMSD.ADD:   239

1) In order to enable tracing for say major trace code 239 (USBMSD.ADD), add this to config.sys and reboot:
TRACEBUF=2048 /M=W,Q,NODTI /D=ALL
TRACE=ON 239
Note: in order to say trace 224,225 and 226 you'd enter:
TRACEBUF=2048 /M=W,Q,NODTI /D=ALL
TRACE=ON 224,225,226


2) try to reproduce any problem that you want to trace

3) once you are done, run "tracefmt.exe" which will format the collected info. Then do a File->Save Formatted and save to a file with extension .ftf
Make sure you save a FORMATTED trace and not an UNFORMATTED trace !

4) Send the .ftf file to me

Note: if your system traps once you did 1) then you need to get a replacement OS2DLR:
http://212.12.30.18/other/QS_LDR.ZIP
Read the contained readme in order to learn how to replace OS2LDR against the one contained in the package.


-----------------------------------------------------------------------------------------------------------------------

FAQ
Q: I am using the drivers from the ArcaNoae website and they work fine for me. Why should I use the drivers in this package ?
A: You shouldn't. These drivers are meant for those where the ArcaNoae drivers do not work.

Q: Can I mix the ArcaNoae drivers with the ones from the package ?
A: No you cannot, except for USBMSD.ADD. The ArcaNoae drivers have a builtin version check that will fail with the drivers
from this package. The exception (for now) is USBMSD.ADD which is an updated version that is currently under development.

Q: Can I mix different versions of drivers ?
A: No you cannot. The problems is that there are logical dependencies between USBHID.SYS and USBMOUSE.SYS/USBKBD.SYS,
between USBD.SYS and USBAUDIO.SYS/USBMSD.ADD/USBCOM.SYS/USBPRT.SYS/USBHID.SYS/USBETHR.OS2 and between USBD.SYS and
USBUHCD.SYS/USBOHCD.SYS/USBEHCD.SYS.
Putting it all together: all drivers are directly or indirectly dependent on one another.

Q: I tried your drivers but I would like to revert back to the ArcaNoae drivers. How ?
A: Just rerun the ArcaNoae USB WPI install and have it overwrite all files. Remember that you might be forced to boot from
your eCS installation CD-ROM, for example, if your USB mouse/keyboard fails with drivers contained in this package.
For this reason, it is a good idea to make backup copies of the ArcaNoae provided drivers which will allow you to copy
them back from a commandline.

Q: Why does the USBAUDIO driver come as a zip package (copied to the \MMOS2 directory) within this zip ?
A: For audio drivers it's not sufficient to just copy them to a directory and modify config.sys.
They need to be installed via the "minstall" tool.
You need to extract the USBAUDIO.ZIP file into a temporary directory, open a commandline and run "minstall /*" from within that directory.
That will properly install the USB Audio Driver. Note that the ArcaNoae drivers might add an entry to config.sys
for USBAUDIO.SYS which you will need to remove/comment out first.

Q: The ArcaNoae drivers come in a nifty WPI install package. Why don't you do the same ?
A: I am too lazy/have too little time. Just copy the zip into the root directory of your drive and do a "unzip usbdrv2xx.zip" to
have it unzip all contained files to the proper directories. You can run "unzip -lM usbdrv2xx.zip" to view the ZIPs contents first.
You will also need to manually update your config.sys if necessary (USBAUDIO is the exception see preceding question).

Q: So what's the deal with the contained USBMSD.ADD ?
A: It's an updated driver that will allow you to seamlessly use Windows formatted USB sticks (provided that you also have the
proper filesystem installed, for example FAT32.IFS if your Windows formatted stick was formatted with FAT32).
Explanation: Unless you explicitely partition it, Windows will format a USB stick as a "large floppy".
That means, it is not partitioned and will resemble the media layout of a floppy disk (therefore the name: "large floppy").
Sticks formatted in this way are not supported by IBM version 10.162 of USBMSD.ADD
even when you specify the /REMOVABLE_AS_FLOPPY switch (which is no longer necessary with this updated driver).
All partitioned USB media (for example, media that you partitioned under OS/2) will continue to work as before.

Q: How do I change a large floppy formatted stick to a partitioned stick ?
A: Use DFSee to wipe the first sectors of the stick (Mode=FDISK -> Wipe start of disk to ZERO).
USBMSD.ADD will detect this and will turn off large floppy media support and
instead will treat the media as a media that is to be partitioned. Eject the media (by running eject.exe X: if X: is the drive letter)
and do a "Refresh Removable Media" (by double clicking the corresponding icon or by running lvm.exe /rediscoverprm from a command line).
You can then use lvm.exe or minilvm.exe to partition the media. Once you have done this you can format the just created partition(s).

Q: What's the drawback with USBMSD.ADD ?
A: It's under development. In contrast to the IBM provided driver version 10.162 it can also not handle multi-LUN devices
(example of a multi-LUN device is a USB cardreader with multiple slots). Multi-LUN support is still on the todo list.

Q: How does USBRESMG.SYS and USBCALLS.DLL differ from the drivers from Wim Brul ?
A: USBRESMG.SYS and USBCALLS.DLL match the latest drivers from Wim Brul. If Wim's drivers work for you,
these 2 should also work for you.

Q: What is the /L switch of USBCOM.SYS,USBPRT.SYS,USBAUDIO.SYS good for ?
A: The host controller specifications (UHCI,OHCI,EHCI) mandate that a host controller shall be able to address physical
memory with 32-bit addressing, for EHCI it is optional to support physical addresses up to 64-bit.
However, (older ?) NVIDIA host controllers only supported 31 bits of physical addresses (at least when accessing
management structures that are placed into memory). The /L switch will allocate below the 16 MB physical address line
(therefore 24 address bits are sufficient) for all memory that the drivers allocate dynamically.
It is highly unlikely you will ever need this switch but if you have continued data transmission failure you might want
to try these switches.



