i-tech-brillance

README

b'$Id: README,v 1.17 2007/12/03 09:59:21 tomazb Exp $\n\nCSPI -- Control System Programming Interface\n\nCopyright (C) 2004-2006 Instrumentation Technologies\nSee the COPYING file for copying conditions.\n\nControl System Programming Interface (CSPI) is a high-level C library\nthat allows you to implement a range of applications for the Libera\nfamily of processors in a consistent and documented way.\n\nCSPI separates control-system specific knowledge from low level\ndetails and logic related to a Libera processor. Using this model, the\nunderlying software (i.e. the Libera GNU/Linux driver) or hardware can\nundergo a change without affecting the application.\n\nCSPI also allows for maximum interoperability -- an application can\naccess data from different Libera data sources and even different\nmembers of the Libera family through a single interface.\n\nDirectory listing:\nDOC\t- documentation\nSRC\t- source files\n\n1. BUILDING\n\nTo build the CSPI library, you require headers for the GNU/Linux\ndriver for Libera. Please review and, if necessary, edit the\nconfiguration section of the Makefile to match the location of the\nheaders on your system. Next, type:\n\n cd src\n make\n\nWhen cross-compiling, either set the toolchain prefix (CROSS_COMPILE)\nin the configuration section of the Makefile or on the command line:\n\n CROSS_COMPILE=arm-linux- make\n\nTo install the library, type:\n\n make install\n\nThis will copy library files to the location specified in the\nMakefile.\n\nLibera Electron: CORDIC algorithm is used to calculate apmlitudes from\nI and Q values. CORDIC is an iterative algorithm. In the process, the\namplitude is multiplied by a CORDIC Gain (cumulative magnitude) of\nabout 1.647. The actual CORDIC gain depends on the number of\niterations.\n\nFor positions X and Y alone, the CORDIC gain is irrelevant and the\nprocessing speed can be somewhat improved by building the library with\nCORDIC_IGNORE_GAIN defined.\n\n2. USING\n\nFirst, you should include the driver and library header files in your\napplication:\n\n#include "libera.h"\n#include "cspi.h"\n\nNext, when passing options to GNU C compiler, you should use -lcspi to\nlink the application against the library.\n\nTo find out more about the library, see CSPI User\'s Guide in the\ndocumentation directory. To learn how to use the library functions,\nsee CSPI Reference in the documentation directory.\n\nLibera Electron: The src/test directory includes two sample data\nacquisition utilities called \'libera\' and \'acquire\'. The later is\ndeprecated and may be removed in the future. Consider using \'libera\'\ninstead. To learn more about usage, run libera with option --help:\n\n libera --help\n\nWhen run with option --acquire, the utility outputs one sample per\nline to standard output. The ordering and meaning of the values depend\non the selected data source.\n\nWith option --using-dd or --using-pm specified, each sample consists\nof eight whitespace separated integer values:\n\n Va, Vb, Vc, Vd, X, Y, Sum, Q\n or, with option --raw specified,\n cosVa, sinVa, cosVb, sinVb, cosVc, sinVc, cosVd, sinVd\n\nWith option --using-sa specified, each sample consists of ten\nwhitespace separated integer values. Units (where applicable) are\nnanometers:\n\n Va, Vb, Vc, Vd, X, Y, Sum, Q, Cx, Cy\n\nWith option --using-adc specified, each sample consists of four\nwhitespace separated integer values:\n\n chA, chB, chC, chD\n\nWith option --binary, data is not formatted as text and is instead\noutput as a binary stream of samples, or more precisely, as a stream\nof 32-bit integer values (16-bit for ADC-rate data). This allows for\nfaster acquisition and off-line processing (i.e. integration into an\napplication such as Matlab).\n\nWhen run with option --set-environment, the utility reads Libera\nenvironment parameters from standard input. In this way, to set the\nLibera environment, use:\n\n libera --set-environment < my_conf_file\n\nSample environment and gain configuration files are included with the\nprogram. The later allows one to set analog board attenuators based on\ninput power, using a predefined gain scheme.\n\nA configuration file should consist of parameters of a form:\nNAME VALUE\n\nThe configuration file is line-based - that is, each\nnewline-terminated line represents either a comment, or a\nparameter. Parameter names are case sensitive. Leading and trailing\nwhitespace in parameter names and values is irrelevant and\ndiscarded. Any line beginning with a hash (\'#\') character is ignored,\nas are lines containing only whitespace.\n\n libera --set-environment < env.conf\nThis will set Libera environment parameters listed in the\nconfiguration file. See sample configuration file env.conf\nincluded with the utility for more information.\n\n libera --acquire --on-trigger --using-dd 1000 > some_file\nThis will acquire 1000 data-on-demand samples on trigger into\nsome_file. The operation will time out after 30 seconds if no\ntrigger is received.\n\n libera --acquire --on-trigger --using-dd --with-timestamp \\n --loop --raw 1000 > /dev/null\nThis will acquire data-on-demand on trigger in a loop,\ndiscarding the data and printing a timestamp only on each\niteration.\n\n libera --set-time :200602091223.00\nThis will set the system time (ST) at next trigger to Feb 09\n12:23:00 2006. Machine time (MT) will not change.\n\nLibera Bunch-by-Bunch: A sample data acquisition utility called\n\'libera-bbfp\' is included in the src/test directory. To learn more\nabout usage, run libera-bbfp with option -h:\n\n libera -h\n\nThe utility outputs four samples per line to standard output.\n\n\n3. LIMITATIONS\n\nLibera Electron: The variable \'sum\' of the CSPI_DD_ATOM structure\nreturned by the cspi_read or cspi_read_ex has two least significant\nbits truncated to prevent an overflow.\n\n\nThis version of CSPI has been developed and tested using:\n- gcc 3.4\n- Libera driver 1.80\n- FPGA design 1.80\n'