/******************************************************************************* * overview.doc Main overview page for LibTms ******************************************************************************* */ /** \author Dr Terry Barnaby \version 0.4.0 \date 2007-09-27 \mainpage \section Introduction This document covers the BEAM LibTms software API for the CERN trajectory measurement system. This API provides the ability to control and receive data from the TMS System. The API is an object orientated API implemented in 'C++' with a number of object classes. The API operates over a network type interface using an RPC type mechanism. The LibTms API makes use of the BEAM standard class library. The BEAM standard class library provides a small set of low level 'C++' classes for strings, lists and system interface functions. There is some brief information on the BEAM class library later on in this page. \section Overview Generally users of the system are only concerned with the top level, System Controller API. This is the API that control and data gathering clients use to control and gather data from the system. The System Controller API (TmsApi) is implemented using a simple, object orientated, RPC mechanism. Two main objects, the <b>Tms::TmsControl</b> and <b>Tms::TmsProcess</b> objects, provide the full API. The TmsApi has been developed using the BOAP (BEAM Object Access Protocol). This provides a simple but powerful Object Orientated RPC mechanism. The TmsApi is written in a high level interface definition language (IDL). The bidl tool generates the client and server side 'C++' interface and implementation files for the API. These are then provided as a set of 'C++' header files and a binary library file for the clients to link to. The BOAP system employs a simple BOAP name server process that provides a translation between object names and IPAddress/Socket numbers. The BOAP name server runs on the System Controller. More information on the BOAP system can be found in the libBeam documentation. There are two main Objects that are used by clients of the TMS API. They are the <b>Tms::TmsControl</b> and the <b>Tms::TmsProcess</b> objects. The <b>Tms::TmsControl</b> object is used for system configuration, testing and diagnostics. The <b>Tms::TmsProcess</b> object is used for normal clients for Proton Synchrotron (PS) Cycle information configuration and data access. There is some example client code in the tmsExamples of the source code and displayed later on this page. These objects communicate through a network connection with the TmsServer process running on the TMS System Controller. The TMS System Controller operates as a multi-threaded process and can communicate with multiple clients simultaneously. The TMS system takes most of its system timing signals from digital timing lines connected to the TMS rack hardware. The only timing information that external software needs to supply is the next cycle number and cycle type information. The cycle number is a 32bit unsigned number identifying the next Proton Synchrotron (PS) machine cycle. The cycle type is and ASCII string defining the type of BEAM present in the PS machine. The cycle type defines a set of state/phase tables to be loaded in order to measure the BEAM in the machine. The CERN client software needs to provide this information by calling the setNextCycle() function before the next PS cycle is initiated. The TMS system keeps a library of state/phase tables indexed by the cycle type. These are loaded into the individual PUPE engines FPGA's during the CYCLE_STOP to CYCLE_START period. The API provides the <b>setControlInfo</b> and <b>delControlInfo</b> calls to maintain this database. A client would generally use the <b>Tms::TmsProcess</b> object for its interface to the TMS system. It would use call getData() to fetch the required data from the system. There is also an event based data interface implemented using the requestData() call and dataEvent() event call. Each of the TMS API calls return an error object. If there is an error, an appropriate error number will be given together with an ASCII string describing the error. \section libbeam BEAM class library The BEAM class library implements some basic low level classes and is used by the TMS API implementation itself. The main class functionaly includes: - BString - A simple string class - BList - A templated list class - BArray - A templated array class - BError - An error return class containg an integer and string - BSocket - A Network socket access class - BThread - A thread implementation class - BPoll - A file descriptor event polling class - BMutex - A mutex lock - BRWLock - A read/write lock - BSema - A semaphore - BCondInt - An integer condition class - BFile - A simple file access class - BDir - A simple directory access class - BEntry - A name/value pair list class - BNameValue - A name/value pair class - BRtc - A realtime clock - BTimer - A simple timer class - BUrl - URL access class \section TmsApi Examples There are some examples of client applications using the TmsApi in the <b>tmsExamples</b> directory of the source code. A simple Data Access client example is listed bellow: \include tmsDataClient1.cpp A simple Control client example is listed below: \include tmsControlClient1.cpp A simple Control client to set the next cycle information example is listed below: \include tmsControlClient2.cpp */