camdrv

- CAMAC device driver for Linux -

Japanese

'camdrv' is a device driver for Linux 2.x/3.x for the CAMAC controller CC-7x00 (manufactured by TOYO Corporation) and CCP USB/PCI/ISA (manufactured by Hoshin-Denshi). The camdrv driver is a loadable module with full CAMAC access functionality, such as CAMAC single action, wait LAM, and interrupt on LAM. The driver package also provides driver interface libraries which are compatible with some commonly used CAMAC libraries.

This driver was written as carefully as possible, and is distributed in the hope that it will be useful, but it comes with ABSOLUTELY NO WARRANTY. Please do not use it if you do not agree with these terms. The licence for this software is set as "LGPL Version 2.1". For details of LGPL2.1, please refer to COPYING-LGPL2.1 file inside the distributed packege.

The camdrv device driver was developed as a part of the Kinoko project, which aims to develop a general-purpose, scalable and extensible data acquisition system. For futher derails about the Kinoko project, please refer to the KiNOKO Home Page.

Available Platforms

OS CC/7700-PCI CC/7700-ISA CC/7000-ISA CCP-USB CCP-PCI/ISA CCP-PCI (PCI-2703A)
Linux 2.0.x available available available - available -
Linux 2.2.x available availeble available - available -
Linux 2.4.x available available available - available available
Linux 2.6.x / 3.x available available available available available available

The following is a list of verified Linux distributions.

kernel 3.x

Ubuntu 11.10 / 12.04 LTS (32bit / 64bit)
No change is needed. Use camdrv for Linux 2.6.x.

Fedora 16 (32bit / 64bit)
No change is needed. Use camdrv for Linux 2.6.x.
The 'kernel-devel' package must be installed before compiling the driver.

kernel 2.6

Fedora 8 / 10 / 12
No change is needed.
Ubuntu 10.04 LTS
No change is needed.

Fedora Core 6
The 'kernel-devel' package must be installed before compiling the driver.
Fedora Core 5
The 'kernel-devel' package must be installed before compiling the driver.
Fedora Core 4
No change is needed.
Fedora Core 3
Set the SYSTEM variable in the Makefile to "FC3".
Fedora Core 2
Set the SYSTEM variable in the Makefile to "FC2".

kernel 2.4

Red Hat Linux 8.0
The 'kernel-source' package must be installed before compiling the driver.
Set the KERNEL_INCLUDE_DIR variable in the Makefile to "/usr/src/linux-2.4/include".
Vine Linux 2.5
Set the KERNEL_INCLUDE_DIR variable in the Makefile to "/usr/include".
Red Hat Linux 7.1J
The 'kernel-source' package must be installed before compiling the driver.
Set the KERNEL_INCLUDE_DIR variable in the Makefile to "/usr/src/linux-2.4/include".

kernel 2.2

Red Hat Linux 7.0J
The 'kernel-source' package must be installed before compiling the driver.
Set the KERNEL_INCLUDE_DIR variable in the Makefile to "/usr/src/linux/include".
Red Had Linux 6.2 / 6.2J
No change is needed.
Kondara MNU/Linux 2000
No change is needed.
Vine Linux 2.1.5
No change is needed.
Vine Linux 2.0
No change is needed.
Debian GNU/Linux (woody)
No change is needed, but the 'kernel-headers' package might need to be installed.
Debian GNU/Linux (potato)
No change is needed, but the 'kernel-headers' package might need to be installed.

Download and Feedback

If you have any questions, comments, etc, please email the system developer at http://www.awa.tohoku.ac.jp/~sanshiro/kinoko-feedback/sendmail-e.html

Installation

  1. Unpack the tarfile. 
        % gunzip camdrv-?.?.?.tar.gz
    % tar xvf camdrv-?.?.?.tar
    A new directory "camdrv" will be created.
  2. Change directory to an appropreate source directory and compile the driver. 
        % cd camdrv/Linux2.2_CC77pci
    % make
    The directory name of the source files has the structure below:
    {OS name}{OS version}_{model}

  3. Edit Makefile according to your environment. Change the following variables near the begining in Makefile. The environments the developer uses have settings listed in the "Avaliable Platform" section so please use those as a reference.

    KERNEL_INCLUDE_DIR
    The directry that has the kernel header files. Must be exactly the same as the header files used in compiling the kernel currently running.

    In some distributions, the kernel header in the "kernel-headers" package is not the one that was used when compiling. For these distributions, install the kernel-source package first and then indicate the header files inside the package (you do not need to compile the kernel source).

    If you built your own kernel, indicate the header files' directory of the source you used.

    USE_MODVERSIONS
    If the kernel running was compiled with MODVERSIONS enabled, choose 1, if not, choose 0. In most recent distributions, MODVERSIONS seems to be used (indicate "1" ).

    If you rebuilt the kernel, indicate according to the settings you chose.

    To find out if MODVERSIONS is used in your current kernel, "cat" in /proc/ksyms and see if the kernel function has the version information added. 
    % cat /proc/ksyms | grep kmalloc
c012e880 kmalloc_R93d4cfe6            <-- MODVERSION used
% cat /proc/ksyms | grep kmalloc
c012e880 kmalloc                      <-- MODVERSION not used

  4. If you use CC-7x00/ISA or CCP-PCI, you need to set I/O ports and IRQ manually (CCP-PCI does not requre IRQ setting since it does not use interrupt). Find unused I/O ranges and unused IRQ, set the jumpers on the card, and edit the Makefile. In the Makefile, edit the following lines which you can find at the begning of the file: 
        IOPORT = 0x0c00
    IRQ = 10

  5. Switch user to root and install the driver. Use the 'dmesg' UNIX command to check the installation status. 
        % su
    # make install
    # dmesg
           [many many lines here]
    camdrv: at 0x0c00 on irq 10 (major = 126).
    #

  6. Everytime the Linux system is rebooted, the driver must be installed again. 
        # make install

    Refer to Kinoko-DAQ technical tips for information on loading the driver automatically when rebooting.

  7. To remove the driver from the operating system, use the following commands (you need to be root): 
        # make uninstall
    # dmesg
           [many many lines here]
    camdrv: removed.
    #

If a user is using a newer version of Linux than the one the developer used, there is a possibility that compiling and installing will end unsuccessfully. In this case, please let us know by sending an e-mail to the system developer at http://www.awa.tohoku.ac.jp/~sanshiro/kinoko-feedback/sendmail-e.html

Testing the Driver

The camdrv driver package comes with some sample/test programs. These programs can be used to verify the driver installation. Change directory to your camdrv root directory and compile the programs: 
    % cd ..
    % make

To make sure that the driver is installed correctly:

Send INHIBIT to the controller and check the INHIBIT LED on the front panel. 
    % ./inhibit_test 
    press ENTER to set inhibit...
    press ENTER to release inhibit...
    %
After the program launches, press [ENTER] and check the LED on the front panel. If the LED does not turn on, the I/O port settings might be incorrect. Make sure that the jumper settings on the card are consistent with Makefile parameters, and that the assigned I/O port range does not conflict with any other devices (note that CC-7700/PCI does not require manual I/O port assignment).

To make sure that the driver handles interrupts on CAMAC LAM correctly:

Use any CAMAC module that issues LAM requests. Let the module issue LAM requests with 1 Hz input pulses, and check that they are handled. This test program will return 'timed out' if a LAM request does not arrive for 3 seconds. Check the timeout behavior by disconnecting the input signal.

Since this program uses LAM handling, the module has to be configured to issue LAM requests. If the module requires F26 (or any other function) to enable LAM assertion, the test program has to be modified to do that. Note that some CAMAC modules require jumper setting to enable LAM assertion. 

    % ./lam_test 
    Waiting LAM ...OK.
    Waiting LAM ...timed out.
    Waiting LAM ...OK.
    (repeat 16 times)
    %
If timeout occurs when LAM requests are being asserted (you can check this condition by looking at the controller front panel LED), the IRQ setting might be incorrect. Make sure that the jumper settings on the card are consistent with Makefile parameters, and that the assigned IRQ does not conflict with any other devices (note that CC-7700/PCI does not require manual IRQ assignment).

If you are using an ISA CAMAC controller or any other ISA devices on the PC, sometimes other device may interfere with IRQ handling. Try other IRQ numbers and/or other card slots if IRQ handling does not work properly.

If LAM is handled ('OK' is displayed) but the LAM request is not being asserted, it means that camdrv has bug[s] (or that the hardware is broken). In this case, please let us know by sending an e-mail to the system developer at http://www.awa.tohoku.ac.jp/~sanshiro/kinoko-feedback/sendmail-e.html

To verify that the driver handles CAMAC action correctly:

Use any CAMAC module that responds to the F0 CAMAC function (normal data readout fuction). The module has to be able to issue a LAM request when data is ready to be read. Since this program does not use interrupt on LAM (LAM flags on the controller are used instead), this test can be done even if the IRQ setting is not configured correctly.

This program uses the F0 CAMAC function to read data, and watchs the Q response. The data address starts from 0, and is incremented while the Q response is '1'.

Since this program uses LAM handling, the module has to be configured to issue LAM requests. If the module requires F26 (or any other function) to enable LAM assertion, the test program has to be modified to do that. Note that some CAMAC modules require jumper setting to enable LAM assertion. 

    % ./camaction_test
    [00:04:00] 110
    [00:04:01] 104
    [00:04:02] 110
    [00:04:03] 108
    (more more lines...)
    %
The output format is "[EventNumber:StationNumber(N):Address(A)] Data". Check timing behavior with 1Hz LAM requests, as in the LAM handling test. Also use appropriate signal input to check the Data value.

If this test does not work correctly but all of the other tests pass, it means that camdrv has bug[s] (or hardware is broken). In this case, please let us know by sending an e-mail to the system developer at http://www.awa.tohoku.ac.jp/~sanshiro/kinoko-feedback/sendmail-e.html

Usage

camdrv is very useful when used through KiNOKO, a general purpouse data acquisition system. For details, please see the KiNOKO Homepage.

camdrv is most useful when used through KiNOKO, but it comes with driver interface libraries which are compatible with some commonly used CAMAC libraries.

KEK Standard CAMAC Library (camlib) Compatible Library

A library follows the KEK standard CAMAC library definitions.

To use this library,
Include the header file "camlib.h".
Link the object file "camlib.o".
The source code is "camlib.c".

Differences are
Only one controller can be connected from a PC, and the only one valid crate number is 0.
Block data processing is not supported.
List processing is not supported.
LAM masking is not supported, and the mask parameter of CWLAM(int mask) will be ignored.

For further detailes,
Refer to the KEK Online Group CAMAC page.

TOYO Corporation CAMAC Library for DOS/WIN Compatible Library

A library compatible with the CAMAC library that comes with the CC-7x00 CAMAC interface card.

To use this library,
Include the header file "toyocamac.h".
Link the object file "toyocamac.o".
The source code is "toyocamac.c".

Differences are
The header file name "toyocamac.h" is different from the original name.
SetIOP()/GetIOP() is not implemented since it is not necessary for camdrv.
SetWait()/GetWait() is not implemented since it might not be necessary for camdrv.
SetLIN()/GetLIN() is not supported.
RStat() is not supported.
Only one controller can be connected from a PC, and the only one valid crate number is 0.
Block data processing is not supported.

For further detailes,
Refer to the manuals which comes with the interface card.
The test program "camaction_test.c" might be useful as a sample.

Known Bugs

Edited by: Enomoto Sanshiro