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

Previous Topic Next Topic
 

busTRACE 10.0 includes an application that allows you to send any Command Descriptor Block (CDB) to a storage device. For example, you can use this feature to quickly send an Inquiry command to a device and see how it responds. To gain access to this application, simply run the busTRACE Start Menu and choose the Send a single CDB to a storage device option.

The application itself is broken up into four sections: Device List, List of CDBs, Properties, and the I/O Details.

Device List

In the upper left of the application, a list of all devices that busPROBE has detected will appear. Simply click on the device that you wan to send a CDB. When you select a device, the List of CDBs tree in the window directly to the right will be updated with a list of all the CDBs you can send to the selected device.

At the bottom of the device list, you will find a special User Defined CDBs option. Clicking on this option will cause our List of CDBs tree to show you only user defined execution CDBs.

The toolbar provides additional configuration options. If you are not seeing your storage device in the device tree, try changing the enumeration method.

Enumeration Method

You can configure how busPROBE will scan your system for CDB capable devices.

All Devices

This method will scan for devices using all available techniques including searching for Plug and Play (PnP) devices and non PnP devices (i.e. unclaimed devices). This is the default setting.

Plug and Play Only

This method will only scan for Plug and Play devices.

Legacy Method 1

This method will only scan for unclaimed devices using IOCTL_SCSI_GET_INQUIRY_DATA.

Legacy Method 2

This method will scan for unclaimed devices by checking each Path ID, Target ID, and LUN for a potential device.

Legacy Method 3 This method is a combination of "Legacy Method 2" and "Plug and Play Only"

List of CDBs

Once you select a device in the Device List, this window will update itself to show you a tree list of all the available commands (CDBs) that you can send to the selected device. To send the command, simply click on it and it will be sent immediately. The result of the command can then be viewed in the window directly below.

Note that if the CDB is user defined, the command is not immediately sent. We do this as a safety measure as a CDB defined by a user could do any number of destructive things. For user defined CDBs, once a CDB is selected, you will need to click on the Send CDB toolbar option

Properties

The Properties window is located in the lower left and allows you to view and edit specific application settings. The options available here will vary depending on what you are currently working on.

Application Settings

Auto Tab Selection

busPROBE shows you the results of the CDB in one of three docked panes: Error Analysis pane, CDB pane, and Raw Data pane. In its default configuration each of these three panes are grouped together. Each pane is accessible by clicking its tab.

When a CDB fails, busPROBE defaults to activating the Error Analysis pane. If it succeeds, it activates the CDB pane. If you do not want busPROBE to automatically switch tabs, based on the success or failure of the CDB, remove the checkmark from this option.

User Defined CDB Warning

busPROBE ships with a variety of built-in CDBs that you can submit to a device. By design, the CDBs that we include are non-destructive. The same cannot necessarily be said for a CDB that a user defined. Perhaps a user defined a CDB to format a hard drive, or zero a block.

By default, before letting a user defined custom CDB be sent, busPROBE will double-check with you to make sure you want to send the CDB. If you do not want busPROBE to check with you any longer, remove the checkmark from this option.

Default Sense Length

When a CDB fails with a check condition, the operating system automatically issues a Request Sense CDB. The returned sense data is visible within busPROBE. We use a default sense allocation length of 18 bytes.

Data Length Analysis

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 busPROBE.

Automatic

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

Analyze Data

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

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.

NUMA Node Settings

If your system has multiple NUMA nodes, you will also see NUMA Node Settings.

NUMA Node Memory

Specify the NUMA node where the CDB's data buffer should be allocated.

NUMA Node Processor

Specify the NUMA Node that will submit the CDB.

CDB Settings

After selecting a CDB, you will be given additional options to edit the CDB.

CDB

In this field, you can adjust any of the CDB bytes. After adjusting the CDB, you can click on the Send CDB toolbar button to submit your altered CDB to the device to see how it responds.

Buffer Length

In this field, you can adjust the buffer length. For example, if you adjust the CDB to requests a larger amount of data returned, you should adjust the size of this buffer to match.

Loop Count

This option allows you to set a loop count. busPROBE will issue the same CDB the listed number of times. The results of the last CDB sent are then shown. For example, if you want to send 10,000 back-to-back Inquiry commands to the device, simply enter 10000 in this field and click on the Send CDB toolbar option. When using the Loop Count feature, busPROBE will show you a progress indicator.

CDB Statistics

Time Sent

This field tells you the time the CDB was sent.

Execution Time

This field shows you how long it took for the CDB to execute. If you set the loop count feature, this field tells you how long it took to execute all of the CDBs.

I/O Details

When a CDB is executed, the results of that execution appear in the I/O Details pane. Three tabbed panes are available to you.

Error Analysis

If the CDB fails, the Error Analysis pane provides you details on why the I/O failed. This is similar to how our bus capture program shows you its error analysis.

CDB

The CDB pane will show you, when possible, the fully decoded CDB and any data in/out.

Raw Data

If the CDB has any inbound or outbound data, the raw data can be viewed by selecting this tab. This is similar to how our bus capture program shows you its data capture.

Data Structures

This pane will show you the SCSI Pass Through structure (i.e. SCSI_PASS_THROUGH_DIRECT) as it was sent to the port/miniport driver and as it was returned from the port/miniport driver. The SCSI_PASS_THROUGH_DIRECT structure is the structure used to submit Command Descriptor Blocks from a Windows application to a storage device.

Sharing with busTRACE

When a CDB has completed, you can choose to save the results of the I/O execution to a busTRACE capture file. Simply click on the busTRACE icon at the top of the toolbar. By saving to a busTRACE capture file, you can then share the results with other busTRACE 10.0 users. You can also get to this option from the "File" main menu.

See Also: