ASPIROUT

Installation notes ------------------ Unzip the archive into a directory of your choice. Run INSTALL.CMD to start the "Device Driver Install" program. When prompted, select your chosen directory as the Source directory and the root of your Boot drive as the Destination directory. This will then allow you to select whether to install ASPIROUT.SYS and/or the optional OS2ASPI.DMD update. The latter only fixes one minor bug. You then need to reboot before the driver can be used. Uninstallation notes -------------------- Delete the "DEVICE=x:\OS2\BOOT\ASPIROUT.SYS" statement from CONFIG.SYS and delete the file x:\OS2\BOOT\ASPIROUT.SYS, substituting your boot drive for x: Delete the contents of the directory where you originally unzipped the archive. History ------- ASPIROUT V1.1 Beta 10 --------------------- Changed ASPIROUT to attempt to cancel any outstanding commands when an application using the ASPI interface shuts down. This may prevent Ring 0 traps which take the whole system down. Nevertheless, programmers should use a pair of DosEnterMustComplete() / DosExitMustComplete() calls around the IOCTL call to ASPIROUT. Changed ASPIROUT default to enable 'Application fix' mode. This improves performance significantly with badly coded applications. To disable this, add /D to the ASPIROUT.SYS line in CONFIG.SYS and reboot, or run "ASPIOPT /D". To re-enable it, use /E instead of /D. Notes for programmers: Somebody complained to me that CDRDAO2 was running slowly, which indeed it was when I tested it here. This resulted in the implementatin of 'Application fix' mode. I used ASPIDBUG to check what CDRDAO2 was doing and found out that it was not using SRB_Post, so it must be polling and was therefore doing at least 1 DosSleep(1) for every command sent to ASPIROUT. This is not the correct way to do things and reduces throughput significantly. You should only not use SRB_Post on commands which take a significant time and where you want the application not to be blocked in the driver. Here is what happens inside ASPIROUT: 1) With SRB_Post and semaphore set: driver returns control to the app. and posts the sem. when the command is complete. App. should block on the event sem. or on a muxwait which includes the event sem. 2) With SRB_Post and no semaphore set: the app. is blocked in the driver until the command is complete. 3) Without SRB_Post: the driver returns control to the app. which has to poll the 'done' flag somehow. If you use 'Application fix' mode, calls without SRB_Post are forced into situation 2) as just described. So, CDRDAO2 should be using SRB_Post and not polling the 'done' flag. ASPIROUT V1.1 Beta 9 -------------------- Fixed major deadlock problems introduced in Beta 7 and made worse in Beta 8. Fixed weird trap problems with some applications. Added ASPIOPT utility to enable dynamic switching of "Application fix" mode. ASPIDBUG now uses ASC-NUM.TXT to decode Sense Code errors. ASPIROUT V1.1 Beta 8 -------------------- ASPIDBUG now looks for OP-NUM.TXT in the same directory as ASPIDBUG.EXE to make the command decode work properly. Minor improvements to ASPIDBUG display. Fixed a race condition between ASPIROUT and ASPIDBUG under certain circumstances. ASPIROUT V1.1 Beta 7 -------------------- Fixed SRB_Busy problems on device Reset command. Fixed Extended Inquiry data and Extended Device Type data. Removed potential hangs in the kernel resulting in unkillable processes. Improved error checking and sanitisation of user supplied parameters to prevent problems in OS2ASPI. Added OS2ASPI.DMD to distribution to fix bugs in the Extended Inquiry and Extended Device Type commands. This should be copied over the existing one in \OS2\BOOT on your boot drive (take a backup first). Improved debugging interface and debug monitor to show much more information. There is now a pre-call and a post-call display, single and multi-stepping, log to file. ASPIROUT V1.1 Beta 6 -------------------- Removed the "Interface Busy" error when trying to set the data buffer or semaphore more than once. This is now handled gracefully, and fixes problems with CDRECORD etc. complaining about buffer problems - this was caused by it trying to set the buffer twice (why?), which was previously prohibited. Added a debugging interface and simple debug monitor (ASPIDBUG.EXE) so that users can see which commands are getting sent to the driver. Increased the number of device instances from 4 to 64. ASPIROUT V1.1 Beta 5 -------------------- Fixed SRB_Busy problems when not using SRB_Post. Fixed performance problems when not using SRB_Post. Fixed Abort and Reset commands when using SRB_Post. Fixed permanent Interface Busy error. Increased the number of device instances from 2 to 4. ASPIROUT V1.1 Beta 4 -------------------- More backwards compatibility bugs fixed. Initialisation now fails silently if OS2ASPI.DMD is not loaded, rather than stopping the boot process with a prompt. Notes for programmers: 1) The SRB size validation was too stringent previously, causing needless error reporting. 2) Note 1 for Beta 3 is now wrong. If you call category 0x92 function 4 to specify the data buffer, this will always be used in preference to the data pointer field in the SRB. This is the opposite way to Beta 3. 3) The IOCTL return codes are as follows to give better reporting of what the problem is when something goes wrong: Unknown SRB command 0xFF20 Unable to access data buffer 0xFF21 Interface busy 0xFF22 Unable to access Abort SRB 0xFF23 4) Attempting to specify the semaphore or data buffer more than once or issuing multiple simultaneous commands on the same file handle will now cause an "Interface busy" error. ASPIROUT V1.1 Beta 3 -------------------- Due to bugs in some applications and a bug in OS2ASPI.DMD, the code has had to be rewritten slightly to provide better backwards compatibility with the old ASPIROUT. Notes for programmers: 1) Note 1 for Beta 2 is now wrong. If you call category 0x92 function 4 to specify the data buffer, the data buffer is now locked immediately again, as per the original ASPIROUT. You DO need to check the data returned by this function to make sure the data buffer was locked. The data pointer field in the SRB still takes priority if both are used. 2) Attempting to specify the semaphore (category 0x92 function 3) multiple times will now cause an invalid parameter error. 3) Attempting to specify the data buffer (category 0x92 function 4) multiple times will now cause an invalid parameter error. 4) Attempting to issue mutiple simultaneous commands on the same file handle will now cause an invalid parameter error. 5) Let me re-iterate... a) it is better not to use the data buffer - use the data pointer field in the SRB. b) it is better not to use the semaphore - let the application block in the driver until the function is complete. ASPIROUT V1.1 Beta 2 -------------------- OK, I think all the code is now written and working properly. Multiple processes should now be able to access ASPIROUT simultaneously - at the moment, this is limited to 2 processes which should show up any bugs. This will be increased to a larger number (probably 64) for the final version. As before, please report anything good or bad. I am especially interested in people trying to stress test this driver! Notes for programmers: The IOCTL interface has been altered to be slightly more logical and easier to use, whilst retaining backwards compatibility. 1) The SCSI data buffer can now be specified using the data pointer field in the SRB - you do NOT need to call category 0x92 function 4 any more to set this up. If you do call this function, the memory is not locked until a command is issued, so the data returned by this function is always 0 to indicate success (previously, it was the return value of the Lock operation), meaning you needn't check it any more. The data pointer field in the SRB takes priority if both are used. 2) The semaphore as set by calling category 0x92 function 3 is now also optional. The driver will block the application until the function completes if this is not called. 3) If you do use the semaphore method, you MUST not issue multiple calls from the same application on the same file handle before the original call has completed. 4) You can open the device multiple times from the same application. 5) The sharing mode you specify on DosOpen is forcibly ignored by the driver. 6) Category 0x92 function 1 now returns the version number of the driver in the IOCTL data buffer. The low byte is the minor version number (0x0A) and the high byte is the major version number (1) for Version 1.1 Beta 2. Previous versions didn't support this call, so will return an error. 7) All pointers and buffers are now checked for validity. This should stop the driver cusing a ring 0 trap of the system if the application feeds it a duff address. ASPIROUT V1.1 Beta 1 -------------------- This project is a complete rewite of the ASPIROUT device driver originally written by Daniel Dorau. You should refer to the documentation in that package for details on how to use it. The original version had many bugs and limitations, as I discovered when trying to rewrite it - the bugs have hopefully been fixed and the limitations will be addressed in future versions. This Beta is to confirm that everything still works as expected with existing applications. To install it, just copy the file ASPIROUT.SYS to somewhere on your hard disk (preferably not over the old copy, just in case you need to revert to that version) and edit your CONFIG.SYS file's DEVICE=x:\path\ASPIROUT.SYS statement to point to this copy instead of the old one. By default, the device driver does not announce itself on loading (why do people write drivers that do that?) - you should use the /V switch on the DEVICE= line if you wish to see it. The driver is also Resource Manager aware, not that it makes a lot of difference for this driver. Please note that the driver is capable of crashing your system (ring 0 trap - screenful of register values) if something is buggy (although I think I have protected against this), and that you should make sure any critical data is saved before experimenting. If you do get a crash, please look at the trap screen - if it says "Exception in device driver: ASPIROU$", then I need to know about it. A note of the register values from the trap screen would be appreciated - at the very least, you must report the CS:EIP value. Any feedback either good or bad is welcomed to me at aspirout2@orac12.clara34.co56.uk78 (remove the numbers from the RHS) Thanks, Paul Ratcliffe aspirout2@orac12.clara34.co56.uk78 (remove the numbers from the RHS)