README

$Id: README,v 1.17 2007/12/03 09:59:21 tomazb Exp $

CSPI -- Control System Programming Interface

Copyright (C) 2004-2006 Instrumentation Technologies
See the COPYING file for copying conditions.

Control System Programming Interface (CSPI) is a high-level C library
that allows you to implement a range of applications for the Libera
family of processors in a consistent and documented way.

CSPI separates control-system specific knowledge from low level
details and logic related to a Libera processor. Using this model, the
underlying software (i.e. the Libera GNU/Linux driver) or hardware can
undergo a change without affecting the application.

CSPI also allows for maximum interoperability -- an application can
access data from different Libera data sources and even different
members of the Libera family through a single interface.

Directory listing:
DOC	- documentation
SRC	- source files

1. BUILDING

To build the CSPI library, you require headers for the GNU/Linux
driver for Libera. Please review and, if necessary, edit the
configuration section of the Makefile to match the location of the
headers on your system. Next, type:

  cd src
  make

When cross-compiling, either set the toolchain prefix (CROSS_COMPILE)
in the configuration section of the Makefile or on the command line:

  CROSS_COMPILE=arm-linux- make

To install the library, type:

  make install

This will copy library files to the location specified in the
Makefile.

Libera Electron: CORDIC algorithm is used to calculate apmlitudes from
I and Q values. CORDIC is an iterative algorithm. In the process, the
amplitude is multiplied by a CORDIC Gain (cumulative magnitude) of
about 1.647. The actual CORDIC gain depends on the number of
iterations.

For positions X and Y alone, the CORDIC gain is irrelevant and the
processing speed can be somewhat improved by building the library with
CORDIC_IGNORE_GAIN defined.

2. USING

First, you should include the driver and library header files in your
application:

#include "libera.h"
#include "cspi.h"

Next, when passing options to GNU C compiler, you should use -lcspi to
link the application against the library.

To find out more about the library, see CSPI User's Guide in the
documentation directory.  To learn how to use the library functions,
see CSPI Reference in the documentation directory.

Libera Electron: The src/test directory includes two sample data
acquisition utilities called 'libera' and 'acquire'. The later is
deprecated and may be removed in the future. Consider using 'libera'
instead. To learn more about usage, run libera with option --help:

  libera --help

When run with option --acquire, the utility outputs one sample per
line to standard output. The ordering and meaning of the values depend
on the selected data source.

With option --using-dd or --using-pm specified, each sample consists
of eight whitespace separated integer values:

  Va, Vb, Vc, Vd, X, Y, Sum, Q
  or, with option --raw specified,
  cosVa, sinVa, cosVb, sinVb, cosVc, sinVc, cosVd, sinVd

With option --using-sa specified, each sample consists of ten
whitespace separated integer values. Units (where applicable) are
nanometers:

  Va, Vb, Vc, Vd, X, Y, Sum, Q, Cx, Cy

With option --using-adc specified, each sample consists of four
whitespace separated integer values:

  chA, chB, chC, chD

With option --binary, data is not formatted as text and is instead
output as a binary stream of samples, or more precisely, as a stream
of 32-bit integer values (16-bit for ADC-rate data). This allows for
faster acquisition and off-line processing (i.e. integration into an
application such as Matlab).

When run with option --set-environment, the utility reads Libera
environment parameters from standard input. In this way, to set the
Libera environment, use:

  libera --set-environment < my_conf_file

Sample environment and gain configuration files are included with the
program. The later allows one to set analog board attenuators based on
input power, using a predefined gain scheme.

A configuration file should consist of parameters of a form:
NAME VALUE

The configuration file is line-based - that is, each
newline-terminated line represents either a comment, or a
parameter. Parameter names are case sensitive. Leading and trailing
whitespace in parameter names and values is irrelevant and
discarded. Any line beginning with a hash ('#') character is ignored,
as are lines containing only whitespace.

  libera --set-environment < env.conf
This will set Libera environment parameters listed in the
configuration file. See sample configuration file env.conf
included with the utility for more information.

  libera --acquire --on-trigger --using-dd 1000 > some_file
This will acquire 1000 data-on-demand samples on trigger into
some_file. The operation will time out after 30 seconds if no
trigger is received.

  libera --acquire --on-trigger --using-dd --with-timestamp \
         --loop --raw 1000 > /dev/null
This will acquire data-on-demand on trigger in a loop,
discarding the data and printing a timestamp only on each
iteration.

  libera --set-time :200602091223.00
This will set the system time (ST) at next trigger to Feb 09
12:23:00 2006. Machine time (MT) will not change.

Libera Bunch-by-Bunch: A sample data acquisition utility called
'libera-bbfp' is included in the src/test directory. To learn more
about usage, run libera-bbfp with option -h:

  libera -h

The utility outputs four samples per line to standard output.


3. LIMITATIONS

Libera Electron: The variable 'sum' of the CSPI_DD_ATOM structure
returned by the cspi_read or cspi_read_ex has two least significant
bits truncated to prevent an overflow.


This version of CSPI has been developed and tested using:
- gcc 3.4
- Libera driver 1.80
- FPGA design 1.80