This web page refers to our older busTRACE 7.0 which is no longer shipping. Click here for details on our latest generation busTRACE software.
This WEB page comes from the busTRACE 7.0 User's Manual. (Table of Contents)
busTRACE 7.0 includes the ability to scan for certain software defects in the data structures that we capture. This is different than the defects we can detect and report in Command Descriptor Blocks. This feature is currently limited to analyzing SCSI Request Blocks as well as SCSI Pass Through requests.
You can enable or disable this feature. Our default mode is to have it enabled. When you stop the capture sequence, if busTRACE detects an error, you will immediately receive a notification message:
busTRACE is informing you that one or more software defects were detected in your captured SCSI Request Blocks and/or SCSI Pass Through structures. You can use the find next/previous bookmarks feature to move between the defective requests. A user comment is attached to each defective requests providing full details as to why busTRACE thinks the request is wrong.
Most of the checks that busTRACE performs deal with the direction bits within the I/O request. Even when the direction bits are not 100% correct, it is very likely that the program will run just fine. The main purpose of this feature is to assist software developers in writing their software to more fully follow the Windows specifications.
In this screenshot, busTRACE has found a defect SCSI Pass Through request. The data direction bits contradict the CDB definition.
SCSI_PASS_THROUGH and SCSI_PASS_THROUGH_DIRECT
When a user mode application submits a SCSI request, they use the IOCTL_SCSI_PASS_THROUGH request. This IOCTL instructs the port driver to send an embedded SCSI command (i.e. CDB) to the target device. The structure that is used with this IOCTL is the SCSI_PASS_THROUGH or SCSI_PASS_THROUGH_DIRECT structures. Both these structures are defined in the Windows DDK / WDK.
Embedded within the SCSI Pass Through structure is the DataIn variable. This variable can be one of three values:
SCSI_IOCTL_DATA_IN is used to indicate that data is read in from the device. SCSI_IOCTL_DATA_OUT is used to indicate that data is being written out to the device. SCSI_IOCTL_DATA_UNSPECIFIED is used to indicate that no data is transferred (e.g. a Test Unit Ready CDB). Please be aware that the definition of SCSI_IOCTL_DATA_UNSPECIFIED is more restrictive starting with the Windows Vista WDK. Prior to the Vista WDK, this flag would indicate that the direction of data transfer is unspecified.
busTRACE 7.0 honors the Vista WDK requirements and will validate that SCSI_IOCTL_DATA_UNSPECIFIED is used for CDBs that are known not to transfer data. There is a lot of legacy software that will use, for example, SCSI_IOCTL_DATA_IN with a DataTransferLength of zero. busTRACE 7.0 will flag this as an error since the software should be using SCSI_IOCTL_DATA_UNSPECIFIED.
busTRACE 7.0 is flagging this as a software defect even though the end user will not see any failure (in most circumstances). This gives the software developer an opportunity to refine their code to match the WDK requirements.