readme.txt

rt 7520采集卡 linux驱动源代码

DM7520 driver, library, and example programs for Linux.

SWP-700010005 rev C

Version 1.8

Copyright (c) 2004 RTD Embedded Technologies, Inc.  All Rights Reserved.

Using this software indicates acceptance of the RTD End-User Software
License Agreement.  See the file LICENSE.TXT.



------------------
Supported Hardware
------------------

This software supports the RTD DM7520 dataModule.



-------------------------
Supported Kernel Versions
-------------------------

This software works on Linux kernel version 2.4.x.

This software was tested on the following distributions:

    * Red Hat 7.3 (unmodified kernel 2.4.18-3)
    * Red Hat 8.0 (unmodified kernel 2.4.18-14)
    * Red Hat 9.0 (unmodified kernel 2.4.20-8)
    * Red Hat 9.0 (2.4.25 kernel built from kernel.org source)



-------------------
Supported Compilers
-------------------

The driver, library, and example program software were compiled using the gcc
compiler under Red Hat versions 7.3, 8.0, and 9.0 (unmodified kernels).



------
Driver
------

The directory driver/ contains source code related to the driver.


In order to use the driver, one must first compile it, load it into the kernel,
and create device files for the board(s).  To do this, issue the following
commands while sitting in the driver/ directory:

    * make
    * make insmod
	NOTE:	This target assumes that the driver produces only minimal
		message output.
    * make devices


The driver object file is named rtd-dm7520.o.


The following arguments to insmod are accepted when loading the driver:

    * verbose
	Flag which controls verbosity of messages printed by the driver.  Valid
	values are 0 (minimize messages) and 1 (maximize messages).  If this
	option is not given, the driver defaults to minimizing message
	printing.


Here are some example insmod command lines along with a description of what
each does (each example assumes that your current directory is driver/):

    - /sbin/insmod ./rtd-dm7520.o
	Load the driver into the kernel.  The driver minimizes message output.

    - /sbin/insmod ./rtd-dm7520.o verbose=0
	Load the driver into the kernel.  The driver minimizes message output.

    - /sbin/insmod ./rtd-dm7520.o verbose=1
	Load the driver into the kernel.  The driver maximizes message output.


When you load the kernel driver, the message "Warning: loading rtd-dm7520.o
will taint the kernel: non-GPL license - Proprietary" will be printed.  You
can safely ignore this message since it pertains to GPL licensing issues
rather than to driver operation.



-----------------
Library Interface
-----------------

The directory lib/ contains source code related to the user library.


The DM7520 library is created with a file name of librtd-dm7520.a and is a
statically linked library.


Please refer to the software manual for details on using the user level
library functions.  These functions are prototyped in the file
include/dm7520_library.h; this header file must be included in any code which
wishes to call library functions.


To build the library, issue the command "make" within lib/.



----------------
Example Programs
----------------

The directory examples/ contains source code related to the example programs.
This code demonstrates how to use features of the DM7520 board or tests the
driver.  In addition to source files, examples/ holds other files as well; the
purpose of these files will be explained below.


The following files are provided in examples/:

    * ad.c
	Demonstrates A/D conversion using the pacer clock without DMA.
    * ad_dma.c
	Demonstrates A/D conversion using the pacer clock with DMA.
    * async.c
	Demonstrates asynchronous notification of interrupts.
    * da.c
	Demonstrates D/A conversion without DMA.
    * da_dma.c
	Demonstrates D/A conversion with DMA.  The waveform changes as the
	program runs.
    * da_dma_cycle.c
	Demonstrates D/A conversion with DMA.  The waveform does not change as
	the program runs.
    * demo
	Binary file containing 8-bit digital values which can be used as the
	input file for the pattern example program.
    * dig.c
	Demonstrates writing to a digital I/O port.
    * etrig.c
	Demonstrates usage of an external trigger.
    * extint.c
	Demonstrates usage of an external interrupt.
    * fifo.c
	Demonstrates how to use software triggering to start an A/D conversion.
    * hd.c
	Demonstrates how to use the high speed digital input.
    * hd_dma.c
	Demonstrates how to use on demand DMA with high speed digital input.
    * Makefile
	Make description file for building the example programs.
    * mcbsp.c
	Demonstrates usage of the Multi-channel Buffered Serial Port (McBSP).
    * pattern.c
	Reads digital data from a file and writes it to digital I/O port 0.
    * test.c
	Test driver and library functionality.
    * user_inp.c
	Demonstrates usage of User Input 0 and User Input 1 lines.


To build the example programs, issue the command "make" within examples/.


Some of the example programs require that the S-Lang static library and header
files be installed on the system.  S-lang is a C-like programming language
designed to be embedded in programs.  The da_dma_cycle, etrig, extint, mcbsp,
and test programs all need these files.  If your Linux distribution is RPM
based, you will need to install the slang-devel and slang RPMs.  Please see
the S-Lang web site (http://www.s-lang.org) for more information.



------------
Header Files
------------

The directory include/ contains all header files needed by the driver,
libraries, example programs, and user applications.



---------------
IOCTL Interface
---------------

Please refer to the software manual for details on how to communicate with
the driver using the ioctl() system call.



-----------------
Known Limitations
-----------------

 1. The major argument on the insmod command is no longer supported by the
    driver.  Instead, the driver now asks the kernel to dynamically assign a
    character major number when the kernel module is loaded.

 2. Any activity on the PCI bus can interfere with the maximum throughput
    achievable from a DM7520 device.  For example, merely having the X server
    running on a CPU with an integrated PCI video chip is known to interfere
    with A/D conversion at 1 megahertz.  Higher throughput rates equate to
    increasing likelihood that something will get in the way.

 3. Calling the UnSetDMAMode7520() library function in certain circumstances
    can lead to odd system behavior.  When processing this request, the driver
    waits for any outstanding DMA requests to complete (by examining the status
    of the FIFO used in the transfer).  To prevent the wait from becoming
    infinitely long, the driver also uses a timeout mechanism to limit the wait
    to at most two seconds.  Because of the way the wait is implemented,
    interrupts are repeatedly disabled and enabled during the process.  The
    system may appear to lock up or become unresponsive if a request does not
    complete before the timeout expires.  If the library function is called at
    a point where the FIFOs are no longer being updated (for example, if A/D
    conversion is stopped or the D/A converter clock is halted), then the
    driver will use up the entire two second timeout.  During this period, any
    system activity which depends upon interrupts will appear to come to a
    halt.  Once the timeout expires, said system activity resumes.

 4. The ReadData7520() function does not return any status from its attempts
    to disable paging for the user buffer (lock it into memory via a mlock(2)
    call) and to enable paging for the user buffer (unlock it from memory via
    a munlock(2) call).  Therefore, these functions can fail and you will not
    be able to detect the failure.

 5. Because the example program test (test.c) uses loops as a delay mechanism,
    it is sensitive to the speed of the system it runs on.  Therefore, some
    errors may occur during execution.



-------------------------
Getting Technical Support
-------------------------

If you require additional support with this product, or any other products
from RTD Embedded Technologies, contact us using the information below:

	RTD Embedded Technologies, Inc.
	103 Innovation Boulevard
	State College, PA 16803 USA

	Telephone: [phone]
	Fax: [phone]
	Sales Information and Quotes: [e-mail]
	Technical Assistance: [e-mail]
	Web Site: http://www.rtd.com