STB Suite

Using BAM in your program


BAM – the Bus Analyzer Module (included with the STB Suite) – is a piece of the STB Suite that is used daily by our in-house development programmers. It is so useful, to verify our programs as we write them, to watch that the proper command is being sent, the expected data is being returned, etc. The interactive, gui-based BAM is super useful!

Using BAM in a program

But there is a whole other “version” of BAM available for programmers who are writing their own programs, tests, or utilities. This consists of the BAM function calls in the Developers Toolbox (DTB) api.

Functions are available to completely control BAM programmatically. You can select the device(s) to monitor, the phases to capture, start and stop traces – all from within your programs.

Here are a few examples of what is possible –

  1. Start a BAM capture when any event occurs – on a drive error, when a certain command is executed. Any time you need to capture I/O you can.
  2. Stop the BAM capture when an event occurs. You can start the BAM trace, then stop it and save the trace when an event occurs. Have BAM running, stop and save the trace when an error occurs – now you have a record of all of the I/O leading up to the error.
  3. Put in an option to help you troubleshoot your users problems. If you are writing a utility or test you can put in a user option to grab a trace, save it, send it back in a report, etc.

An example

Here is a simple example of how to use the BAM api functions, taken from the DTB reference documentation:

Appendix C – Using BAM from a Program


Beginning in the STB Suite version 8.1 the Developers Toolbox (DTB) API includes functions to use the Bus Analyzer Module (BAM) from within an application program.

This article will describe the DTB functions used to control BAM and show an example of a simple program to capture a trace and save it to a file.


The BAM-specific DTB functions

The DTB api calls to control BAM are as follows:

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();

enum _BAM_FILE_TYPES {eBAMFileRaw, eBAMFileExcel };


int VCSCSIBAMsaveCapture(BYTE *fname,eBAM_FILE_TYPES eSaveType);


In short these functions are used to define the device which you wish to capture bus traffic to/from, which BAM phases you wish to capture, the size of your capture buffer, and flags such as STOP_ON_BUFFER_FULL to control trace capture behavior.

Once a capture session as been defined it is a simple matter to call one function to start the capture, another function to stop the capture, and finally a function to save the capture data to either raw BAM type data or to an Excel-type (comma delimited) text file.

A programming example

The following code snip shows how to control a complete BAM capture session via DTB:



Capturing BAM trace data for any device on your test system is simply a matter of a few basic DTB function calls. If you are interested in using BAM in your own programs we encourage you to look here at the DTB documentation –

And to feel free to contact us to discuss BAM, the BAM DTB API, or any other part of the STB Suite. Live training and support is part of your Performa coverage – we’d be happy to tailor an online meeting to help you accomplish your goals.

You can contact us online: Request Online Meeting or call 720-249-2641 to set up a meeting.