3 Software

3.1 Compatibility

Linux

The Cheetah software is compatible with all standard distributions of Linux with integrated USB support. Kernel 2.6 or greater is required.

Windows

The Cheetah software is compatible with Windows 2000 SP4 and Windows XP SP2.

3.2 Linux USB Driver

The Cheetah 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 Cheetah 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 Cheetah adapter 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 Cheetah adapter, 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 Cheetah adapter.

1. As superuser, unpack 99-totalphase.rules to /etc/udev/rules.d

2. chmod 644 /etc/udev/rules.d/99-totalphase.rules

3. Unplug and replug your Cheetah adapter(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: cheetah and cheetah.usermap. Please follow the following steps to enable hotplugging.

1. As superuser, unpack cheetah and cheetah.usermap to /etc/hotplug/usb

2. chmod 755 /etc/hotplug/usb/cheetah

3. chmod 644 /etc/hotplug/usb/cheetah.usermap

4. Unplug and replug your Cheetah adapter(s)

5. 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 Cheetah adapter 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.

1. Check the current permissions by executing the following command:
   “ls -al /proc/bus/usb/001”

2. If the contents of that directory are only writable by root, proceed with the remaining steps outlined below.

3. Add the following line to the /etc/fstab file:

        none /proc/bus/usb usbfs defaults,devmode=0666 0 0
   

4. Unmount the /proc/bus/usb directory using “umount”

5. Remount the /proc/bus/usb directory using “mount”

6. Repeat step 1. Now the contents of that directory should be writable by all users.

7. Set the environment variable USB_DEVFS_PATH to /proc/bus/usb

3.3 Windows USB Driver

Driver Installation

On the Windows platform, the Cheetah software uses a version of the libusb-win32 open source driver to access the Cheetah device. For more information on this driver, please refer to the README.txt that is included with the driver. To install the appropriate USB communication driver under Windows, step through the following instructions. This is only necessary for the very first Cheetah adapter that is plugged into the PC. Subsequent plugs and unplugs should be automatically handled by the operating system.

Windows 2000:

1. When you plug in the Cheetah adapter into your PC for the first time, Windows will present the “Found New Hardware Wizard.” Select “Next.”

2. On the next dialog window, select “Search for a suitable driver for my device (recommended)” and click “Next.”

3. On the third screen, uncheck all settings and check “Specify a location” and click “Next.”

4. Click “Browse…”, navigate to either the CD-ROM (\usb-drivers\windows directory), or temporary directory where the driver files have been unpacked (for downloaded updates).

5. Select “cheetah.inf” and click “Open”, then click “OK.”

6. Click “Next” on the subsequent screen, followed by “Finish” to complete the installation. This completes the installation of the USB driver.

Windows XP:

1. When you plug in the Cheetah adapter into your PC for the first time, Windows will present the “Found New Hardware Wizard.”

2. Select “Install from a list or specific location (Advanced)” and click “Next.”

3. Select “Search for best driver in these locations:”, uncheck “Search removable media”, check “Include this location in the search.”

4. Click “Browse…”, expand My Computer and then navigate to either the CD-ROM (\usb-drivers\windows directory), or temporary directory where the driver files have been unpacked (for downloaded updates).

5. Click “OK”, then click “Next.”

6. A dialog will inform the user that the USB driver has been installed. Click “Finish.”

Both Windows 2000 and Windows XP:

1. Once the installation is complete, confirm that the installation was successful by checking that the device appears in the “Device Manager.” To navigate to the “Device Manager” screen select “Control Panel | System Properties | Hardware | Device Manager.”

2. The Cheetah device should appear under the “LibUSB-Win32 Devices” section.

Driver Removal

Ordinarily, there is usually no harm in leaving the Cheetah USB drivers installed in the operating system. However, if it is necessary that the drivers be removed, please follow the steps outlined below.

1. Plug in the Cheetah device whose driver you wish to uninstall.

2. Navigate to the “Device Manager” screen by selecting “Control Panel | System Properties | Hardware | Device Manager.”

3. Right click on the Cheetah device which should appear under the “LibUSB-Win32 Devices” section.

4. Open the properties dialog.

5. Select the “Driver” tab and choose “Uninstall.”

6. Now use the file searching feature of Windows to search in c:\WINNT\inf for all files containing the text “Cheetah.”

7. Delete all files with the extension “.inf”.

3.4 USB Port Assignment

The Cheetah adapter 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 Cheetah adapter is subsequently removed from the system, the remaining analyzers shift their port numbers accordingly. Hence with n Cheetah adapters attached, the allocated ports will be numbered from 0 to n−1.

Detecting Ports

As described in following API documentation chapter, the ch_find_devices routine can be used to determine the mapping between the physical Cheetah analyzers and their port numbers.

3.5 Cheetah Dynamically Linked Library

DLL Philosophy

The Cheetah DLL provides a robust approach to allow present-day Cheetah-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 communicate SPI through a Cheetah device. At the time the program is built, the Cheetah software is released as version 1.2. The Cheetah 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 Cheetah 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 Cheetah 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 Cheetah 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 Linux system this is as follows:

1. First, search for the shared object in the application binary path. Note, that this step requires /proc filesystem support, which is standard in 2.4.x kernels. If the /proc filesystem is not present, this step is skipped.

2. Next, search in the application’s current working directory.

3. Search the paths explicitly specified in LD_LIBRARY_PATH.

4. Finally, check any system library paths as specified in /etc/ld.so.conf and cached in /etc/ld.so.cache.

On a Windows system, this is as follows:

1. The directory from which the application binary was loaded.

2. The application’s current directory.

3. 32-bit system directory. (Ex: c:\winnt\System32) [Windows NT/2000/XP only]

4. 16-bit system directory. (Ex: c:\winnt\System or c:\windows\system)

5. The windows directory. (Ex: c:\winnt or c:\windows)

6. The directories listed in the PATH environment variable.

If the DLL is still not found, the CH_UNABLE_TO_LOAD_LIBRARY error will be returned by the binding function.

DLL Versioning

The Cheetah DLL checks to ensure that the firmware of a given Cheetah device 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.

3.6 Rosetta Language Bindings: API Integration into Custom Applications

Overview

The Cheetah Rosetta language bindings make integration of the Cheetah API into custom applications simple. Accessing Cheetah functionality simply requires function calls to the Cheetah 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.)

1. Include the cheetah.h file included with the API software package in any C or C++ source module. The module may now use any Cheetah API call listed in cheetah.h.

2. Compile and link cheetah.c with your application. Ensure that the include path for compilation also lists the directory in which cheetah.h is located if the two files are not placed in the same directory.

3. Place the Cheetah 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 Cheetah 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., cheetah.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, CH_INCOMPATIBLE_LIBRARY.

Customizations

While the 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 cheetah.c for more details.

3.7 Application Notes

Threading

The Cheetah 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 Cheetah functionality, each Cheetah 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 Cheetah open and close operations are thread-safe and cannot happen concurrently with any other Cheetah operations. However, once a Cheetah device is opened, all operations to that device can be dispatched to a separate thread as long as no other threads access that same Cheetah device.

USB Scheduling Delays

More specifically, each API call that is used to send data to and from the Cheetah adapter can incur up to 125 µs (1 ms) in delay on the PC host for USB High Speed (Full Speed) connections. This is caused by the inherent design of the USB architecture. The operating system will queue any outgoing USB transfer request on the host until the next USB frame period. The frame period is 125 µs (1 ms). Thus, if the application attempts to execute several transactions in rapid sequence there can be 1–2 ms delay between each transaction plus any additional process scheduling delays introduced by the operating system. The best throughput can be achieved for single transactions that transfer a large number of bytes at a time.