W. Grandegger, E. Pasqualucci, I. Sfiligoi

Methods and Rules for KLOE Level-1 Software Development

The purpose of this document is to define rules and methods for level-1 software development.

The strategy to build the test tools for the KLOE readout system is based on the integration of different libraries, each of them written to access a given module. In order to allow an easy integration, each developer has to follow some simple rules regarding software portability, use of common tools and libraries, general programming criteria, naming conventions, and documentation.

As for the general rules of the KLOE online software, the rules and methods described here should be regarded as a starting point for discussion. So, if some rule will be added or modified, according to developers' experience, this document will be updated accordingly. The updated topics will be marked with .

Packages and general rules
Software portability and supported OS
Naming conventions
Operations on registers
Bit and mask manipulation
Error management
Some other useful criteria

Packages and general rules

While in a second step all the software will be included in a single package, each developer has to create his own package in order to develop the software related to a board, following the naming conventions described in the following.

All the rules contained in the general document about the online software development hold if not otherwise specified.

It is mandatory to use packman to configure and maintain the software. Once a version of a package will be released, it will be freezed and integrated in the level-1 general package and a new version will be created as developing area.

Each version of a package must be certified both by the responsible of the related board and by the responsible of software integration.

Software portability and supported OS

The KLOE DAQ and online environment is a distributed heterogeneous UNIX environment. Various UNIX operating systems, mainly HP-UX, OSF/1, LynxOS, are in use on different hardware platforms including VME processor boards. All the level-1 software must support almost these three OS.

Some general criteria have to be followed to build multi-platform code with only one set of source files:

use of ANSI C with prototyping.

use of C preprocessor directives like #define, #ifdef etc. to handle platform dependent source code.

use of Makefile built as described in the document about general online software rules.
use of the symbol COMMONCC in the Makefile to define the compiler with the right options.
use of released online libraries and tools whenever possible: all this software works on the supported operating systems, making easy to implement portability. For instance, VME in the currently released version provides a set of portable functions to access Vme; other facilities are provided in common. Please look at the KLOE online documentation.

Furthermore, all the released tools, such as the TL compiler to produce graphic interfaces and the source2html or c2html tool to produce updated documentation in HTML format should be used.

Naming conventions

Some naming conventions have to be adopted to avoid entry point duplication and to build easy-to-read software. These conventions applies to:

Package names:
use short, simple names, possibly referred to the module you are working on (for instance: adc, tcd, rock...).
Library source file name:
provide one source file containing library functions, calling it consequently (for instance: adclib.c, tcdlib.c, ...).
Library name:
use the "unix default" name (like libadc.a, libtdc.a, ...).
Function and macro names:
use long and self-explaining names, beginning with package name in one of the following forms:
```
       	adc_load_pedestals     (preferred)
        AdcLoadPedestals
```
Choose one or the other, anyway, please be coherent!

Almost one include files must be provided, named package.h or package_public.h, containing:

All the needed generic constants. The names of the constants must be in capital letters and must begin with the package name; long self-explaining names are strongly recommended. For instance:
```
	#define TDC_MAX_TDC_NUMBER    256
```

        #define ADC_REGNAME_OFFSET  0x24

Bit field positions and lengths (or positions and masks):

        #define ADC_FIELDNAME        4  /* begins at the 4th bit */
        #define ADC_FIELDNAME_LEN    2

or the equivalent:

        #define ADC_FIELDNAME        4  /* begins at the 4th bit */
        #define ADC_FIELDNAME_MASK   3

Macro definitions:

        #define adc_set_fieldname(id,value)  definition

Public structures

Error codes, for instance:

        #define ROCK_ERR_SYNCFAIL  errcode

Function prototypes:
```
        void adc_load_pedestal (adc_id id, int ped);
```
Please name the variables in function prototypes; it is not needed by the compiler but helps to make the code readable.

Another include file can be provided if encapsulated type definitions are needed. This file will be called package_private.h.

Operations on registers

Simple operations on registers (such as read, write or modify operations) should be implemented using macros and an easy-to-learn naming scheme:

	#define package_operation_register-name

For instance, to read the register called pippo in the adc, in the public include file you will have:

        #define ADC_PIPPO_OFFSET    0x32

        #define adc_get_pippo (id, val_pippo) \
                               VmeRead(id.cid, ADC_PIPPO,\
                               (char *) &val_pippo,\
                               sizeof (val_pippo))

In general, working with macros helps to have compact and efficient code, avoiding overload. A macro can easily implement low-level operations. Furthermore, writing a macro for each register allows the user to work easily, calling the appropriate procedures for each operation on the hardware.

Bit and mask manipulation

To implement operations on bits or bit fields similar criteria should be used. A basic macro should be provided to implement each operation for each bit field; bit and field manipulation can be performed by using the utility bits, included in the common package. For instance, to set the flag called MYFLG in the ADC register PIPPO:

	#include "bits.h"

        #define ADC_PIPPO_OFFSET   0x20

        #define ADC_MYFLG          4

        #define adc_set_myflg (id, value) \
                              {char rval;\
                               VmeRead (id.cid, ADC_PIPPO,\
                                        &rval, sizeof (char));\
                               bits_set_bit (rval, ADC_MYFLG,\
                                             value);\
                               VmeWrite (id.cid, ADC_PIPPO,\
                                         &rval, sizeof (char));}

It is possible to manage bit fields (see bits documentation). Use macros to manage single fields; use functions to perform complex operation, such as modifying two fields in the same register. This will avoid overload due to unuseful VME accesses when calling two `set' macros.

Error management

Use the Error library (included in the package common) to manage error conditions.
Define error codes (and messages) in the public include file.
It is possible to assign a severity bit and to assign an offset to each module.

Some other useful criteria

Please provide:
Updated documentation in standard HTML form, possibly using source2html or c2html.

Comments inside the code.

Simple example applications.

If possible, build graphic tools using the TL compiler and tcl/tk.
Do never use external variables; in order to access global variables in the library provide access functions. Anyway, avoid the use of global variables whenever possible.
Do never use as function parameters command strings to be decoded.
Describe macro and function parameters with comments (see for example bits.h).