Exacq Data Acquisition Linux Tools v1.0.8 03/07/08 Exacq Technologies, Inc. http://www.exacqdaq.com support@exacq.com I. Introduction ============ The Exacq Data Acquisition Linux Tools (EDALT) package provides drivers, applications, and programming tools needed to use Exacq Technologies data acquisition hardware under Linux. II. Requirements ============= EDALT requires an Intel Linux distribution based on a v2.4 or v2.6kernel with module and proc file system support. III. Installation ============ 1) Copy the archive to the intended base directory (/usr/local is the default). Make the base directory current (cd /usr/local) and extract the archive using the command 'tar xfz exacqdalt-1.0.x.tar.gz' (replace the version number part of the file name with the version number of your archive). If you don't use /usr/local as your base, you will have to create a file in /etc called exacq.conf that contains text specifying the various directories used by the applications and drivers. See the section on xdvapi.conf below. The remainder of this document assumes you have used the default installation directory. 2) Create the necessary symbolic links and scripts by running edaltsetup from the bin directory passing the EDALT base directory as a parameter (/usr/local/bin/edaltsetup /usr/local). 4) The EDALT drivers require a section of contiguous physical memory which is reserved for exclusive use. In order to reserve this memory, you can either: a) Pass the 'mem=' command line argument to the kernel at boot. This can be accomplished by adding a line that reads 'append="mem=###M"' in the appropriate section of lilo.conf or by adding 'mem=###M' at the end of the line which specifies the kernel name in a grub.conf section. In both cases, '###' should be replaced by a number which is the total amount of memory in the system minus the amount reserved for EDALT DMA. The amount required depends upon the buffer sizes that will be specified by any EDALT applications you will run, but at least 1MB is recommended. To reserve 1MB of memory for EDALT in a 512MB system, you would add 'mem=511M' at the end of the kernel line in the appropriate grub.conf section. The reserved memory must be located below 896MB. This means that large memory machines will not be able to use all of their memory when running EDALT applications. You must limit memory to no more than 895MB (mem=895M). b) Apply the Bigphysarea patch to the kernel and pass the 'bigphysarea=' command line argument to the kernel at boot. This can be accomplished by adding a line that reads 'append="bigphysarea=####"' in the appropriate section of lilo.conf or by adding 'bigphysarea=####' at the end of the line which specifies the kernel name in a grub.conf section. In both cases, '####' should be replaced by the number of pages you want to reserve for the EDALT DMA. Pages are normally 4Kbyes. There is no limit to the ammount of memory avaible with this option. Bigphysarea patch is avaible at http://www.polyware.nl/~middelink/En/hob-v4l.html#bigphysarea 4) The kernel modules must be built for the specific Linux kernel version on your system. The source code for that kernel must be installed on the system in /usr/src/linux. The gcc compiler and tools must also be installed. Move to the exacq modules directory (cd /usr/local/exacqda/modules) and type 'make clean', then 'make'. If all goes well, the modules will be built and installed in the proper modules directory. 5) Start the EDALT modules by typing 'startedamods'. If the EDALT bin directory (/usr/local/bin) is not in your path you will get an error message. Add the bin directory to your path, or copy the files from the bin directory to a directory that is in your path. The EDALT modules can be stopped using the command 'stopedamods'. 6) To run any application that uses the EDALT shared libraries, the Linux loader must be able to find those libraries. The 'startxxx' scripts created in the EDALT bin directory by edaltsetup can be used to tell the loader where to find the libraries and start the corresponding application. If you want to run the applications directly without using the start scripts, you'll need to use other methods to modify which libraries are known to the loader. This can be accomplished by adding the EDALT library directory (usr/local/lib) to the /etc/ld.so.config file and running ldconfig, or by adding the lib directory to the LD_LIBRARY_PATH environment variable (export LD_LIBRARY_PATH=/usr/local/lib). The supplied edalibs script can be used to export the correct path. To add the environment variable to the current environment, you must execute the script within the current shell using '. edalibs' or 'source edalibs'. Note if you use the ldconfig method, you may still need to export the LD_LIBRARY_PATH for some of the GUI apps that were written using Borland Kylix and the libborqt library. Some versions of ldconfig incorrectly resolve the shared library links needed for that shared library. 7) Finally, you must run either ExacqCCL from X Windows or exacqenuc from a command line to scan the hardware in your system and assign a logical device number to Exacq data acquisition devices. You can use the startecc or starteenuc scripts to set the proper environment and run the application. ExacqCCL presents an interface that allows you to test your Exacq hardware and assign whatever physical device numbers you choose. The exacqenuc application is provided for those who are not running X, and simply assigns consecutive logical device numbers to all Exacq devices in the order which they are found. IV. Exacq Data Acquisition Linux Tools Directories and Files ============================================ /usr/local/exacqda ---------------------- readme.txt This file. /usr/local/exacqda/docs ---------------------------- Exacq Data Acquisition SDK Manual.pdf Programming information for Exacq data acquisition hardware. Exacq CH User Manual.pdf Exacq CM User Manual.pdf Exacq XH User Manual.pdf Exacq XM User Manual.pdf Hardware and software information for various Exacq data acquisition devices. Note that some of the discussed software components are only available under Microsoft Windows at this time. /usr/local/exacqda/modules --------------------------------- makefile Used to make both of the EDALT kernel modules. See the installation instructions above for more information. /usr/local/exacqda/modules/exaciomod /usr/local/exacqda/modules/exacqtmmod ------------------------------------------------- Source code directories for the EDALT kernel modules. /usr/local/exacqda/CCenter --------------------------------- ExacqCCL Exacq Control Center is used to verify installation of Exacq hardware devices and to assign logical device numbers to those devices. This application must be run at least once prior to running any other application so that a logical device number will be assigned to all Exacq devices. It can also be used to verify functionality of the hardware following installation. ExacqEnuL Exacq Enumerator is run by Control Center when it is launched, or when a rescan is requested. Enumerator scans hardware and software found on the system and writes INI files used by Control Center and other Exacq applications. ShowBrowser ShowHelp Shell scripts used to start a browser to show the Exacq Technologies web site and the HTML help files for Control Center. The scripts call Mozilla by default, but can be edited to launch your preferred browser. /usr/local/exacqda/DemoCfg ---------------------------------- EDemoCfgL Exacq Demo Config is used to enable / disable 'demo mode' and to configure demo data used by Exacq applications when running in demo mode. Demo mode can be used to run Exacq applications when Exacq hardware is not present in the system. Note that demo mode is only valid for Enumerator and Control Center. ShowHelp Shell scriptd used to start a browser to show the HTML help files for Demo Config. The script calls Mozilla by default, but can be edited to launch your preferred browser. /usr/local/exacqda/EnumC -------------------------------- exacqenmc Exacq Enumerator (console version) is a text only application which scans hardware and software found on the system and writes INI files used by Exacq applications. It can be used in place of Exacq Control Center when X Windows is not running. /usr/local/exacqda/samples/C ----------------------------------- 'C' source and executable files which demonstrate using the EDALT API to perform various input and output functions using Exacq data acquisition hardware devices. Note that these samples assume the Exacq device has been assigned logical device number 1. A makefile is provided to rebuild all samples. See the source code and SDK manual for more information on the samples. /usr/local/bin ---------------- edaltsetup This script will make the necessary symbolic links for the EDALT shares libraries and start scripts for the EDALT applications. It must be run at least once following installation. It takes a single parameter which is the edalt installation base directory (edaltsetup /usr/local). It assumes that the libraries are in a directory called lib below the base directory and that the start scripts are in a directory called bin below the base directory. If this is not the case, edaltsetup can be run with two parameters which are the full lib path and the full script path (edaltsetup /usr/local/lib /usr/local/bin). startecc starteenu startedemocfg starteenuc These scripts are used to export needed environment variables and launch the corresponding applications. startedamods This script starts the kernel modules used by the EDALT drivers. Modules must be started before any Exacq application can be used. stopedamods This script stops the kernel modules used by the EDALT drivers. edalibs This script exports the LD_LIBRARY_PATH variable needed by the ld loader to find the EDALT shared libraries. /usr/local/etc --------------- ExacqDef.ini This file is used by Enumerator to help identify Exacq hardware devices. ExacqApp.ini This file is used by Enumerator to help identify Exacq software. ExacqDA.ini ExacqEHW.ini ExacqESW.ini These files are created by Enumerator and Control Center. They contain lists of hardware and software found on the system as well as settings for Exacq devices. /usr/local/lib --------------- libexacqda.so libexacqio.so Shared libraries used to communicate with Exacq data acquisition devices. These libraries should be linked to any application that accesses Exacq hardware. *.rbf tcx.out Binary files used to initialize the Exacq data acquisition devices. libborqt-6-9-0-qt2.3.so libqtintf-6.9.0-qt2.3.so libqt.so.2.3.0 Shared library files used by Borland Kylix GUI apps including Enumerator and Control Center. /usr/local/include --------------------- exacqda.h The 'C' header file which defines the API, constants, and data types used to program Exacq data acquisition devices. Note that your application or make file should define _LINUX before including this header. xdaerr.h A 'C' header file which provides text strings associated with error numbers which can be returned by EDALT API calls. /etc ---- xdvapi.conf This file should be created if the EDALT package is not installed into the /usr/local default directory. See details above and the example template in /usr/local/exacqda/docs. V. Miscellaneous ============= xdvapi.conf File ------------------ If you do not install the EDALT package into /usr/local, you will need to create a text file in /etc called exacq.conf. Use this template (also found in exacqda/docs) replacing the specified default paths with the ones used on your system. basedir=/usr/local instdir=/usr/local/exacqda confdir=/usr/local/etc libdir=/usr/local/lib bindir=/usr/local/bin incdir=/usr/local/include XDA_Board_AllocateBuffer ----------------------------------- DMA buffers for streaming analog input and streaming digital input must be allocated and released with a special function not found in the exacqda.h header file nor documented in the SDK Manual. The prototypes is: i32 XDA_Board_AllocateBuffer(i32 device, i32 index, i32 count, void **buffer); To allocate an index value of 0 is passed, to de-allocate an index value of 1 is passed. See the ain-buf.c sample for a usage example. Exacq hardware devices support scatter gather DMA under Windows allowing DMA buffers to be allocated with normal malloc calls. The function prototype will not be added to the header file since scatter gather will also be supported in a future Linux release, making the function unnecessary. It will, however, continue to be supported in future releases to insure backward compatibility. If you get a -9008 error (Memory full) make sure you are freeing the allocated memory or increase the size of your availible DMA buffer. (Section IIII. 4.) V. History ============= v1.0 4/16/2004 Initial release v1.01 6/18/2004 Modules source cleanup. GPL headers and license text now included. v1.02 6/24/2004 Fixed a problem that sometimes prevented the DSP from initializing. v1.03 11/19/2004 Libraries built from Windows version 1.71 source. v1.04 12/22/2004 Fixed a problem with new board models. v1.05 01/04/2005 Support for 3160 and 64MB boards. v1.06 05/05/2005 Synced with Windows version 1.8 Added interupt based signaling Added Multibuffer output Added option support for Bigphysarea kernel patch v1.07 08/04/2005 Synced with Windows version 1.8.2 Fixed issued with CM Increased Aout Upload speed v1.08 03/07/2008 Version 1.8.3.791 Synced modules and io library with DVR Boards Support for Linux kernel 2.6 Please note: This shared library will not work with older modules and older shared library will not work with new modules