Contents:

Introduction

This document contains a description of the hardware access library for the Pierre Auger Fluoresence Detector Electronic (FE) other experiments. The library provides (nearly) the same functionality for Linux and Windows and Apple operating system.

The library is divided in three layers:

Application Programmers Interface This layer provides the interface to the for the application programms. The function of this layer are rather independent from the realization of the hardware.
The register model layer implements the address model of the hardware. Changes in the hardware structure will also cause changes in this layer. This means also that for the different experiments own register models exist. Implemented are:

Pbus Interface This layer provides the interface to the hardware via the Pbus protocol (simple VME bus type).

Included in the package are some more general utility functions:

Dependancies of the libraries in the package

   akutil
  
   akshell -- akutil
  
   
   calib -- Hw -- Pbus\<AccessType\> -- akutil
  
   am_testutil -- Hw -- Pbus\<AccessType\> -- akutil
  
   FEdata --Hw --Pbus\<AccessType\> -- akutil
    
  
   FE -- Hw -- Pbus\<AccessType\> -- akutil
  
   Hw -- Pbus\<AccessType\> -- akutil
   
   Pbus\<AccessType\> -- akutil

Usage

Projects using the hardware access library need to add the directory fdhwlib/fdhwlib to their include path.

Example (Auger API):

#include <FE/FE.h>

main(){

  FE fe;
  FE fe.config.init();
  ...

}

Linking the project it is necessary to add the hardware access library and Pbus library.

Example (Katrin Register Model):

#include <katrinhw/kasubrack.h>

main(){

   KaSubrack *s;
   s = new KaSubrack(katrin.ini);
   ...
}

Directory Structure

The directory fdhwlib contains project file for Kdevelop/Linux and MS Visual C++/MS Windows to create the approritate version of the library. The sources for the different layers can be found in the directories fdhwlib/FE, fdhwlib/Hw and fdhwlib/Pbus. Some more general utilities will be found in fdhwlib/akutil. The definition of the KATRIN hardware model is based on the same generic classes used in the Auger register model. All KATRIN specific classes can be found in fdhwlib/katrinhw

The documentation generated can be found in the directory fdhwlib-api. It is available in html and latex format.

Compilation of the libraries

Linux

To compile and install the library use the commands

./configure
./makeAll
./makeAll daq
./make doc
./makeInstall
./makeInstall daq

Without the argument "daq" no fd-das or ROOT support is required. For most applications it may be sufficient to omit creating the fd-daq dependant part of the package.

The package requires some external packages. These are Root, fd-das and the microEnable drivers. Use the environment variable CPLUS_INCLUDE_PATH to specify the path to the header files. E.g. use

CPLUS_INCLUDE_PATH=/usr/software/fdhwlib/include:
       /home/kopmann/FD-das/include:/home/kopmann/FD-das/mirror/include:
	   /cern/root/include:/usr/src/menable/include:/usr/lib/qwt/include:

To install the package it is necessary to have write access to the install directory /usr/software.

Windows

For all libraries a MSVC project exists. Use these to compile a separate library.

To generate all libraries use the script fdhwlib/makeAll.bat. The script accepts two additional arguments to generate the menable and daq dependant parts of the library. For these libraies it is required to specify the location of the required packages (menable + daq + root) in the INCLUDE environment variable. The path of the root libraries has to be added to to the LIB environment variable.

makeAll                  Generate the standard libraries
makeAll menable          Generate menable depandant part
makeAll daq              Generate daq dependant part

To use the libraries add the directory fdhwlib/fdhwlib to the include path and all required fdhwlib/fdhwlib/<subdir>/debug directories (e.g. fdhwlib/fdhwlib/Hw/debug) to the library path.

Documentation

The documentation can be automatically generated from the header files using doxygen (or other programs handling javadoc type comments).

Using "make doc" will generate documentation for all packages.

Build system internals

The packages uses the standard build system of the kdevelp IDE and MSVC where this is possible and sufficient. However in some case it turned out to be adequate to provide additional scripts. The scripts are named on both platforms as "makeAll" and "makeInstall". The scripts will accept additional arguments ("daq", "meanble") to create microenable or DAQ dependant parts of the package.

Central with kdevelop are the files Makefile.am in every directory of the projects. The configure step will generate from this file the required Makefiles. Some manual work has to be done in the scripts to activate all make options and to install some parts that are not installed automatically.

In MSVC the information of the build process is hidden in the DSP project files. It is possble to generate makefiles (extension MAK) for Microsofts nmake program. The redundand MAK files allow to build the whole project automatically from the command line and to control the make process by script files.

Remark on version numbers

There are several version numbers used in the package fdhwlib. First comes the overall version of the package It can be found in the files fdhwlib.h config.h (only in the development version, not included in the tar-ball!) somewhere in the kdevelop project file and in the doxygen configuration. The project file will automatically update config.h but not the other places. This has to be done manually. All files should show the same version number.

There are other version numbers that are hardware related. The purpose of these numbers is to keep the library compatible with older versions of the hardware design. The version numbers are used in this case for conditional comiplation. (PBUS_VER, FLT_VER and FLT_VER).