ll2.h

Go to the documentation of this file.

/* ------------------------------------------------------------------------- */
/* file ll2.h                                                                 */
/* ------------------------------------------------------------------------- */
/*   Copyright (C) 2011 Peter Milne, D-TACQ Solutions Ltd
 *                      <Peter dot Milne at D hyphen TACQ dot com>
 *  Created on: Sep 14, 2011
 *      Author: pgm

    http://www.d-tacq.com

    This program is free software; you can redistribute it and/or modify
    it under the terms of Version 2 of the GNU General Public License
    as published by the Free Software Foundation;

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
/* ------------------------------------------------------------------------- */

/** @file ll2.h API definition for LOWLATENCY2.
 *
 */

/**

@mainpage llcontrol2

@author Peter Milne <peter.milne@d-tacq.com>

- Low Latency control operation:
 - Target push data transfer to slave memory on host card.
 - Data is delivered with minimum latency after the sample clock.

 - This implementation uses the same firmware and mechanism as the original
 LLCONTROL, but it's implemented as an API rather than a framework.
 In other words, USER code calls the API rather than the FRAMEWORK call USER code
 as before.


  - The API is implemented in C++. This allows the same efficient interface to the
  device driver as before, while at the same time making for a clean dynamic system instantiation.
  - The API is callable from C and, appropriately packaged from another math environment eg Python or IDL.
  - In particular, the API allows the user to work with a single array of each
  of AI, AO, DI, DO across multiple cards, and the complexity of memory buffering
  is completely hidden by the API.
  - The user defined the system using a simple config_file (xml).
  -The system generates an xml representation of itself. This should be used by
  higher level code to establish position of channels in the data buffers. The channel position does not change
  unless the configuration changes, so it is reasonables to code this as a constant.
  - Alternatively the system can be instantiated in a few lines of C++, with direct access methods for the channel offsets.

 - Implementing a control loop in C:
  -# Define the system cards and slots and operating parameters by calling RtSetup();
  -# Arm the system by calling RtArm()
  -# Run the control loop calling RtIO()
  -# Terminate RtStop();

 - Implementing a control loop in C++
  -# Define the system cards and slots, by creating an instance of LL_ControlSystem
  and populating it with ACQ_Cards.
  -# Define operating parameters using LL_ControlSystem::init();
  -# Set up IO buffers
  -# Call LL_ControlSystem::Arm()
  -# Run the control loop calling LL_ControlSystem::IO()
  -# Terminate with LL_ControlSystem::Stop();

- For overview, please refer to
 - http://www.d-tacq.com/resources/D-Tacq_2G_UserGuide.pdf

- Operation still relies on capture setup scripts as before, or the equivalent.
- D-TACQ examples still use the same automated test environment of
 - MB : ACQ196 Master board
 - SB : optional ACQ196Slave board[s]
 - Sx : optional AO32 slave board[s]
 - CB : Clock Board - a further ACQ196 to provide external clock and trigger

- D-TACQ recommends example-dynamic.cpp, this has complete system definition in xml and is therefore the most general example.
- To run example-dynamic from bash prompt. Assume system definition "xml/example1-krypton.xml":
 - lookup_xml exports a few environment variables used in scripting..
@verbatim
./xml_lookup xml/example1-krypton.xml system/exports
CB=2 S1=3 MB=4
export $(./xml_lookup xml/example1-krypton.xml system/exports)
@endverbatim
 - Connect AO32 S1 AO0132 connector to ACQ196 MB AI0132 input
 - Connect AO32 S1 DO0132 connector to ACQ196 MB AI3364 input
 - Connect AO32 S1 DO3364 connector to ACQ196 MB AI6596 input
 - Host-side ACQ200 and AO32 drivers must be loaded.

 - Validate driver load:
@verbatim
acqcmd -s MB hostname

set.ao32 $S1 AO_MODE M_AWGI
get.ao32 $S1 AO_MODE
# ... returns M_AWGI

@endverbatim
 - Build LLC Software-
@verbatim
cd LOWLATENCY2; make
@endverbatim
 - define the system by editing a local xml system def file:
  -eg xml/example1-krypton-96AI.xml
@verbatim
# create a job control file, example:

# top-level-launcher
cd PROJECTS/LOWLATENCY2/
 export LL2_SYSFILE=xml/example1-krypton.xml 
 export LL_OUTPUTS=data/ai-ramps.dat 
 export $(./xml_lookup $LL2_SYSFILE system/exports)
 cd scripts
 ./setup.ao32 $MB $S1
 ./deploy-script set.llc.wd $MB
 acqcmd -s $MB set.llc.wd
 source ./setup.clocks2 $MB 0 96 $CB
 init_clocks
@endverbatim
 - now configure and run the system
@verbatim
source ./top-level-launcher
# options
./web-trigger
# run the shot -n ITERATIONS ECM (sample interval in 1usec ticks)
./example-dynamic -v 2 -n 10000 100
@endverbatim
  - sample output
@verbatim
[dt100@krypton LOWLATENCY2]$ LL_OUTPUTS=data/ai-ramps.dat ./example-dynamic -v 2 -n 100 1000
slot:2 class:acq196
slot:3 class:ao32
ECM 1000
mmap 0xb7f4b000 offset 16
data: 00000004 37400000 ffffffff 00000ec6
mmapDmaBuffer() 01: open /dev/acq32/acq32.2.host
mmapDmaBuffer() ask for full bigbuf portion 400000
mmapDmaBuffer() fd_in:4 physaddr 0x37400000 vaddr 0xb7b42000 len 4194304
mmapDmaBuffer() written host0.dat, zeroed
speed=1197 ticks per microsecond
ACQ196::init(0x9d49e1c) mbox 0x9d48ee8
M_SYNC_2V sample size 256
appEnterLLC_SYNC_2V() va:0xb7b42000 pa:0x37400000 MASTER slaves 1
enterLLC()
llSetAddr [2] 0x37400000
leave LLC
~LL_ControlSystemI()
@endverbatim
 - Validation
  - Channel 33-64 DO64 loopback to AI, data in AI.dat
@verbatim
[dt100@krypton LOWLATENCY2]$ ./scripts/dump.ai.decimal ai.dat 33-64 | ./scripts/do-analyse  | head
         1:00000000000000000000000000000000
         2:00000000000000000000000000000000
         3:11111111111111111111111111111111
         4:00000000000000000000000000000000
         5:11111111111111111111111111111111
         6:00000000000000000000000000000000
         7:11111111111111111111111111111111
         8:00000000000000000000000000000000
@endverbatim
  - Timestamps
@verbatim
# NB: does not work on ACQ196-96-500, only ACQ196-96-250
./scripts/dump.status.decimal | cut -d\  -f 12 | tail
9999920
9999940
9999960
9999980
10000000
@endverbatim
  - AO/AI data. 
   - AO32 loopback to AI01-32 Data saved to ai.dat
   - use gnu-octave to view the data
@verbatim
cat llplot.m 

1;
nchan=96
tb=1:100;
fp=fopen("ai.dat");
raw=fread(fp,Inf,"short");
len=length(raw)
chx=reshape(raw,nchan,len/nchan);
plot(tb,chx(1:32,tb))
octave
octave:1> llplot

@endverbatim

*/

#ifndef LL2_H_
#define LL2_H_

#include <iostream>
#include <vector>
#include <stdio.h>
#include <string.h>

using namespace std;

/** id's the classes of IO. */
enum IO {

        AI, AO, DI, DO, ST, IONUM
};

/** id's the slot numbers. 1:1 correspondence */
enum SLOTS {

        SLOT1=1, SLOT2, SLOT3, SLOT4, SLOT5, SLOT6, SLOT7, SLOT8
};
static const char* IO(enum IO io);

/** new zero'd data - avoids valgrind errors. */
template <class T> T* znew(int nwords) {
        T *buf = new T [nwords];
        memset(buf, 0, nwords*sizeof(T));
        return buf;
}

#define NO_VALUE                        0                               /**< null buffer arg (ignore). */
#define AI_SIZE                         sizeof(short)
#define AO_SIZE                         sizeof(short)
#define DO_SIZE                         sizeof(u32)
#define DI_SIZE                         sizeof(u32)
#define STATUS_SIZE                     sizeof(u32)

#define BITS_PER_DX_WORD        32              /**< DX packed into 32 bit words */

/** base class for cards and system. */
class ACQ {

protected:
        const char* id;
        const int ai_count;
    const int di_count;
        const int ao_count;
        const int do_count;


        ACQ(int _ai_count, int _di_count, int _ao_count, int _do_count):
                ai_count(_ai_count),
                di_count(_di_count),
                ao_count(_ao_count),
                do_count(_do_count)
        {}

public:
        virtual int getAI(short* ai_values) {
                return -1;
        }
        virtual int putAO(const short* ao_values) {
                return -1;
        }
        virtual int putDO(const unsigned *do_values){
                return -1;
        }
        virtual int getDI(unsigned *di_values){
                return -1;
        }
        virtual int getStatus(unsigned *status_values){
                return -1;
        }
        virtual void print() {
                cerr << id << " [" << "AI=" << ai_count << ","
                                           << "DI=" << di_count << ","
                                           << "AO=" << ao_count << ","
                                           << "DO=" << do_count << "]" << endl;
        }

        virtual int getAI_count(void) const { return ai_count; }
        virtual int getAO_count(void) const { return ao_count; }
        virtual int getDI_count(void) const { return di_count; }
        virtual int getDO_count(void) const { return do_count; }
        virtual int getStatus_count(void) const { return 0; }
        virtual ~ACQ() {}
};

/** opaque structure hooks to old llcontrol code. */
struct Card;


/** base class for physical cards. */
class ACQ_Card: public ACQ {

protected:
        const int slot;
        void registerCard(int slot);

public:
        ACQ_Card(
                        int _slot,
                        int _ai_count, int _di_count, int _ao_count, int _do_count):
                ACQ(_ai_count, _di_count, _ao_count, _do_count),
                slot(_slot)
        {
                registerCard(slot);
        }
        Card *card;
        virtual void init(Card *card) {}

        int getSlot() const { return slot; }
        static ACQ_Card* getCard(int slot);
};


class ACQ196 : public ACQ_Card {

public:
        virtual int getAI(short* ai_values);
        virtual int putAO(const short* ao_values);
        virtual int putDO(const unsigned *do_values);
        virtual int getDI(unsigned *di_values);
        virtual int getStatus(unsigned *status_values);
        void toggle_wd();


        virtual void init(Card *card);

        ACQ196(int _slot, int _ai_count=96, int _di_count=32,
                int _ao_count=16, int _do_count=0) :
                ACQ_Card(_slot, _ai_count, _di_count, _ao_count, _do_count)
        {
                        char* _id = new char[64];
                        sprintf(_id, "acq196.%d", slot);
                        id = _id;
        }
        virtual ~ACQ196()
        {
                delete [] id;
        }
        int getStatus_count(void) const;
};

class AO32 : public ACQ_Card {
        ACQ196* master;         /**< master card controlling this AO32. */
        int seq;                        /**< AO32 card # in set. */

public:
        virtual int putAO(const short* ao_values);
        virtual int putDO(const unsigned *do_values);

        AO32(int _slot, int _ao_count=32, int _do_count=64) :
                ACQ_Card(_slot, 0, 0, _ao_count, _do_count),
                master(0), seq(0)
        {
                char* _id = new char[64];
                sprintf(_id, "ao32.%d", slot);
                id = _id;
        }

        void setMaster(ACQ196* _master) {
                master = _master;
        }
        void setIndex(int _index) {
                seq = _index;
        }
        virtual ~AO32()
        {
                delete [] id;
        }
};



/** abstract factory class - implementation detail hidden */
class LL_ControlSystem : public ACQ {

protected:
        LL_ControlSystem(const char *_id = "LL_ControlSystem"):
                ACQ(0,0,0,0)
        {
                id = _id;
        }

public:
        virtual int addCard(ACQ196* _acq196) = 0;
        /**< add ACQ196 card to system. */
        virtual int addCard(AO32* _ao32) = 0;
        /**< add AO32 card to system. */

        virtual void print() = 0;
        /**< print a summary of the system.
         * xml output could be used to auto initialise application buffers
         */

        virtual void init(int argc, const char* argv[]) = 0;
        /**< initialise capture parameters. */

        virtual int Arm(
                        const short* ao_values_init = NO_VALUE,
                        const unsigned* do_values_init = NO_VALUE) = 0;
        /**< Arm the capture with initial conditions.
         * @param ao_values_init ensure initial AO condition.
         * @param do_values_init ensure initial DO condition.
         */
        virtual int IO(
                        const short* ao_values, const unsigned* do_values,
                        short* ai_values, unsigned* di_values, unsigned *status) = 0;
        /**< Block and return on next sample.
         *  Sets outputs before blocking, returns inputs.
         */
        virtual int Stop() = 0;
        /**< Stop the capture. */

        virtual int getSamples() const = 0;
        /**< returns samples to capture set in init(). */

        virtual int getOffset(ACQ_Card* card, enum IO io) = 0;
        /**< return offset in client vector for <card> with IO type <io>. */
        static LL_ControlSystem& create(const char *_id);
        /**< factory method
         * @param _id name to identify system
         * */

        static LL_ControlSystem& createFromFile(const char *config_file);
        /**< factory method
         * @param config_file names xml state file that pre-defines the system.
         * */

        static void closedown(LL_ControlSystem& sys);
        /**< cleanup */
};

#endif /* LL2_H_ */