Subversion Repositories ssbcc

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

#

# Copyright 2013, Sinclair R.F., Inc.

#

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

import math

import re;

from ssbccPeripheral import SSBCCperipheral

from ssbccUtil import SSBCCException;

class AXI4_Lite_Slave_DualPortRAM(SSBCCperipheral):

  """

  AXI-Lite slave implemented as a dual-port RAM.  The dual-port RAM has at most

  256 bytes addressable by a single 8-bit value.  The data is stored in little

  endian format (i.e., the LSB of the 32-bit word is stored in the lowest

  numbered address).\n

  Usage:

    PERIPHERAL AXI4_Lite_Slave_DualPortRAM              \\

                                basePortName=<name>     \\

                                address=<O_address>     \\

                                read=<I_read>           \\

                                write=<O_write>         \\

                                [size=<N>]              \\

                                [ram8|ram32]\n

  Where:

    basePortName=<name>

      specifies the name used to construct the multiple AXI4-Lite signals

    address=<O_address>

      specifies the symbol used to set the address used for read and write

      operations from and to the dual-port memory

    read=<I_read>

      specifies the symbol used to read from the dual-port memory

    write=<O_write>

      specifies the symbol used to write to the dual-port memory

    size=<N>

      optionally specify the size of the dual-port memory.

      Note:  N must be either a power of 2 in the range from 16 to 256 inclusive

             or it must be a local param with the same restrictions on its

             value.

      Note:  N=256, i.e., the largest memory possible, is the default.

      Note:  Using a localparam for the memory size provides a convenient way

             to use the size of the dual port RAM in the micro controller code.\n

    ram8

      optionally specifies using an 8-bit RAM for the dual-port memory instantiation

      Note:  This is the default

    ram32

      optionally specifies using a 32-bit RAM for the dual-port memory instantiation

      Note:  This is required for Vivado 2013.3.\n

  Vivado Users:

    The peripheral creates a TCL script to facilitate turning the micro

    controller into an IP core.  Look for a file with the name

    "vivado_<basePortName>.tcl".\n

  Example:  The code fragments

              <addr> .outport(O_address) .inport(I_read)

            and

              <addr> .outport(O_address) <value> .outport(O_write)

            will read from and write to the dual-port RAM.\n

  Example:  Function to read the byte at the specified address:

              ; ( u_addr - u_value)

              .function als_read

                .outport(O_address) .inport(I_read) .return

            or

              ; ( u_addr - u_value)

              .function als_read

                .outport(O_address) I_read .return(inport)

            To invoke the function:

              <addr> .call(als_read)

            or

              .call(als_read,<addr>)\n

  Example:  Function to write the byte at the specified address:

              ; ( u_value u_addr - )

              .function als_write

                .outport(O_address) O_write outport .return(drop)

            To invoke the function:

              <value> <addr> .call(als_write)

            or

              <value> .call(als_write,<addr>)\n

  Example:  Spin on an address, waiting for the host processor to write to the

            address, do something when the address is written to, and then

            clear its contents.

              0x00 .outport(O_address)

              :loop .inport(I_read) 0= .jumpc(loop)

              ; Avoid race conditions between the processor writes and the micro

              ; controller read.

              .inport(I_read)

              ...

              ; clear the value and start waiting again

              0x00 O_address outport O_write outport .jump(loop,drop)\n

  LEGAL NOTICE:  ARM has restrictions on what kinds of applications can use

  interfaces based on their AXI protocol.  Ensure your application is in

  compliance with their restrictions before using this peripheral for an AXI

  interface.

  """

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

    # Use the externally provided file name for the peripheral

    self.peripheralFile = peripheralFile;

    # Get the parameters.

    def validateSize(x):

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

        if not config.IsParameter(x):

          raise SSBCCException('"size=%s" is not a parameter at %s' % (x,loc,));

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

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

        if not re.match(r'[1-9]\d*$', y):

          raise SSBCCException('localparam must be a numeric constant, not "%s", to be used in "size=%s" at %s' % (y,x,loc,));

        y = int(y);

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

        if not config.IsConstant(x):

          raise SSBCCException('"size=%s" is not a constant at %s' % (x,loc,));

        y = int(config.constants[x]);

      elif re.match(r'[1-9]\d*$',x):

        y = int(x);

      else:

        raise SSBCCException('Malformed entry for "size=%s" at %s' % (x,loc,));

      if math.modf(math.log(y,2))[0] != 0:

        raise SSBCCException('size=%d must be a power of 2 at %s' % (y,loc,));

      if not (16 <= y <= 256):

        raise SSBCCException('size=%d must be between 16 and 256 inclusive at %s' % (y,loc,));

      return y;

    allowables = (

      ('address',       r'O_\w+$',      None,           ),

      ('basePortName',  r'\w+$',        None,           ),

      ('ram8',          None,           None,           ),

      ('ram32',         None,           None,           ),

      ('read',          r'I_\w+$',      None,           ),

      ('size',          r'\S+$',        validateSize,   ),

      ('write',         r'O_\w+$',      None,           ),

    );

    names = [a[0] for a in allowables];

    for param_tuple in param_list:

      param = param_tuple[0];

      if param not in names:

        raise SSBCCException('Unrecognized parameter "%s" at %s' % (param,loc,));

      param_test = allowables[names.index(param)];

      self.AddAttr(config,param,param_tuple[1],param_test[1],loc,param_test[2]);

    # Ensure the required parameters are provided.

    for paramname in (

      'address',

      'basePortName',

      'read',

      'write',

    ):

      if not hasattr(self,paramname):

        raise SSBCCException('Required parameter "%s" is missing at %s' % (paramname,loc,));

    # Set optional parameters.

    for optionalpair in (

        ('size',        256,    ),

      ):

      if not hasattr(self,optionalpair[0]):

        setattr(self,optionalpair[0],optionalpair[1]);

    # Ensure exclusive pair configurations are set and consistent.

    for exclusivepair in (

        ('ram8','ram32','ram8',True,),

      ):

      if hasattr(self,exclusivepair[0]) and hasattr(self,exclusivepair[1]):

        raise SSBCCException('Only one of "%s" and "%s" can be specified at %s' % (exclusivepair[0],exclusivepair[1],loc,));

      if not hasattr(self,exclusivepair[0]) and not hasattr(self,exclusivepair[1]):

        setattr(self,exclusivepair[2],exclusivepair[3]);

    # Set the string used to identify signals associated with this peripheral.

    self.namestring = self.basePortName;

    # Add the I/O port, internal signals, and the INPORT and OUTPORT symbols for this peripheral.

    self.address_width = int(math.log(self.size,2));

    for signal in (

      ( 'i_%s_aresetn',         1,                      'input',        ),

      ( 'i_%s_aclk',            1,                      'input',        ),

      ( 'i_%s_awvalid',         1,                      'input',        ),

      ( 'o_%s_awready',         1,                      'output',       ),

      ( 'i_%s_awaddr',          self.address_width,     'input',        ),

      ( 'i_%s_wvalid',          1,                      'input',        ),

      ( 'o_%s_wready',          1,                      'output',       ),

      ( 'i_%s_wdata',           32,                     'input',        ),

      ( 'i_%s_wstrb',           4,                      'input',        ),

      ( 'o_%s_bresp',           2,                      'output',       ),

      ( 'o_%s_bvalid',          1,                      'output',       ),

      ( 'i_%s_bready',          1,                      'input',        ),

      ( 'i_%s_arvalid',         1,                      'input',        ),

      ( 'o_%s_arready',         1,                      'output',       ),

      ( 'i_%s_araddr',          self.address_width,     'input',        ),

      ( 'o_%s_rvalid',          1,                      'output',       ),

      ( 'i_%s_rready',          1,                      'input',        ),

      ( 'o_%s_rdata',           32,                     'output',       ),

      ( 'o_%s_rresp',           2,                      'output',       ),

    ):

      thisName = signal[0] % self.basePortName;

      config.AddIO(thisName,signal[1],signal[2],loc);

    config.AddSignal('s__%s__mc_addr'  % self.namestring, self.address_width, loc);

    config.AddSignal('s__%s__mc_rdata' % self.namestring, 8, loc);

    config.AddOutport((self.address,False,

                      ('s__%s__mc_addr' % self.namestring, self.address_width, 'data', ),

                      ),loc);

    config.AddInport((self.read,

                      ('s__%s__mc_rdata' % self.namestring, 8, 'data', ),

                      ),loc);

    self.ix_write = config.NOutports();

    config.AddOutport((self.write,False,

                      # empty list

                      ),loc);

    # Add the 'clog2' function to the processor (if required).

    config.functions['clog2'] = True;

  def GenVerilog(self,fp,config):

    body = self.LoadCore(self.peripheralFile,'.v');

    for subpair in (

      (r'\bL__',        'L__@NAME@__',                  ),

      (r'\bgen__',      'gen__@NAME@__',                        ),

      (r'\bi_a',        'i_@NAME@_a',                           ),

      (r'\bi_b',        'i_@NAME@_b',                           ),

      (r'\bi_r',        'i_@NAME@_r',                           ),

      (r'\bi_w',        'i_@NAME@_w',                           ),

      (r'\bix__',       'ix__@NAME@__',                         ),

      (r'\bo_',         'o_@NAME@_',                            ),

      (r'\bs__',        's__@NAME@__',                          ),

      (r'@IX_WRITE@',   "8'h%02x" % self.ix_write,              ),

      (r'@NAME@',       self.namestring,                        ),

      (r'@SIZE@',       str(self.size),                         ),

      (r'@MEM8@',       '1' if hasattr(self,'mem8') else '0',   ),

    ):

      body = re.sub(subpair[0],subpair[1],body);

    body = self.GenVerilogFinal(config,body);

    fp.write(body);

    # Write the TCL script to facilitate creating Vivado IP for the port.

    vivadoFile = os.path.join(os.path.dirname(self.peripheralFile),'vivado_AXI4_Lite_Bus.py');

    execfile(vivadoFile,globals());

    WriteTclScript('slave',self.basePortName,self.address_width);