6 API Documentation

6.1 Introduction

The API documentation describes the Beagle Rosetta C bindings.

6.2 General Data Types

The following definitions are provided for convenience. The Beagle API provides both signed and unsigned data types.

typedef unsigned char        u08;
typedef unsigned short       u16;
typedef unsigned int         u32;
typedef unsigned long long   u64;
typedef signed   char        s08;
typedef signed   short       s16;
typedef signed   int         s32;
typedef signed   long long   s64;

6.3 Notes on Status Codes

Most of the Beagle API functions can return a status or error code back to the caller. The complete list of status codes is provided at the end of this chapter. All of the error codes are assigned values less than 0, separating these responses from any numerical values returned by certain API functions.

Each API function can return one of two error codes with respect to the loading of the Beagle DLL, BG_UNABLE_TO_LOAD_LIBRARY and BG_INCOMPATIBLE_LIBRARY. If these status codes are received, refer to the previous sections in this datasheet that discuss the DLL and API integration of the Beagle software. Furthermore, all API calls can potentially return the errors BG_UNABLE_TO_LOAD_DRIVER or BG_INCOMPATIBLE_DRIVER. If either of these errors are seen, please make sure the driver is installed and of the correct version. Where appropriate, compare the language binding versions (BG_HEADER_VERSION found in beagle.h and BG_CFILE_VERSION found in beagle.c) to verify that there are no mismatches. Next, ensure that the Rosetta language binding (e.g., beagle.c and beagle.h) are from the same release as the Beagle DLL. If all of these versions are synchronized and there are still problems, please contact Total Phase support for assistance.

Note that any API function that accepts a Beagle handle can potentially return the error code BG_INVALID_HANDLE if the handle does not correspond to a valid Beagle analyzer that has already been opened. If this error is received, check the application code to ensure that the bg_open command returned a valid handle and that this handle was not corrupted before being passed to the offending API function.

Finally, any API call that communicates with a Beagle analyzer can also return the error BG_COMMUNICATION_ERROR. This means that while the Beagle handle is valid and the communication channel is open, there was an error communicating with the device. This is possible if the device was unplugged while being used.

If either the I2C, SPI, MDIO, or USB subsystems have been disabled by bg_disable, all other API functions that interact with I2C, SPI, MDIO, and USB will return BG_I2C_NOT_ENABLED, BG_SPI_NOT_ENABLED, BG_MDIO_NOT_ENABLED, or BG_USB_NOT_ENABLED, respectively.

These common status responses are not reiterated for each function. Only the error codes that are specific to each API function are described below.

All of the possible error codes, along with their values and status strings, are listed following the API documentation.

6.4 General

Interface

Find Devices (bg_find_devices)

int bg_find_devices (int   num_devices,
                     u16 * devices);

Get a list of ports to which Beagle devices are attached.

Arguments
num_devices	maximum number of devices to return
devices	array into which the port numbers are returned

Return Value
This function returns the number of devices found, regardless of the array size.

Specific Error Codes
None.

Details

Each element of the array is written with the port number. Devices that are in use are OR’ed with BG_PORT_NOT_FREE (0x8000). Under Linux, such devices correspond to Beagle analyzers that are currently in use. Under Windows, such devices are currently in use, but it is not known if the device is a Beagle analyzer. Example: Devices are attached to port 0, 1, 2 ports 0 and 2 are available, and port 1 is in-use. array => { 0x0000, 0x8001, 0x0002 } If the input array is NULL, it is not filled with any values. If there are more devices than the array size (as specified by nelem), only the first nelem port numbers will be written into the array.

Find Devices (bg_find_devices_ext)

int bg_find_devices_ext (int   num_devices,
                         u16 * devices,
                         int   num_ids,
                         u32 * unique_ids);

Get a list of ports and unique IDs to which Beagle devices are attached.

Arguments
num_devices	maximum number of devices to return
devices	array into which the port numbers are returned
num_ids	maximum number of device IDs to return
unique_ids	array into which the unique IDs are returned

Return Value
This function returns the number of devices found, regardless of the array sizes.

Specific Error Codes
None.

Details

This function is the same as bg_find_devices() except that it also returns the unique IDs of each Beagle device. The IDs are guaranteed to be non-zero if valid. The IDs are the unsigned integer representation of the 10-digit serial numbers. The number of devices and IDs returned in each of their respective arrays is determined by the minimum of num_devices and num_ids. However, if either array is NULL, the length passed in for the other array is used as-is, and the NULL array is not populated. If both arrays are NULL, neither array is populated, but the number of devices found is still returned.

Open a Beagle analyzer (bg_open)

Beagle bg_open (int port_number);

Open the Beagle port.

Arguments
port_number	The Beagle analyzer port number. This port number is the the same as the one obtained from the bg_find_devices() function. It is a zero-based number.

Return Value
This function returns a Beagle handle, which is guaranteed to be greater than zero if valid.

Specific Error Codes
BG_UNABLE_TO_OPEN	The specified port is not connected to a Beagle analyzer or the port is already in use.
BG_INCOMPATIBLE_DEVICE	There is a version mismatch between the DLL and the hardware. The DLL is not of a sufficient version for interoperability with the hardware version or vice versa. See bg_open_ext() in Section 107 for more information.

Details
This function is recommended for use in simple applications where extended information is not required. For more complex applications, the use of bg_open_ext() is recommended.

Open a Beagle analyzer (bg_open_ext)

Beagle bg_open_ext (int port_number, BeagleExt *bg_ext);

Open the Beagle port, returning extended information in the supplied structure.

Arguments
port_number	same as bg_open
bg_ext	pointer to pre-allocated structure for extended version information available on open

Return Value
This function returns a Beagle handle, which is guaranteed to be greater than zero if valid.

Specific Error Codes
BG_UNABLE_TO_OPEN	The specified port is not connected to a Beagle analyzer or the port is already in use.
BG_INCOMPATIBLE_DEVICE	There is a version mismatch between the DLL and the hardware. The DLL is not of a sufficient version for interoperability with the hardware version or vice versa. The version information will be available in the memory pointed to by bg_ext.

Details

If 0 is passed as the pointer to the structure bg_ext, this function will behave exactly like bg_open(). The BeagleExt structure is described below: struct BeagleExt { BeagleVersion version; /* Feature bitmap for this device. */ int features; }; The features field denotes the capabilities of the Beagle analyzer. See the API function bg_features for more information. The BeagleVersion structure describes the various version dependencies of Beagle components. It can be used to determine which component caused an incompatibility error. struct BeagleVersion { /* Software, firmware, and hardware versions. */ u16 software; u16 firmware; u16 hardware; /* * Hardware revisions that are compatible with this software version. * The top 16 bits gives the maximum accepted hw revision. * The lower 16 bits gives the minimum accepted hw revision. */ u32 hw_revs_for_sw; /* * Firmware revisions that are compatible with this software version. * The top 16 bits gives the maximum accepted fw revision. * The lower 16 bits gives the minimum accepted fw revision. */ u32 fw_revs_for_sw /* * Driver revisions that are compatible with this software version. * The top 16 bits gives the maximum accepted driver revision. * The lower 16 bits gives the minimum accepted driver revision. * This version checking is currently only pertinent for WIN32 * platforms. */ u32 drv_revs_for_sw; /* Software requires that the API must be >= this version. */ u16 api_req_by_sw; }; All version numbers are of the format: (major << 8) | minor example: v1.20 would be encoded as 0x0114. The structure is zeroed before the open is attempted. It is filled with whatever information is available. For example, if the hardware version is not filled, then the device could not be queried for its version number. This function is recommended for use in complex applications where extended information is required. For simpler applications, the use of bg_open() is recommended.

Close a Beagle analyzer connection (bg_close)

int bg_close (Beagle beagle);

Close the Beagle analyzer port.

Arguments
beagle	handle of a Beagle analyzer to be closed

Return Value
The number of analyzers closed is returned on success. This will usually be 1.

Specific Error Codes
None.

Details
If the handle argument is zero, the function will attempt to close all possible handles, thereby closing all open Beagle analyzer. The total number of Beagle analyzers closed is returned by the function.

Get Features (bg_features)

int bg_features (Beagle beagle);

Return the device features as a bit-mask of values, or an error code if the handle is not valid.

Arguments
beagle	handle of a Beagle analyzer

Return Value
The features of the Beagle analyzer are returned. These are a bit-mask of the following values. #define BG_FEATURE_NONE (0) #define BG_FEATURE_I2C (1<<0) #define BG_FEATURE_SPI (1<<1) #define BG_FEATURE_USB (1<<2) #define BG_FEATURE_MDIO (1<<3)

Specific Error Codes
None.

Details
None.

Get Features by Unique ID (bg_unique_id_to_features)

int bg_unique_id_to_features (u32 unique_id);

Return the bitmask of device features for the given Beagle device, identified by unique_id.

Arguments
beagle	unique ID of a Beagle analyzer

Return Value
The features of the Beagle analyzer are returned. See bg_features() for details on the bit map.

Specific Error Codes
None.

Details
None.

Get Port (bg_port)

int bg_port (Beagle beagle);

Return the port number for this Beagle handle.

Arguments
beagle	handle of a Beagle analyzer

Return Value
The port number corresponding to the given handle is returned. It is a zero-based number.

Specific Error Codes
None.

Details
None.

Get Unique ID (bg_unique_id)

u32 bg_unique_id (Beagle beagle);

Return the unique ID of the given Beagle analyzer.

Arguments
beagle	handle of a Beagle analyzer

Return Value
This function returns the unique ID for this Beagle analyzer. The IDs are guaranteed to be non-zero if valid. The ID is the unsigned integer representation of the 10-digit serial number.

Specific Error Codes
None.

Details
None.

Status String (bg_status_string)

const char *bg_status_string (int status);

Return the status string for the given status code.

Arguments
status	status code returned by a Beagle API function

Return Value
This function returns a human readable string that corresponds to status. If the code is not valid, it returns a NULL string.

Specific Error Codes
None.

Details
None.

Version (bg_version)

int bg_version (Beagle beagle, BeagleVersion *version);

Return the version matrix for the device attached to the given handle.

Arguments
beagle	handle of a Beagle analyzer
version	pointer to pre-allocated structure

Return Value
A Beagle status code is returned with BG_OK on success.

Specific Error Codes
BG_COMMUNICATION_ERROR	The firmware of the specified device can not be determined.

Details
If the handle is 0 or invalid, only the software version is set. See the details of bg_open_ext() for the definition of BeagleVersion.

Capture Latency (bg_latency)

int bg_latency (Beagle beagle, u32 milliseconds);

Set the capture latency to the specified number of milliseconds.

Arguments
beagle	handle of a Beagle analyzer
milliseconds	new capture latency in milliseconds

Return Value
A Beagle status code is returned with BG_OK on success.

Specific Error Codes
BG_STILL_ACTIVE	An attempt was made to change the configuration while the capture was still active.

Details

Set the capture latency to the specified number of milliseconds. The capture latency effectively splits up the total amount of buffering (as determined by bg_host_buffer_size()) into smaller individual buffers. Only once one of these individual buffers is filled, does the read function return. Therefore, in order to fulfill shorter latency requirements these individual buffers are set to a smaller size. If a larger latency is requested, then the individual buffers will be set to a larger size. Setting a small latency can increase the responsiveness of the read functions. It is important to keep in mind that there is a fixed cost to processing each individual buffer that is independent of buffer size. Therefore, the trade-off is that using a small latency will increase the overhead per byte buffered. A large latency setting decreases that overhead, but increases the amount of time that the library must wait for each buffer to fill before the library can process their contents. This setting is distinctly different than the timeout setting. The latency time should be set to a value shorter than the timeout time.

Timeout Value (bg_timeout)

int bg_timeout (Beagle beagle, u32 milliseconds);

Set the read timeout to the specified number of milliseconds.

Arguments
beagle	handle of a Beagle analyzer
milliseconds	new timeout value in milliseconds

Return Value
A Beagle status code is returned with BG_OK on success.

Specific Error Codes
None.

Details

Set the idle timeout to the specified number of milliseconds. This function sets the amount of time that the read functions will wait before returning if the bus is idle. If a read function is called and there has been no new data on the bus for the specified timeout interval, the function will return with the BG_READ_TIMEOUT flag of the status value set and the return value will indicate the number of bytes of data that the Beagle analyzer was able to capture prior to the timeout. If the timeout is set to 0, there is no timeout interval and the read functions will block until the requested amount of data is captured or a complete packet with the appropriate bus end condition is observed. This setting is distinctly different than the latency setting. The timeout time should be set to a value longer than the latency time.

Sleep (bg_sleep_ms)

u32 bg_sleep_ms (u32 milliseconds);

Sleep for given amount of time.

Arguments
milliseconds	number of milliseconds to sleep

Return Value
This function returns the number of milliseconds slept.

Specific Error Codes
None.

Details
This function provides a convenient cross-platform function to sleep the current thread using standard operating system functions. The accuracy of this function depends on the operating system scheduler. This function will return the number of milliseconds that were actually slept.

Target Power (bg_target_power)

int bg_target_power (Beagle beagle, u08 power_flag);

Activate/deactivate target power pins 4 and 6.

Arguments
beagle	handle of a Beagle analyzer
power_mask	enumerated values specifying power pin state. See Table 6.

Return Value
The current state of the target power pins on the Beagle analyzer will be returned. The configuration will be described by the same values as in the table above.

Specific Error Codes
BG_FUNCTION_NOT_AVAILABLE	The hardware version is not compatible with this feature. Only the Beagle I2C/SPI/MDIO monitor supports switchable target power pins.

Details
This function is only available on the Beagle I2C/SPI/MDIO Protocol Analyzer. Both target power pins are controlled together. Independent control is not supported. This function may be executed in any operation mode. For the most part, target power should be left off, as the Beagle analyzer is normally passively monitoring the bus.

Host Interface Speed (bg_host_ifce_speed)

int bg_host_ifce_speed (Beagle beagle);

Query the host interface speed.

Arguments
beagle	handle of a Beagle analyzer

Return Value
This function returns enumerated values specifying the USB speed at which the analysis computer is communicating with the given Beagle analyzer. See Table 7.

Specific Error Codes
None.

Details
Used to determine the USB communication rate between the Beagle analyzer and the analysis PC. The Beagle analyzers require a high-speed USB connection with the host. Capturing from a Beagle analyzer that is connected at full-speed can cause data to be lost and corruption of capture data.

Buffering

Host Buffer Size (bg_host_buffer_size)

int bg_host_buffer_size(Beagle beagle, u32 size_bytes);

Set the amount of buffering that is to be allocated on the analysis PC

Arguments
beagle	handle of a Beagle analyzer
num_bytes	number of bytes in buffer

Return Value
This function returns the actual amount of buffering set.

Specific Error Codes
BG_STILL_ACTIVE	An attempt was made to change the configuration while the capture was still active.

Details

This function sets the amount of memory allocated to buffering data that has been siphoned off the Beagle analyzer by the host software library, but not yet read by the application. The absolute minimum and maximum values for this buffer size are 64 kB and 16 MB, respectively. The requested buffer size is matched as closely as possible by the function, and the function will keep the actual buffer size within these boundaries. For example, if 32 kB of buffering is requested, then 64 kB will actually be set. If num_bytes is 0, the function will return the amount of buffering currently set on the PC and will leave the amount of buffering unmodified. This function can be called in this fashion even when the capture is active as it does not attempt to change the configuration. It is important to note that bg_latency() and bg_sample_rate() can have an effect on the total buffer size. Therefore, to accurately determine how much buffering has been set on the PC, this call should be made after all the configurations have been set. If the application does not read data from the software library quickly enough, the entire host-side buffer will fill. For most of the Beagle analyzers this means that any new traffic on the target bus will be dropped. The Beagle USB 480 analyzer, however, has a large on-board memory buffer to solve this issue. To understand the operation of the Beagle USB 480 analyzer and how it relates to the API, please refer to Section 6.8.

Available Read Buffering (bg_host_buffer_free)

int bg_host_buffer_free (Beagle beagle);

Query the amount of read buffering available.

Arguments
beagle	handle of a Beagle analyzer

Return Value
The amount of available USB read buffering in bytes.

Specific Error Codes
None.

Details
USB read buffers are used by the analysis computer to receive the incoming data from the Beagle analyzer. Calling this function will return the amount of PC buffering available to receive data as of the last bg_*_read() call. If the amount of available USB buffering drops close to zero, capture data from the device may be lost.

Used Read Buffering (bg_host_buffer_used)

int bg_host_buffer_used (Beagle beagle);

Query the amount of used USB read buffering.

Arguments
beagle	handle of a Beagle analyzer.

Return Value
The amount of used USB read buffering in bytes.

Specific Error Codes
None.

Details
USB read buffers are used by the analysis computer to receive the incoming data from the Beagle analyzer. Calling this function will return the amount of PC buffering filled with received data as of the last bg_*_read() call. If the amount of used USB buffering comes close to the total buffer size, capture data from the device may be lost.

Communication Speed Benchmark (bg_commtest)

int bg_commtest (Beagle beagle, int num_samples, int delay_count);

Test the Beagle analyzer communication link performance.

Arguments
beagle	handle of a Beagle analyzer
num_samples	number of samples to receive from the analyzer.
delay_count	count delay on the host before processing each sample

Return Value
The number of communication errors received during the test.

Specific Error Codes
None.

Details

This function tests the host computer’s ability to process data received from the Beagle analyzer. The function commands the given Beagle analyzer to send test packets at the given frequency (see bg_samplerate()) to the host computer over the USB interface. The delay_count variable provides a way for the application programmer to add an artificial counter delay between each sample processed by the host. For large delay values, it will be harder for the host to keep up with the data rate over the USB bus, thereby leading to more communication errors.

Monitoring API

Enable Monitoring (bg_enable)

int bg_enable (Beagle beagle, BeagleProtocol protocol);

Start monitoring packets on the selected interface.

Arguments
beagle	handle of a Beagle analyzer
protocol	enumerated values specifying the protocol to monitor (see Table 8)

Return Value
A Beagle status code of BG_OK is returned on success.

Specific Error Codes
BG_FUNCTION_NOT_AVAILABLE	The connected Beagle analyzer does not support capturing for the requested protocol.
BG_UNKNOWN_PROTOCOL	A protocol was requested that does not appear in the enumeration detailed in Table 8.

Details
This function enables monitoring on the given Beagle analyzer. See the section on the protocol-specific APIs. Functions for retrieving the capture data from the Beagle analyzer are described therein.

Stop Monitoring (bg_disable)

int bg_disable (Beagle beagle);

Stop monitoring of packets.

Arguments
beagle	handle of a Beagle analyzer

Return Value
A Beagle status code of BG_OK is returned on success.

Specific Error Codes
None.

Details
Stops monitoring on the given Beagle analyzer.

Sample Rate (bg_samplerate)

int bg_samplerate (Beagle beagle, int samplerate_khz);

Set the sample rate in kilohertz.

Arguments
beagle	handle of a Beagle analyzer
samplerate_khz	New sample rate in kilohertz

Return Value
This function returns the actual sample rate set.

Specific Error Codes
BG_FUNCTION_NOT_AVAILABLE	The Beagle analyzer does not support changing the sample rate.
BG_STILL_ACTIVE	An attempt was made to change the configuration while the capture was still active.

Details
Changes the sample rate for a Beagle analyzer. The device must not currently have monitoring enabled. If samplerate_khz is 0, the function will return the sample rate currently set on the Beagle analyzer and the sample rate will be left unmodified. The Beagle USB 12 analyzer and the Beagle USB 480 analyzer do not support changing the sample rate, so it will always return the current sample rate.

Bit Timing Size (bg_bit_timing_size)

int bg_bit_timing_size (BeagleProtocol protocol, int num_data_bytes);

Get the size of the timing data for the given protocol and data size.

Arguments
protocol	enumerated values specifying the protocol of the data (see Table 8)
num_data_bytes	number of data bytes expected

Return Value
The number of timing entries to expect for given number of data bytes for the given protocol.

Specific Error Codes
None.

Details
Call this function before calling the bg_***_read_bit_timing() API functions to determine how large a bit_timing array to allocate. For BG_PROTOCOL_MDIO, this function will always return the value 32, regardless of the the value passed for num_data_bytes.

6.5 Notes on Protocol-Specific Read Functions

All read functions return a status value through the status parameter. Table 9 provides a listing of all the status codes that are shared throughout all the protocols.

6.6 I2C API

Notes

The I2C API functions are only available for the Beagle I2C/SPI/MDIO Protocol Analyzer.

I2C Monitor Interface

I2C Pullups (bg_i2c_pullup)

int bg_i2c_pullup (Beagle beagle,
                   u08    pullup_flag);

Enables, disables and queries the I2C pullup resistors.

Arguments
beagle	handle of a Beagle analyzer
pullup_flag	the function to perform as detailed in Table 10

Return Value
A Beagle status code of BG_OK is returned on success. If the value passed for pullup_flag is BG_I2C_PULLUP_QUERY, the state of the pullups is returned.

Specific Error Codes
BG_FUNCTION_NOT_AVAILABLE	The hardware version is not compatible with this feature. Only I2C devices support switchable pullup pins.

Details
Sets and queries the state of the pullup resistors on the I2C lines. Normally the pullups will be set by the host and target devices, so this function will not be used.

Read I2C (bg_i2c_read)

int bg_i2c_read (Beagle  beagle,
                 u32 *   status,
                 u64 *   time_sop,
                 u64 *   time_duration,
                 u32 *   time_dataoffset,
                 int     max_bytes,
                 u16 *   data_in);

Read packet from the I2C port.

Arguments
beagle	handle of a Beagle analyzer
status	filled with the status bitmask as detailed in Tables 9 and 11
time_sop	filled with the timestamp when the packet begins
time_duration	filled with the number of ticks that it took to read the data
time_dataoffset	filled with the timestamp when data appeared on the bus
max_bytes	maximum number of bytes to read
data_in	an allocated array of u16 which is filled with the received data

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

The function will block until the requested amount of data is captured, a complete packet with a stop or repeated start condition is observed, or the bus is idle for longer than the timeout interval set. See Section 6.4 for information on the bg_latency() and bg_timeout() functions which affect the behavior of this function. For each u16 written to data_in by the function, the lower 8-bits represent the value of a byte of data sent across the bus and bit 8 represents the ACK or NACK value for that byte. A 0 in bit 8 represents an ACK and a 1 in bit 8 represents a NACK. See Table 12 for constants that may be used as bit mask to access the appropriate fields in data_in. All of the timing data is measured in ticks of the sample rate clock. Table 12: I2C Data Mask constants Constant name Value Description BG_I2C_MONITOR_DATA 0x00ff Mask to access data field. BG_I2C_MONITOR_NACK 0x0100 Mask to access ACK/NACK field. The data_in pointer should be allocated at least as large as max_bytes. All of the timing data is measured in ticks of the sample clock.

Read I2C with data-level timing (bg_i2c_read_data_timing)

int bg_i2c_read_data_timing (Beagle  beagle,
                             u32 *   status,
                             u64 *   time_sop,
                             u64 *   time_duration,
                             u32 *   time_dataoffset,
                             int     max_bytes,
                             u16 *   data_in,
                             int     max_timing,
                             u32 *   data_timing);

Read data from the I2C port.

Arguments
common_args	see bg_i2c_read() for common arguments
max_timing	size of data_timing array
data_timing	an allocated array of u32 which is filled with timing data for each data word read

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

This function is an extension of the bg_i2c_read() function with the added feature of giving data-level timing. All of the bg_i2c_read() arguments and details apply. The values in the data_timing array give the offset of the start of each data word from time_sop. A data word includes all 8 bits of data as well as the acknowledgment bit. The data_timing array should be allocated at least as large as max_timing.

Read I2C with bit-level timing (bg_i2c_read_bit_timing)

int bg_i2c_read_bit_timing (Beagle  beagle,
                            u32 *   status,
                            u64 *   time_sop,
                            u64 *   time_duration,
                            u32 *   time_dataoffset,
                            int     max_bytes,
                            u16 *   data_in,
                            int     max_timing,
                            u32 *   bit_timing);

Read data from the I2C port.

Arguments
common_args	see bg_i2c_read() for common arguments
max_timing	size of bit_timing array
bit_timing	an allocated array of u32 which is filled with the timing data for each bit read

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

This function is an extension of the bg_i2c_read() function with the added feature of giving bit-level timing. All of the bg_i2c_read() arguments and details apply. The values in the bit_timing array give the offset of each bit from time_sop. The bit_timing array should be allocated at least as large as max_timing. Use the function bg_bit_timing_size() (in Section 6.4) to determine how large an array to allocate for bit_timing.

6.7 SPI API

Notes

The SPI API functions are only available for the Beagle I2C/SPI/MDIO Protocol Analyzer.

SPI Monitor Interface

SPI Configuration (bg_spi_configure)

int bg_spi_configure (Beagle                   beagle,
                      BeagleSpiSSPolarity      ss_polarity,
                      BeagleSpiSckSamplingEdge sck_sampling_edge,
                      BeagleSpiBitorder        bitorder);

Sets SPI bus parameters.

Arguments
beagle	handle of a Beagle analyzer
ss_polarity	sets the slave select detection to active-low or active-high bit polarity, see Table 13
sck_sampling_edge	sets data sampling on the leading or trailing edge of the clock signal, see Table 14
bitorder	sets big-endian or little-endian bit order, see Table 15

Return Value
A Beagle status code of BG_OK is returned on success or an error code as detailed in Table 30.

Specific Error Codes
BG_STILL_ACTIVE	An attempt was made to change the configuration while the capture was still active.
BG_FUNCTION_NOT_AVAILABLE	The hardware version is not compatible with this feature. Only the I2C/SPI/MDIO device supports SPI configuration.

Details
The SPI standard is much more loosely defined than I2C, MDIO, or USB. As a consequence, the SPI monitor must be configured to match the parameters of the device being monitored. If the configuration of the SPI monitor does not match the configuration of the SPI devices being monitored, the capture data from the monitor may be corrupted.

Read SPI (bg_spi_read)

int bg_spi_read (Beagle  beagle,
                 u32 *   status,
                 u64 *   time_sop,
                 u64 *   time_duration,
                 u32 *   time_dataoffset,
                 int     mosi_max_bytes,
                 u08 *   data_mosi,
                 int     miso_max_bytes,
                 u08 *   data_miso);

Read data from the SPI port.

Arguments
beagle	handle of a Beagle analyzer
status	filled with the status bitmask as detailed in Table 9
time_sop	filled with the timestamp when the data read begins
time_duration	filled with the number of ticks that it took to read the data
time_dataoffset	filled with the timestamp when data appeared on the bus
mosi_max_bytes	maximum number of MOSI bytes to fill
data_mosi	an allocated array of u08 which is filled with the data sent from the master to the slave
miso_max_bytes	maximum number of MISO bytes to fill
data_miso	an allocated array of u08 which is filled with the data sent from the slave to the master

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

The function will block until the requested amount of data is captured, a complete packet with slave select deassertion is observed, or the bus is idle for longer than the timeout interval set. See Section 6.4 for information on the bg_latency() and bg_timeout() functions which affect the behavior of this function. The data_mosi array should be allocated at least as large as mosi_max_bytes. The data_miso array should be allocated at least as large as miso_max_bytes. All of the timing data is measured in ticks of the sample clock.

Read SPI with data-level timing (bg_spi_read_data_timing)

int bg_spi_read_data_timing (Beagle  beagle,
                             u32 *   status,
                             u64 *   time_sop,
                             u64 *   time_duration,
                             u32 *   time_dataoffset,
                             int     mosi_max_bytes,
                             u08 *   data_mosi,
                             int     miso_max_bytes,
                             u08 *   data_miso,
                             int     max_timing,
                             u32 *   data_timing);

Read data from the SPI port.

Arguments
common_args	see bg_spi_read() for common arguments
max_timing	size of data_timing array
data_timing	an allocated array of u32 which is filled with timing data for each data word read

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details
This function is an extension of the bg_spi_read() function with the added feature of byte-level timing. All of the bg_spi_read() arguments and details apply. The values in the data_timing array give the offset of the start of each data word from time_sop. For SPI, a data word is considered a single byte. The data_timing array should be allocated at least as large as max_timing.

Read SPI with bit-level timing (bg_spi_read_bit_timing)

int bg_spi_read_bit_timing (Beagle  beagle,
                            u32 *   status,
                            u64 *   time_sop,
                            u64 *   time_duration,
                            u32 *   time_dataoffset,
                            int     mosi_max_bytes,
                            u08 *   data_mosi,
                            int     miso_max_bytes,
                            u08 *   data_miso,
                            int     max_timing,
                            u32 *   bit_timing);

Read data from the SPI port.

Arguments
common_args	see bg_spi_read() for common arguments
max_timing	size of bit_timing array
bit_timing	an allocated array of u32 which is filled with the timing data for each bit read

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

This function is an extension of the bg_spi_read() function with the added feature of bit-level timing. All of the bg_spi_read() arguments and details apply. The values in the bit_timing array give the offset of each bit from time_sop. The bit_timing array should be allocated at least as large as max_timing. Use the function bg_bit_timing_size() (in Section 6.4) to determine how large an array to allocate for bit_timing.

6.8 USB API

Notes

1. The USB 12 API functions are only available for the Beagle USB 12 Protocol Analyzer.

2. The USB 480 API functions are only available for the Beagle USB 480 Protocol Analyzer.

3. The first byte of the captured USB packet is the packet ID (PID). An enumeration is provided that defines all the possible PIDs which is listed in Table 16.

   Table 16: USB Packet ID definitions

   BG_USB_PID_OUT	0xe1
   BG_USB_PID_IN	0x69
   BG_USB_PID_SOF	0xa5
   BG_USB_PID_SETUP	0x2d
   BG_USB_PID_DATA0	0xc3
   BG_USB_PID_DATA1	0x4b
   BG_USB_PID_DATA2	0x87
   BG_USB_PID_MDATA	0x0f
   BG_USB_PID_ACK	0xd2
   BG_USB_PID_NAK	0x5a
   BG_USB_PID_STALL	0x1e
   BG_USB_PID_NYET	0x96
   BG_USB_PID_PRE	0x3c
   BG_USB_PID_ERR	0x3c
   BG_USB_PID_SPLIT	0x78
   BG_USB_PID_PING	0xb4
   BG_USB_PID_EXT	0xf0

4. In addition to the general read status values in Table 9, the USB read functions can also return USB specific status values. The enumerated types are listed in Table 17.

   Table 17: USB Read Status definitions

   Status Codes for USB 12 and USB 480
   BG_READ_USB_ERR_BAD_SIGNALS	Incorrect line states
   BG_READ_USB_ERR_BAD_PID	Captured packet has bad PID
   BG_READ_USB_ERR_BAD_CRC	Captured packet has bad CRC
   USB 12 Specific Status Codes
   BG_READ_USB_ERR_BAD_SYNC	Cannot find SYNC signal
   BG_READ_USB_ERR_BIT_STUFF	Bit stuffing error detected
   BG_READ_USB_ERR_FALSE_EOP	Incorrect End of packet
   BG_READ_USB_ERR_LONG_EOP	End of packet too long
   USB 480 Specific Status Codes
   BG_READ_USB_TRUNCATION_MODE	Captured packet in truncation mode
   BG_READ_USB_END_OF_CAPTURE	Capture has ended

5. Additional event information is returned by the USB read functions through the events argument. The event information is bitmask encoded with the enumerated types defined in Table 18. Refer to Section 1.1 for details on how these events pertain to the USB architecture.

   Table 18: USB Event Code definitions

   Event Codes for USB 12 and USB 480
   BG_READ_USB_HOST_DISCONNECT	Target Host disconnected
   BG_READ_USB_TARGET_DISCONNECT	Target Device disconnected
   BG_READ_USB_HOST_CONNECT	Target Host connected
   BG_READ_USB_TARGET_CONNECT	Target Device connected
   BG_READ_USB_RESET	Bus put into reset state
   USB 480 Specific Event Codes
   BG_EVENT_USB_J_CHIRP	Chirp-J detected
   BG_EVENT_USB_K_CHIRP	Chirp-K detected
   BG_EVENT_USB_SPEED_UNKNOWN	Communication speed is unknown
   BG_EVENT_USB_LOW_SPEED	Low-speed bus operation detected
   BG_EVENT_USB_FULL_SPEED	Full-speed bus operation detected
   BG_EVENT_USB_HIGH_SPEED	High-speed bus operation detected
   BG_EVENT_USB_LOW_OVER_FULL_SPEED	Low-over-full-speed bus operation detected
   BG_EVENT_USB_SUSPEND	Bus has entered suspend state
   BG_EVENT_USB_RESUME	Bus has left suspend state
   BG_EVENT_USB_KEEP_ALIVE	Low-speed keep-alive detected
   BG_EVENT_USB_OTG_HNP	OTG HNP detected
   BG_EVENT_USB_OTG_SRP_DATA_PULSE	OTG SRP data-line pulse detected
   BG_EVENT_USB_OTG_SRP_VBUS_PULSE	OTG SRP Vbus pulse detected
   BG_EVENT_USB_DIGITAL_INPUT	One or more digital inputs have changed state
   BG_EVENT_USB_DIGITAL_INPUT_MASK	Bitmask of line state for each input pin

USB 12 Monitor Interface

Read USB (bg_usb12_read)

int bg_usb12_read (Beagle  beagle,
                   u32 *   status,
                   u32 *   events,
                   u64 *   time_sop,
                   u64 *   time_duration,
                   u32 *   time_dataoffset,
                   int     max_bytes,
                   u08 *   packet);

Read data from the USB port.

Arguments
beagle	handle of a Beagle analyzer
status	filled with the status bitmask as detailed in Table 9 and Table 17
events	filled with the event bitmask as detailed in Table 18
time_sop	filled with the timestamp when the data read begins
time_duration	filled with the number of ticks that it took to read the data
time_dataoffset	filled with the timestamp when data appeared on the bus
max_bytes	maximum number of bytes to read
packet	an allocated array of u08 which is filled with the received data

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details

The function will block until the requested amount of data is captured, a complete packet with the appropriate end of packet condition is observed, or the bus is idle for longer than the timeout interval set. See Section 6.4 for information on the bg_latency() and bg_timeout() functions which affect the behavior of this function. The packet array should be allocated at least as large as max_bytes. All of the timing data is measured in ticks of the sample clock. The Beagle USB 12 analyzer is locked to a 48 MHz sample rate, thus each count measures 20.83 ns.

Read USB with data-level timing (bg_usb12_read_data_timing)

int bg_usb12_read_data_timing (Beagle  beagle,
                               u32 *   status,
                               u32 *   events,
                               u64 *   time_sop,
                               u64 *   time_duration,
                               u32 *   time_dataoffset,
                               int     max_bytes,
                               u08 *   packet,
                               int     max_timing,
                               u32 *   data_timing);

Read data from the USB port.

Arguments
common_args	see bg_usb12_read() for common arguments
max_timing	size of data_timing array
data_timing	an allocated array of u32 which is filled with timing data for each data-word read

Return Value
This function returns the number of bytes read or a negative value indicating an error.

Specific Error Codes
None.

Details
This function is an extension of the bg_usb12_read() function with the added feature of byte-level timing. All of the bg_usb12_read() arguments and details apply. The values in the data_timing array give the offset of the start of each data word from time_sop. For USB, a data word is considered a single byte. The data_timing array should be allocated at least as large as max_timing.

Read USB with bit-level timing bg_usb12_read_bit_timing)

int bg_usb12_read_bit_timing (Beagle  beagle,
                              u32 *   status,
                              u32 *   events,
                              u64 *   time_sop,
                              u64 *   time_duration,
                              u32 *   time_dataoffset,
                              int     max_bytes,
                              u08 *   packet,
                              int     max_timing,
                              u32 *   bit_timing);

Read data from the USB port.

Arguments
common_args	see