Subversion Repositories ssbcc

# Copyright 2012-2015, Sinclair R.F., Inc.

# Base classes and utility function for generating general-purpose and interrupt

# peripherals.

import re

from ssbccUtil import IntValue

from ssbccUtil import IsIntExpr

from ssbccUtil import IsPosInt

from ssbccUtil import IsPowerOf2

from ssbccUtil import ParseIntExpr

from ssbccUtil import SSBCCException

class SSBCCperipheral:

  """Base class for peripherals"""

  def __init__(self,peripheralFile,config,param_list,loc):

    """

    Prototype constructor.

    peripheralFile      the full path name of the peripheral source

                        Note:  "__file__" doesn't work because 'execfile" and

                        "exec" are used to load the python script for the

                        peripheral.

    config              the ssbccConfig object for the processor core

    param_list          parameter list for the processor

    loc                 file name and line number for error messages

    """

    pass;

  def AddAttr(self,config,name,value,reformat,loc,optFn=None):

    """

    Add attribute to the peripheral:

    config      ssbccConfig object for the procedssor core

    name        attribute name

    value       possibly optional value for the attribute

    reformat    regular expression format for the attribute value

                Note:  reformat=None means the attribute can only be set to True

    loc         file name and line number for error messages

    optFn       optional function to set stored type

                Note:  See IntPow, RateMethod, etc. below for example methods.

    """

    if hasattr(self,name):

      raise SSBCCException('%s repeated at %s' % (name,loc,));

    if reformat == None:

      if value != None:

        raise SSBCCException('No parameter allowed for %s at %s' % (name,loc,));

      setattr(self,name,True);

    else:

      if value == None:

        raise SSBCCException('%s missing value at %s' % (name,loc,));

      if not re.match(reformat,value):

        raise SSBCCException('I/O symbol at %s does not match required format "%s":  "%s"' % (loc,reformat,value,));

      if optFn != None:

        try:

          value = optFn(value);

        except SSBCCException,msg:

          raise SSBCCException('Parameter "%s=%s" at %s:  %s' % (name,value,loc,str(msg),));

        except:

          raise SSBCCException('Value for "%s" not parsable at %s:  "%s"' % (name,loc,value,));

      setattr(self,name,value);

  def GenAssembly(self,config):

    """

    Virtual method to generate assembly modules associated with the peripheral.

    """

    pass;

  def GenHDL(self,fp,config):

    """

    Generate the peripheral HDL.

    fp          file pointer for the output processor

    config      ssbccConfig object for the procedssor core

    """

    if config.Get('hdl') == 'Verilog':

      self.GenVerilog(fp,config);

    elif config.Get('hdl') == 'VHDL':

      self.GenVHDL(fp,config);

    else:

      raise SSBCCException('HDL "%s" not implemented' % config.Get('hdl'));

  def GenVerilog(self,fp,config):

    """

    Virtual method to generate the Verilog version of the peripheral.

    Raise an exception if there is no Verilog version of the peripheral.

    """

    raise Exception('Verilog is not implemented for this peripheral');

  def GenVerilogFinal(self,config,body):

    """

    Clean up the peripheral code.

    Change "$clog2" to "clog2" for simulators and synthesis tools that don't

      recognize or process "$clog2."

    """

    if config.Get('define_clog2'):

      body = re.sub('\$clog2','clog2',body);

    return body;

  def GenVHDL(self,fp,config):

    """

    Virtual method to generate the VHDL version of the peripheral.

    Raise an exception if there is no VHDL version of the peripheral.

    """

    raise Exception('VHDL is not implemented for this peripheral');

  def LoadCore(self,filename,extension):

    """

    Read the source HDL for the peripheral from the same directory as the python

    script.

    filename    name for the python peripheral (usually "__file__")

    extension   the string such as ".v" or ".vhd" required by the HDL\n

    Note:  The '.' must be included in the extension.  For example, the UART

           peripheral uses '_Rx.v' and '_Tx.v' or similar to invoke the UART_Tx

           and UART_Rx HDL files.

    """

    hdlName = re.sub(r'\.py$',extension,filename);

    fp = open(hdlName,'rt');

    body = fp.read();

    fp.close();

    return body;

  ##############################################################################

  #

  # Methods to supplement python intrisics for the optFn argument of AddAttr

  #

  # Note:  AddAttr embelleshes exception messages with the symbol name and

  #        source code line number.

  #

  # Note:  One weird side effect of using lambda expressions is that the

  #        functions won't be recognized unless they're members of the

  #        SSBCCperipheral class.

  #

  ##############################################################################

  def IntPow2Method(self,config,value,lowLimit=1,highLimit=None):

    """

    Return the integer value of the argument if it is a power of 2 between the

    optional limits (inclusive).  Otherwise throw an error.\n

    Note:  Other than a lower limit of 1 for "lowLimit", IntMethod validates

           "lowLimit" and "highLimit".

    """

    value = self.IntMethod(config,value,lowLimit,highLimit)

    if lowLimit < 1:

      raise SSBCCException('Program bug:  lowLimit = %d is less than 1' % lowLimit);

    if not IsPowerOf2(value):

      raise SSBCCException('Must be a power of 2');

    return value;

  def IntMethod(self,config,value,lowLimit=None,highLimit=None):

    """

    Return the integer value of the argument.  Throw an error if the argument is

    unrecognized, not an integer, or is outside the optionally specified range.

    """

    if (lowLimit != None) and (highLimit != None) and (highLimit < lowLimit):

      raise SSBCCException('Program bug:  lowLimit = %d and highLimit = %d conflict' % (lowLimit,highLimit,));

    if re.match(r'L_\w+$',value):

      if not config.IsParameter(value):

        raise SSBCCException('Unrecognized parameter');

      ix = [param[0] for param in config.parameters].index(value);

      value = config.parameters[ix][1];

    elif re.match(r'C_\w+$',value):

      if not config.IsConstant(value):

        raise SSBCCException('Unrecognized constant');

      value = config.constants[value];

    value = ParseIntExpr(value);

    if (lowLimit != None) and value < lowLimit:

      if lowLimit == 1:

        raise SSBCCException('Must be a positive integer');

      else:

        raise SSBCCException('Cannot be less than %d' % lowLimit);

    if (highLimit != None) and value > highLimit:

      raise SSBCCException('Cannot be more than %d' % highLimit);

    return value;

  def IntValueMethod(self,value):

    """

    """

    return IntValue(value);

  def RateMethod(self,config,value):

    """

    Return the string to evaluate the provided value or ratio of two values.

    The value can be an integer (including underscores), a constant, or a

    parameter.  Ratios are restated to do rounding instead of truncation.\n

    Examples:

      123456

      123_456

      L_DIVISION_RATIO

      G_CLOCK_FREQUENCY_HZ/19200

      C_CLOCK_FREQUENCY_HZ/19200

      G_CLOCK_FREQUENCY_HZ/L_BAUD_RATE

      100_000_000/G_BAUD_RATE

    """

    def LocalIntMethod(self,config,value,position=None):

      try:

        if config.IsParameter(value):

          return value;

        else:

          v = self.IntMethod(config,value,lowLimit=1);

          return str(v);

      except SSBCCException, msg:

        if not position:

          raise SSBCCException(msg);

        else:

          raise SSBCCException('%s in %s' % (msg,position,));

    if value.find('/') < 0:

      return LocalIntMethod(self,config,value);

    else:

      ratearg = re.findall('([^/]+)',value);

      if len(ratearg) != 2:

        raise SSBCCException('Only one "/" allowed in expression');

      ratearg[0] = LocalIntMethod(self,config,ratearg[0],'numerator');

      ratearg[1] = LocalIntMethod(self,config,ratearg[1],'denominator');

      return '(%s+%s/2)/%s' % (ratearg[0],ratearg[1],ratearg[1],);

  def TimeMethod(self,config,value,lowLimit=None,highLimit=None):

    """

    Convert the provided time from the specified units to seconds.

    """

    if not re.match(r'(0|[1-9]\d*)(\.\d*)?(e[+-]?\d+)?[mun]?s$',value):

      raise SSBCCException('Malformed time value');

    if value[-2:] == 'ms':

      v = float(value[:-2]) * 1.e-3;

    elif value[-2:] == 'us':

      v = float(value[:-2]) * 1.e-6;

    elif value[-2:] == 'ns':

      v = float(value[:-2]) * 1.e-9;

    else:

      v = float(value[:-1]);

    if (lowLimit != None) and (v < lowLimit):

      raise SSBCCException('%s must be %s or greater' % (v,lowLimit,));

    if (highLimit != None) and (v > highLimit):

      raise SSBCCException('%s must be %s or smaller' % (v,highLimit,));

    return v;

################################################################################

#

# Base class for interrupt peripherals.

#

################################################################################

class SSBCCinterruptPeripheral(SSBCCperipheral):

  """

  Base class for interrupt peripherals.

  """

  instance = None;

  def __init__(self,config,loc):

    """

    Perform tasks common to all interrupt peripherals:

      Ensure only one interrupt peripheral is defined.

      Declare the O_INTERRUPT_DIS and O_INTERRUPT_ENA output ports.

        These are set/reset outports and only require 2 instructions.

        These 2-instruction sequences are automatically generated by the ".ena"

          and ".dis" macros.

      ...\n

    Note:  The "param_list" normally part of a peripheral __init__ method is

           missing.  First, it isn't required here.  Second, that helps ensure

           that this class is not instantiated by itself as a peripheral.

    """

    # Ensure only one interrupt peripheral gets defined.

    if SSBCCinterruptPeripheral.instance:

      raise SSBCCException('Interrupt peripheral already defined before line %d' % loc);

    SSBCCinterruptPeripheral.instance = self;

    # Add the signals required by the interrupt handler.

    config.AddSignal('s_interrupt',1,loc);

    config.AddSignal('s_interrupted',1,loc);

    # Add the outports to disable and enable interrupts.

    self.ix_outport_interrupt_dis = config.NOutports();

    config.AddOutport(('O_INTERRUPT_DIS',True,),loc);

    self.ix_outport_interrupt_ena = config.NOutports();

    config.AddOutport(('O_INTERRUPT_ENA',True,),loc);

################################################################################

#

# Utilties for interrupt peripherals.

#

################################################################################

def InterruptPeripheralAssigned():

  """

  Indicate whether or not an interrupt peripheral has been generated.

  """

  return True if SSBCCinterruptPeripheral.instance else False;