regmap.h

#ifndef regmap_h
#define regmap_h

#include "hash.h"
#include "netbuf.h"
#include "input.h"
#include "output.h"

#include "gcp/util/common/CoordAxes.h"
#include "gcp/util/common/Coord.h"

#include <map>

/*   ***** PLEASE READ BEFORE MAKING MODIFICATIONS *****
 * The following define must be incremented by 1 whenever a
 * modification to the register map declarations makes
 * the register template incompatible with older archived register
 * maps. This number is recorded with archived register maps for
 * subsequent comparison against the current value.
 */
#define REGMAP_REVISION 1

/*
 * List supported addressing modes.
 */
typedef enum {
  ADDR_A16D08_O,    /* A 16-bit address of an 8-bit-odd register */
  ADDR_A24D08_O,    /* A 24-bit address of an 8-bit-odd register */
  ADDR_A32D08_O,    /* A 32-bit address of an 8-bit-odd register */
  ADDR_A16D08_EO,   /* A 16-bit address of an 8-bit-even/odd register */
  ADDR_A24D08_EO,   /* A 24-bit address of an 8-bit-even/odd register */
  ADDR_A32D08_EO,   /* A 32-bit address of an 8-bit-even/odd register */
  ADDR_A16D16,      /* A 16-bit address of a 16-bit register */
  ADDR_A24D16,      /* A 24-bit address of a 16-bit register */
  ADDR_A32D16,      /* A 32-bit address of a 16-bit register */
  ADDR_A16D32,      /* A 16-bit address of a 32-bit register */
  ADDR_A24D32,      /* A 24-bit address of a 32-bit register */
  ADDR_A32D32,      /* A 32-bit address of a 32-bit register */
  ADDR_A16D16_L,    /* A 16-bit address of a 32-bit (aka longword) */
                    /*  register to be read via two D16 transfers */
  ADDR_A24D16_L,    /* A 24-bit address of a 32-bit (aka longword) */
                    /*  register to be read via two D16 transfers */
  ADDR_A32D16_L,    /* A 32-bit address of a 32-bit (aka longword) */
                    /*  register to be read via two D16 transfers */
  ADDR_DEFAULT      /* A local 32-bit array of 32-bit integers */
} RegAddrMode;

/*
 * The following bit-mask enumerators are used to specify many of the
 * characteristics of each register. When describing a register in
 * a RegBlkTmpl template, the value of the flags member is either 0,
 * or the bitwise OR of one or more of the following enumerators.
 * Note that REG_READABLE and REG_WRITABLE are ignored for REG_LOCAL
 * registers. Also note that when writing to unreadable vme registers,
 * a copy of the written value is recorded in a software shadow
 * register. This value will be returned on subsequent reads.
 * REG_EXC should be used for registers that are used internally
 * but shouldn't be archived. Note that reading from vme registers can
 * sometimes have side-effects such as acknowledging an interrupt, so
 * be careful to exclude such registers from the archive. 
 */
enum RegFlags {
  REG_NONE    = 0x0,     // None of the following.
  REG_COMPLEX = 0x1,     // Include if register contains real,imaginary
                         // pairs Exclude if register contains only real
                         // values
  REG_R       = 0x4,     // Include if the register's vme address is
                 // readable. Exclude to read written values from
                 // the shadow array.
  REG_W       = 0x8,     // Include if the register's vme address is
                 // writable. Exclude if the register can't be
                 // written to.
  REG_RW = REG_R | REG_W,
  REG_PREAVG  = 0x10,    // Include for integrated registers.  Exclude if
  REG_POSTAVG = 0x20,    // Include for integrated registers.  Exclude if
  REG_SUM     = 0x40,    // Include for integrated registers.  Exclude if
                 // the register contains a snapshot value.
  REG_UNION   = 0x80,    // Including this tells the archiver to
                 // integrate this register by taking the
                 // bit-mask union of the values of the register
                 // that are to be combined.
  REG_EXC     = 0x100,   // Include to exclude the register from the
                 // archive.  Exclude to include the register in
                 // the archive.
  REG_UTC     = 0x200,   // Include for registers that represent times in
                 // UTC. Such registers must consist of one or
                 // more pairs of elements in which the first
                 // element contains a modified Julian day
                 // number, and the second element contains the
                 // corresponding time of day in milliseconds.
  REG_PCI     = 0x400,   // A PCI register.
  REG_BOOL    = 0x800,   // This register of single bytes
  REG_CHAR    = 0x1000,  // This register of single bytes
  REG_UCHAR   = 0x2000,  // This register of single bytes
  REG_SHORT   = 0x4000,  // This register of shorts
  REG_USHORT  = 0x8000,  // This register of shorts
  REG_INT     = 0x10000, // A register of ints
  REG_UINT    = 0x20000, // A register of ints
  REG_FLOAT   = 0x40000, // A register of floating point values
  REG_DOUBLE  = 0x80000, // A register of doubles
  REG_DEFAULT = REG_UINT,// The default is a register of unsigned ints
             // which should be summed together on integration
  REG_DPRAM   = 0x100000,// Include if this is a register on the PMAC's
                 // DPRAM. These registers will correspond to an
                 // actual memory space in the PMAC DPRAM, but
                 // are read and written over a serial
                 // connection. Internally these registers are
                 // read from and written to shadow registers.
  REG_FAST   =  0x200000,// Include for multidimensional registers
             // where the fastest-changing axis is a time
             // subsample
};

/*
 * The following bit-mask enumerators are used to specify many of the
 * characteristics of each register. When describing a register in
 * a RegBlkTmpl template, the value of the flags member is either 0,
 * or the bitwise OR of one or more of the following enumerators.
 * Note that REG_READABLE and REG_WRITABLE are ignored for REG_LOCAL
 * registers. Also note that when writing to unreadable vme registers,
 * a copy of the written value is recorded in a software shadow
 * register. This value will be returned on subsequent reads.
 * REG_EXC should be used for registers that are used internally
 * but shouldn't be archived. Note that reading from vme registers can
 * sometimes have side-effects such as acknowledging an interrupt, so
 * be careful to exclude such registers from the archive.
 */
typedef enum {
  CBI_REG_DEFAULT = 0,    /* None of the following */
  CBI_REG_COMPLEX = 1,    /* Include if register contains real,imaginary pairs */
                      /* Exclude if register contains only real values */
  CBI_REG_SIGNED = 2,     /* Include if register contains signed values (2s-comp) *\/
             /* Exclude if register contains unsigned values */
  CBI_REG_R_VME = 4,      /* Include if the register's vme address is readable */
                      /* Exclude to read written values from the shadow array *\/
             REG_W_VME = 8,      /* Include if the register's vme address is writable */
                      /* Exclude if the register can't be written to */
  CBI_REG_W_VME = 8,      /* Include if the register's vme address is writable */
                      /* Exclude if the register can't be written to */
  CBI_REG_RW_VME = CBI_REG_R_VME | CBI_REG_W_VME,

  CBI_REG_SUM = 16,       /* Include for integrated registers */
                      /* Exclude if the register contains a snapshot value */
  CBI_REG_UNION = 32,     /* Including this tells the archiver to integrate */
                      /*  this register by taking the bit-mask union of */
                      /*  the values of the register that are to be combined. *\/
              REG_EXC = 64,       /* Include to exclude the register from the archive */
                      /* Exclude to include the register in the archive */
  CBI_REG_EXC = 64,       /* Include to exclude the register from the archive */
                      /* Exclude to include the register in the archive */
  CBI_REG_UTC = 128       /* Include for registers that represent times in UTC. */
                      /*  Such registers must consist of one or more pairs */
                      /*  of elements in which the first element contains */
                      /*  a modified Julian day number, and the second */
                      /*  element contains the corresponding time of day in */
                      /*  milliseconds. */
} CbiRegFlags;

/*
 * Record the locations at which VME address spaces are mapped
 * into VxWorks memory.
 */
#define VME_A16_BASE 0x0
#define VME_A24D16_BASE 0x0
#define VME_A24D32_BASE 0x0
#define VME_A32_BASE 0x0

/*
 * Set the max length of names of register blocks and boards.
 */
#define REG_NAME_LEN 31

/*
 * Define type aliases for the structures that are being declared
 * below.
 */
typedef struct RegMapBlock RegMapBlock;
typedef struct RegMapBoard RegMapBoard;
typedef struct RegMap RegMap;
 
/*
 * Describe an array of registers.
 */
struct RegMapBlock {
  RegMapBoard* brd_;          // The parent register board
  unsigned number_;           // The index of the block on its parent
                  // board
  char name_[REG_NAME_LEN+1]; // The name of the block of registers
  std::string* comment_;      // Description of register
  char axesHelp_[REG_NAME_LEN+1];  // Description of axis indices
  unsigned flags_;            // A bit-set of RegFlags enumerators
  RegAddrMode addr_mode_;     // The addressing mode of the register
  unsigned location_;         // The address of the first register in
                              // VxWorks address-space (0 for non-VME
                              // registers)
  unsigned ireg_;             // The sequential number of the first
                  // register
  unsigned nreg_;             // The total number of elements in the
                  // block
  int slot_;                  // The start index of the block in the
                              // archive array (or -1 if [flags &
                              // REG_EXC != 0].

  gcp::util::CoordAxes* axes_;// An axis specifier for this register

  int iSlot_;                 // The sequential slot index of the
                  // first register in parent slot array
  int iArcSlot_;              // The sequential slot index of the
                  // first register in parent archived
                  // slot array
  unsigned iByte_;            // The sequential byte index of the
                  // first register in the parent register
                  // map
  int iArcByte_;              // The starting index of this block in
                  // the archive byte array, or -1 if this
                  // register is not archived
  unsigned nBytePerEl_;       // The number of bytes in each element
                  // of this register

  // Methods of the RegMapBlock struct

  // Constructors

  RegMapBlock();

  RegMapBlock(RegMapBoard* parent, void* tbrd, void* tblk, 
          unsigned iBlock, unsigned nper_brd_blocks);

  // Destructor

  ~RegMapBlock();

  // Return the number of bytes in this register block

  unsigned nByte();        

  // Return the total number of elements in this register

  unsigned nEl();

  // Return the number of butes per element of this register

  unsigned nBytePerEl() {
    return nBytePerEl_;
  }

  // Return the offset, in bytes, of the requested element of this
  // register in the register map archive array

  int byteOffsetInWholeRegMapOf(gcp::util::Coord* coord=0);
  int byteOffsetInArcRegMapOf(gcp::util::Coord* coord=0);

  int byteOffsetInBoardOf(bool archivedOnly, gcp::util::Coord* coord=0);

  // Convenience method for the above

  int byteOffsetInRegMapOf(bool archivedOnly, gcp::util::Coord* coord=0) {
    return archivedOnly ? byteOffsetInArcRegMapOf(coord) :
      byteOffsetInWholeRegMapOf(coord);
  }

  // Methods for returning the slot offset of an element of this
  // register

  int slotOffsetInArcRegMapOf(gcp::util::Coord* coord=0) {
    return (iArcSlot_ < 0) ? -1 : (int)(iArcSlot_ + elementOffsetOf(coord));
  }

  int slotOffsetInWholeRegMapOf(gcp::util::Coord* coord=0) {
    return iSlot_ + (int)elementOffsetOf(coord);
  }

  // Return the start index of this block in the archived slot array

  int slotOffsetInRegMapOf(bool archivedOnly, gcp::util::Coord* coord=0) {
    return archivedOnly ? slotOffsetInArcRegMapOf(coord) :
      slotOffsetInWholeRegMapOf(coord);
  }

  // Methods returning the element offset of the requested coordinate

  int elementOffsetOf(gcp::util::Coord* coord);

  // Return true if this block is archived

    bool isArchived();

  // Return true if the block type matches 

    bool isBool()
    {
      return (flags_ & REG_BOOL);
    }
    
    bool isChar()
    {
      return (flags_ & REG_CHAR);
    }
    
    bool isUchar()
    {
      return (flags_ & REG_UCHAR);
    }
    
    bool isUshort()
    {
      return (flags_ & REG_USHORT);
    }
    
    bool isShort()
    {
      return (flags_ & REG_SHORT);
    }
    
    bool isUint()
    {
      return (flags_ & REG_UINT);
    }
    
    bool isInt()
    {
      return (flags_ & REG_INT);
    }
    
    bool isFloat()
    {
      return (flags_ & REG_FLOAT);
    }
    
    bool isDouble()
    {
      return (flags_ & REG_DOUBLE);
    }
    
    bool isUtc()
    {
      return (flags_ & REG_UTC);
    }  

    bool isSummed();       // True if summed on integration
    bool isUnioned();      // True if bitwise-unioned on integration
    bool isPreAveraged();  // True if averaged on integration
    bool isPostAveraged(); // True if averaged when read

    bool isComplex();
  void checkConsistency();

  void checkType(unsigned flags);

  void checkIntegration(unsigned flags);

  void checkAttributes();

  friend std::ostream& operator<<(std::ostream& os, RegMapBlock& block);
};

/*
 * Collect registers that reside on a given board.
 */
struct RegMapBoard {
  RegMap *regmap;            /* The parent register map */
  unsigned number;           /* The index of the board in the register map */
  char name[REG_NAME_LEN+1]; /* An unambiguous name for the board */
  std::string* comment_;
  std::vector<RegMapBlock*> blocks;       /* The registers of the board */
  int nblock;                /* The number of register blocks in blocks[] */

#if USE_HASH
  HashTable *hash;           /* Symbol table of register blocks */
#else
  std::map<std::string, RegMapBlock*> mapOfBlocks_;
#endif
  unsigned nreg;             /* The total number of registers on the board */
  unsigned narchive;         /* The number of archived registers on the board */

  unsigned nByte_;
  unsigned nArcByte_;

  unsigned iSlot_;          // The sequential index of the first
                // register of this board in the parent
                // register map slot array
  int iArcSlot_;            // The sequential index of the first
                // register of this board in the parent
                // archived slot array
  unsigned iByte_;          // The sequential index of the first byte
                // of this board in the parent register map
  int iArcByte_;            // The sequential index of the first byte
                // of this board in the archived parent
                // register map

  // Return the byte offset of this board in the parent register map

  int byteOffsetInRegMap(bool archivedOnly) {
    return archivedOnly ? iArcByte_ : iByte_;
  }

  // Return the slot offset of this board in the parent register map

  int slotOffsetInRegMap(bool archivedOnly) {
    return archivedOnly ? iArcSlot_ : iSlot_;
  }

  // Return the number of bytes in this board

  unsigned nByte(bool archivedOnly) {
    return archivedOnly ? nArcByte_ : nByte_;
  }

  RegMapBoard();

  RegMapBoard(RegMap* parent, void* vbrd, unsigned iboard, 
          void* vper_brd_blocks, unsigned nper_brd_blocks);

  ~RegMapBoard();

  // Return the named register block

  RegMapBlock* findRegMapBlock(std::string blockName);

  // Return a vector of blocks matching the input string

  std::vector<RegMapBlock*> matchRegMapBlock(std::string regExpStr);
};

/*
 * Collect information about all boards.
 */
struct RegMap {
  unsigned ref_count_;       // Reference counter 
  std::vector<RegMapBoard*> boards_; // All addressable boards 
  int nboard_;               // The number of boards 
#if USE_HASH
  HashMemory *hash_mem_;     // Memory for hash tables 
  HashTable *hash_;          // Symbol table of boards 
#else
  std::map<std::string, RegMapBoard*> mapOfBoards_;
#endif
  unsigned nreg_;            // The total number of registers 
  unsigned narchive_;        // The total number of archived registers
  unsigned nByte_;           // The size in bytes of all registers in
                 // this register map
  unsigned nArcByte_;        // The size in bytes of all archived
                 // registers in this register map

  // A constructor

  RegMap(void *regtmp, bool addDefaults=true);

  // Destructor

  ~RegMap();

  // Return the offset, in bytes_ of the named board and block from
  // the start of the archived array

  int byteOffsetInArcRegMapOf(std::string board, std::string block, 
                   gcp::util::Coord* coord=0);
  int byteOffsetInWholeRegMapOf(std::string board, std::string block, 
                gcp::util::Coord* coord=0);

  // Convenience method for the above two

  int byteOffsetInRegMapOf(bool archivedOnly, 
               std::string board, std::string block, 
               gcp::util::Coord* coord=0) {
    return archivedOnly ? byteOffsetInArcRegMapOf(board, block, coord) :
      byteOffsetInWholeRegMapOf(board, block, coord);
  }

  int byteOffsetInArcRegMapOf(RegMapBlock* blk, gcp::util::Coord* coord=0);
  int byteOffsetInWholeRegMapOf(RegMapBlock* blk, gcp::util::Coord* coord=0);

  // Convenience method for the above two

  int byteOffsetInRegMapOf(bool archivedOnly, 
               RegMapBlock* blk,
               gcp::util::Coord* coord=0) {
    return archivedOnly ? byteOffsetInArcRegMapOf(blk, coord) :
      byteOffsetInWholeRegMapOf(blk, coord);
  }

  unsigned nByte() {return nByte_;};
  unsigned nArcByte() {return nArcByte_;};

  // Convenience method for the above two

  int nByte(bool archivedOnly) {
    return archivedOnly ? nArcByte() : nByte();
  }

  // Find the named block

  RegMapBlock* findRegMapBlock(std::string board_name, std::string block_name,
         bool          booldoThrow=false);
};

/* NB. new_RegMap() is prototyped in regtemplate.h */

RegMap* del_RegMap(RegMap* regmap);

/* Allocate a readonly alias to a given register map. */
/*  When no longer required this should be discarded by calling */
/*  del_RegMap(). */

RegMap *alias_RegMap(RegMap *regmap);

/* Return non-zero if two register maps are equivalent. */

int equiv_RegMap(RegMap *regmap1, RegMap *regmap2);

RegMapBoard *find_RegMapBoard(RegMap *regmap, std::string board_name);
RegMapBlock *find_RegMapBoard_Block(RegMapBoard *board, std::string block_name);
RegMapBlock *find_RegMapBlock(RegMap *regmap, std::string board_name,
                  std::string block_name);

/*
 * Enumerate the register-specifications read by input_RegMapReg().
 * The comment next to each mode indicates the type of input expected,
 * where "board" is the name of a board, "register" is the name of
 * a block of registers, and index is the sequential number of
 * a register within a block.
 */
typedef enum {
  REG_INPUT_BLOCK,     /* board.register */
  REG_INPUT_ELEMENT,   /* board.register[index] */
  REG_INPUT_RANGE      /* board.register[index-index] */
} RegInputMode;

/*
 * When the extend argument of input_RegMapReg() is true, and a complex or
 * utc register-pair specification is read, a member of the following type
 * is used to record what aspect of the complex register has been selected
 * by the user. If the user doesn't specify anything then REG_PLAIN is
 * substituted. Where appropriate these enumerators can be used as
 * indexes of arrays of REG_NASPECT elements.
 */
typedef enum {
  REG_PLAIN,          /* Treat complex register pairs as two registers */
  REG_REAL,           /* The real member of the complex register pair */
  REG_IMAG,           /* The imaginary member of the complex register pair */
  REG_AMP,            /* The amplitude of a complex register pair */
  REG_PHASE,          /* The phase of a complex register pair */
  REG_DATE,           /* The Modified Julian Date of a day/time utc pair */
  REG_TIME            /* The time-of-day of a day/time utc pair */
} RegAspect;

enum {REG_NASPECT = 7};  /* The number of enumerators in RegAspect */

char *name_RegAspect(RegAspect aspect);

typedef enum {
  REG_INT_PLAIN, // Treat the register normally                                                                
  REG_INT_INT,   // Integrate the register                                                                     
  REG_INT_DER    // Take the derivative of the register                                                        
} RegInteg;

enum {REG_NINTEG = 3};  /* The number of enumerators in RegInteg */

char *name_RegInteg(RegInteg integ);

/*
 * A structure of the following form is filled by input_RegMapReg().
 * The meanings of reg and nreg depend on the input mode as follows:
 *
 *  REG_INPUT_BLOCK:
 *   index will be 0.
 *   slot will be the frame index of the first register of the block.
 *   nreg will be the number of registers in the block.
 *  REG_INPUT_ELEMENT:
 *   index will be the block index of the selected member of the block.
 *   slot will be the frame index of the selected member of the block.
 *   nreg will always be 1.
 *  REG_INPUT_RANGE:
 *   index will be the block index of the selected member of the block.
 *   slot will be the frame index of the first selected member of the block.
 *   nreg will be the number of registers in the range.
 *
 * Note that if the selected register is not an archived register, the
 * slot index will be -1.
 */
struct RegMapReg {
  int board;           // The index of the specified board in the
               // register-map
  int block;           // The index of the specified block on the
               // regmap board
  unsigned index;      // The block index of the first register
               // specified
  signed slot;         // The frame index of the first register
               // specified
  unsigned nreg;       // The number of registers specified. The
                       // associated regmap slots are: slot -> slot +
                       // nreg*size - 1
  unsigned size;       // The number of slots per register. This is 1
                       // unless aspect!=REG_PLAIN, in which case it
                       // becomes 2
  RegAspect aspect;    // The quantity to derive from complex or utc
                       // register pairs
  RegInteg integ;      // The integration status of this register                                              
                       // register pairs                                                                       
  int iByte_;          // The byte index into the register map of the
               // first register specified
  int iArcByte_;       // The byte index into the archived register
               // map of the first register specified
  unsigned nBytePerEl_;// The number of bytes per element of this register

  gcp::util::CoordAxes* axes_;   // An axis specifier for this register
  gcp::util::CoordRange* range_; // An index-range specifier
};

int find_RegMapReg(RegMap *regmap, std::string board_name, std::string block_name,
           RegAspect facet, unsigned index, unsigned n,
           RegMapReg *reg);

int init_RegMapReg(RegMap *regmap, unsigned board, unsigned block,
           unsigned index, unsigned nreg, RegAspect aspect,
           RegMapReg *reg);

typedef enum {
  REG_VALID=0,    /* A valid register was found */
  REG_UNKNOWN,    /* Valid specification syntax, but unknown register */
  REG_INVALID     /* Invalid register specification syntax */
} RegValidity;

RegValidity input_RegMapReg(InputStream *stream, int tell, RegMap *regmap,
                RegInputMode mode, int extend, RegMapReg *reg);

/*
 * Save a register specification in the form read by input_RegMapReg().
 */
typedef enum {
  REG_OUTPUT_BLOCK,     /* board.register */
  REG_OUTPUT_ELEMENT,   /* board.register[index] */
  REG_OUTPUT_RANGE      /* board.register[index-index] */
} RegOutputMode;

int output_RegMapReg(OutputStream *stream, RegMap *regmap, RegOutputMode mode,
             RegMapReg *reg);

void clr_RegMapReg(RegMapReg *reg);

/*
 * If registers are represented as 32-bit integers then we need a method
 * to pack a string into an array of 32-bit integers. The following function
 * does this.
 */
int pack_int_string(char *string, int ndata, unsigned *data);

/*
 * Unpack a string that was previously packed by pack_int_string().
 */
int unpack_int_string(unsigned *data, int ndata, int size, char *string);

/*
 * Unpack a string that was previously packed by pack_int_string() and
 * then assigned to a parallel array of double.
 */
int unpack_double_string(double *data, int ndata, int size, char *string);

#endif