04 July 2000 CAMAC++ Steve Wotton

Transcription

1 04 July 2000 CAMAC++ Steve Wotton

2 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 (0x (N<<19)) where N is the selected branch number. This information, and the width of the address space containing the CBD branch registers (0x10000), must be passed to the VME library using the VME configuration file (the National Instruments implementation uses its own VME configuration database). Here is an example VME configuration file for a VME system containing a CBD: # File is read using C-style format " %s %d %i %i %i " # The fields are: # name, logical address, physical address, size, address space( A16,24,32 ) branch1 4 0x x other VME modules Note that in the example the CBD is driving branch 1. Also note that it is only necessary to specify the width of the address space large enough to span the branch registers (0x10000 is the minimum value which satisfies this requirement). The address space corresponding to the individual CAMAC crates is not included in the above but is mapped in by the CAMAC library as required. The description of the CAMAC branch (crates and modules) is contained in a separate configuration file described below. 3 The classes There are three basic classes in the library which describe the logical concepts of CAMAC branch (cbranch), CAMAC crate (ccrate) and CAMAC module (cmodule). cmodule is an abstract class from which concrete classes representing actual CAMAC modules must be derived. The constructors of the above classes take care of doing any desirable initialisation. 3.1 The class cbranch The cbranch constructor has two forms. The recommended form cbranch(vme,file) reads the branch configuration from an ASCII file and causes the ccrate and cmodule constructors to be called as required. Note that the cbranch constructor takes a pointer to an object of class vme as an argument. The vme class takes care of initialising the VME interface. 2

3 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[]) 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 0x 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

4 CAMAC defines a set of function s 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 s 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-F 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 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::s 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, s, 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 s in the same way as other member functions and also allows messages to be reported from deeply nested function calls and still allow the to be precisely located. The trace buffer continues to accumulate messages until flushed to cout or cerr using the << operator. The trace buffer is then truncated to zero length. See the example programs for how to test for conditions in this scheme. 7 Advanced features 4

5 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- d application. They serve as context arguments used by the library. Since these are jacket routines, this 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 int closecbranch(cbranchid cid) Close CAMAC branch int getcbranch(cbranchid cid) Get exclusive access to (lock) branch int releasecbranch(cbranchid cid) Release lock on branch int getcmodule(cbranchid cid, CMODULEID *mid, Get pointer to named module const char *crate, const char *module) 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 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 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

6 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