sam-t2/sam/devices/common/regdef/include/Signature.h

/*
* ========== Copyright Header Begin ==========================================
*
* OpenSPARC T2 Processor File: Signature.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 __Signature_h
#define __Signature_h

#include <iostream>
#include <fstream>
#include <assert.h>
#include "Datatype.h"
#include "List.h"
#include "Trace.h"
using namespace std;

/** @file Signature.h
 *  Signature.h defines classes that are used for signatures.
 *
 *  @sa Signature_Module
 */

/** @defgroup Signature_Module The Signature Module
 *  Signature.h defines classes that are used for signatures. A signature
 *  is used to specify the fields of a class isntance that are traceable. Once
 *  a signature has been created, the process of tracing that class instance
 *  is fully automated. The main purpose of the Signature mechanism is to
 *  identify the state to be traced, and to provide symbolic names for the
 *  trace. This is currently to trace Register and Transaction instances
 *  with supporting infrastructure in Object, Block, Port and Signal classes.
 *
 *  @{
 */

/** SignType is the base class for types that can be included in a Signature.
 *  This class is derived from Traceable which causes each SignType instance
 *  to have a unique Trace ID. Apart from the constructor, the other methods
 *  of this class are virtual or pure virtual, and provided by sub-classes. */

class SignType : public Traceable
{
public:
  /** Constructor for SignType.
   *    @param t the name of this type.
   *    @param p the name of the parent Object containing this data.
   *    @param n the name of this data.
   */
  SignType(string t, string p, string n);

  /** Destructor for SignType. This is virtual so that the appropriate
   *  destructor for any derived class is used. */
  virtual ~SignType() {}

  /** Convert the value of this data to a string (for tracing). Since
   *  the data is provided by the sub-class, and not by SignType,
   *  this is a pure virtual method. */
  virtual string toString() = 0;

  /** Convert the value of this data to a 64-bit integer. Since
   *  the data is provided by the sub-class, and not by SignType,
   *  this is a pure virtual method. */
  virtual Data getValue() = 0;

  /** Get the name of this type. */
  virtual string getType() { return type; }

  /** Get the basename of the data instance associated with this SignType. */
  virtual string getBaseName() { return baseName; }

  /** Get the full name of the data instance associated with this SignType. */
  virtual string getFullName() { return fullName; }

protected:
  string type;
  string baseName;
  string fullName;
};

/** SignAddr is a specific SignType used for holding the signature for a
 *  piece of data of type Addr. This allows the value of that data to be
 *  traced. */
class SignAddr : public SignType
{
public:
  /** Constructor for SignAddr.
   *    @param p the name of the parent Object containing this Addr data.
   *    @param n the name of this Addr data.
   *    @param a a pointer to the Addr data. This is used to retrieve the
   *    value when required for tracing.
   */
  SignAddr(string p, string n, Addr *a) : SignType("addr", p, n)
  {
    addr = a;
  }

  /** Destructor for SignAddr. */
  ~SignAddr() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return Data(*addr); }

private:
  Addr *addr;
};

/** SignByte is a specific SignType used for holding the signature for a
 *  piece of data of type Byte. This allows the value of that data to be
 *  traced. */
class SignByte : public SignType
{
public:
  /** Constructor for SignByte.
   *    @param p the name of the parent Object containing this byte.
   *    @param n the name of this byte.
   *    @param a a pointer to the byte. This is used to retrieve the
   *    value when required for tracing.
   */
  SignByte(string p, string n, Byte *a) : SignType("byte", p, n)
  {
    byte = a;
  }

  /** Destructor for SignByte. */
  ~SignByte() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return Data(*byte); }

private:
  Byte *byte;
};

/** SignData is a specific SignType used for holding the signature for a
 *  piece of data of type Data. This allows the value of that data to be
 *  traced. By default all 64 bits of the Data will be traced. However,
 *  start and end bit positions can be specified in the constructor so
 *  that a single contiguous bit-field from the Data can be traced. This
 *  is used to support the tracing of a Field inside a Register. */

class SignData : public SignType
{
public:
  /** Constructor for SignData.
   *    @param p the name of the parent Object containing this data.
   *    @param n the name of this data.
   *    @param d a pointer to the data. This is used to retrieve the
   *    value when required for tracing.
   *    @param e the end bit position of this field (highest bit number).
   *    @param s the start bit position of this field (lowest bit number).
   */
  SignData(string p, string n, Data *d, uint e=63, uint s=0);

  /** Destructor for SignData. */
  ~SignData() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return *data & mask; }

  /** Get the basename of the data instance associated with this SignData. */
  string getBaseName();

  /** Get the full name of the data instance associated with this SignData. */
  string getFullName();

private:
  Data *data;
  Data mask;
  uint start;
  uint end;
};

/** SignBool is a specific SignType used for holding the signature for a
 *  piece of data of type bool. This allows the value of that data to be
 *  traced. */

class SignBool : public SignType
{
public:
  /** Constructor for SignBool.
   *    @param p the name of the parent Object containing this "bool" data.
   *    @param n the name of this "bool" data.
   *    @param b a pointer to the "bool" data. This is used to retrieve the
   *    value when required for tracing.
   */
  SignBool(string p, string n, bool *b) : SignType("bool", p, n)
  {
    boolean = b;
  }

  /** Destructor for SignBool. */
  ~SignBool() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return Data(*boolean ? 1 : 0); }

private:
  bool *boolean;
};

/** SignEnum is a specific SignType used for holding the signature for a
 *  piece of data which is an enumerated int. This allows the value of
 *  that data to be traced. */

class SignEnum : public SignType
{
public:
  /** Constructor for SignEnum.
   *    @param p the name of the parent Object containing this "enum" data.
   *    @param n the name of this "enum" data.
   *    @param e a pointer to the "enum" data. This is used to retrieve the
   *    value when required for tracing.
   */
  SignEnum(string p, string n, int *e) : SignType("enum", p, n)
  {
    integer = e;
  }

  /** Destructor for SignEnum. */
  ~SignEnum() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return Data(*integer); }

private:
  int *integer;
};

/** SignIdentifier is a specific SignType used for holding the signature for a
 *  piece of data which is an Identifier. This allows the value of
 *  that data to be traced. */

class SignIdentifier : public SignType
{
public:
  /** Constructor for SignIdentifier.
   *    @param p the name of the parent Object containing this Identifier data.
   *    @param n the name of this Identifier data.
   *    @param e a pointer to the Identifier data. This is used to retrieve the
   *    value when required for tracing.
   */
  SignIdentifier(string p, string n, Identifier *e) :
    SignType("id", p, n)
  {
    identifier = e;
  }

  /** Destructor for SignIdentifier. */
  ~SignIdentifier() {}

  /** Convert the value of this data to a string (for tracing). */
  string toString();

  /** Convert the value of this data to a 64-bit integer. */
  Data getValue() { return Data(*identifier); }

private:
  Identifier *identifier;
};

/** The Signature class is used to create and output signatures.
 *  A Signature consists of a list of signatures taken from instances of
 *  classes derived from SignType. Once the signature has been created,
 *  there are two operations that can be performed upon it:
 *
 *    - sign: this outputs a description of the signature definition
 *            (the parts of the signature that do not vary over time).
 *    - print: this outputs the values associated with the signature
 *             at the current time.
 *
 *  The sign operations can be used to print out information for a trace
 *  header (listing the static properties of everything that is to be traced),
 *  followed by a trace body (the dynamically varying values of things that
 *  are being traced). The separation ensures that the static parts can
 *  be output once at the beginning of the trace, and not repeated every clock
 *  cycle that an item is traced. This approach reduces trace file size.
 */

class Signature
{
public:
  /** PrintMode is an enumerated type indicating the mode of a print
   *  operation for a signature.
   */
  enum PrintMode {
    VALUE,      /**< print the value of each signature item. */
    DONTCARE,   /**< ignore values and print "X" to indicate "don't care". */
    IMPEDANCE   /**< ignore values and print "Z" to indicate "impedance". */
  };

  /** Constructor for Signature. */
  Signature() {}

  /** Destructor for Signature. */
  ~Signature();

  /** Add a SignType to this Signature. In fact, it is usually instances of
   *  classes that are derived from SignType. This is necessary because
   *  SignType has no associated data to trace, and also contains pure
   *  virtual functions that must be over-loaded to provide useful
   *  functionality.
   */
  void add(SignType *s);

  /** Output a textual representation of the signature onto the specified
   *  output file stream.
   *    @param ofs the output file stream.
   *    @param n the name of the scope of this signature (empty string if
   *             no new scope required).
   *    @param k a string containing the name of this kind of trace.
   *
   *  For each SignType in the signature, the output representation is
   *  as follows:
   *
   *    DEFN : VAR id kind type name
   *
   *  where:
   *    - id is the Trace Id of this SignType instance. This unique ID is used
   *      to associate the "DEFN" entries produced by Signature::sign with the
   *      "DATA" entries produced by Signature::print.
   *    - kind is the kind of trace and is given by parameter k (see above).
   *    - type is the type of this SignType instance.
   *    - name is the full-name of this SignType instance.
   *
   *  If a scope name is specified and if there is more than one SignType in
   *  this Signature, then the output will be bracketed by begin-scope and
   *  end-scope markers.
   */
  void sign(ofstream &ofs, string n, string k);

  /** Output a textual representation of the values associated with this
   *  signature onto the specified file stream.
   *    @param ofs the output file stream.
   *    @param pm print mode, see @see PrintMode for the available options.
   *
   *  For each SignType in the signature, the output representation is
   *  as follows:
   *
   *    DATA clock : type id value
   *
   *  where:
   *    - clock is the time at which this trace is produced.
   *    - type is the type of this SignType instance.
   *    - id is the Trace Id of this SignType instance. This unique ID is used
   *      to associate the "DEFN" entries produced by Signature::sign with the
   *      "DATA" entries produced by Signature::print.
   *    - value is the value of this SignType instance. This is produced by
   *      calling the "toString" virtual method of SignType.
   */
  void printThis(ofstream &ofs, PrintMode pm=VALUE);

  /** Output a marker to the output file stream indicating the beginning of
   *  a new scope.
   *    @param ofs the output file stream.
   *    @param s the name of this scope.
   *
   *  The output representation of a begin scope is:
   *
   *  DEFN : SCOPE BEGIN scope
   *
   *  where:
   *    - scope is the name of the new scope.
   */
  static void signScopeBegin(ofstream &ofs, string s);

  /** Output a marker to the output file stream indicating the end of
   *  the current scope.
   *    @param ofs the output file stream.
   *    @param s the name of this scope.
   *
   *  The output representation of end scope is:
   *
   *  DEFN : SCOPE END scope
   *
   *  where:
   *    - scope is the name of the current scope.
   */
  static void signScopeClose(ofstream &ofs, string s);

private:
  List<SignType> signatures;
};

/** @} */

#endif