Beagle Protocol Analyzer Data Sheet v3.04
| Prev: Device Operation | Table of Contents | Next: Firmware |
4 Software
4.1 Compatibility
Overview
The Beagle software is offered as a 32-bit Dynamic Linked Library (or shared object) and is compatible with 64-bit operating systems. The specific compatibility for each operating system is discussed below. Be sure the device driver has been installed before plugging in the Beagle analyzer.
Windows Compatibility
The Beagle software is compatible with Windows 2000 (SP4 or later), Windows XP (SP2 or later, 32-bit only), and Windows Vista (32-bit and 64-bit). Legacy 16-bit Windows 95/98/ME operating systems are not supported.
Linux Compatibility
The Beagle software is compatible with all standard 32-bit and 64-bit distributions of Linux with integrated USB support. Kernel 2.6 is required and the appropriate 32-bit system libraries are also required.
Mac OS X Compatibility
The Beagle software is compatible with Intel versions of Mac OS X 10.4 Tiger and 10.5 Leopard. Installation of the latest available update is recommended.
4.2 Windows USB Driver
Driver Installation
To install the appropriate USB communication driver under Windows, use the Total Phase USB Driver Installer before plugging in any device. The driver installer can be found either on the CD-ROM (use the HTML based guide that is opened when the CD is first loaded to locate the Windows installer), or in the Downloads section of the Beagle analyzer product page on the Total Phase website. Note that the drivers used for Windows 2000 are different from the drivers used for Windows XP and greater. The driver installer will install the appropriate drivers for the system.
After the driver has been installed, plugging in a Beagle analyzer for the first time will cause the analyzer to be installed and associated with the correct driver. The following steps describe the feedback the user should receive from Windows after a Beagle analyzer is plugged into a system for the first time:
Windows 2000:
The Found New Hardware dialog window will appear during installation and will disappear when the installation completes.
Windows XP:
The Found New Hardware notification bubble will pop up from the system tray and state that the “Total Phase Beagle Protocol Analyzer” has been detected. Note that installation may take a while (30-60 seconds per device).
When the installation is complete, the Found New Hardware notification bubble will again pop up and state that “your new hardware is installed and ready to use.”
Windows Vista:
A notification bubble will pop up from the system tray and state that Windows is “installing device driver software.”
When the installation is complete, the notification bubble will again pop up and state that the “device driver software installed successfully.”
To confirm that the device was correctly installed, check that the device appears in the “Device Manager.” To navigate to the “Device Manager” screen, select “Control Panel | System Properties | Hardware | Device Manager” for Windows 2000/XP or select “Control Panel | Hardware and Sound | Device Manager” for Windows Vista. The Beagle analyzer should appear under the “LibUSB-Win32 Devices” section for Windows 2000 or under the “Universal Serial Bus Controllers” section for Windows XP/Vista.
Driver Removal
The USB communication driver can be removed from the operating system by using the Windows program removal utility. Instructions for using this utility can be found below. Alternatively, the Uninstall option found in the driver installer can also be used to remove the driver from the system. It is critical that all Total Phase devices have been removed from your system before removing the USB drivers.
Windows 2000/XP:
Select “Control Panel | Add or Remove Programs”
Select “Total Phase USB Driver” and select “Change/Remove”
Follow the instructions in the uninstaller
Windows Vista:
Select “Control Panel | Uninstall a program”
Right click on “Total Phase USB Driver” and select “Uninstall/Change”
Follow the instructions in the uninstaller
4.3 Linux USB Driver
The Beagle communications layer under Linux does not require a specific kernel driver to operate. However, the user must ensure independently that the libusb library is installed on the system since the Beagle library is dynamically linked to libusb.
Most modern Linux distributions use the udev subsystem to help manipulate the permissions of various system devices. This is the preferred way to support access to the Beagle analyzer such that the device is accessible by all of the users on the system upon device plug-in.
For legacy systems, there are two different ways to access the Beagle analyzer, through USB hotplug or by mounting the entire USB filesystem as world writable. Both require that /proc/bus/usb is mounted on the system which is the case on most standard distributions.
UDEV
Support for udev requires a single configuration file that is available on the software CD, and also listed on the Total Phase website for download. This file is 99-totalphase.rules. Please follow the following steps to enable the appropriate permissions for the Beagle analyzer.
As superuser, unpack 99-totalphase.rules to /etc/udev/rules.d
chmod 644 /etc/udev/rules.d/99-totalphase.rules
Unplug and replug your Beagle analyzer(s)
USB Hotplug
USB hotplug requires two configuration files which are available on the software CD, and also listed on the Total Phase website for download. These files are: beagle and beagle.usermap. Please follow the following steps to enable hotplugging.
As superuser, unpack beagle and beagle.usermap to /etc/hotplug/usb
chmod 755 /etc/hotplug/usb/beagle
chmod 644 /etc/hotplug/usb/beagle.usermap
Unplug and replug your Beagle analyzer(s)
Set the environment variable USB_DEVFS_PATH to /proc/bus/usb
World-Writable USB Filesystem
Finally, here is a last-ditch method for configuring your Linux system in the event that your distribution does not have udev or hotplug capabilities. The following procedure is not necessary if you were able to exercise the steps in the previous subsections.
Often, the /proc/bus/usb directory is mounted with read-write permissions for root and read-only permissions for all other users. If an non-privileged user wishes to use the Beagle analyzer and software, one must ensure that /proc/bus/usb is mounted with read-write permissions for all users. The following steps can help setup the correct permissions. Please note that these steps will make the entire USB filesystem world writable.
Check the current permissions by executing the following command:
“ls -al /proc/bus/usb/001”If the contents of that directory are only writable by root, proceed with the remaining steps outlined below.
Add the following line to the /etc/fstab file:
none /proc/bus/usb usbfs defaults,devmode=0666 0 0Unmount the /proc/bus/usb directory using “umount”
Remount the /proc/bus/usb directory using “mount”
Repeat step 1. Now the contents of that directory should be writable by all users.
Set the environment variable USB_DEVFS_PATH to /proc/bus/usb
4.4 Mac OS X USB Driver
The Beagle communications layer under Mac OS X does not require a specific kernel driver to operate. Both Mac OS X 10.4 Tiger and 10.5 Leopard are supported. It is typically necessary to ensure that the user running the software is currently logged into the desktop. No further user configuration should be necessary.
4.5 USB Port Assignment
The Beagle analyzer is assigned a port on a sequential basis. The first analyzer is assigned to port 0, the second is assigned to port 1, and so on. If a Beagle analyzer is subsequently removed from the system, the remaining analyzers shift their port numbers accordingly. Hence with n Beagle analyzers attached, the allocated ports will be numbered from 0 to n−1.
Detecting Ports
As described in following API documentation chapter, the bg_find_devices routine can be used to determine the mapping between the physical Beagle analyzers and their port numbers.
4.6 Beagle Dynamically Linked Library
DLL Philosophy
The Beagle DLL provides a robust approach to allow present-day Beagle-enabled applications to interoperate with future versions of the device interface software without recompilation. For example, take the case of a graphical application that is written to monitor I2C, SPI, MDIO, or USB through a Beagle analyzer. At the time the program is built, the Beagle software is released as version 1.2. The Beagle interface software may be improved many months later resulting in increased performance and/or reliability; it is now released as version 1.3. The original application need not be altered or recompiled. The user can simply replace the old Beagle DLL with the newer one. How does this work? The application contains only a stub which in turn dynamically loads the DLL on the first invocation of any Beagle API function. If the DLL is replaced, the application simply loads the new one, thereby utilizing all of the improvements present in the replaced DLL.
On Linux, the DLL is technically known as a shared object (SO).
DLL Location
Total Phase provides language bindings that can be integrated into any custom application. The default behavior of locating the Beagle DLL is dependent on the operating system platform and specific programming language environment. For example, for a C or C++ application, the following rules apply:
On a Windows system, this is as follows:
The directory from which the application binary was loaded.
The application’s current directory.
32-bit system directory. Examples:
c:\Windows\System32 [Windows 2000/XP/Vista 32-bit]
c:\Windows\SysWow64 [Windows Vista 64-bit]
The windows directory. (Ex: c:\Windows)
The directories listed in the PATH environment variable.
On a Linux system this is as follows:
First, search for the shared object in the application binary path. If the /proc filesystem is not present, this step is skipped.
Next, search in the application’s current working directory.
Search the paths explicitly specified in LD_LIBRARY_PATH.
Finally, check any system library paths as specified in /etc/ld.so.conf and cached in /etc/ld.so.cache.
On a Mac OS X system this is as follows:
First, search for the shared object in the application binary path.
Next, search in the application’s current working directory.
Search the paths explicitly specified in DYLD_LIBRARY_PATH.
Finally, check the /usr/lib and /usr/local/lib system library paths.
If the DLL is still not found, the BG_UNABLE_TO_LOAD_LIBRARY error will be returned by the binding function.
DLL Versioning
The Beagle DLL checks to ensure that the firmware of a given Beagle analyzer is compatible. Each DLL revision is tagged as being compatible with firmware revisions greater than or equal to a certain version number. Likewise, each firmware version is tagged as being compatible with DLL revisions greater than or equal to a specific version number.
Here is an example.
DLL v1.20: compatible with Firmware >= v1.15
Firmware v1.30: compatible with DLL >= v1.20
Hence, the DLL is not compatible with any firmware less than version 1.15 and the firmware is not compatible with any DLL less than version 1.20. In this example, the version number constraints are satisfied and the DLL can safely connect to the target firmware without error. If there is a version mismatch, the API calls to open the device will fail. See the API documentation for further details.
4.7 Rosetta Language Bindings: API Integration into Custom Applications
Overview
The Beagle Rosetta language bindings make integration of the Beagle API into custom applications simple. Accessing a Beagle analyzer’s functionality simply requires function calls to the Beagle API. This API is easy to understand, much like the ANSI C library functions, (e.g., there is no unnecessary entanglement with the Windows messaging subsystem like development kits for some other embedded tools).
First, choose the Rosetta bindings appropriate for the programming language. Different Rosetta bindings are included with the software distribution on the distribution CD. They can also be found in the software download package available on the Total Phase website. Currently the following languages are supported: C/C++, Python, Visual Basic 6, Visual Basic .NET, and C#. Next, follow the instructions for each language binding on how to integrate the bindings with your application build setup. As an example, the integration for the C language bindings is described below. (For information on how to integrate the bindings for other languages, please see the example code included on the distribution CD and also available for download on the Total Phase website.)
Include the beagle.h file included with the API software package in any C or C++ source module. The module may now use any Beagle API call listed in beagle.h.
Compile and link beagle.c with your application. Ensure that the include path for compilation also lists the directory in which beagle.h is located if the two files are not placed in the same directory.
Place the Beagle DLL, included with the API software package, in the same directory as the application executable or in another directory such that it will be found by the previously described search rules.
Versioning
Since a new Beagle DLL can be made available to an already compiled application, it is essential to ensure the compatibility of the Rosetta binding used by the application (e.g., beagle.c) against the DLL loaded by the system. A system similar to the one employed for the DLL-Firmware cross-validation is used for the binding and DLL compatibility check.
Here is an example.
DLL v1.20: compatible with Binding >= v1.10
Binding v1.15: compatible with DLL >= v1.15
The above situation will pass the appropriate version checks. The compatibility check is performed within the binding. If there is a version mismatch, the API function will return an error code, BG_INCOMPATIBLE_LIBRARY.
Customizations
While provided language bindings stubs are fully functional, it is possible to modify the code found within this file according to specific requirements imposed by the application designer.
For example, in the C bindings one can modify the DLL search and loading behavior to conform to a specific paradigm. See the comments in beagle.c for more details.
4.8 Application Notes
Receive Saturation
Once enabled, the Beagle analyzer is constantly monitoring data on the target bus. Between calls to the Beagle API, these messages must be buffered somewhere in memory. This is accomplished on the analysis computer, courtesy of the operating system. Naturally the buffer is limited in size and once this buffer is full, data will be dropped. An overflow can occur when the Beagle analyzer receives data faster than the rate that it is processed — the receive link is ‘saturated.” The system is most susceptible to saturation when monitoring large amounts of traffic over USB or high-speed SPI bus.
Threading
The Beagle DLL is designed for single-threaded environments so as to allow for maximum cross-platform compatibility. If the application design requires multi-threaded use of the Beagle analyzer’s functionality, each Beagle API call can be wrapped with a thread-safe locking mechanism before and after invocation.
It is the responsibility of the application programmer to ensure that the Beagle analyzer open and close operations are thread-safe and cannot happen concurrently with any other Beagle analyzer operations. However, once a Beagle analyzer is opened, all operations to that device can be dispatched to a separate thread as long as no other threads access that same Beagle analyzer.
| Prev: Device Operation | Table of Contents | Next: Firmware |