#
# Copyright 2001,2002 Free Software Foundation, Inc.
# 
# This file is part of GNU Radio
# 
# GNU Radio is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2, or (at your option)
# any later version.
# 
# GNU Radio is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with GNU Radio; see the file COPYING.  If not, write to
# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.
# 

This is the source for a linux 2.4 driver for the Measurement
Computing PCI DAS4020/12 Analog to Digital Conversion board.  

It implements direct DMA into user space via mmap, and is capable of
transferring data at the full rate of the card (1 or 2 channels at 20M
samples/sec, or 4 channels at 10M samples/sec.)

Directory hierarchy:

    kernel  -- the source for the kernel module
    user    -- test code and simple application "mc4020-read-adc" for
               grabbing data.



INSTALLATION
------------

Running as normal user:

  $ ./configure
  $ make

Running as root

  # make install
  # depmod
  # make devs

Then add the following line to your /etc/modules.conf

        alias char-major-127 mc4020

At this point, you should be able to run mc4020-set-adc and mc4020-read-adc.


USAGE NOTES
-----------

The easiest way to use this driver is with the supplied mc4020-read-adc
program.  

To read data at 20M samples/second from channel 0 with the input range
set at +/- 1V use:

    mc4020-read-adc -f 20000000 --ch0 --1v

The output will be written to stdout.  Using the --ascii flag will
result in ascii output, --binary gets you binary shorts.  You can
specify the number of samples to read with the --count=<value> option.
If not specified, there is no limit.  The raw converter produces
values in the range [0,4095].  The --fix-offset option (enabled by
default) subtracts 0x800 resulting in values in [-2048, 2047]

Type mc4020-read-adc --help for other options.


USING THE DRIVER DIRECTLY
-------------------------

This driver does not have a typical read/write interface.  In fact,
it does not implement the read or write entry points at all.  

   0)   include "mc4020.h"

   1)   open the device read only (open)

   2)   configure buffer size (GIOCSETBUFSIZE ioctl)
        Buffer size must be a multiple of 1MB (use 16MB if you're not
        sure), and less than or equal to 32MB.

   3)   configure channels, gain, sample rate, input source
        (GIOCSETCONFIG ioctl)
        
   4)   mmap the device into user space (mmap)

   5)   issue GIOCSTART ioctl to begin continuous A/D conversions

   6)   In the main loop of your application call the
        GIOCSETGETSTATUS ioctl which communicates buffer usage
        information between your application and the driver.

See mc4020-read-adc.c for an example.


RESOURCES
---------

Main web page: http://www.gnu.org/software/gnuradio

Questions, discussion, etc., send email to discuss-gnuradio@gnu.org.

You can subscribe or unsubscribe on the web with mailman
<http://mail.gnu.org/mailman/listinfo/discuss-gnuradio>, or by sending
an email to discuss-gnuradio-request@gnu.org with subscribe as the
subject line. Volume is typically low.

Archives of the discussion list are stored at
http://mail.gnu.org/pipermail/discuss-gnuradio 

Bugs?	bug-gnuradio@gnu.org


KNOWN PROBLEMS
--------------

The AMD 768 southbridge used on dual processor Athlon motherboards
(and maybe others too) has a problem with the secondary PCI bus
arbiter.  It will allow the on chip IDE controller to hog the bus,
regardless of the PCI latency timer settings.  The symptoms are that the
mc4020 driver logs "mc4020: overrun" to the kernel log, and that you've got
gaps in your data.  One work around is to disable the on board IDE
controllers, and use an add-in IDE card.
