WARNING: There is absolutely no warranty for this software
package. See the file COPYING for details.

**************************************************************************
This is alpha stage software, so if you test it you do this absolutely on
your own risk! As this is a hardware driver there is the possibility 
of damaging your computer, your CCD camera or something else of your
equipment. 
**************************************************************************


Linux Kernel driver for the astronomical CCD camera "LcCCD14"
-------------------------------------------------------------

This is a "module" (which is the terminus for a hardware driver in the Linux
world) for operating the LcCCD14 astronomical camera on a linux system. At
the time of writing only systems with kernel 2.0.x are supported (the
authors machine has 2.0.36), so you shouldn't expect it to run with current
2.2.x kernels. This will change in the future. 

The aim of this driver is to provide a system standard software interface
for the operation of the camera, such as setting up integration time and
other preferences, starting an image aquisition and reading the raw image
data from the camera. 


Some words on kernel modules
----------------------------

On Unix systems everything is a file, so the camera presents itself as a
file as well. Hardware drivers have a special node in the directory, mostly
located in the /dev part of the file system. A typical node entry looks like
this:

----------8<----------
robert@callisto:/dev ! ls -l lcccd14
crw-rw-rw-   1 root     root      34,   0 Sep 10 10:08 lcccd14
---------->8----------

From left to right you can see the first character, the "c", indicating this
is a character driver, followed by the normal Unix file permission flags,
the owner and group of the node. The two numbers (34 and 0) are the maior
and minor device number which identify the kernel module that will handle
this node. If there is no such filesystem entry on your system you have to
create it by hand - later versions of this software will do that as part of
the installation routines. If you do not know how to make a special node
entry look at the INSTALL file (what you should do anyway). 


Communication with the module
-----------------------------

There are three possibilities for a user program to communicate with the
kernel module: 

1. read() and write()  If the device special file is opened with the open() 
                       function like a normal file you can simply use the 
                       system's default read() and write() functions.
                       The LcCCD14 driver uses the first one to readout the 
                       image data. 

2. ioctl()             The ioctl() function lets the user program execute 
                       special predefined commands. This mechanism is used
                       by the LcCCD14 module for setup purposes. 

3. /proc               In the /proc directory of your Linux system you can 
                       find special "virtual" entries which can be pseudo
                       files provided by the module for bidirectional 
                       communication between the user space program and the
                       kernel module. This is not used at the moment - but
                       it will in the future. 

If you want to know how you can talk to the module from a user space program
(and I'm pretty sure you want to :-) ) have a look at the test file called
"test.c". 


Testing and bug reports
-----------------------

At the time of writing the module is in a very early stage of development.
Nevertheless, it basically works! :-) I'm strongly interested in people
testing the software, so please feel free to contact me by email if you have
any remarks, bug reports or patches!

--
Robert Schwebel <robert@schwebel.de> / Kiel, Germany, 19.09.1999