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

Previous Topic Next Topic
 

This section describes the I/O Handling configuration options available within busTRACE.

General Settings

Perform automatic data corruption analysis when capture stops

Place a checkmark on this option to configure busTRACE to automatically perform a data corruption analysis each time you stop the capture process.

Report underruns as errors

An underrun occurs when a device transfers less data than what is available in the data buffer. An overrun occurs if a device wants to transfer more data than is available in the data buffer. Unfortunately, the SCSI_REQUEST_BLOCK structure is defined to return a SRB_STATUS_DATA_OVERRUN value in the SrbStatus field whether it's a data underrun OR a data overrun. The subsequent Irp status would be STATUS_BUFFER_OVERFLOW.

Data underruns are usually not error conditions while data overruns are always error conditions. This presents a problem for busTRACE since one status code represents both conditions. By default, busTRACE will try and detect if it's an underrun or overrun. If the checkmark is left disabled on this option (the default), we will filter out any underrun conditions and not report them as an error. If this checkmark is set, whenever the SrbStatus value is set to SRB_STATUS_DATA_OVERRUN, we will always report it as an error.

Let's give an example as to why underrun conditions are normally not a fatal error. Let's assume that you send a 240 byte buffer sent with an Inquiry CDB. Let's assume the device only has 36 bytes of Inquiry data. In this example, we have an underrun condition but it is not an error. In fact, this is quite common especially when dealing with Inquiry CDBs. In order for busTRACE to not confuse you, we default to not reporting any underrun condition as an error.

NOTE: This option only applies to SCSI Request Blocks (SRBs).

Track mouse movements over interleaved I/O activity

If busTRACE is configured to show you interleaved I/O activity, leaving a checkmark on this option will cause busTRACE to highlight the point where the I/O starts (i.e. going down the I/O stack) as well as where the I/O finishes (i.e. going up the I/O stack). A gradient background color is used to visually show you where the I/O starts, where it finishes, and what other I/O activity might be occurring in between.

This feature is only available when you have busTRACE configured to sort I/O activity on the Counter column in ascending order (the default setting).

Show single interleave indicator for lifetime of one I/O request

For some I/O activity, such as MPIO or some USB activity, the same I/O Request Packet (IRP) is used and captured multiple times. For example, with MPIO, you may have a IRP sent to a virtual device and then that same IRP sent to a physical device. Once the physical device IRP completes, the virtual device IRP completes.

This option configures busTRACE as to how you want the interleave indicators draw. With this option disabled, if you have the same IRP being used for a virtual and physical device (as one example), you would see something like this:

In the above example, you can see how I/O counter 778 is wrapped by I/O 777. You can also see by the "IRP Pointer" value, this is the exact same IRP.

If you take this exact same example, but this time place a checkmark next to this "Show single interleave indicator for lifetime of one I/O request" setting, you will see this:

In the above example, we notice that the "Interleave" column now only shows one indicator line for the one IRP that is being processed. The red indicator for I/O #778 allows you to see the wrapped nature of the captured I/O request.

Understanding how the same IRP is sent from one device stack down to another device stack is a complex topic. The above example is its simplest form but can get far more complex, particularly with MPIO. If you are uncertain, you can simply leave this option disabled and you will see an arrow indicator for each individual I/O.

Always export data values as decimal to CSV or XML files

Because spreadsheet programs tend to not understand hex data values, selecting this option will ensure that we always export data values to decimal to CSV or XML files.

Enable multi-core optimizations

busTRACE detects if your system has multiple cores / processors and will utilize the multiple processors during time consuming tasks, such as when busTRACE analyzes all of your captured I/Os for defects once you stop the capture process. You can remove the checkmark from this option if you want to disable this option. Note that if your computer only has a single core (i.e. only one CPU), then this option will be disabled.

Data Length Analysis (CDB Decoding)

When a Command Descriptor Block is sent to a device, the device might not transfer the full data buffer. As an example, you can send an Inquiry CDB through Windows with a 252 byte buffer, but the device may only return 36 bytes of valid data. This is an example of an underrun where the device returns less data than what was specified in the data buffer. It is not an error and happens quite regularly.

Windows clearly defines that port/miniport drivers are supposed to let drivers and applications know the actual amount of data transferred. Unfortunately, a variety of such drivers do NOT properly return the amount of data transferred. Using our Inquiry example above, the port/miniport driver should return that only 36 bytes of data were transferred. However, it is common to see the port/miniport driver incorrectly return that 252 bytes of data were transferred.

This poses challenges for our CDB decoding engine as we need to know how much of the data, in the captured data buffer, is actually valid. Since we cannot fully trust the data transferred length (as returned by the port/miniport driver), we have provided several options to allow you to configure busTRACE.

Automatic - Let busTRACE determine data length (default setting)

Selecting this option lets busTRACE determine how best to determine how much data is actually valid to decode.

Analyze Data - Use length determined by analyzing data buffer

Selecting this option will cause busTRACE to, where possible, look at any CDB values and/or data headers to let the device tell us how much of the data is actually valid.

Port/Miniport - Use length returned by port/miniport driver

Selecting this option tells busTRACE to use the amount of data transferred as reported by the port/miniport driver. If your port/miniport driver is not properly returning this value, you may see the CDB decoded with more data than was actually transferred.

See Also: