This web page refers to our older busTRACE 6.0 which is no longer shipping. Click here for details on our latest generation busTRACE software.

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

Previous Topic Next Topic
 

Within the Capture Settings pane, you can adjust the selected device's Trigger Points . The available parameters will vary depending on whether you have selected a USB device or a storage device. Some options are also not available if you are running Windows Me.

 
Sample Storage Device Trigger Points
 
Sample USB Device Trigger Points

 

In its default state, busTRACE continues capturing I/O activity until you manually stop the capture. During the capture process, if the buffer gets full, the oldest I/O activity is removed from memory to make room for any newer I/O activity. For most users, this is what you are looking for.

What do you do, however, if you do not want to sit in front of the computer waiting for some specific event to occur so that you can turn off the capture? What if you want busTRACE to automatically stop the capture as soon as any error is detected? That is where Trigger Points come in.

A trigger point is an event that, when it occurs, tells busTRACE to automatically stop the capture process.

Trigger Points (Any Device Type)

Trigger Position

When a trigger point is hit, you may want to see all I/O activity before the trigger point, all I/O activity after the trigger point, or an equal number of I/O activity before and after the trigger point. Simply choose the option that suits your needs.

  • Start: Select this option if you want to see all bus activity that occurred after the trigger point was hit, including the trigger point.
  • Middle: Select this option if you want to see an equal number of I/Os that occurred before and after the trigger point.
  • End: Select this option if you want to see all bus activity prior to, and including, the trigger point.
Trigger on any error Placing a checkmark on this option notifies busTRACE that you want a trigger point to be set if any error is detected by busTRACE.

Trigger Points (Storage Devices)

SRB status

If a SCSI_REQUEST_BLOCK IRP returns with the specified SRB Status, a trigger point will be set. The following options are available:

  • 00h - SRB_STATUS_PENDING
  • 01h - SRB_STATUS_SUCCESS
  • 02h - SRB_STATUS_ABORTED
  • 03h - SRB_STATUS_ABORT_FAILED
  • 04h - SRB_STATUS_ERROR
  • 05h - SRB_STATUS_BUSY
  • 06h - SRB_STATUS_INVALID_REQUEST
  • 07h - SRB_STATUS_INVALID_PATH_ID
  • 08h - SRB_STATUS_NO_DEVICE
  • 09h - SRB_STATUS_TIMEOUT
  • 0Ah - SRB_STATUS_SELECTION_TIMEOUT
  • 0Bh - SRB_STATUS_COMMAND_TIMEOUT
  • 0Dh - SRB_STATUS_MESSAGE_REJECTED
  • 0Eh - SRB_STATUS_BUS_RESET
  • 0Fh - SRB_STATUS_PARITY_ERROR
  • 10h - SRB_STATUS_REQUEST_SENSE_FAILED
  • 11h - SRB_STATUS_NO_HBA
  • 12h - SRB_STATUS_DATA_OVERRUN
  • 13h - SRB_STATUS_UNEXPECTED_BUS_FREE
  • 14h - SRB_STATUS_PHASE_SEQUENCE_FAILURE
  • 15h - SRB_STATUS_BAD_SRB_BLOCK_LENGTH
  • 16h - SRB_STATUS_REQUEST_FLUSHED
  • 20h - SRB_STATUS_INVALID_LUN
  • 21h - SRB_STATUS_INVALID_TARGET_ID
  • 22h - SRB_STATUS_BAD_FUNCTION
  • 23h - SRB_STATUS_ERROR_RECOVERY
  • 24h - SRB_STATUS_NOT_POWERED
Target status

If a SCSI_REQUEST_BLOCK IRP returns with the specified target status, a trigger point will be set. The following options are available:

  • 00h - SCSISTAT_GOOD
  • 02h - SCSISTAT_CHECK_CONDITION
  • 04h - SCSISTAT_CONDITION_MET
  • 08h - SCSISTAT_BUSY
  • 10h - SCSISTAT_INTERMEDIATE
  • 14h - SCSISTAT_INTERMEDIATE_COND_MET
  • 18h - SCSISTAT_RESERVATION_CONFLICT
  • 22h - SCSISTAT_COMMAND_TERMINATED
  • 28h - SCSISTAT_QUEUE_FULL
Sense data trigger

You can set a trigger point on a Sense Key, Additional Sense Code, or Additional Sense Code Qualifier. A value of xx indicates no trigger point condition. Some examples can help explain this:

02 04 01 (Sense Key 02, Sense Code 04, Sense Code Qualifier of 01)
Looking in the various CDB specifications, a sense key of 02 indicates a "Not Ready" condition. The Sense Code of 04 01 indicates "Logical Unit is in process of becoming ready."

02 04 xx (Sense Key 02, Sense Code 04, NO Sense Code Qualifier)
This value sets a trigger point if the sense key returns 02 and the sense code returns 04. The sense code qualifier is not used.

04 xx xx (Sense Key 02, NO Sense Code, NO Sense Code Qualifier)
This value sets a trigger point if the sense key returns 02. Neither the sense code or sense code qualifier is used.

CDB trigger

You can set a trigger point on Command Descriptor Blocks (CDBs). For example, you can configure a trigger point to be hit if the CDB opcode is set to 12h. A value of "xx" tells busTRACE to ignore that CDB field. Let's look at a few examples:

To set a trigger point if any Inquiry (12h) command is sent to the device, you would set the CDB Trigger as:
12 xx xx xx xx xx xx xx xx xx xx xx xx xx xx xx

To set a trigger point if any Inquiry (12h) command, with an allocation length of 24h, is sent to the device, you would set the CDB Trigger as:
12 xx xx xx 24 xx xx xx xx xx xx xx xx xx xx xx

To set a trigger point on a Test Unit Ready (00h) command, you would set the CDB Trigger as:
00 00 00 00 00 00 xx xx xx xx xx xx xx xx xx xx

If your mouse has a mouse wheel, you can scroll through the available values by scrolling the mouse wheel. Also note that you can determine what CDB offset you are positioning the cursor on by letting the mouse pointer float over the CDB for a few seconds until a tool tip appears.

Trigger Points (USB Devices)

URB Function

To send a USB request to a device, a device driver builds up a USB Request Block (URB). At the beginning of the URB is the URB header structure (_URB_HEADER). Within that header structure, there is a Function field. The Function field specifies a numerical code indicating the requested operation for the URB.

The possible URB functions are documented in Microsoft's Windows Driver Development Kit.

The default status for the URB Function trigger point is Disabled. If you want a trigger point to be hit, when a specific URB Function is sent, simply click on the drop-down arrow and choose the function. The following options are available:

  • 0000h - Select Configuration
  • 0001h - Select Interface
  • 0002h - Abort Pipe
  • 0003h - Take Frame Length Control
  • 0004h - Release Frame Length Control
  • 0005h - Get Frame Length
  • 0006h - Set Frame Length
  • 0007h - Get Current Frame Number
  • 0008h - Control Transfer
  • 0009h - Bulk or Interrupt Transfer
  • 000Ah - Isochronous Transfer
  • 000Bh - Get Descriptor from Device
  • 000Ch - Set Descriptor to Device
  • 000Dh - Set Feature to Device
  • 000Eh - Set Feature to Interface
  • 000Fh - Set Feature to Endpoint
  • 0010h - Clear Feature to Device
  • 0011h - Clear Feature to Interface
  • 0012h - Clear Feature to Endpoint
  • 0013h - Get Status from Device
  • 0014h - Get Status from Interface
  • 0015h - Get Status from Endpoint
  • 0017h - Vendor Device
  • 0018h - Vendor Interface
  • 0019h - Vendor Endpoint
  • 001Ah - Class Device
  • 001Bh - Class Interface
  • 001Ch - Class Endpoint
  • 001Eh - Sync Reset Pipe and Clear Stall
  • 001Fh - Class Other
  • 0020h - Vendor Other
  • 0021h - Get Status from Other
  • 0022h - Clear Feature to Other
  • 0023h - Set Feature to Other
  • 0024h - Get Descriptor from Endpoint
  • 0025h - Set Descriptor to Endpoint
  • 0026h - Get Configuration
  • 0027h - Get Interface
  • 0028h - Get Descriptor from Interface
  • 0029h - Set Descriptor to Interface
  • 002Ah - Get MS Feature Descriptor
  • 0030h - Sync Reset Pipe
  • 0031h - Sync Clear Stall

Note that we are using a more user friendly description than what appears in the DDK. For example, the DDK refers to the "Get Configuration" function as URB_FUNCTION_GET_CONFIGURATION. We simply dropped the "URB_FUNCTION_" portion from the text.

URB Status

To send a USB request to a device, a device driver builds up a USB Request Block (URB). At the beginning of the URB is the URB header structure (_URB_HEADER). Within that header structure, there is a Status field. The Status field is set by the USB host controller driver indicating the success or failure of the URB. This field is only valid once the URB has finished.

The possible URB status values are documented in Microsoft's Windows Driver Development Kit and/or its associated header files (i.e. usb.h).

The default status for the URB Status trigger point is Disabled. If you want a trigger point to be hit, when a specific URB status is returned, simply click on the drop-down arrow and choose the status. The following options are available:

  • USBD_STATUS_SUCCESS
  • USBD_STATUS_PENDING
  • USBD_STATUS_CRC
  • USBD_STATUS_BTSTUFF
  • USBD_STATUS_DATA_TOGGLE_MISMATCH
  • USBD_STATUS_STALL_PID
  • USBD_STATUS_DEV_NOT_RESPONDING
  • USBD_STATUS_PID_CHECK_FAILURE
  • USBD_STATUS_UNEXPECTED_PID
  • USBD_STATUS_DATA_OVERRUN
  • USBD_STATUS_DATA_UNDERRUN
  • USBD_STATUS_BUFFER_OVERRUN
  • USBD_STATUS_BUFFER_UNDERRUN
  • USBD_STATUS_NOT_ACCESSED
  • USBD_STATUS_FIFO
  • USBD_STATUS_XACT_ERROR
  • USBD_STATUS_BABBLE_DETECTED
  • USBD_STATUS_DATA_BUFFER_ERROR
  • USBD_STATUS_ENDPOINT_HALTED
  • USBD_STATUS_INVALID_URB_FUNCTION
  • USBD_STATUS_INVALID_PARAMETER
  • USBD_STATUS_ERROR_BUSY
  • USBD_STATUS_INVALID_PIPE_HANDLE
  • USBD_STATUS_NO_BANDWIDTH
  • USBD_STATUS_INTERNAL_HC_ERROR
  • USBD_STATUS_ERROR_SHORT_TRANSFER
  • USBD_STATUS_BAD_START_FRAME
  • USBD_STATUS_ISOCH_REQUEST_FAILED
  • USBD_STATUS_FRAME_CONTROL_OWNED
  • USBD_STATUS_FRAME_CONTROL_NOT_OWNED
  • USBD_STATUS_NOT_SUPPORTED
  • USBD_STATUS_INAVLID_CONFIGURATION_DESCRIPTOR
  • USBD_STATUS_INSUFFICIENT_RESOURCES
  • USBD_STATUS_SET_CONFIG_FAILED
  • USBD_STATUS_BUFFER_TOO_SMALL
  • USBD_STATUS_INTERFACE_NOT_FOUND
  • USBD_STATUS_INAVLID_PIPE_FLAGS
  • USBD_STATUS_TIMEOUT
  • USBD_STATUS_DEVICE_GONE
  • USBD_STATUS_STATUS_NOT_MAPPED
  • USBD_STATUS_CANCELED
  • USBD_STATUS_ISO_NOT_ACCESSED_BY_HW
  • USBD_STATUS_ISO_TD_ERROR
  • USBD_STATUS_ISO_NA_LATE_USBPORT
  • USBD_STATUS_ISO_NOT_ACCESSED_LATE

See Also: