Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / sam / devices / common / regdef / include / Register.h

/*
* ========== Copyright Header Begin ==========================================
* 
* OpenSPARC T2 Processor File: Register.h
* Copyright (c) 2006 Sun Microsystems, Inc.  All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES.
* 
* The above named program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public
* License version 2 as published by the Free Software Foundation.
* 
* The above named 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 work; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
* 
* ========== Copyright Header End ============================================
*/
#ifndef __Register_h
#define __Register_h

#include <stddef.h>
#include <assert.h>
#include <iostream>
#include <fstream>
#include <string>
#include "Block.h"
#include "Object.h"
#include "Datatype.h"
#include "Signature.h"
using namespace std;

/** @file Register.h
*  Register.h provides a set of classes for representing registers.
*
*  @see RegisterModule
*/

/** @defgroup RegisterModule The Register Module
*
*  Registers are 8, 16, 32 or 64 bits wide, and are composed of Fields. 
*  Fields are contiguous collections of bits within a Register. The value
*  of a Register can be accessed at the Register level or at the
*  Field level. Care is taken to ensure that large arrays of 64-bit registers
*  are implemented efficiently - in terms of memory usage and run-time
*  cost. Note that there is significant waste in the storage of narrower
*  registers since they are held in 64-bit containers (with unused upper bits
*  always zero).
*
*  The classes and types defined here are:
*    - AccessType
*    - Register
*    - Field
*
*  The following classes are also defined in this file, but are not 
*  intended for use outside Register/Field implementation:
*    - RegisterType
*    - RegisterState
*    - RegisterInfo
*    - FieldType
*
*  The "public" interface provided by this file consists of AccessType,
*  Register and Field. The other classes are internal and not intended 
*  for use outside the Register/Field implementation.
*
*  Note that there are no FieldState/FieldInfo classes. This is because 
*  the register state and info are held in RegisterState/RegisterInfo
*  and the field-level mechanisms pull out the necessary bits from 
*  the register. There are (too) many friendships
*  between the various register and field classes - they work together
*  very closely and this avoids having to define a lot more methods
*  to access the internal state. Originally, this class was implemented
*  as just Register and Field classes with simple array container
*  classes that replicated registers. This was very inefficient for 
*  large register arrays, which turned out to be a significant problem at
*  run-time. The classes were then restructured and rewritten so that only
*  RegisterState/RegisterInfo had to be replicated for every element in a 
*  RegisterArray, and the amount of overhead data in this class was
*  massively reduced.
*
*  See also RegisterArray.h
*
*  @{
*/

/** AccessType is an enumerated type used to distinguish the various
*  supported access types. The access types are specified at the
*  Field level. Since a Register can contain more than one Field,
*  then a Register can have multiple access types associated with
*  its Fields. The access types are:
*    - Access_RC: read-to-clear.
*    - Access_RO: read-only.
*    - Access_RW: read-write.
*    - Access_RW1C: read, write-one-to-clear.
*    - Access_RW1S: read, write-one-to-set.
*    - Access_RCW1C: read-to-clear, write-one-to-clear.
*    - Access_RCW1S: read-to-clear, write-one-to-set.
*    - Access_WO: read undefined, write-only.
*    - Access_L: read as zero, write-only.
*/
 
typedef enum {
 Access_RC,    /**< - READ: return value and clear.
                    - WRITE: set value. */
 Access_RO,    /**< - READ: return value.
                    - WRITE: ignored. */
 Access_RW,    /**< - READ: return value.
                    - WRITE: set value. */
 Access_RW1C,  /**< - READ: return value.
                    - WRITE: clear the bits written as "1". */
 Access_RW1S,  /**< - READ: return value.
                    - WRITE: set the bits written as "1". */
 Access_RCW1C, /**< - READ: return value and clear.
                    - WRITE: clear the bits written as "1". */
 Access_RCW1S, /**< - READ: return value and clear.
                    - WRITE: set the bits written as "1". */
 Access_WO,    /**< - READ: undefined.
                    - WRITE: set value. */
 Access_L      /**< - READ: return zero.
                    - WRITE: set value. */
} AccessType;

/** The static constant value used for an undefined Register value. */
// static const Data UNDEFINED_DATA = Data(0xCAFEBABEBEEFFACE);
static const Data UNDEFINED_DATA = Data(0x0);

class FieldType;                                // forward reference

/** RegisterType contains the type information for a Register. These are
*  static properties of a Register that are not typically modified once 
*  the Register has been created, and are consistent across all elements in a 
*  RegisterArray. A number of the fields in RegisterType are used to 
*  accelerate accesses to that Register by pre-calculating mask values,
*  and also collate relevant information from the FieldType classes for the
*  Register. Two booleans are used to keep track of whether the call-back
*  mechanism has been enabled for read and write accesses. It is possible
*  to enable/disable this mechanism on-the-fly but it is typically a
*  static property. The call-back flags for a RegisterArray apply to every
*  Register element in that array.
*
*  Note that RegisterType is used in the implementation of the Register class.
*  There should be no reason to use this class from elsewhere since Register
*  provides a complete public interface to registers. Most of the state
*  inside RegisterType is private without any direct access methods.
*/

class RegisterType
{
friend class Register;
friend class RegisterArray;
friend class FieldType;

public:
 /** Constructor for RegisterType.
  *    @param w width of the Register in bytes (1, 2, 4 or 8 bytes).
  */
 RegisterType(uint w=8);

private: 
 void check(string n);

 uint widthBits;
 uint widthBytes;
 Data widthMask;
 Data checkMask;
 Data writeMask;
 Data writeOneToClearMask;
 Data writeOneToSetMask;
 Data readMask;
 Data readAsUndefinedMask;
 Data readAsZeroMask;
 Data readToClearMask;
 Data resetValue;
 Data resetAssigned;
 bool writeBlockCB;
 bool readBlockCB;  
 List<FieldType> fieldTypes;
};

/** RegisterState holds the value for a particular Register in a 64-bit 
*  container. 
*
*  The RegisterState class contains the value for an undefined Register, and
*  this is also used to derive the value for an undefined Field. This is
*  arranged so that if all Fields of a Register are given the undefined
*  Field value, then the value of the Register is the undefined Register
*  value. Note that a "randomized" undefined value is good for catching
*  discrepanies between hardware and software views of registers, but 0x0
*  is more convenient when tracing or debugging.
*
*  Note that RegisterState is used in the implementation of the Register 
*  class. There should be no reason to use this class from elsewhere since 
*  Register provides a complete public interface to registers.
*/

class RegisterState
{
friend class Register;
friend class RegisterArray;
friend class Field;

public:
 /** Constructor for RegisterState.
  *    @param v initial value of the Register (defaults to UNDEFINED_DATA).
  */
 RegisterState(Data v=UNDEFINED_DATA)
 {
   value=v;
 }
 
private:
 Data value;
};

/** RegisterInfo holds other information associated with each RegisterState
*  instance. This includes fields to track whether this Register is 
*  clean/dirty (used for tracing) and whether this Register has been 
*  assigned a value (ie. initialized - this information is maintained 
*  but not actually used for anything yet). The reason for separating 
*  out RegisterInfo from RegisterInfo is to give more efficient memory 
*  usage (smaller class size).
*
*  TODO - one idea for the assigned bit is to ensure that unassigned 
*  Register instances can take an UNDEFINED_DATA value without having 
*  to set them to this value at construction or reset time. This could 
*  be useful to reduce the amount of memory initialization
*  (and in-core memory) required for the simulation of very large 
*  RegisterArrays. In fact, the RegisterState instance of an unassigned
*  RegisterArray could be allocated lazily (ie. on first write). This
*  would require modifications to all register and field access mechanisms
*  (get, set, read, write, etc) to catch accesses to unassigned state.
*  This potential optimization does not seem worthwhile yet and thus has
*  not been implemented. Note that care has been taken to minimize the amount
*  of overhead for large RegisterArrays and this has been sufficient so far.
*
*  Note that RegisterInfo is used in the implementation of the Register 
*  class. There should be no reason to use this class from elsewhere since 
*  Register provides a complete public interface to registers.
*/

class RegisterInfo
{
friend class Register;
friend class RegisterArray;
friend class Field;

public:
 /** Constructor for RegisterInfo.
  *    @param a initial setting for the assigned bit (defaults to unassigned).
  *    @param b initial setting of the clean bit (defaults to dirty).
  */
 RegisterInfo(bool a=false, bool b=false)
 {
   assigned=a;
   clean=b;
 }
 
 /** Get the assigned boolean. */
 bool getAssigned() const { return assigned; }
 
 /** Set the assigned boolean. 
  *    @param b the new value for the assigned boolean. */
 void setAssigned(bool b) { assigned = b; }

 /** Get the clean boolean. */
 bool getClean() const { return clean; }
 
 /** Set the clean boolean.
  *    @param b the new value for the clean boolean. */
 void setClean(bool b) { clean = b; }

 /** Get the dirty boolean. */
 bool getDirty() const { return !clean; }
 
 /** Set the dirty boolean.
  *    @param b the new value for the dirty boolean. */
 void setDirty(bool b) { clean = !b; }

private:
 bool assigned;
 bool clean;
};

/** The Register class provides mechanisms to construct and access Register
*  instances. After a Register is constructed, it is necessary to construct
*  one or more instances of the Field class and associate them with the
*  Register. A Register must be populated with Fields to define how each
*  bit in the Register should behave for reads and writes, and to specify
*  any defined initial value for the Register.
* 
*  Internally, the Register class contains pointers to RegisterType and 
*  RegisterState instances, which hold the type and state for this 
*  Register respectively. For a RegisterArray, an array of Registers is
*  not allocated since this is too expensive. Instead one RegisterState
*  is allocated for each Register in the array, and one RegisterType is
*  allocated for the whole array. When a RegisterArray is subscripted to
*  yield a Register, an instance of the Register class is initialized
*  appropriately. This is returned-by-value so that the state is
*  provided by the caller of the RegisterArray subscription operator.
*  This Register instance gets destructed when it goes out of 
*  scope or is deallocated by the caller. Additionally, the returned
*  Register refers to the correct RegisterState structure in the original
*  RegisterArray so that writes/sets to the returned Register structure
*  will correctly update the value in the array. In some ways it is more
*  appropriate to consider the Register structure as a register 
*  handle, and not the register value itself.                            
*/

class Register
{
friend class Field;
friend class RegisterArray;

public:
 /** Constructor for Register.
  *    @param n the basename for this Register.
  *    @param b a pointer to the Block with which this Register is associated.
  *             The fullname of this Register is scoped within that Block.
  *    @param a the address of this Register.
  *    @param w the width of this Register in bytes, defaults to 8 bytes.
  *
  *  If the parent block is specified as NULL (which is its default), then 
  *  this Register will not be associated with any parent and will not
  *  be included in any of the register mechanisms provided by the Block
  *  class. In particular the Register will not be in the print, reset, 
  *  sign or trace trees, and the Register will not be included in the 
  *  address map of that Block. Additionally, the call-back mechanism
  *  for side-effecting reads/writes cannnot be used.
  *
  *  If there is no parent block then no interpretation will be placed on 
  *  the address by the Register class. This mechanism is convenient for 
  *  modelling structures that have similar structure to registers 
  *  (e.g. composed of fields) but that are not architectural state. 
  *  If the Register class is used in this way, then it is up to the 
  *  user to provide all required infrastructure (such as a call to 
  *  reset its state). The RegisterArray/FieldArray classes do not 
  *  support Blockless registers.
  */
 Register(string n, Block *b=NULL, Addr a=Addr(0), uint w=8);
 
 /** The copy constructor for Register. The destination Register is marked
  *  as derived so that destructing that Register does not deallocate the
  *  heap state allocated by the source Register. It is assumed that
  *  non-derived Register instances (the original source of one or more
  *  copies) will out-live all copies. This is reasonable since non-derived
  *  Register instances correspond to architectural state and should be
  *  allocated for the entire simulation.
  *    @param r the source Register for the copy construction.
  */
 Register(const Register &r);
 
 /** Constructor for Register with no parameters to initialize the register
  *  to a default state. This is provided for the RegisterArray::lookup()
  *  mechanism. */
 Register();

 /** Destructor for Register. This is virtual so that the appropriate
  *  destructor for any derived class is used. */
 virtual ~Register();
 
 /** The copy assignment operator for Register. The destination Register is 
  *  marked as derived so that destructing that Register does not deallocate
  *  the heap state allocated by the source Register. It is assumed that
  *  non-derived Register instances (the original source of one or more
  *  copies) will out-live all copies. This is reasonable since non-derived
  *  Register instances correspond to architectural state and should be
  *  allocated for the entire simulation.
  *    @param r the source Register for the copy assignment.
  */
 Register &operator=(const Register &r);

 /** Clone a new copy of this Register. This creates a Register instance
  *  using new and performs a shallow copy of this Register into the new
  *  Register. The new Register is marked as derived so that deletion of
  *  the new Register does not deallocate the heap state of this Register.
  *  A pointer to the new Register is returned, and it is the responsibility
  *  of the caller to delete the pointer when the new Register is no
  *  longer required. This is a virtual function so that it can be
  *  overloaded by sub-classes of Register as appropriate. */
 virtual Register *clone() const { return new Register(*this); }
 
 /** Get the basename of this Register. */
 string getBaseName() const;
   
 /** Get the fullname of this Register. */
 string getFullName() const;

 /** Get the address of this Register. */
 Addr getAddr() const { return addr; }

 /** Get the width in bytes of this Register. */
 uint getWidth() const { return regType->widthBytes; }

 /** Get a pointer to the Data associated with this Register. */
 Data *getPtr() { return &regState->value; }

 /** Return true if this Register is an element in a RegisterArray,
  *  otherwise false. */
 bool isElement() const { return element; }

 /** If this Register is an element in a RegisterArray, get the index 
  *  of this element. If this Register is not an element in a RegisterArray
  *  the behavior of this method is undefined. */
 uint getIndex() const { assert(element); return index; }

 /** Get the value of this Register. This returns the value of the full
  *  width of the Register regardless of the AccessType settings of the 
  *  associated fields. For Registers that are narrower than 64 bits, the
  *  upper unused bits will be returned as zero. This method is suitable
  *  for simulator code that models internal hardware 
  *  accesses. It should not be used to model software accesses to the 
  *  architectural state - these should use the Register::read method.
  */
 inline Data get() const
 {
   return regState->value;
 }

 /** Get the value of this Register. This returns the value of the full
  *  width of the Register regardless of the AccessType settings of the 
  *  associated fields. For Registers that are narrower than 64 bits, the
  *  upper unused bits will be returned as zero. This method is suitable
  *  for simulator code that models internal hardware 
  *  accesses. It should not be used to model software accesses to the 
  *  architectural state - these should use the Register::read method.
  */
 inline operator Data() const
 {
   return regState->value;
 }  

 /** Get the reset value of this Register. For Registers that are narrower 
  *  than 64 bits, the upper unused bits will be returned as zero. */
 Data getResetValue() const
 {
   return regType->resetValue;
 }

 /** Set the value of this Register. This sets the value for the full width
  *  of the Register regardless of the AccessType settings of the associated 
  *  fields. For Registers that are narrower than 64 bits, the
  *  upper unused bits will be forced to zero, regardless of the parameter d.
  *  This method is suitable for simulator code that models internal 
  *  hardware accesses. It should not be used to model software accesses 
  *  to the architectural state - these should use the Register::write method.
  *    @param d the new Data value for this Register.
  */
 inline void set(Data d)
 {
   regState->value = d & regType->widthMask;
   regInfo->assigned = true;
   regInfo->clean = false;
 }

 /** Set the value of this Register. This sets the value for the full width
  *  of the Register regardless of the AccessType settings of the associated 
  *  fields. For Registers that are narrower than 64 bits, the
  *  upper unused bits will be forced to zero, regardless of the parameter d.
  *  This method is suitable for simulator code that models internal 
  *  hardware accesses. It should not be used to model software accesses 
  *  to the architectural state - these should use the Register::write method.
  *    @param d the new Data value for this Register.
  */
 inline Register &operator=(Data d)
 {
   set(d);
   return *this;
 }

 /** Read the value of this Register. This returns from the value with
  *  the AccessType of each Field applied appropriately. For Registers 
  *  that are narrower than 64 bits, the upper unused bits will be 
  *  returned as zero. There may be other hardware side-effects caused by the 
  *  act of reading, as required by the architecture specification for 
  *  this Register. This method is suitable to model software 
  *  accesses to the architectural state. Other uses should consider 
  *  the Register::get method.
  */
 Data read()
 {
   Data original = regState->value;
   Data d = (original & regType->readMask) |
            (UNDEFINED_DATA & regType->readAsUndefinedMask);

   if (regType->readToClearMask != 0) {
     regState->value &= ~regType->readToClearMask;
     regInfo->assigned = true;
     regInfo->clean = false;
   }

   d = regReadCB(block, original, d);

   if (regType->readBlockCB) {
     assert(block != NULL);
     d = block->regReadBlockCB(this, original, d);
   }

   return d;
 }

 /** Write the value of this Register. This writes to the value with
  *  the AccessType of each Field applied appropriately. For Registers 
  *  that are narrower than 64 bits, the upper unused bits will be 
  *  forced to zero, regardless of the parameter d. There may be other
  *  hardware side-effects caused by the act of writing, as required by 
  *  the architecture specification for this Register. This method should
  *  be used to model software accesses to the architectural state. Other
  *  uses should consider the Register::set method.
  *    @param d the new Data value for this Register.
  */
 void write(Data d)
 { 
   Data original = regState->value;

   if (regType->writeMask != 0) {
     regState->value = (original & ~regType->writeMask) | 
                       (d & regType->writeMask);
     regInfo->assigned = true;
     regInfo->clean = false;
   }

   if (regType->writeOneToClearMask != 0) {
     Data clearMask = d & regType->writeOneToClearMask;
     if (clearMask != 0) {
       regState->value &= ~clearMask;
       regInfo->assigned = true;
       regInfo->clean = false;
     }
   }

   if (regType->writeOneToSetMask != 0) {
     Data setMask = d & regType->writeOneToSetMask;
     if (setMask != 0) {
       regState->value |= setMask;
       regInfo->assigned = true;
       regInfo->clean = false;
     }
   }

   regWriteCB(block, original, d);

   if (regType->writeBlockCB) {
     assert(block != NULL);
     block->regWriteBlockCB(this, original, d);
   }
 }

 /** Call-back function for when a register is read from.
  *    @param b the Block associated with this Register, or NULL if no Block.
  *    @param origValue the value of this register prior to the read.
  *    @param readValue the result of the read of this register (following
  *           the conventions for the FieldType of each Field in the 
  *           Register).
  *    @result the value that will be returned for this read.
  *
  *  The regReadCB virtual method provides a call-back function called
  *  upon any read from this register. This can be
  *  be used to monitor accesses, trigger control side-effects or
  *  over-ride the default access semantics. The call-back function is
  *  called AFTER the architectural state of the register has been
  *  accessed/updated for the access, though the call-back has the opportunity
  *  to modify the architectural state if it needs to.
  *
  *  Typically, the call-back will return readValue as the result. However,
  *  the call-back code has the opportunity to return any value allowing
  *  the FieldType conventions to be over-ridden if required. The value
  *  of the Register after the read can be accessed via the Register pointer.
  *  It must not be read/written as this will cause recursion into the
  *  call-back mechanism!! Instead, use Register::get and Register::set to
  *  access the register value directly.
  *
  *  This is a virtual method, and its default implementation is to
  *  return the expected read value with no side-effects. Subclasses
  *  of Register can over-ride this method so that specific code is executed
  *  when a register is read from. It is NOT necessary to enable the 
  *  Register-level call-back mechanism - providing a virtual method that 
  *  over-rides Register::regReadCB is sufficient to catch the call-back.
  *
  *  See also Block::regReadCB(). Note that Register-level call-backs are 
  *  made before Block-level call-backs.
  */
 virtual Data regReadCB(Block *b, Data origValue, Data readValue)
 {
   return readValue;
 }

 /** Call-back function for when a register is written to.
  *    @param b the Block associated with this Register, or NULL if no Block.
  *    @param origValue the value of this register prior to the write.
  *    @param writeValue the value that is being written to the register.
  *
  *  The regWriteCB virtual method provides a call-back function called
  *  upon any write to this register. This can be
  *  be used to monitor accesses, trigger control side-effects or
  *  over-ride the default access semantics. The call-back function is
  *  called AFTER the architectural state of the register has been
  *  accessed/updated for the access, though the call-back has the opportunity
  *  to modify the architectural state if it needs to.
  *  
  *  The value of the Register after the write can be accessed via the 
  *  Register pointer. It must not be read/written as this will cause 
  *  recursion into the call-back mechanism!! Instead, use Register::get 
  *  and Register::set to access the register value directly.
  *  Typically, the call-back will not modify the register value. However,
  *  the call-back code has the opportunity to write any value allowing
  *  the FieldType conventions to be over-ridden if required. 
  *
  *  This is a virtual method, and its default implementation is empty
  *  so that there are no side-effects. Subclasses of Register can over-ride 
  *  this method so that specific code is executed when a register is 
  *  written to. It is NOT necessary to enable the 
  *  Register-level call-back mechanism - providing a virtual method that 
  *  over-rides Register::regWriteCB is sufficient to catch the call-back.
  *
  *  See also Block::regWriteCB(). Note that Register-level call-backs are 
  *  made before Block-level call-backs.
  */
 virtual void regWriteCB(Block *b, Data origValue, Data writeValue) {}

 /** Mark this Register as unassigned and give this Register
  *  an undefined value. */
 void undefined()
 {
   regState->value = UNDEFINED_DATA & regType->widthMask;
   regInfo->assigned = false;
   regInfo->clean = false;
 }
 
 /** Make this Register dirty. */
 void makeDirty() { regInfo->clean = false; }
 
 /** Make this Register clean. */
 void makeClean() { regInfo->clean = true; }
 
 /** Return true if this Register is dirty, else false. */
 bool isDirty()   { return !regInfo->clean; }
 
 /** Return true if this Register is clean, else false. */
 bool isClean()   { return regInfo->clean; }

 /** Enable write Block-level call-backs for this Register. */
 void enableWriteBlockCB()
 {
   assert(block != NULL);
   regType->writeBlockCB = true;
 }

 /** Disable write Block-level call-backs for this Register. */
 void disableWriteBlockCB()
 {
   regType->writeBlockCB = false;
 }

 /** Enable read Block-level call-backs for this Register. */
 void enableReadBlockCB()
 {
   assert(block != NULL);
   regType->readBlockCB = true;
 }

 /** Disable read Block-level call-backs for this Register. */
 void disableReadBlockCB()
 {
   regType->readBlockCB = false;
 }

 /** Print this Register to the specified output stream. */
 void printThis(ostream &os);
 
 /** Reset this Register to its initial value. */
 void resetThis();
 
 /** Create the Signature for this Register so that it can subsequently
  *  be traced. 
  *    @param ofs the output file stream.*/
 void signThis(ofstream &ofs);
 
 /** Trace this Register to the specified output stream.
  *    @param ofs the output file stream.*/
 void traceThis(ofstream &ofs);

private:
 /** Initialize a derived Register to the specified values.
  *    @param b a pointer to the Block with which this Register is associated.
  *    @param a the address of this Register.
  *    @param e true if the Register is an element in an array, else false.
  *    @param i the index of the Register in the array if e is true.
  *    @param rt the RegisterType for this Register.
  *    @param rs the RegisterState for this Register.
  *    @param ri the RegisterInfo for this Register.
  *    @param s the Signature for this Register.
  */ 
 void init(Block *b, Addr a, bool e, uint i, RegisterType *rt,
           RegisterState *rs, RegisterInfo *ri, Signature *s);

 string baseName;
 Block *block;
 Addr addr;
 bool derived;
 bool element;
 uint index;
 RegisterType *regType;
 RegisterState *regState;
 RegisterInfo *regInfo;
 Signature *mySignature;
};

/** FieldType contains the type information for a Field. These are
*  static properties of a Field that cannot be modified once the Field
*  has been created, and are consistent across all elements in a FieldArray.
*
*  Note that FieldType is used in the implementation of the Field class.
*  There should be no reason to use this class from elsewhere since Field
*  provides a complete public interface to fields. Most of the state
*  inside FieldType is private without any direct access methods.
*/

class FieldType
{
friend class Field;
friend class FieldArray;
friend class Register;

public:
 /** Constructor for FieldType.
  *    @param f the fullname of the associated Register.
  *    @param n the basename of this field.
  *    @param r the RegisterType to which this FieldType belongs.
  *    @param a the AccessType of this field.
  *    @param e the end bit position of this field (highest bit number).
  *    @param s the start bit position of this field (lowest bit number).
  *    @param b field has a defined initial value if true, otherwise 
  *             undefined.
  *    @param d the initial value of the field (if it has one).
  */
 FieldType(string f, string n, RegisterType *r, AccessType a,
           uint e, uint s, bool b=false, Data d=0);

 /** Get the basename of this FieldType. */
 string getBaseName() const { return baseName; }  

 /** Get the access type of this FieldType as a string. */
 string getAccessType() const;

private:
 bool overlap(FieldType *f);
 void check(RegisterType *r, string n);

 string baseName;
 RegisterType *regType;

 AccessType access;
 uint start;
 uint end;
 Data regMask;
 Data fieldMask;
 Data resetValue;
};

/** The Field class provides mechanisms to construct and access Field
*  instances. When a Field is constructed, it is associated with a
*  Register instance. The Register provides the state for the field
*  (in the RegisterState class), while the Field provides the type
*  information which is then collated into the RegisterType class. 
* 
*  Internally, the Field class contains pointers to FieldType, RegisterType
*  and RegisterState instances. For a FieldArray, an array of Fields is
*  not allocated since this is too expensive. Instead just one FieldType is
*  allocated for the whole array. When a FieldArray is subscripted to
*  yield a Field, an instance of the Field class is initialized
*  appropriately. This is returned-by-value so that the state is
*  provided by the caller of the FieldArray subscription operator.
*  This Field instance gets destructed when it goes out of 
*  scope or is deallocated by the caller. Additionally, the returned
*  Field refers to the correct RegisterState structure in the original
*  RegisterArray so that writes/sets to the returned Field structure
*  will correctly update the value in the array. In some ways it is more
*  appropriate to consider the Field structure as a field
*  handle, and not the field value itself.                               
*/

class Field
{
friend class FieldArray;

public:
 /** Constructor for Field.
  *    @param n the basename of this field.
  *    @param r the Register to which this Field belongs.
  *    @param a the AccessType of this field.
  *    @param e the end bit position of this field (highest bit number).
  *    @param s the start bit position of this field (lowest bit number).
  *    @param b field has a defined initial value if true, otherwise 
  *             undefined.
  *    @param d the initial value of the field (if it has one).
  */
  Field(string n, Register *r, AccessType a,
        uint e, uint s, bool b=false, Data d=0);
       
 /** The copy constructor for Field. The destination Field is marked
  *  as derived so that destructing that Field does not deallocate the
  *  heap state allocated by the source Field. It is assumed that
  *  non-derived Field instances (the original source of one or more
  *  copies) will out-live all copies. This is reasonable since non-derived
  *  Field instances correspond to architectural state and should be
  *  allocated for the entire simulation.
  */
 Field(const Field &f);
 
 /** Constructor for Field with no parameters to initialize the field
  *  to a default state. This is provided for the FieldArray::lookup()
  *  mechanism. */
 Field();
 
 /** Destructor for Field */
 ~Field();

 /** The copy assignment operator for Field.  The destination Field is 
  *  marked as derived so that destructing that Field does not deallocate
  *  the heap state allocated by the source Field. It is assumed that
  *  non-derived Field instances (the original source of one or more
  *  copies) will out-live all copies. This is reasonable since non-derived
  *  Field instances correspond to architectural state and should be
  *  allocated for the entire simulation.
  *    @param f the source Field for the copy assignment.
  */
 Field &operator=(const Field &f);

 /** Get the basename of this Field. */
 string getBaseName() const;
 
 /** Get the fullname of this Field. */
 string getFullName() const;

 /** Get the access type of this field. */
 AccessType getAccessType() const { return fieldType->access; }

 /** Get the start bit number of this field. */
 uint getStartBit() const { return fieldType->start; }

 /** Get the end bit number of this field. */
 uint getEndBit() const { return fieldType->end; }

 /** Get a bit-mask for masking the field when the field is held 
  *  in the appropriate bit positions in the associated Register. */
 Data getRegMask() const { return fieldType->regMask; }

 /** Get a bit-mask for masking the field when the lowest bit of
  *  field is held in bit 0 of a Data variable. */
 Data getFieldMask() const { return fieldType->fieldMask; }

 /** Get the value of this Field. This returns the full field value
  *  regardless of the AccessType setting. The value will be shifted
  *  down to bit 0 and masked to the width of the field. This method 
  *  is suitable for simulator code that models internal hardware 
  *  accesses.
  */
 inline Data get() const
 {
   return (reg->regState->value >> fieldType->start) & fieldType->fieldMask;
 }

 /** Get the value of this Field. This returns the full field value
  *  regardless of the AccessType setting. The value will be shifted
  *  down to bit 0 and masked to the width of the field. This method 
  *  is suitable for simulator code that models internal hardware 
  *  accesses.
  */
 inline operator Data() const
 {
   return get();
 }

 /** Get the value of this Field without shifting. This returns the full 
  *  field value regardless of the AccessType setting. The value will
  *  NOT be shifted but will be left in the same bit position as the field
  *  in the whole Register. The value will be masked to the width of the 
  *  field. This method is suitable for simulator code that models 
  *  internal hardware accesses.
  */
 inline Data getNoShift() const
 {
   return reg->regState->value & fieldType->regMask;
 }

 /** Get the reset value of this Field. */
 Data getResetValue() const
 {
   return fieldType->resetValue;
 }

 /** Set the value of this Field. This sets the full field value
  *  regardless of the AccessType setting. The provided value will 
  *  be shifted up to the start bit position of the field and masked 
  *  to the width of the field. This method is suitable 
  *  for simulator code that models internal hardware accesses.
  *    @param d the new Data value for the Field.
  */
 inline void set(Data d)
 {
   reg->regState->value = (reg->regState->value & ~fieldType->regMask) | 
                          ((d & fieldType->fieldMask) << fieldType->start);
   reg->regInfo->assigned = true;
   reg->regInfo->clean = false;
 }

 /** Set the value of this Field. This sets the full field value
  *  regardless of the AccessType setting. The provided value will 
  *  be shifted up to the start bit position of the field and masked 
  *  to the width of the field. This method is suitable 
  *  for simulator code that models internal hardware accesses.
  *    @param d the new Data value for the Field.
  */
 inline Field &operator=(Data d)
 {
   set(d);
   return *this;
 }

 /** Set the value of this Field without shifting. This sets the full field 
  *  value regardless of the AccessType setting. The provided value will 
  *  NOT be shifted and is required to already be in the same bit position 
  *  as the field in the whole Register. It will be masked to the width of 
  *  the field. This method is suitable for simulator code that models 
  *  internal hardware accesses.
  *    @param d the new Data value for the Field.
  */
 inline void setNoShift(Data d)
 {
   reg->regState->value = (reg->regState->value & ~fieldType->regMask) | 
                          (d & fieldType->regMask);
   reg->regInfo->assigned = true;
   reg->regInfo->clean = false;
 }

 /** Read the value of this Field. This returns the value with
  *  the AccessType of each Field applied appropriately. Note that the 
  *  Register call-back mechanism is applied only to whole Register 
  *  reads/writes and not Field reads/writes. For this reason, architectural
  *  reads of Register values should use Register::read, and not be broken
  *  down into Field-level reads.
  */
 Data read()
 {
   Data d;

   if (fieldType->access == Access_WO)
     d = (UNDEFINED_DATA >> fieldType->start) & fieldType->fieldMask;
   else if (fieldType->access == Access_L)
     d = 0;
   else
     d = (reg->regState->value >> fieldType->start) & fieldType->fieldMask;

   if (fieldType->access == Access_RC ||
       fieldType->access == Access_RCW1C ||
       fieldType->access == Access_RCW1S) {
     reg->regState->value &= ~fieldType->regMask;
     reg->regInfo->assigned = true;
     reg->regInfo->clean = false;
   }

   return d;
 }

 /** Write the value of this Field. This writes to the value with
  *  the AccessType of each Field applied appropriately.  Note that the 
  *  Register call-back mechanism is applied only to whole Register 
  *  reads/writes and not Field reads/writes. For this reason, architectural
  *  writes to Register values should use Register::write, and not be broken
  *  down into Field-level writes.
  *    @param d the new Data value for the Field.
  */
 void write(Data d)
 {
   if (fieldType->access == Access_RW1C ||
       fieldType->access == Access_RCW1C) {
     Data clearMask = (d & fieldType->fieldMask) << fieldType->start;
     if (clearMask != 0) {
       reg->regState->value &= ~clearMask;
       reg->regInfo->assigned = true;
       reg->regInfo->clean = false;
     }      
   }
   else if (fieldType->access == Access_RW1S ||
            fieldType->access == Access_RCW1S) {
     Data setMask = (d & fieldType->fieldMask) << fieldType->start;
     if (setMask != 0) {
       reg->regState->value |= setMask;
       reg->regInfo->assigned = true;
       reg->regInfo->clean = false;
     }      
   }
   else if (fieldType->access != Access_RO) {
     reg->regState->value = (reg->regState->value & ~fieldType->regMask) | 
                            ((d & fieldType->fieldMask) << fieldType->start);
     reg->regInfo->assigned = true;
     reg->regInfo->clean = false;
   }
 }

private:
 bool derived;
 Register *reg;
 FieldType *fieldType;
};

/** @} */

#endif