STB Suite

Bus Analyzer Module functions in Developer Toolbox (DTB) API

There are six new BAM-related functions in DTB version 8.1!

They are:

int VCSCSIBAMconfigure(long BufSize, long PhaseSize, int Flags, int Phases);
int VCSCSIBAMclearBuffer();
int VCSCSIBAMdrive(int ha, int target, int lun, int capture);
int VCSCSIBAMstartCapture();
int VCSCSIBAMstopCapture();
int VCSCSIBAMsaveCapture(CString *fname);

General Use of the BAM function


The order of operation to control the capture of a BAM trace in a DTB-enabled application is as follows:

  1. Configure BAM
  2. This step will define which phases will be captured, what size the capture buffer should be, how much data in a data phase will be recorded, and any operational option flags such as “Stop on Buffer Full”

    Use the function int VCSCSIBAMconfigure(long BufSize, long PhaseSize, int Flags, int Phases);
    with the following parameters:

    BufSize is the capture buffer size in MB.
    PhaseSize is the amount of data to record, in bytes
    Flags can be any combination of or’d values of:
    1 = Stop Capture on Buffer Full
    2 = Stop Capture on Bus Reset
    4 = Immediately clear the capture buffer

    Phases can be any combination of or’d values of:
    #define CDB_PHASE        0x00000001  // cdb bytes
    #define SENSE_PHASE      0x00000002  // sense data
    #define OK_PHASE         0x00000004  // command complete
    #define DATA_IN_PHASE    0x00000008  // data in bytes
    #define DATA_OUT_PHASE   0x00000010  // data out bytes
    #define ATA_PHASE        0x00000020  // ATA task file command
    #define ATA_STATUS_PHASE 0x00000040  // ATA task file response
    #define ATP_PHASE        0x00000080  // ATA pass through structure
    #define SPT_PHASE        0x00000200  // SCSI Pass through struct
    #define SRB_PHASE        0x00000400  // SRB structure
    #define SRB_STATUS_PHASE 0x00000800  // srb status byte
    #define NT_STATUS_PHASE  0x00004000  // nt status

    Passing a value of 0 for the phases parameter will select the default phases to capture, which are:

  3. Define what drive I/O to capture
  4. Use the function  int VCSCSIBAMdrive(int ha, int target, int lun, int capture);
    To define what drive to capture I/O from, and the capture parameter defines whether to set the trace to capture or not capture I/O once the trace capture is started.
    Set capture =  1 to turn on capture for this device.

  5. Start the capture
  6. Note: You may want to clear the capture buffer before starting a new capture, using the function VCSCSIBAMclearBuffer();

    Use the function int VCSCSIBAMstartCapture();
    To begin capturing

  7. Stop the capture
  8. Use the function int VCSCSIBAMstopCapture();
    To stop capturing.

  9. Save the trace
  10. Use the function int VCSCSIBAMsaveCapture(CString *fname);

    To save the captured trace to your specified file name.

    Note: Trace data will be stored in the new BAM version 8.1 data format. You will not be able to read it using BAM version 2 or below.

    Some Specific Items

    • The DTB BAM functions allow I/O to/from a specified drive to be captured and saved.
    • At present there are no DTB BAM functions that analyze BAM data
    • Captured data is viewed by using BAM version 8.1, using the File->Open menu.
    • Once you have the capture file open in BAM you can analyze it, save it out as a CSV text file, etc.