Subversion Repositories nocmodel

#!/usr/bin/env python
# -*- coding: utf-8 -*-
 
#
# NoC Code generator
#   This module defines the basic structure for code generation
#
# Author:  Oscar Diaz
# Version: 0.2
# Date:    11-11-2011
 
#
# This code is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This code 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
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the
# Free Software  Foundation, Inc., 59 Temple Place, Suite 330,
# Boston, MA  02111-1307  USA
#
 
#
# Changelog:
#
# 11-11-2011 : (OD) initial release
#
 
"""
Base for code generation support
 
This module defines:
* Class 'noc_codegen_base'
* Class 'noc_codegen_ext'
"""
 
from myhdl import intbv, SignalType
from nocmodel import *
 
#import scipy
#import networkx as nx
from copy import deepcopy
from sys import exc_info
import warnings
 
class noc_codegen_base():
    """
    Base class for code generator
 
    This class holds a basic model of a hardware description. Although inspired 
    in VHDL, it also holds for Verilog.
 
    Note that its necessary a defined noc model to generate this code model.
 
    Note that this class is meant to be extended by a particular code generator:
    VHDL generator, Verilog generator, etc.
 
    This object will assume a module has the following sections:
    --------------------
    <docheader>  : File header and documentation about the module
    <libraries>  : Declarations at the beginning (VHDL: libraries declarations)
    <modulename> : Module name (VHDL: entity name)
    <generics>   : Parameters for the module (VHDL: generics inside an entity)
    <ports>      : Declaration of inputs and outputs (VHDL: ports inside an entity)
    <implementation> : Code implementation (pure VHDL or Verilog code)
    --------------------
 
    Objects type:
    * docheader, libraries, modulename and implementation are simple strings.
    * generics are list of dictionaries with this required keys:
        * "class" : always "generic"
        * "name"
        * "type" : string formatted data type 
        * "type_array" : 2-element list of strings that declares array boundaries 
            either using numbers or generics names. None for simple data types
        * "default_value"
        * "current_value" 
        * "description"
    * ports are list of dictionaries with this required keys:
        * "class" : always "port"
        * "name"
        * "type" : port type, if applicable
        * "nocport" : index to related port in the nocobject' ports dictionary or
            others signal containers in the nocobject.
        * "signal_list" : list of signals that compose the port
        * "description"
    * external_signals are list of signals that aren't related to any port.
    * signals are dictionaries with this required keys:
        * "class" : always "signal"
        * "name"
        * "type" : string formatted data type 
        * "type_array" : 2-element list of strings that declares array boundaries 
            either using numbers or generics names. None for simple data types
        * "direction"
        * "default_value"
        * "related_generics" : when the data type is an array, this list has 
            references to generics to be used to build array declaration.
        * "description"
 
    Attributes:
    * modulename
    * nocobject_ref
    * docheader
    * libraries
    * generics
    * ports
    * external_signals
    * implementation
    * interface_hash
 
    Notes:
    * Code generation methods are meant to return strings. The user is 
      responsible to write it in files.
    * This object maintains the code model and use it to generate code. Any
      particular changes or adjustments to the model should be done by a 
      'noc_codegen_ext' object. 
    * This code generation model are restricted to noc models, because 
      routers and ipcores are generated by MyHDL code converter (this 
      could change if the noc objects needs to keep hierarchy in its 
      internal implementation). 
      This converter keeps routers and ipcores hierarchy.
    """
 
    def __init__(self, nocobject_ref, **kwargs):
        # nocobject reference
        if not isinstance(nocobject_ref, (nocobject, noc)):
            raise TypeError("Argument must be an instance of nocobject or noc class")
        self.nocobject_ref = nocobject_ref
 
        # External conversion flag
        self.external_conversion = False
 
        # string type objects
        self.docheader = ""
        self.libraries = ""
        self.modulename = ""
 
        # list of dictionaries (generic and port)
        self.generics = []
        self.ports = []
        self.external_signals = []
 
        # implementation 
        self.implementation = ""
 
        # module hash
        self.interface_hash = ""
 
        # optional arguments
        for key in kwargs.keys():
            setattr(self, key, kwargs[key])
 
    # main methods
    def generate_file(self):
        """
        Generate the entire file that implements this object.
        """
        raise NotImplementedError("What language for code generation?")
 
    def generate_component(self):
        """
        Generate a component definition for this object.
        """
        raise NotImplementedError("What language for code generation?")
 
    def generate_generic_declaration(self, generic=None, with_default=False):
        """
        Generate a generic declaration for this object.
 
        Arguments:
        * generic : either a name or a list index for a particular generic
        * with_default : True to add the default value
 
        Returns:
        * A string when generic argument is used
        * A list of strings with all generics 
        """
        raise NotImplementedError("What language for code generation?")
 
    def generate_port_declaration(self, port=None, with_default=False):
        """
        Generate a port declaration for this object.
 
        Arguments:
        * port : either a name or a list index for a particular port
        * with_default : True to add the default value
 
        Returns:
        * A list of strings with all signals in port when port argument is used
        * A list of strings with all signals in all ports
        """
        raise NotImplementedError("What language for code generation?")
 
    def generate_signal_declaration(self, inport=None, signal=None, with_default=False):
        """
        Generate a signal declaration for this object.
 
        Arguments:
        * inport : either a name or a list index for a particular port. None 
            means use the external_signals list
        * signal : either a name or a list index for a particular signal
        * with_default : True to add the default value
 
        Returns:
        * A string when signal argument is used
        * A list of strings with all signals
        """
        raise NotImplementedError("What language for code generation?")
 
    def make_comment(self, data):
        """
        Convert string data to language comment
 
        Argument:
        * data: string or list of strings to convert
 
        Returns: string or list of strings with comments added.
        """
        raise NotImplementedError("What language for code generation?")
 
    def add_tab(self, data, level=1):
        """
        Add an indentation level to the string
 
        Argument:
        * data: string or list of strings
        * level: how many indentation levels to add. Default 1
 
        Returns: string or list of strings with <level> indentation levels.
        """
        raise NotImplementedError("What language for code generation?")
 
    def to_valid_str(self, str_in):
        """
        Convert an input string, changing special characters used on
        the HDL language. Useful for set names .
 
        Argument:
        * str_in: string to convert
 
        Returns: the converted string.
        """
        raise NotImplementedError("What language for code generation?")
 
    # codegen model management
    def add_generic(self, name, value, description="", **kwargs):
        """
        Add a generic to the model. 
 
        Arguments:
        * name : must be a string
        * value : default value for this generic
        * description : 
        * Optional arguments (just for method call format)
 
        Returns:
        * Reference to added generic dictionary.
 
        Note:
        * This method can override an existing generic entry.
        * This basic method just add name, default value and description. 
          Extended class methods must fill correct type arguments.
        """
        if not isinstance(name, str):
            raise TypeError("Name must be string, not '%s'." % repr(name))
 
        # supported types:
        if not isinstance(value, (bool, int, intbv, str)):
            raise TypeError("Unsupported type '%s'." % repr(type(value)))
 
        # check if new entry
        g = filter(lambda x: x["name"] == name, self.generics)
        if len(g) == 0:
            g = get_new_generic(name = name)
            self.generics.append(g)
        else:
            g = g[0]
        g.update(default_value = value, description = description)
        # optional kwargs
        g.update(kwargs)
        # return reference to added generic dict
        return g
 
    def add_port(self, name, signal_desc=None, description="", **kwargs):
        """
        Add a port to the model. 
 
        Arguments:
        * name : must be a string
        * signal_desc : optional dictionary with signal information included. 
          None to just add/update port without changing its signals.
        * description : 
        * Optional arguments (just for method call format)
 
        Returns:
        * Reference to added port dictionary.
 
        Note:
        * This method can add a new port or update an existing port with new 
          signals.
        * This basic method just add name and description, and update a signal 
          using signal_desc information. Extended class methods must fill 
          correct type arguments in the updated signal.
        """
        if not isinstance(name, str):
            raise TypeError("Name must be string, not '%s'." % repr(name))
 
        # check signal dict keys: must have at least class and name
        if signal_desc is not None:
            if not all([x in signal_desc for x in ("class", "name")]):
                raise TypeError("Argument signal_desc must be a signal dict ('%s')." % repr(signal_desc))
            if signal_desc["class"] != "signal":
                raise TypeError("Argument signal_desc must be a signal dict ('%s')." % repr(signal_desc))
 
        # check if new entry
        p = filter(lambda x: x["name"] == name, self.ports)
        if len(p) == 0:
            p = get_new_port(name = name)
            self.ports.append(p)
        else:
            p = p[0]
 
        # only update description when string is non-empty
        if description != "":
            p.update(description = description)
 
        # check existing signal
        if signal_desc is not None:
            sig = filter(lambda x: x["name"] == signal_desc["name"], p["signal_list"])
            if len(sig) == 0:
                p["signal_list"].append(signal_desc)
            else:
                sig[0].update(signal_desc)
 
        # optional kwargs
        p.update(kwargs)
        # return reference to added/updated port dict
        return p
 
    def add_external_signal(self, name, direction, value, description="", **kwargs):
        """
        Add a external signal to the model. 
 
        Arguments:
        * name : must be a string
        * direction : "in" or "out"
        * value : initial value for this port
        * description
        * Optional arguments (just for method call format)
 
        Returns:
        * Reference to added external_signals dictionary.
 
        Note:
        * This method can override an existing signal entry.
        * This basic method just add name, direction, intial value and 
          description. Extended class methods must fill correct type arguments.
        """
        if not isinstance(name, str):
            raise TypeError("Name must be string, not '%s'." % repr(name))
 
        # supported types:
        if isinstance(value, SignalType):
            value = value._init
        if not isinstance(value, (bool, int, intbv)):
            raise TypeError("Unsupported type '%s'." % repr(type(value)))
        if direction not in ["in", "out"]:
            raise ValueError("Direction must be 'in' or 'out', not '%s'." % repr(direction))
        # check if new entry
        sig = filter(lambda x: x["name"] == name, self.external_signals)
        if len(sig) == 0:
            sig = get_new_signal(name = name)
            self.external_signals.append(sig)
        else:
            sig = sig[0]
        sig.update(direction = direction, default_value = value, description = description)
        # optional kwargs
        sig.update(kwargs)
        # return reference to added generic dict
        return sig
 
    def build_implementation(self):
        """
        Try to generate the implementation section. Check if a "codemodel" 
        object exists and try to call "generate_implementation" method.
 
        If the call is successful, self.implementation will store its return
        string. Do nothing on failure (report a warning).
        """
        if hasattr(self.nocobject_ref, "codemodel"):
            implementation = ""
            if not hasattr(self.nocobject_ref.codemodel, "generate_implementation"):
                warnings.warn("Method 'generate_implementation()' not found.")
            elif not callable(self.nocobject_ref.codemodel.generate_implementation):
                warnings.warn("Attribute 'generate_implementation()' not callable")
            else:
                implementation = self.nocobject_ref.codemodel.generate_implementation()
            ##except:
                ### Report a warning instead of the exception
                ##exctype, value = exc_info()[:2]
                ##warnings.warn("%s: %s" % (exctype, value))
            if isinstance(implementation, str):
                self.implementation = implementation
 
    def model_hash(self):
        """
        Calculate a hash string based on the nocobject interface: Generics, 
        ports and external signals. 
 
        Two nocobject with the same model hash can be instantiated by the same
        module code (with different generics' values).
 
        Returns: a string with a predefined format.
        """
        hash_str = ""
 
        # 1. Generics information
        hash_gen = []
        for g in self.generics:
            hash_gen.append([g["name"], g["type"]])
        # sort generics by name
        hash_gen.sort(key = lambda x: x[0])
        # add a stream of "<name><type>"
        for g in hash_gen:
            hash_str += "%s%s" % (g[0], g[1])
 
        # 2. Ports information
        hash_port = []
        for g in self.ports:
            hash_port.append([g["name"], g["type"], len(g["signal_list"])])
        # sort ports by name
        hash_port.sort(key = lambda x: x[0])
        # add a stream of "<name><type><num-of-signals>"
        for g in hash_port:
            hash_str += "%s%s" % (g[0], g[1])
 
        # 3. External ports information
        hash_ext = []
        for g in self.external_signals:
            hash_ext.append([g["name"], g["type"], g["direction"]])
        # sort external_signals by name
        hash_ext.sort(key = lambda x: x[0])
        # add a stream of "<name><type><direction>"
        for g in hash_ext:
            hash_str += "%s%s" % (g[0], g[1])
 
        self.interface_hash = hash_str
        return hash_str
 
class noc_codegen_ext():
    """
    Extension class for code generator
 
    This class supports an access point to do transformations on a 
    'noc_codegen_base' code model.
 
    This transformation methods should be declared on extended classes of this 
    class, and are close related to the particular noc object.
 
    Notes:
    * This object maintains the code model and use it to generate code. Any
      particular changes or adjustments to the model should be done by a 
      'noc_codegen_ext' object. Usually this object is related to a particular 
      nocobject (router, ipcore or channel).
    """
 
    def __init__(self, codegen_ref):
        # must be related to a noc_codegen_base object
        if not isinstance(codegen_ref, noc_codegen_base):
            raise TypeError("Argument must be an instance of 'noc_codegen_base' class")
 
        self.codegen_ref = codegen_ref
        self.nocobject_ref = codegen_ref.nocobject_ref
 
# helper structures:
# base objects for generics, ports and signals
_empty_generic = {
    "class": "generic", 
    "name": "", 
    "type": "", 
    "type_array": [None, None],
    "default_value": "",  
    "current_value": "", 
    "description": ""}
_empty_port = {
    "class": "port", 
    "name": "",  
    "type": "",
    "nocport": None,
    "signal_list": [],
    "description": ""}
_empty_signal = {
    "class": "signal", 
    "name": "",  
    "type": "",  
    "type_array": [None, None],
    "direction": "",
    "default_value": "",  
    "related_generics": [], 
    "description": ""}
 
# new structures generation
def get_new_generic(**kwargs):
    s = deepcopy(_empty_generic)
    s.update(kwargs)
    return s
def get_new_port(**kwargs):
    s = deepcopy(_empty_port)
    s.update(kwargs)
    return s
def get_new_signal(**kwargs):
    s = deepcopy(_empty_signal)
    s.update(kwargs)
    return s