gAttr.py

#!/usr/local/bin/python
#
#                               Copyright 2004
#                                     by
#                        The Board of Trustees of the
#                     Leland Stanford Junior University.
#                            All rights reserved.
#


## \namespace gAttr
##
## \brief GLAST LAT record attribute definitions.
##
## \b Contents:
##
## GLAST LAT functional block hierarchy representation in Python
## See <a href="http://www-glast.slac.stanford.edu/IntegrationTest/ONLINE/docs/TEM.pdf">
## The Tower Electronics Module (TEM) - Programming ICD specification (LAT-TD-00605-D1)</a>
## for more info

__facility__ = "Online"
__abstract__ = "GLAST LAT record attribute definitions"
__author__   = "Selim Tuvi <stuvi@slac.stanford.edu> SLAC - GLAST LAT I&T/Online"
__date__     = ("$Date: 2005/08/02 21:08:49 $").split(' ')[1]

__version__  = "$Revision: 2.17 $"
__release__ = "$Name: R04-12-00 $"
__credits__  = "SLAC"

import LATTE.copyright_SLAC

from LATTE.client.gException import LATInterfaceException

from gRule       import GruleBase
from gConstraint import GconstraintBase
from gEGU        import GEGU

import                  warnings

ATTR_READ             = 0x1
ATTR_WRITE            = 0x2
ATTR_READ_ONLY        = ATTR_READ
ATTR_WRITE_ONLY       = ATTR_WRITE
ATTR_READ_WRITE       = ATTR_READ | ATTR_WRITE
ATTR_NO_DIRECT_ACCESS = 0x4
ATTR_COMMAND          = 0x8 | ATTR_WRITE
ATTR_DEPRECATED       = 0x10

# The following is for backward compatibility only
REG_READ_ONLY        = ATTR_READ_ONLY
REG_WRITE_ONLY       = ATTR_WRITE_ONLY
REG_READ_WRITE       = ATTR_READ_WRITE
REG_NO_DIRECT_ACCESS = ATTR_NO_DIRECT_ACCESS



class Gattr(object):
  """\brief Base class which is instantiated once for each attribute kind.
  """
  # Set up a single instance of the defaults rather than one per Gattr
  defaultRule       = GruleBase()
  defaultConstraint = GconstraintBase()
  defaultEgu        = GEGU("")


  def __init__(self, name, id, size, flags, rule=None, constraint=None, egu=None):
    """Gattr constructor.

    \param name        The name of the attribute.
    \param size        Attribute size in bytes.
    \param rule        Optional. Attribute rule.
    \param constraint  Optional. Attribute constraint.
    \param egu         Optional. Attribute EGU
    """
    self.__name       = name.lower()
    self.__id         = id
    self.__size       = size
    self.__flags      = flags

    self.__rule       = rule
    self.__constraint = constraint
    self.__egu        = egu

  def create(self, node):
    return _Attr(node, self, self.__egu)

  def set(self, node, value, attr, bypass=0):
    raise Exception, "Missing set() implementation"      # Revisit status

  def get(self, node, attr, bypass=0):
    raise Exception, "Missing get() implementation"      # Revisit status

  def getName(self):
    return self.__name

  def size(self):
    """Method for returning the size of the attribute

    \return Attribute size in bytes
    """
    return self.__size

  def id(self):
    return self.__id

  def setRule(self, rule):
    """Method to attach a rule to a gAttr after the gAttr has been constructed.

    \param rule A Grule object instance
    """
    self.__rule = rule

  def getRule(self):
    """Retrieve the rule associated with the gAttr.
    """
    return self.__rule

  def setConstraint(self, constraint):
    """
    Method to attach a constraint to a gAttr after the gAttr has been constructed.
    This method will go away once constraints are loaded from a configuration file.

    \param constraint A Gconstraint object instance
    """
    self.__constraint = constraint

  def setEGU(self, egu):
    """
    Method to attach a EGU to a gAttr after the gAttr has been constructed.

    \param egu A Gegu object instance
    """
    self.__egu = egu

  def getEGU(self):
    """
    Method that returns the gEGU.GEGU class for this gAttr

    \return A Gegu object instance
    """
    return self.__egu

  def getConstraint(self):
    """
    Method that returns the gConstraint.Gconstraint class for this gAttr

    \return A Gconstraint object instance
    """
    return self.__constraint

  def flags(self):
    return self.__flags

  def isReadOnly(self):
    """ Returns a boolean value indicating if the attribute is read only or not

    \return 1=Read Only, 0=Not Read Only.
    """
    return self.__flags == ATTR_READ

  def isWriteOnly(self):
    """ Returns a boolean value indicating if the attribute is write only or not

    \return 1=Write Only, 0=Not Write Only.
    """
    return self.__flags == ATTR_WRITE

  def isReadWrite(self):
    """ Returns a boolean value indicating if the attribute is read write or not

    \return 1=Read Write, 0=Not Read Write.
    """
    return self.__flags == ATTR_READ_WRITE

  def isNoDirectAccess(self):
    """ Returns a boolean value indicating if the attribute is no direct access or not

    \return 1=No Direct Access, 0=Not No Direct Access.
    """
    return self.__flags == ATTR_NO_DIRECT_ACCESS

  def isCommand(self):
    """Returns a boolean value indicating if the attribute is a dataless command or not

    \return 1=Dataless command, 0=Not a dataless command.
    """
    return self.__flags & ATTR_COMMAND == ATTR_COMMAND

  def isDeprecated(self):
    """Returns a boolean value indicating if the attribute is deprecated or not

    \return 1=Deprecated, 0=Not deprecated.
    """
    return self.__flags & ATTR_DEPRECATED == ATTR_DEPRECATED


class GattrRaw(Gattr):
  """\brief Class which is instantiated for each raw register kind
  """
  def __init__(self, name, regno, size, flags=ATTR_READ_WRITE):
    """GattrRaw constructor

    \param name        The name of the register
    \param regno       Register no.
    \param size        Register size in bytes.

    """
    Gattr.__init__(self, name, regno, size, flags)

  def set(self, node, val, attr, bypass=0):
    """
    Method for setting the value of a register attribute.
    Calls the functions in the base class for setting values.

    \param val    Register value to be set
    \param bypass Optional. Flag for bypassing EGU conversion

    """
    response = node.load(self.id(), val)
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)
    return None, response.timestamp()

  def get(self, node, attr, bypass=0):
    """
    Method for getting the value of a register attribute.
    Calls the functions in the node class for getting values.
    If bypass=0 (the default), the value will be returned in EU.
    If bypass=1, the raw value will be returned.
    """
    response = node.read(self.id())
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)

    return response.value(), response.timestamp()


class GattrReg(Gattr):
  """\brief Class which is instantiated for each register
  """
  def __init__(self, name, regno, size, flags=ATTR_READ_WRITE,
               rule=Gattr.defaultRule, constraint=Gattr.defaultConstraint, egu=Gattr.defaultEgu):
    """GattrReg constructor

    \param name        The name of the register
    \param regno       Register no.
    \param size        Register size in bytes.
    \param rule        Optional. Register rule.
    \param constraint  Optional. Register constraint.
    \param egu         Optional. Register EGU

    """
    Gattr.__init__(self, name, regno, size, flags, rule, constraint, egu)

  def set(self, node, val, attr, bypass=0):
    """\brief Method for setting the value of a register attribute.

    Calls the functions in the base class for setting values.

    \param node   Node this register belongs to
    \param val    Register value to be set
    \param attr   _Attr instance
    \param bypass Optional. Flag for bypassing EGU conversion

    """
    if bypass:
      raw = val
    else:
      (val, rejected) = self._Gattr__constraint.evaluate(val)
      if rejected:
        return None, None
      raw = attr.getEGU().raw(val)

    response = node.load(self.id(), raw)
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)
    return None, response.timestamp()

  def get(self, node, attr, bypass=0):
    """\brief Method for getting the value of a register attribute.
    Calls the functions in the node class for getting values.

    \param node   Node this register belongs to
    \param attr   _Attr instance
    \param bypass Optional. Flag for bypassing EGU conversion
                  bypass=0 (the default), the value will be returned in EU.
                  bypass=1, the raw value will be returned.

    \return Register value.

    """
    response = node.read(self.id())
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)

    raw = response.value()
    if bypass:
      return raw, response.timestamp()
    else:
      egu = attr.getEGU().egu(raw)
      self._Gattr__rule.evaluate(egu, self, node)
      return egu, response.timestamp()

class GattrRegDepr(GattrReg):
  def __init__(self, name, regno, size, flags=ATTR_DEPRECATED|ATTR_READ_WRITE,
               rule=Gattr.defaultRule, constraint=Gattr.defaultConstraint, egu=Gattr.defaultEgu):
    GattrReg.__init__(self, name, regno, size, flags, rule, constraint, egu)

  def set(self, node, val, attr, bypass=0):
    """
    Method for setting the value of a register attribute.
    Calls the functions in the base class for setting values.

    \param val    Register value to be set
    \param bypass Optional. Flag for bypassing EGU conversion

    """
    warnings.warn("GattrReg.set: Attribute %s.%s deprecated. Please use the new attribute name"
                  % (node.getName(), self.getName())
                  , DeprecationWarning, stacklevel=2)
    return GattrReg.set(self, node, val, attr, bypass)

  def get(self, node, attr, bypass=0):
    """
    Method for getting the value of a register attribute.
    Calls the functions in the node class for getting values.
    If bypass=0 (the default), the value will be returned in EU.
    If bypass=1, the raw value will be returned.
    """

    warnings.warn("GattrReg.get: Attribute %s.%s deprecated. Please use the new attribute name"
                  % (node.getName(), self.getName())
                  , DeprecationWarning, stacklevel=2)

    return GattrReg.get(self, node, bypass)

class GattrDlc(Gattr):
  """Attribute class for implementing dataless commands"""
  def __init__(self, name, cmdNo, size=0, flags=ATTR_COMMAND):
    Gattr.__init__(self, name, cmdNo, 0, flags)
    self.get = self.set

  def set(self, node, *args):
    """
    Method for invoking a dataless command.
    The value parameter is meaningless for this method and is only supplied to
    satisfy the function signature.
    """
    response = node.send(self.id())
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)
    return None, response.timestamp()

class GattrBF(Gattr):
  """\brief Bit field class which is instantiated for each bit field kind

  This class allows operation on bit fields of the form (end, start]
  in a register specified by the register number (regno).

  N.B. This attribute operates on the raw value of the associated register
  """
  def __init__(self, name, regno, start, end, flags=ATTR_READ_WRITE):
    """GattrBF constructor

    \param name        The name of the bit field
    \param regno       Register no. containing the bit field
    \param start       Bit offset to start (inclusive) of the bit field
    \param end         Bit offset to the end (exclusive) of the bit field
    \param flags       Optional flags to govern access to the bit field

    """
    Gattr.__init__(self, name, regno, 0, flags)

    if end <= start:
      raise Exception, "Invalid bit field specification: start %d, end %d" % (start, end) # Revisit
    self.__offset = start
    self.__mask   = long(2**(end - start) - 1) << start

    # Find the size of the bitfield in bytes. Required by the register browser -ST
    (d,m) = divmod(end-start,8)
    self._Gattr__size = d + (m>0)

  def set(self, node, val, attr, bypass=0):
    """
    Method for setting the value of a bit field.
    Calls the functions in the base class for setting values.

    \param val    bit field value to be set
    \param bypass ignored

    """

    response = node.read(self.id())
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)

    value = ((response.value() & ~self.__mask) |
             ((long(val) << self.__offset) & self.__mask))

    response = node.load(self.id(), value)
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)
    return None, response.timestamp()

  def get(self, node, attr, bypass=0):
    """
    Method for getting the value of a bit field.

    \param val    bit field value to be set
    \param bypass ignored
    """
    response = node.read(self.id())
    status = response.status()
    if status & 0x3:  raise LATInterfaceException(status)

    value = (response.value() & self.__mask) >> self.__offset

    return value, response.timestamp()

class _Attr(object):
  """Helper class for private use in this file only.
  """


  def __init__(self, node, attr, egu):
    #print node.getName(), attr
    self.__node = node
    self.__attr = attr

    self.__timestamp = -1L

    #print id(self), id(attr), node.getName(), attr.getName(), attr.flags()
    if attr.flags() == (ATTR_READ | ATTR_NO_DIRECT_ACCESS):
      self.set = self.__badSet
      self.get = self.__badGet
    else:
      self.set = self.__set
      self.get = self.__get

    if egu is not None and egu is not Gattr.defaultEgu:
      self.setEGU(egu)

    # Callthroughs to 'parent' class

# This callthrough is only in effect if the _Attr__egu is not instantiated
#    getEGU           = Gattr.getEGU

#    setRule          = Gattr.setRule
#    setConstraint    = Gattr.setConstraint
#    getRule          = Gattr.getRule
#    getConstraint    = Gattr.getConstraint
#    getName          = Gattr.getName

#    id               = Gattr.id
#    size             = Gattr.size
#    isReadOnly       = Gattr.isReadOnly
#    isWriteOnly      = Gattr.isWriteOnly
#    isReadWrite      = Gattr.isReadWrite
#    isNoDirectAccess = Gattr.isNoDirectAccess
#    isCommand        = Gattr.isCommand


  def getName(self):
    return self.__attr.getName()

  def size(self):
    """Method for returning the size of the attribute

    \return Attribute size in bytes
    """
    return self.__attr.size()

  def id(self):
    return self.__attr.id()

  def setRule(self, rule):
    """Method to attach a rule to a gAttr after the gAttr has been constructed.

    \param rule A Grule object instance
    """
    return self.__attr.setRule(rule)

  def getRule(self):
    """Retrieve the rule associated with the gAttr.
    """
    return self.__attr.getRule()

  def setConstraint(self, constraint):
    """
    Method to attach a constraint to a gAttr after the gAttr has been constructed.
    This method will go away once constraints are loaded from a configuration file.

    \param constraint A Gconstraint object instance
    """
    return self.__attr.setConstraint(constraint)

  def setEGU(self, egu):
    """
    Method to attach a EGU to a gAttr after the gAttr has been constructed.

    \param egu A Gegu object instance
    """
    self.__egu = egu

  def getEGU(self):
    """
    Method that returns the gEGU.GEGU class for this gAttr

    \return A Gegu object instance
    """
    return getattr(self, '_Attr__egu', self.__attr.getEGU())

  def getConstraint(self):
    """
    Method that returns the gConstraint.Gconstraint class for this gAttr

    \return A Gconstraint object instance
    """
    return self.__attr.getConstraint()

  def flags(self):
    return self.__attr.flags()

  def isReadOnly(self):
    """ Returns a boolean value indicating if the attribute is read only or not

    \return 1=Read Only, 0=Not Read Only.
    """
    return self.__attr.isReadOnly()

  def isWriteOnly(self):
    """ Returns a boolean value indicating if the attribute is write only or not

    \return 1=Write Only, 0=Not Write Only.
    """
    return self.__attr.isWriteOnly()

  def isReadWrite(self):
    """ Returns a boolean value indicating if the attribute is read write or not

    \return 1=Read Write, 0=Not Read Write.
    """
    return self.__attr.isReadWrite()

  def isNoDirectAccess(self):
    """ Returns a boolean value indicating if the attribute is no direct access or not

    \return 1=No Direct Access, 0=Not No Direct Access.
    """
    return self.__attr.isNoDirectAccess()

  def isCommand(self):
    """Returns a boolean value indicating if the attribute is a dataless command or not

    \return 1=Dataless command, 0=Not a dataless command.
    """
    return self.__attr.isCommand()

  def isDeprecated(self):
    """Returns a boolean value indicating if the attribute is deprecated or not

    \return 1=Deprecated, 0=Not deprecated.
    """
    return self.__attr.isDeprecated()

  def __set(self, val, bypass=0, node=None):
    if node is not None:
      junk, self.__timestamp = self.__attr.set(node, val, self, bypass)
    else:                             # For backward compatibility
      junk, self.__timestamp = self.__attr.set(self.__node, val, self, bypass)

  def __get(self, bypass=0, node=None):
    if node is not None:
      val, self.__timestamp = self.__attr.get(node, self, bypass)
    else:                             # For backward compatibility
      val, self.__timestamp = self.__attr.get(self.__node, self, bypass)
    return val

  def __badSet(self, node, val, bypass=0):
    return -1                         # revisit
    #raise LATInterfaceException(1)

  def __badGet(self, node, val, bypass=0):
    return -1                         # revisit
    #raise LATInterfaceException(1)

  def getNode(self):
    return self.__node

  def setTimeStamp(self, value):
    self.__timestamp = value

  def getTimeStamp(self):
    """
    Method that returns the timestamp at the moment when the register was accessed.

    \return Timestamp in seconds as a floating point value
    """
    if self.__timestamp == -1:
      return self.__timestamp
    else:
      return ((self.__timestamp >> 32) +
              (self.__timestamp & 0xffffffffL) / 1000000000.0)

---