readme.txt

rt 6430 采集卡 linux下驱动源代码

DM6430 driver, library, and example programs for Linux.

SWP-700010033 rev A

Version 2.0

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 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 8.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 and 8.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.  To do this, issue the following
commands while sitting in the driver/ directory:

    * make
    * make insmod
	NOTE:	This target assumes 1) a single DM6430 board is installed,
		2) its base I/O address is set to the factory default of 0x300,
		3) the board will use IRQs 3 and 5, and 4) the board will use
		DMA channels 5 and 6.  You may need to edit the Makefile and
		change this rule to reflect your board and system configuration
		or manually issue an appropriate insmod command.
    * make devices


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


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

    * io
	List of 4 base I/O addresses.  Note that multiple addresses must be
	separated by commas.  An empty or 0 value indicates that the specified
	device should be ignored.
    * irq1
	List of 4 IRQ line numbers for a board's first interrupt circuit.  Note
	that multiple IRQ numbers must be separated by commas.  An empty or 0
	value indicates that an IRQ number should not be assigned.
    * irq2
	List of 4 IRQ line numbers for a board's second interrupt circuit.
	Note that multiple IRQ numbers must be separated by commas.  An empty
	or 0 value indicates that an IRQ number should not be assigned.
    * dma1
	List of 4 DMA channel numbers for a board's first DMA circuit.  Note
	that multiple DMA channels must be separated by commas.  An empty or 0
	value indicates that a DMA channel number should not be assigned.
    * dma2
	List of 4 DMA channel numbers for a board's second DMA circuit.  Note
	that multiple DMA channels must be separated by commas.  An empty or 0
	value indicates that a DMA channel number should not be assigned.
    * buflength
	Size of DMA buffer in bytes.  If this option is not given, a default
	size of 65536 bytes is used.
    * force
	Binary flag which controls resource allocation.  A value of 0 indicates
	that I/O ports, IRQs, and DMA channels should be allocated when a
	device file is opened.  Any other value indicates that these resources
	should be allocated when the driver is loaded.  If this option is not
	given, resources are allocated whenever a device file is opened.
    * debug
	Bit mask which controls what debug information is printed about driver
	operation.  This argument only has meaning if the driver was compiled
	with -DDEBUG.  Valid bit mask values can be found in
	include/dm6430driver.h.  If this option is not given and the driver
	was compiled with -DDEBUG, no debug information is printed.


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

    - insmod ./rtd-dm6430.o io=0x300 irq1=3 irq2=5 dma1=0 dma2=0

	Configure a single DM6430 board at base I/O address of 0x300.  Use IRQ
	number 3 for the first interrupt circuit.  Use IRQ number 5 for the
	second interrupt circuit.  Do not allocate a DMA channel number for
	either DMA circuit.

    - insmod ./rtd-dm6430.o io=0x200,0x220 irq1=0,9 irq2=5,0 dma1=5,0 dma2=6,0

	Configure two DM6430 boards at base I/O addresses of 0x200 and 0x220.
	Do not allocate an IRQ for the first interrupt circuit on board one or
	for the second interrupt circuit on board two.  Use IRQ 9 for the first
	interrupt on board one and use IRQ 5 for the second interrupt on board
	two.  Allocate DMA channel 5 for the first DMA circuit on board one
	and DMA channel 6 for the second DMA on board one.  No DMA channel is
	configured for either of the DMA circuits on board two.

    - insmod ./rtd-dm6430.o io=0x300 irq1=5 force=1 debug=0x8

	Configure a single DM6430 board at base I/O address of 0x300.  Use IRQ
	5 for the first interrupt circuit.  Do not allocate an IRQ for the
	second circuit.  No DMA channel is configured for either DMA circuit.
	Resources are allocated when the module is loaded rather than when the
	device file is opened.  If the driver was built with -DDEBUG, print
	debug information regarding ioctl() calls.


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


It is recommended that you not build the driver module with the -DDEBUG switch.
When the driver is built with DEBUG defined, extra code which prints debugging
information is compiled into the driver  This code causes a driver performance
penalty and extra system load in the form of more work for syslogd (the system
log daemon).  Also, a small delay is added to each access of an address in the
board's I/O space.



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

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


The DM6430 library is created with a file name of librtd-dm6430.a and is a
statically linked library.  Note that the shared library is no longer built,
which means that any existing applications using the shared library must be
relinked with the static library.


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


The major change to the library in this version of the driver is the addition
of error checking.  All library functions now return an indication of whether
or not they succeeded.  Any library function that returned a value (other than
a status indication, for example the contents of a board register) now takes
as an additional parameter the address where this value is to be stored.
Because of these changes, existing source code which uses the library will not
compile.  Users must update their source code to pass additional addresses
where needed and to check for error status.


Some library functions have been made private (that is, no longer visible to
user applications) and some routines have been deleted from the library.
Please see the software manual for details.


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



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

The directory examples/ contains source code related to the example programs,
which 1) demonstrate how to use features of the DM6430 board, 2) test the
driver, or 3) test the library.


The following example programs are provided:

    * dm6430-auto-burst
	Demonstrates how to use the pacer clock, burst clock, sample counter,
	and channel gain table features of the DM6430 to do MULTI-BURST
	sampling.
    * dm6430-auto-scan
	Demonstrates how to use the sample counter and the pacer clock
	features of the DM6430 to do MULTI-SCAN sampling.
    * dm6430-dac
	Demonstrates how to perform digital to analog conversion.
    * dm6430-digital-interrupt
	Demonstrates how to use advanced digital interrupts.  This program
	connects the first interrupt circuit to advanced digital interrupts, 
	puts the board in event mode, and waits for a single interrupt.
    * dm6430-digital-io
	Demonstrates how to read and write the digital I/O ports.
    * dm6430-dma
	Demonstrates how to use DMA (Direct Memory Access) to acquire data.
    * dm6430-dual-dma
	Demonstrates how to use dual DMA (Direct Memory Access) mode to
	acquire data.  Dual DMA mode uses both DMA circuits on a board and can
	be used to acquire large amounts of data at high speed.
    * dm6430-multi-burst
	Demonstrates how to perform an analog to digital burst mode conversion
	on multiple channels using the channel gain table.
    * dm6430-sample-counter
	Demonstrates how to use the sample counter to generate interrupts.
    * dm6430-soft-trigger
	Demonstrates how to initiate an analog to digital conversion using a
	software trigger.
    * dm6430-speed-test
	Demonstrates three different IRQ handling and data read methods:
	    - Using a callback routine invoked via the driver interrupt
	      handler sending a signal to the process.  Data is read using
	      streaming input.
	    - Polling the IRQ counter for an interrupt circuit.  Data is read
	      one sample at a time.
	    - Polling the IRQ counter for an interrupt circuit.  Data is read
	      using streaming input.
    * dm6430-stream
	Demonstrates using streaming input to read blocks of data from the
	digital input FIFO.
    * dm6430-test-lib-errors
	Tests the error checking added to all library functions.  Every
	exported library function is verified.
    * dm6430-timers
	Demonstrates how to program the 8254 programmable interval timers
	(PITs).
    * dm6430-user-timer
	Demonstrates how to set up the User Timer to generate interrupts at a
	specified rate.


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



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

The directory include/ contains all header files needed by the driver,
library, 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. In previous versions of the driver, the ReadChannelGainDataStore6430()
    library function would read the Control Register to see if the channel/gain
    data store is enabled and, if enabled, return both the channel/gain and
    converted data.  The function in this driver version only returns the
    channel/gain data because there is no way to check in the hardware whether
    or not the channel/gain data store is enabled.  Rather, user applications
    must remember when the channel/gain data store is enabled and read the
    channel/gain and converted data separately.

 2. Data returned from the GetIRQCounter6430() library call is interpreted
    differently depending upon usage of the force argument on the insmod
    command.  If you specify a nonzero value for the force argument, the
    value returned represents the number of interrupts that occurred since
    the driver module was loaded.  If you specify a zero value for the force
    argument or do not use force at all, the value returned represents the
    number of interrupts that occurred since the device file was opened.



-------------------------
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