CAMAC++

04 July 2000
CAMAC++
Steve Wotton

1 Introduction
This document describes a primitive C++ CAMAC library for systems which utilise the CES CBD8211 CAMAC
branch driver. No attempt has been made to preserve the familiar calling sequences of standard CAMAC libraries.
The motivation for providing this library is to ease the integration of CAMAC systems into modern data acquisition
environments where portability between different operating systems and different hardware environments may be
important. The library is incomplete and under development.
The library has so far been used on the following systems:
• HP742 VME SBC running HPUX
• PC running Windows NT using the National Instruments PCI-to-VME interface.
• SBCs running OS9
• CES RIO running LynxOs
The g++ v2.7.2 compiler has been used except on WNT where Borland C++ v5 was used. It should be
straightforward to modify the library for use in other similar systems. The main requirement is that the host system
should support transparent addressing of the VMEbus. On virtual memory systems (like the HP) this is done by
mapping the physical address space of the CBD into the user's virtual address space. On non-virtual addressing
systems (eg OS-9) the corresponding address mapping function would simply return the "physical" address of the
module. All this architecture dependent stuff is hidden in a vme class for easy portability.
2 About the CAMAC branch driver
The CBD can drive a single CAMAC branch containing up to 7 crates. The physical VME base address of the CBD
depends on the branch number selected with the front panel switch. The base address is then given by the expression
(0x800000 | (N

3.1.1 Member functions
Member function Operation Returns
cbranch(vme *VME, const char brname[], const char config[]) Constructor(1) -
cbranch(vme *VME, CAMACD *address, unsigned brnumber,
Constructor(2) -
const char config[])
3.1.2 Description of arguments
Name
Notes
VME Pointer to VME++ object
brname Name of branch as identified in VME++ configuration file
config Configuration file name or environment variable name
address Physical base address of CBD
brnumber Physical branch number
The following example configuration file describes a system having two camac crates on branch 0 with two
CAMAC modules in each crate:
branch: 0 0x800000
crate: 1 crate1
module: 16 tdc lrs2228
module: 21 scalar1 lrs2551
crate: 2 crate2
module: 7 scalar2 lrs2551
module: 8 scalar3 lrs2551
Each line has one of the following forms:
branch: number CBD_addr
crate: number name
module: slot_number name type
The "name" parameters are arbitrary and are used to locate the named object in the internal lists. The "number"
parameters must be consistent with the hardware configuration. The module "type" parameter is used to determine
which concrete class of module to instantiate.
Refer to the example program for more details.
The alternative form of the constructor cbranch(vme,addr,i,file) allows the creation of a branch to which
crates and modules may be added later by explicit calls to ccrate and cmodule constructors in the user program.
Note that the name of an existing file is still required as this is identified with a semaphore created by the library.
However, in this case, the file may be empty - the branch number and physical address of the CAMAC branch driver
are passed explicitly as constructor arguments.
3.2 The class ccrate
This class represents a CAMAC crate and implements the functions used for crate initialisation and control:
Member function Operation Returns
ccrate(cbranch *branch, int id, char *name ) Constructor -
void reset(void) Crate reset (CCCZ) -
void clear(void) Crate clear (CCCC) -
int clrInhibit(void) Clear inhibit (CCCI) Inhibit state
int setInhibit(void) Set inhibit (CCCI) Inhibit state
int testInhibit(void) Test inhibit (CTCI) Inhibit state
int clrDemand(void)
Clear demand (CCCD) Demand state
int setDemand(void) Set demand (CCCD) Demand state
int testDemand(void) Test demand (CTCD) Demand state
3.3 The class cmodule
This class is an abstraction of a CAMAC module and is used to define the interface functions which all derived
classes must provide. Currently the following functions must exist: read, test, clear, execute. See camac.h for
implementation details.
3

CAMAC defines a set of function codes which perform more or less standard operations on all CAMAC modules
(although not all functions are implemented on all modules). The following is a suggested convention for the
cmodule member function names corresponding to the CAMAC function codes F0-31:
CAMAC read member function CAMAC control member function CAMAC write member function
F0 read F8 testLam F16 write
F1 read2 F9 clear F17 write2
F2 readClear F10 clearLam F18 setSelective
F3 readComplement F11 clear2 F19 setSelective2
F4 - F12 - F20 -
F5 - F13 - F21 clearSelective
F6 - F14 - F22 -
F7 - F15 - F23 clearSelective2
- - F24 disable - -
- - F25 execute - -
- - F26 enable - -
- - F27 test - -
- - F28-F31 - - -
CAMAC Q, X and timeout responses are placed into cmodule::errno which should be checked after every
CAMAC operation which may affect these flags. If 0, no error occurred otherwise bit 0 set indicates CAMAC
timeout, bit 1 set indicates no X response and bit 2 set indicates no Q response.
4 Locating modules
The class library constructors build internal data structures which are lists of which crates belong to a branch and
which modules belong to a crate. Modules may be located by name, the module and crate names being defined in
the branch configuration file. The example program illustrates how to locate the module called "scalar" in the crate
named "crate2". Note the type cast to the actual type of the located module. This expression should be used as a
model for locating other modules.
5 Extending the library
Every CAMAC module in a system is represented by a concrete class derived from class cmodule. Adding support
for new modules means deriving a new class from cmodule which must implement at least the read, test,
clear and execute member functions (although they may be dummy). The simple classes lrs2228 (a D16
module) and lrs2551 (a D24 module) in camac.h serve as simple examples. One should not forget to set
cmodule::errors depending on the CAMAC response.
6 Error handling
For maximum portability C++ exception handling has not been used in this library. Instead, each class contains a
public data member, errors, which behaves as a trace buffer into which arbitrary text can be placed for later
display. This strategy has the advantage of allowing constructors (which cannot return values) to report errors in the
same way as other member functions and also allows messages to be reported from deeply nested function calls and
still allow the error to be precisely located. The trace buffer continues to accumulate error messages until flushed to
cout or cerr using the

8 Multitasking
The hardware must be protected against concurrent access which may arise in a multitasking environment where
more than one process may try to access a CAMAC branch. One possibility would be to confine all CAMAC
operations within a single process. Another possibility would be to protect all CAMAC operations with a
semaphore. In order to avoid incurring any unnecessary software penalties the responsibility of protecting the
CAMAC operations has been left to the user. The example program illustrates the use of the branch semaphore. This
approach has the disadvantage that users can cheat by not protecting CAMAC access with the semaphore either
deliberately or inadvertently (e.g. by using an alternative CAMAC library with different or no protection
mechanism). Note that the semaphore is used in the library to protect the branch initialisation.
Another potential problem in a multi-tasking environment is that of initialisation. Typically the hardware
initialisation should be done only once. Since an initialisation function is called from the class constructors and only
the first use of a constructor by any process in the system should perform initialisation, a second semaphore is used
by the library to guarantee this behaviour. The initialisation routines can always be called from the users program at
any time in order to reinitialise part or all of the CAMAC branch. Again, it is possible to cheat the concurrent access
protection scheme.
8.1 Interrupts
Interrupt handling (generated in response to LAMs) is not implemented. On the HP this would require the
implementation of a device driver. On OS9 a device driver already exists but needs to be integrated with this library.
The Nat. Inst. PCI-VME interface has user-callable software to install interrupt handlers so implementation of LAM
interrupt handlers should be easy here. The main problem is to make the library behave the same on all platforms
given the constraints of using the already existing software.
8.2 C-binding
These functions are implemented as jacket routines to the C++ API. The CBRANCHID and CMODULEID type
arguments are actually pointers to the underlying C++ objects and should never be directly manipulated by a C-
coded application. They serve as context arguments used by the library. Since these are jacket routines, this code is
hardware independent and is split off into a separate file, ccamac.cpp
Function Operation Returns
int opencbranch(CBRANCHID *cid, VMEID vid,
const char *file)
Setup CAMAC branch using
configuration file
error
code
int closecbranch(CBRANCHID cid)
Close CAMAC branch
error
code
int getcbranch(CBRANCHID cid)
Get exclusive access to (lock) branch error
code
int releasecbranch(CBRANCHID cid)
Release lock on branch
error
code
int getcmodule(CBRANCHID cid, CMODULEID *mid,
error
Get pointer to named module
const char *crate, const char *module)
code
int cfnr(CMODULEID mid, int A, int *D, int fn) Perform read operation
QXT
int cfnw(CMODULEID mid, int A, int D, int fn) Perform write operation
QXT
int cfnc(CMODULEID mid, int fn) Perform control operation QXT
Where the return code is indicated as QXT this means a bitmask indicating the status of the CAMAC Q, X and T
response in the least significant 3 bits or some other error code in higher order bits.
In addition to these routines it is also necessary to initialise the VME interface using the openvme() and
closevme() from the VME library as in the example program.
9 Built in support for CAMAC modules
Support for a number of specific common CAMAC modules is included in the library. The following modules are
known in addition to generic 16bit and 24bit data modules:
Module Description
LRS2228 TDC
LRS2229 TDC
5

LRS2249 ADC
LRS2551 Scaler, 12ch.
LRS4416 Discriminator
LRS4418 Programmable delay, 16ch
LRS4516 Programmable Logic Unit
LRS4432 Scaler, 32ch.
or2027 Output register, 16ch.
LRS2341 Input register, 16ch.
c85 CAEN Programmable logic unit
10 Example C++ program
11 Example C program
6