PN540                                           V2.5                                  December 6, 2005

 

 

 LINUX IEEE CAMAC

library for the Jorway 411S SCSI CAMAC Driver[1] and the Jorway 73A SCSI CAMAC Crate Controller

 

 

 

J. Streets, D. Slimmer

 

Online and Database Systems Department

Fermilab Computing Division

 

 

 

 

 

ABSTRACT

 

A description of the LINUX IEEE CAMAC  routine interface and Fermilab extensions for the Jorway[2] model 411S SCSI Bus CAMAC Highway Driver and the Jorway model

73A SCSI Bus CAMAC Crate Controller.


 

1.      Introduction

 

The Jorway 411S CAMAC Highway Driver and the Jorway 73A SCSI CAMAC Crate Controller are both

supported by  this version.

 

The 411S is the SCSI interface variant of the Jorway 411 CAMAC Highway Driver. (The UNIBUS and QBUS Jorway 411 Drivers can be  upgraded to the 411S Driver.) The software driver and CAMAC standard routines for the 411S and the 73A are available for Linux. The branch  Driver has also been run from VMS, IRIX, ULTRIX, and WINNT (PN532[3]) though they are no longer supported.

 

The SJY product consists of a user level interface between the  CAMAC IEEE routines and  the  LINUX generic SCSI driver, as well as  the CAMAC IEEE routines. Generic SCSI driver commands are processed by the low level driver for the SCSI host adapter card. The CAMAC library and test routines were written in C.

 

This release supports multi-user and multi-branch configurations for multiple SCSI bus systems. (If there is only one SCSI bus host adapter card installed, it is considered SCSI bus 0.)

 

Please refer to the Instruction Manual for the 411S SCSI bus CAMAC Highway Driver and the User’s Manual for 73A SCSI Bus CAMAC Crate Controller for hardware specific information.

 

This document describes the SJY installation procedure and the IEEE routines which provide the user interface for CAMAC access. These routines are based on those documented in PN219, “IEEE standard CAMAC Routines”.

 

Readers may be interested in similar software available for Linux systems; CES8210 VME-Parallel CAMAC driver (PN476).

 


2.      Jorway 411S Hardware Installation

 

The upgrade kit for the Jorway 411S can be installed at the Fermilab Equipment Support Department.

See HN133, “Instructions for modifying the JY411 from QBUS to SCSI Bus” for more details.

2.1       Setting the SCSI ID

The 411S SCSI ID is set with the dip switch on the left hand side of the SCSI interface board. To change the setting, remove the top of the 411S case and locate the DIP switch on the LHS of the top PC board, behind the fan. The SCSI ID of the 411S is set with switches 1(LSB) to 3 (MSB). “ON” is binary 0. Switches 4  to 7 should be set to OFF. Unused SCSI ID’s and the host adapter SCSI ID may often be found by observing the initial PC boot phase where the SCSI ID’s of installed devices are displayed.

 

2.2       Setting Little Endian

The 411S can be set to swap bytes in hardware using the jumper on the top PC board near the SCSI connector. For IBM PC’s it needs to be set to Little Endian, which is selected by placing the jumper to join the center and left posts, X16 and X17. This is opposite to IRIX systems.

 

2.3       Power Up

If the 411S is connected to a SCSI bus which contains other SCSI devices, the PC should be shut down so that connecting the SCSI cable to the 411S will not corrupt data on the other devices. Once the 411S is connected to the SCSI bus, the 411S must be powered up before the PC boots so that the PC’s SCSI host adapter  can detect the 411S on the SCSI bus.

 

If the 411S is not recognized by the PC’s SCSI host adapter, it is possible that the fuse on the 411S SCSI interface board has blown.


3.      Jorway 73A Hardware Installation

 

3.1       Setting the SCSI ID

The 73A SCSI ID is set with the front panel thumbwheel switch. Select an ID 0-7 that is different from the SCSI host adapter and all other SCSI devices on the same bus. Unused SCSI ID’s and the host adapter SCSI ID may be found by observing the initial PC boot phase where the SCSI ID’s of installed devices are displayed or through the utilities provided by the SCSI host adapter card manufacturer.

3.2       Setting the Host ID

Setting the SCSI host ID is not necessary.

3.3       Setting Little Endian

The 73A can be set to swap bytes in hardware using a jumper located under the module’s top cover.  For IBM PC’s it needs to be set to Little Endian. To set the byte swap order, remove the 73A top cover  (has the Jorway data plate). Little Endian is selected by placing the jumper to join the posts labeled X2 and X3. The 73A manual contains a diagram showing the jumper post locations.

3.4       Power Up

If the 73A is connected to a SCSI bus which contains other SCSI devices, the PC should be shut down so that connecting the SCSI cable to the 73A will not corrupt data on the other devices. Once the 73A is connected to the SCSI bus, the 73A must be powered up before the PC boots so that the PC’s SCSI host adapter can detect the 73A on the SCSI bus. If the CAMAC crate containing the 73A is powered off, but the PC is not, a SCSI bus reset may be required to re-initialize the 73A after CAMAC crate power is restored. The error message “sjy_tur: File exists” indicates the need for a SCSI reset. There is no utility in SJY for issuing a SCSI reset.

3.5       Misc.

·         SCSI Bus termination: The Jorway 73A is shipped with internal termination resistors installed. If the 73A is not the last device on the SCSI bus, the internal termination resistors need to be removed. Power for the termination resistors is supplied by the CAMAC crate, so the crate power must be left on to prevent disabling other devices on the SCSI bus.

·         Master Crate Controller: When the Jorway is functioning as the master crate controller (not as an auxiliary controller) the front panel REQ should be connected to the front panel G IN.

·         The sjyLX software driver uses the Linux system SCSI device files /dev/sg*. File permissions on these devices must be set to crw-rw-rw- (chmod 666 /dev/sg* as root).


4.      Software Installation

4.1       Generic SCSI driver

 

Generic SCSI support as well as the SCSI low-level driver for the SCSI bus host adapter card must be included in the LINUX kernel or as a loadable module.

 

In most newer Linux systems, SCSI hardware is automatically detected and the appropriate loadable kernel modules are automatically started. The loadable kernel modules can be examined using the lsmod command. The two modules of interest are sg, and the one corresponding to your SCSI host adapter which will vary from system to system. If these modules are loaded, no further work is required.

 

There is no advantage to building the SCSI generic and SCSI host adapters into your kernel, but if you wish to do so, they can be selected by logging in as root and executing the make xconfig command in the /usr/src/linux directory. In the SCSI support section, the following should be selected:

 

SCSI support

SCSI generic support

Verbose SCSI error reporting

 

                and a SCSI low-level driver such as

 

               Adaptec AHA274X/284X/294X support     or

                AdvanSys SCSI support

 

After selecting these SCSI support options and the appropriate SCSI low-level driver for your SCSI host adapter card, the configuration should be saved and the kernel rebuilt. Please contact your local system administrator if you need help in rebuilding and installing a new kernel.

 

4.2             Jorway 411S with Adaptec driver aic7xxx

 

CAMAC non-data commands generate warnings in /var/log/messages. Two possible solutions are:

1)       filter out all warning messages to the system log

2)       install aic7xxx_old instead of aic7xxx

Note that this does not apply to the Jorway 73A.

 

This issue has been resolved for the 411S by adding an extra ioctl call to set the command length for non-data commands. This change makes it possible to use the default Adaptec driver aix7xxx.

 

4.3       Buidling the CAMAC IEEE Software Library (required)

 

After obtaining the sjyLX software, the user must build the libraries and examples using the supplied make files. To build the library and examples:

 

1)       Define the environment variable SJYLX_DIR  (example set SJYLX_DIR=/usr/local/sjyLX/v2_0)

2)       cd  $SJYLX_DIR/src    make

3)       cd ../example  make

 

The built IEEE software libraries, sjy411s.lib and sjy73a.lib are put into the /lib sub-directory. The routines contained in the libraries are identical, and are described in detail in following chapters, and in the Computing Division Product Note PN219. The libraries are created for the X86 CPU type, and are compiled with the debug option using the GNU C compiler.

4.4       Multi-User Support

 

SJY libraries supports n different processes running the on same PC reading and writing different CAMAC modules through the same SCSI host adapter and the same CAMAC controller when the software library is compiled with the semaphore functions. Otherwise, the libraries support only one process. The sjy411s.lib and sjy73a.lib libraries are now created with the semaphore functions stubbed out, but the user may rebuild the libraries with semaphore support. Using semaphores, the LINUX utility xload showed an 80% load with 2 processes (example programs).

4.5       Multi-Branch /Controller Support

 

Any combination of  Jorway 411S or 73A controllers can be installed on a PC’s host adapter SCSI bus. The limitations is that only seven SCSI devices can use the bus (one slot is taken by the SCSI bus host adapter card). Each 411S can have 2 branches, 1 branch with 62 Serial crates, and 1 branch with 7 parallel crates.

4.6       Examples

 

The SJY distribution contains compiled examples in the example sub-directories. The executables were created using GNU make, and are supplied in both source and executable format. The examples are:

 

1.        pdt : loops continuously writing an incrementing integer, reading it back, and checking for data integrity. The following output was produced running pdt with a DTM-399 Visual Display Module in CAMAC crate slot 5.

dahts2:~/sjy/example$ pdt

Usage: pdt <branch> <crate> <slot> <type: serial=0,parallel=1>

dahts2:~/sjy/example$ pdt 2 1 5 1

 1600000 pdt's complete

 

 

2.        dma: loops continuously writing and reading from a Fermilab Bench Mark Module (only) to test for data integrity. The Fermilab Bench Mark module returns incrementing integers to a block read  F2 command, so the data checking  portion of this test will show data mismatches with other CAMAC modules.

 

3.        qxtab: prints a table of Q and X responses for a CAMAC module. The following output was produced with a LRS 2249A in CAMAC crate slot 7.

 

dahts2:~/sjy/example$ qxtab

Usage: qxtab <branch> <crate> <slot> <type: serial=0,parallel=1>

dahts2:~/sjy/example$ qxtab 2 1 7 1

 

 

  S == Q=1 and X=1 

F                         1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3

      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1

A

 

 

 0    S   S           X X X                           X X X         

 1    S   S           S X X                           X X X         

 2    S   S           S X X                           X X X         

 3    S   S           S X X                           X X X         

 4    S   S           S X X                           X X X         

 5    S   S           S X X                           X X X         

 6    S   S           S X X                           X X X         

 7    S   S           S X X                           X X X         

 8    S   S           S X X                           X X X         

 9    S   S           S X X                           X X X         

10    S   S           S X X                           X X X         

11    S   S           X X X                           X X X         

12                                                                  

13                                                                  

14                                                                  

15                                                                  

 

 

4.        cnaf: executes a single CAMAC command. The data argument may be given as 0 for non-data commands. The following shows output this example program.

 

dahts2:~/sjy/example$ cnaf

Usage: cnaf <branch> <crate> <slot> <subad> <function> <data> <type: serial=0,parallel=1>

dahts2:~/sjy/example$ cnaf 2 1 7 0 25 0 1

 

CMSG called from cnaf:, data=0

 

 

5.        cz: executes a CAMAC crate initialization command.

 

6.        2249a: read out the 12 pedestals of a LeCroy 2249A ADC using the test module function and Q-Stop or single word readout mode.

 

Invoking the example programs without arguments will cause the tests to print an argument usage help, and then exit. Note that when running the tests with a Jorway 73A, the branch argument is synonymous with the 73A’s SCSI ID. A valid crate number argument must be given (1 is always safe), but is not used.

 

 

 


5.      IEEE CAMAC Standard Library

 

This function library written to control the  Jorway 411S and 73A  is based on the European Standards on Nuclear Electronics (ESONE) for CAMAC and the ANSI/IEEE CAMAC standard 758-1979. The library routines have a hidden user level interface to the generic SCSI driver sg.c.

 

All functions have been written in C; all argument types are considered pass-by-value unless they are listed with a “*”, in which case they are pass-by-reference. FORTRAN programming stubs have also been written in order to allow each procedure to be called from FORTRAN code, although these were also written in C. Each of these FORTRAN routines have names followed by an underscore (_), and have all arguments passed by reference. The C routines return MURMUR[4] error codes which are defined in the include file camac_murmur_msg_c.h found in the SJY distribution /inc sub-directory. The FORTRAN routines are type “void” and do not return values, unless they are functions. A separate call is given to return the error from the last FORTRAN command.

 

Some of the CAMAC IEEE routines have not been written - most of these concern branch operations, LAM interrupts, and booking. These functions are not currently supported in the software.

 

5.1       Argument names used in IEEE Standard Routines

 

The following names are used as arguments in the implementation of the IEEE CAMAC routines.

 

5.1.1       branch

An integer (0-255), indicating the SCSI bus and SCSI id of the Jorway. The branch should be set to 8*SCSI bus + SCSI id. There is only one controller per branch.

5.1.2   cb

A control block, a 4 integer array containing the

 

1.        Requested Repeat Count.

2.        Tally (Result repeat count).

3.        LAM Identification (not used).

4.        DMA type;  0=Q-Stop, 1=Single Word

 

5.1.3   crate

Jorway 411S: An integer (1-63), indicating the setting of the crate controller.

Jorway 73A: Not used, but should be set to 1.

5.1.4   *data16

A pointer to the first element of an array of 16 bit integers.

 

5.1.5   *data24

A pointer to the first element of an array of  32 bit integers.

 

5.1.6   ext

External address, a 32 bit integer which contains the branch, crate, slot, and sub-address of a CAMAC module.

 

5.1.7   function

An integer (0-24) to indicate the CAMAC function.

 

5.1.8   k

Contains the encoded Q and X response as follows:

 

Value of k

Value of Q

Value of X

0

1

1

1

0

1

2

1

0

3

0

0

 

 

5.1.9   lflag

An integer containing 1 for TRUE and 0 for FALSE.

 

5.1.10 q

An integer containing 1 if there was a Q response, and 0 if there was not a Q response.

 

5.1.11 slot

An integer (1-30) to indicate the slot address of the CAMAC module.

 

5.1.12 sub-address

An integer (0-15) to indicate the sub-address of the function for the CAMAC module.

 

 

5.2       IEEE Standard Routines

5.2.1   cdreg(*ext, branch, crate, slot, sub-address)

Encodes branch, crate, slot, and sub-address into ext argument.

 

5.2.2   cgreg(ext, *branch, *crate, *slot, *sub-address)

Decodes ext argument into branch, crate, slot, and sub-address.

5.2.3   cccc(ext)

Clear the CAMAC dataway pointed to by ext argument.

 

5.2.4   ccci(ext, lflag)

Set (lflag=1) or clear (lflag=0) CAMAC crate inhibit.

 

5.2.5   cccz(ext)

Initialize the CAMAC branch.

 

5.2.6   ctgl(ext, *lflag)

Test for Graded LAM, returns LAM value in flag.

 

5.2.7   cclm(ext, lflag)

Enables (lflag=1) or disables (lflag=0) LAMs on the branch defined by the ext argument.

 

5.2.8   cfsa(function, ext, *data24, *q)

Executes a single 24 bit CAMAC function.

 

5.2.9   cfmad(function, ext, *data24, *cb)

Execute a number of 24 bit CAMAC functions, while incrementing the sub-address when there is a Q response or incrementing the slot when there is no Q response.

 

5.2.10 cfubc(function, ext, *data24, *cb)

Execute a number of 24 bit CAMAC functions at the same address, until there is no Q response. If the last word in array argument cb is 0, the word read when Q is lost is not transferred (Q-Stop). If the last word in argument cb is 1, then the word read when Q is lost is transferred (Single Word). Single Word mode is not valid for transfers longer than one CAMAC word or for Jor 73A write operations. These modes are further described in the IEEE standard 758-1979.

 

 

5.3       IEEE System-Dependent Subroutines

 

These subroutines are not part of the ANSI/IEEE standard 758-1979, but are listed in its appendix.

 

5.3.1   ctstat(*k)

Return the status code of the last CAMAC operation.

 

5.3.2   cdchn(branch, lflag, route)

If the lflag argument is given as 1, it opens up a branch and maps to the SJY SCSI device. If the lflag argument is given as 0, the open SJY SCSI device is closed (from a previous invocation of cdchn with lflag=1). Note that we have followed the PN219 definitions of the arguments, rather than the appendix in ANSI/IEEE standard 758-1979, to conform to existing code.

Jorway 411S: Set the branch to the SCSI ID set with the 411S dip switches. Note that if a Serial and Parallel interface on the same Jorway have the same branch, one must use the ccctype routine to select the correct interface.

Jorway 73A: The branch should be set to the SCSI ID indicated by the front panel thumbwheel.

 

5.3.3   cssa(function, ext, *data16, *q)

Execute a 16 bit mode CAMAC function. Note that we use 16 bit words for data, unlike PN219 which uses 32 bit words for a 16 bit single word transfer. Most FORTRAN applications which used the PN219 convention can be ported by changing the cssa calls to cfsa calls.

 

5.3.4   csmad (function, ext, *data16, *cb)

Execute a number of 16 bit CAMAC functions, while incrementing the sub-address when there is a Q response, or incrementing the slot when there is no Q response.

 

5.3.5   csubc(function, ext, *data16, *cb)

Execute a number of 16 bit CAMAC functions at the same address, until there is no Q response. If the last word in cb is 0, the word read when Q is lost is not transferred (Q-Stop). If the last word in cb is 1, then the word read when Q is lost is transferred (Single Word). Single Word mode is not valid for transfers longer than one CAMAC word or for Jor 73A write operations. These modes are further described in the IEEE standard. 758-1979

 

5.4       Fermilab Extensions to CAMAC Standard Routines

These routines are not in the ANSI/IEEE standard 758-1979, or in its appendix, however they are listed in PN219, and have been found useful in the past.

 

5.4.1   camerr

Returns MURMUR status from the last FORTRAN call.

 

5.4.2   cccbyp(ext, lflag)

Set (lflag=1) or clear (lflag=0) Serial Crate Controller (SCC) bypass. Returns CAM_S_SUCCESS if successful . Returns CAM_S_PARALLEL if branch is parallel.

 

5.4.3   cccoff(ext, lflag)

Set SCC on-line (lflag=0) or off-line (lflag=1). Returns CAM_S_SUCCESS if successful . Returns CAM_S_PARALLEL if branch is parallel.

5.4.4   cmsg(sname, data, branch)

Prints an error message containing sname, data, and tally information from the last SCSI INQUIRY, the hardware version and the software version. Note the SCSI INQUIRY contains information only after a CAMAC error is detected.

5.4.5   qrespn

Get Q response from the last CAMAC operation.

 

5.4.6   xrespn

Get X response from the last CAMAC operation.

 

5.4.7   ccctype(branch, serial, parallel)

Chooses the Serial or Parallel interface for a branch controlled by a Jorway 411S. Only one of Serial or Parallel is allowed in a single process at a time (unlike the earlier UNIBUS and QBUS models.) The default is Serial. In the current implementation of the IEEE routines, one must call ccctype between CAMAC transfers to switch between the Serial and Parallel interfaces on the same Jorway 411S. Note that the ext argument for a CAMAC transfer is identical for the same crate, slot, and sub-address for Serial and Parallel crates on the same branch.

 

The Jorway 73A is a Type A controller, so the ccctype function should choose parallel.

 

Example:

                ccctype(branch, 1, 0) - chooses serial

                ccctype(branch, 0, 1) - chooses parallel

 

5.4.8   cderr

This routine is a stub; it is included for compatibility with existing IEEE FORTRAN programs.

5.4.9   csuns

This routine is a stub; it is included for compatibility with existing IEEE FORTRAN programs.


6.      IEEE Routines not supported

CTCI: Test Dataway Inhibit

CCCD: Enable or Disable Crate Demand

CTCD: Test Crate Demand Enabled

CDLAM: Declare LAM

CCLC: Clear LAM

CTLM: Test LAM

CCLNK: Link LAM to Service Procedure

CFGA: General Multiple Action

CFUBL: LAM-Synchronized Block Transfer

CFUBR: Repeat Mode Block Transfer

CGLAM: Analyze LAM Identifier

CGREG: Analyze Register Identifier

 

Unsupported Routines in the ANSI/IEEE Appendix

CCINIT: Branch Initialize

CGCHN: Analyze Channel Declaration

CSGA: General Multiple Action

CSUBL: LAM-Synchronized Block Transfer

CSUBR: Repeat Mode Block Transfer

CDCRT: Define Crate Identifier


7.      Timings

The following data rates were measured between a Fermilab (CAMAC) Bench Mark Module and a 100MHz Pentium system using an Adaptec 2940 SCSI host adapter card. In testing the  SCSI Jorway 411S, we measured  rates for Serial CAMAC using a Kinetic Systems K3952 Type L-2 Serial Controller, and for Parallel CAMAC using a Jorway Model 71B Crate Controller.

 

The timing test program called cfubc/csubc in a tight loop, using buffers that ranged in size from 2 to 32200 bytes. Times were used from the C time function. We found data rates could be described by a set-up time and a rate in kilobytes per second. The 0.2 millisecond setup time was independent of the variables used.

 

Jorway 411S

 

16 bit

24 bit

Parallel

773 Kbyte/s

1.3 Mbyte/s

Serial

330 Kbyte/s

635 Kbyte/s

 

 

 

Jorway 73A

 

16 bit

24 bit

 

1.5 Mbyte/sec

1.5 Mbyte/sec

 

 

 

7.    Performance

CAMAC programs often rely on polling loops like the one below polling for a LAM from a LRS2249a:

 

    /* poll for LAM */

    polllimit=10000;

    pollcount=0;

 

    cssa(8,ext,dataw,&qres);

    while((!qres) && (pollcount<polllimit)) {

      for (i=0; i<5000; i++){};

      cssa(8,ext,dataw,&qres);

      pollcount++;

    }

 

As noted above, each CAMAC call incurs a 0.2 millisecond setup time. This setup time is Linux system overhead, and is incurred at the beginning of every block and single word transfer. This means that under ideal conditions, the maximum polling rate with single word commands such as the cssa(8,ext,dataw,&qres)above, the maximum polling rate would be 5KHz. Because of loop overhead and the embedded spin wait loop in the above example, the maximum polling rate is about 3KHz.
8.             Appendix A: SJY Kernel Mode Driver

 

8.1       Errors Returned

Whenever an error condition generates an automatic Request Sense operation, the Request Sense buffer is saved and available for decoding by cmsg() from the IEEE library. cmsg() also performs a SCSI Inquiry to find the Jorway 411S firmware version.

 

8.1.1   Read and Write Errors

The following errors are used internally.

 

·         ENODEV: SCSI ok, no Q on transfer

·         EFAULT: SCSI ok, no X on transfer

·         EIO: SCSI problem

 

8.1.2   Implementation Notes

The Request Sense buffer returned by an error condition is automatically cleared after a good CAMAC operation.

 

8.1.3   LAMs

The SJY software does not support LAM interrupts. To have this feature, the SCSI host adapter card has to support target mode as well as host mode. None of the SCSI host adapter cards tested to date support target mode. In practice, LAM interrupts were found to be unimportant since  most users poll for LAMs.

 

The Fermilab RFD02 Programmable LAM latch module may be useful in systems requiring LAM detection and response.

8.1.4   DMA size

The maximum size for DMA transfers, using csubc or cfubc for example, is 32200 data buffer bytes.

 

CAMAC transfer length

Maximum data buffer words

24 bit

8050    (word size = 4 bytes)*

16 bit

16100  (word size = 2 bytes)

 

*A 24 bit SCSI transfer actually uses 32 bits - one byte is used for padding.

 

8.2       Known Bugs

8.2.1   Q response detection without Fermilab modified Jorway controller firmware

8.2.1.1            data transfers

The Jorway 411S and 73A return a SCSI status of  GOOD or CHECK_CONDITION for CAMAC data transfers. The CHECK_CONDITION status is returned any time the transfer length is incorrect, the transfer terminates with Q or X equal to 0, and an error was detected on the branch. Only in the Q-Stop transfer mode however, will a CHECK_CONDITION status be returned if Q=0 when the transfer length is correct. To circumvent this problem, the Q response is derived by checking the transfer length and absence of other errors.

8.2.1.2            non-data transfers

Even though the Jorway 411S and 73A return an extra status, CONDITION_MET, for CAMAC non-data transfers to indicate a Q=1response, the low level SCSI driver does not pass this status up the driver chain.

(aic7xxx driver in the case tested.) The Q response must be derived by the absence of other errors.

 

 

8.2.1.3                        System log fills with SCSI warnings with AHA-2490

Note that this problem no longer exists under the 6.2.36 version of aic7xxx.

 

To summarize, the Jorway controllers return a SCSI status 0x4 which the Linux kernel logs to either /var/log/syslog or /var/log/messages. Beside the performance hit due to logging this message with every CAMAC operation, it can create very large files that consume large amounts of disk. Since this problem lies in the Linux supplied driver(s) interpretation of SCSI status 0x4 as being out of the ordinary, we cannot provide a solution within the SJY software.

 

For users with an Adaptec AHA-2940 SCSI host adapter card  using the aic7xxx.c driver there are two possible solutions. The first is to modify the logging so that only errors are reported and not warnings. As an alternative, you may disable the SCSI status 0x4 "printk" in the aic7xxx.c driver, and rebuilt the kernel. This solution though more drastic was found to work well. Both methods are described in detail below.

 

Advansys SCSI host adapter users can check if this is a problem in their system by issuing a "dmesg" command after running a CAMAC application and by checking the system log files /var/log/messages or

/var/log/syslog.

 

(Thanks to Don Holmgren for the information given below.)

 

8.2.1.3.1                    Modify error status

To modify the error status requires changing the configuration of klogd and/or syslogd. KERN_WARNING is defined in kernel.h (in /usr/src/linux/include/kernel).  By default klogd logs everything less than = 4 (more critical) to /var/log/messages (or wherever /etc/syslog.conf specifies).  On some distributions the threshold might be different - so you may or may not get messages in /var/log/messages (or syslog) in Slackware.

 

In a Slackware 2.0.29 installation, the klogd command was modified to stop SCSI status 0x4 messages from going to the console, and syslog.conf was modified to stop SCSI status 0x4 messages from going to the syslog. To modify the klogd command, find where klogd is started (/etc/rc.d/init.d/syslog in RedHat, /etc/rc.d/rc.inet2 in Slackware) , and change the threshold for logging (see 'man klogd'). In Slackware, this meant adding the “-c n” option to the klogd command with n set to KERN_ERR. The behavior of syslog is changed via /etc/syslog.conf (see ‘man syslog.conf’) to control whether kernel messages get written to disk or not, as a function of level. In the Slackware syslog.conf, *.warn was changed to *.error.

 

8.2.1.3.2          Disable warning message in driver

If you want to rebuild the driver with the printk commented out, you can just rebuild the driver if it's a loadable module.  If the kernel has the driver built-in, you should rebuild the kernel.  'make modules' should

rebuild only aic7xxx.c if that's the only source you've modified.  Remember to either 'make modules_install', or copy the new aic7xxx.o to the /lib/modules/2.0.xx/scsi directory.

 

In a Slackware 2.0.29 installation, line 2873 was simply commented out. The code line is:

/*printk(KERN_WARNING “scsi%d: Unexpected target status 0x%x.\n”, p->host_no, scb>target_status);*/

 

 

 

 

8.2.2   Semaphores

There is a system semaphore used by SJY for multi-user capability. Unfortunately, LINUX preserves the semaphore across boots. Even worse, after a re-boot the semaphore ID is reset to 0, making it unusable by the SJY software. If this semaphore with semaphore ID of 0 is not removed, the SJY software will freeze in the first semget call. The simple solution is to remove the semaphore and its associated key file by hand after a re-boot with the following commands:

 

mynode: ipcs

------ Shared Memory Segments --------

shmid     owner     perms     bytes     nattch    status     

 

------ Semaphore Arrays --------

semid     owner     perms     nsems     status     

1920      jones       777        1        

 

------ Message Queues --------

msqid     owner     perms     used-bytes  messages   

 

mynode: ipcrm sem 1920

resource deleted

 

mynode: rm /tmp/sjykeyfile

 

Note that this is not a problem if using the non-semaphore version of the SJY libraries.

  

8.3       SJY build, debugging, and test environment

 

8.3.1   Rebuilding the Jorway 411S/ 73A libraries

The flavor of library built is controlled by a define switch in the sjy/src/Makefile. To build the 411S library, the Makefile CFLAGS definition should include the switch -DSJY411S. To build the 73A library, CFLAGS should include the -DSJY73A switch. Please note that only one of these switches can be defined in CFLAGS at once. The Makefile always produces a library with the name /lib/libsjy.a, so each library should be appropriately renamed if one is re-building both libraries.

 

8.3.1.1     Rebuilding without semaphores

Rebuild the libraries using the instructions above. The file src/sjy_semops.c contains the stubbed version of the semaphore functions.

 

8.3.1.2     Rebuilding with semaphores

Copy the file src/sjy_semops.c to src/sjy_semops.c.stub. Move the file src/sjy_semops.c.orig to src/sjy_semops.c. Rebuild the libraries using the instructions above.

8.3.2   Development platform

A 100Mhz INTEL pentium system running LINUX 2.0.29 with an Adaptec AHA-2940 SCSI host adapter was the development platform.

8.3.3   CAMAC test module

A Fermilab Bench Mark Module was used for the both the Jorway 411S and Jorway 73A timing tests. However, any CAMAC module that is capable of  24 bit F16 write/ F0 read operations may be suitable for the pdt test.

 

9.      Release Notes

9.1       V1.1

The 24 bit word size mode bit was set incorrectly in sjy_cfsa.c, sjy_cfubc.c, and sjy_cfmad.c for the Jorway 73A. This has been corrected in this release.

 

9.2             V1.2

Bug fixes:

·         Added internal documentation to dma.c test program to indicate it only works with a Fermilab Bench Mark module.

·         Also in dma.c  - corrected block[2] declaration to block[4], fixed error display indexes.

·         sjy_cfubc.c – corrected write to sjy_write.

·         sjy_interface – zero users output data buffer if CAMAC command fails.

·         sjy_cmsg.c – corrected dma byte count display for Jor 73A.

·         Added documentation corrections and additions to the dma test program portion of this document and the descriptions of the CAMAC library routines sjy_csubc.c and sjy_cfubc.c.

 

 

 

9.3       V1.3

Bug fixes:

·         Corrected SCSI device file selection in sjy_cdchn.c. Previously the SCSI device file selector index was incremented only if non-Jorway devices had the type “Unknown”. Now the SCSI device file selector index is incremented for all non-Jorway devices listed in /proc/scsi/scsi.

 

Documentation:

·         Added minor clarifications throughout document.

·         Added documentation on building the SJY library without semaphores.

·         Added documentation on the SCSI status 0x4 problem.

 

 

9.4      V1.4

The sjyLX libraries compiled under 2.0.29 were found to be incompatible with Redhat 5.2.1. The example programs would core dump. This version is a recompilation under Redhat 5.2.1 to address this problem.

There is also an additional example program named 2249a that demonstrates reading out the LeCroy 2249A TDC with a single word and Q-Stop readout.

 

 

9.5             V1.5

The interface between the IEEE CAMAC functions and the Linux SCSI generic driver, sjy_interface.c, was

modified to eliminate extra memcpy() calls. The CAMAC function library has been extended to allow for multiple SCSI bus systems. Previously, the library would only work correctly if the Jorway was connected to SCSI bus 0. The SCSI bus number is now encoded in the branch argument as follows:

branch = SCSI id + 8*SCSI bus

In a single SCSI bus system, no modification is required to user code.

 

 

 

9.6             V1.6

Added support for “short transfers” (number of words returned from block read less than the number of words requested). This affects the csubc/cfubc, csmad/cfmad routines. Previous to v1.6, short transfers

were considered to be an error, and the user buffer was returned zeroed.

 

 

 

9.7             V1.7

Returns  correct number of words read for short transfers described in v1.6 above. Previously, always returned the requested transfer length.

 

 

 

9.8             V1.8

Added Thomas Hadig bug fix to cjy_cdchn.c for multiple controllers. Previously, sjy_cdchn.c did not

correctly increment the SCSI device number when searching for a matching SCSI id/bus number. Tested

under the 2.4.3-12 RH kernel.

 

 

 

9.9             V1.9

Modified sjy_interface.c because CAMAC non-data commands returning Q=1 were not sensed with newer versions of the sg driver(> 2.1.39). Function handle_scsi_cmd uses sg_hd->target_status instead of deprecated sg_hd->result. Function sjy_notify_camac_nondata now makes an explicit check for SJY_CONDITION_MET.

 

** This version was built for Fermi RedHat 7.1.1 using the 2.4.3-12 kernel, but there is a bug in the SCSI

generic driver sg associated with this kernel, version 3.1.17. The bug manifests itself by crashing a running CAMAC program with a “segmentation fault”. The oops output identifies the routine “generic_unplug_device”. This is apparently caused by a race condition in the sg driver, which was fixed in the 2.4.10 kernel. The only solution at this time is to use the 2.4.10 (or higher version) kernel with sg driver version 3.1.20 or higher.

 

9.10         V1.9.2

Cleaned up –Wall warnings for library and examples.

 

9.11         V2.0

Modified single word and block transfer Q response handling to work with modules using zero data suppression like the LRS TDC 3377. This change requires the Fermi modified Q response Jorway controller firmware that returns SCSI response 0x04 for a Q in data transfers. This modification was tested with a Jorwary 73A controller and a Fermilab Linux system using kernel 2.4.18-10.

 

9.12         V2.1

Fixes for bugs identified by Thomas Hadig. Limited sscanf in sjy_cdchn.c to 9 characters to prevent long vendor and type names from exceeding the array size. Increased SJY_MAX_SJY73A in camac_globals.h from 7 to 21 to account for up to 3 SCSI buses in one host.

 

9.13         V2.2

Casts and type changes to satisfy g++ in sjy_cdchn.c, sjy_cmsg.c, and sjy_interface.c. Added extern ”C”

declaration to ieee_fun_types.h.

 

9.14         V2.3

Increased size of internal driver data structure in camac_globals.h to account for systems with 3 SCSI busses. Changed the size of the SJY411S non-data command size from 12 to 6 to account for more strict data checking in the SCSI generic driver.

 

9.15         V2.4

Changed the size of the 411S non-data command from 6 to 10. Added section to this document to describe problem with 411S and the aic7xxx SCSI host bus adapter driver.

 

9.16         V2.5

Changed the size of the 411S non-data command from 10 back to 6. Added an extra ioctl call to sjy_interface.c to set the 411S non-data command size before the write phase. This change makes it possible to use the Adaptec driver aic7xxx without getting warnings logged to /var/log/messages.

 

 

 



[1] The word “Driver”, capitalized, refers to the Jorway 411S Branch Driver hardware. The word “driver”, not capitalized, refers to driver software.

[2] The Jorway Corporation, 27 Bond Street, Westbury, NY 11590.

 

[3] All documents with the label PNnnn or HNmmm refer to Fermilab Computing Division Documents, many of which are available at the WWW address

http://cd-docdb.fnal.gov/

[4] DART Message Reporter, document number PN457.