busTRACE This WEB page comes from the busTRACE 9.0 User's Manual. (Table of Contents)

Previous Topic Next Topic
 

This section describes the Defect Analysis configuration options available within busTRACE. Whenever you stop the busTRACE capture, or when you load a busTRACE capture file, busTRACE will scan through all of the captured I/Os and perform the specified defect checks. If all options are disabled, no defect checks are performed.

SCSI Software Defects

Check Direction Bits

With this defect check enabled, busTRACE will scan through the captured SCSI Request Blocks (SRBs), or SCSI Pass Through requests (SPTI), looking for any direction bit errors. When software submits an SRB or SPTI request, it specifies the direction of the data transfer. For an SRB, the flags are defined as:

  • SRB_FLAGS_DATA_IN - Indicates data will be transferred from the device to the system
  • SRB_FLAGS_DATA_OUT - Indicates data will be transferred from the system to the device
  • SRB_FLAGS_NO_DATA_TRANSFER - Indicates no data transfer with this request

For a SCSI Pass Through request, the flags are defined as:

  • SCSI_IOCTL_DATA_IN - Read data from the device
  • SCSI_IOCTL_DATA_OUT - Write data to the device
  • SCSI_IOCTL_DATA_UNSPECIFIED - No data transferred

If busTRACE detects that the direction bits are incorrect, we will flag this as an error. For example, if a SCSI Pass Through request is submitted, and the CDB is set as Test Unit Ready, and the direction bits are NOT set to SCSI_IOCTL_DATA_UNSPECIFIED, we will flag this with an error. Since Test Unit Ready does not transfer any data, the direction bits should be set to indicate no data transfer.

Any direction bit error reported would indicate a bug in the software / driver that submitted the SCSI Request Block or SCSI Pass Through request.

Check Data Buffer

With this defect check enabled, busTRACE will scan through any captured SCSI Pass Through requests (SPTI) looking for any data buffer errors. Within each SCSI Pass Through structure, a data buffer pointer (or offset) is provided. The data value should be zero for non-data transfers and non-zero for expected data transfers. If busTRACE sees a conflict, we will flag this as an error.

Check CDB Length

Command Descriptor Blocks should be 6, 10, 12, or 16 bytes in length. With this defect check enabled, if busTRACE detects that the CDB Length provided is invalid, we will flag this as an error.

CDB Database

Check CDB Errors

The busTRACE CDB decoding engine will highlight with a red background any CDB field or any data in/out field that shows a bug. This could be a software bug (e.g. invalid field set in CDB) or a firmware bug (e.g. invalid return data). With this defect check enabled, busTRACE will red-flag any CDB where an error is detected.

Check CDB Warnings

This field is similar to the Check CDB Errors option above. The difference is that this defect check will flag all warnings that it sees. A warning is a behavior on the part of the drive that is not necessarily an error, but something that could be improved upon. With this defect check enabled, any CDB warnings will be yellow-flagged on screen.

Additional CDB Checks

Check Transfer Length (Successful I/Os)

With this defect check enabled, busTRACE will check the amount of data transferred against the amount of data busTRACE expected to be transferred (for succesful I/Os).

The best way to describe what this defect check does is by way of example. Let's use a simple Inquiry CDB as our example. In this test case, we are issuing a CDB with a 240 (F0h) byte buffer. We also specify F0h in the CDB itself so that our device knows the maximum number of bytes we would like transfer. Here is the CDB that we send:

For our example, we will use the SanDisk Cruzer Micro flash drive. Here is the return data:

Note that the CDB allowed for a maximum of 240 bytes and the SanDisk device returned 36 bytes. The device itself is telling us how many bytes are valid. We look to the "Additional Length" field in the return data. The device is returning 31 in this field. If you add 5 to that (for the # of bytes preceding and including the Additional Length), you come up with 36 bytes.

So far we have described how software lets the device know the maximum amount of data to transfer (e.g. Allocation Length). We have also described how the device lets the software know how much data it transfers (e.g. Additional Length). The port/miniport driver also provides a means for letting busTRACE know exactly how many bytes were transferred. In a SCSI_REQUEST_BLOCK request and a SCSI_PASS_THROUGH request, the DataTransferLength field is defined:

Indicates the size in bytes of the data buffer. If an underrun occurs, the miniport driver must update this member to the number of bytes actually transferred.

As Microsoft's specifications clearly state, the miniport driver must update this member to the number of bytes actually transferred. Getting back to our Inquiry example above, the DataTransferLength field would be set to 240 (F0h) when the request is submitted. When the request is finished, the miniport driver should return 36 (24h) in the DataTransferLength.

By looking at the DataTransferLength field, the CDB, and any data in/out, busTRACE is able to determine how many bytes of data should have been transferred. If the amount of data busTRACE expects to have transferred doesn't match the DataTransferLength (as set by the port/miniport driver), busTRACE will flag this as a defect. This would either indicate a port/miniport driver bug (more likely) or a bug in the device firmware.

Some engineers may prefer to disable this defect check. The reason for this is that many port/miniport driver do NOT follow the requirement that it set the DataTransferLength to the actual amount of data transferred. This is true, for example, of most ATA, ATAPI, Serial ATA, Serial ATAPI drivers. Instead of returning the amount of data transferred in the DataTransferLength field, they are simply leaving the field unchanged. This could be caused by the driver's inability to know exactly how many bytes were transferred (i.e. hardware limitation).

Most other miniport drivers properly report the number of bytes transferred. Enable this option only if you are working with miniport drivers that handle this properly.

Although we have done our best to explain this defect check above, we do realize that it is a rather complex topic. Please feel free to contact us if you have any questions.

Check Transfer Length (Failed I/Os)

This setting is identical to the one above except it applied to I/Os that fail. This setting has its own check because some miniport drivers do properly return the the data transfer length for successful I/Os, but do not properly return it for any failed I/O.

Check Missing Sense Data

With this defect check enabled, if a device returns a check condition with no sense data, busTRACE will flag this as an error.

Check External Errors

External applications, such as our busCHECK application, can store additional defect information in the busTRACE capture file. With this defect check enabled, busTRACE will flag and notify you of any external errors.

The options available here are also used by busCHECK.

See Also: