soc_maker 0.1.1

data/lib/soc_maker/core_inst.rb

@@ -0,0 +1,305 @@
+###############################################################
+#   
+#  File:      core_inst.rb
+#
+#  Author:    Christian Hättich
+#
+#  Project:   System-On-Chip Maker
+#
+#  Target:    Linux / Windows / Mac
+#
+#  Language:  ruby
+#
+#
+###############################################################
+#
+#
+#   Copyright (C) 2014  Christian Hättich  - feddischson [ at ] opencores.org
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This 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 program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#
+###############################################################
+
+
+module SOCMaker
+
+######
+#
+# This class represents a core instantiation within
+# a SOC. It contains a parameter-hash #params,
+# which is used to define, which parameters are set to which values.
+# The type field is used to identify the SOCMaker::CoreDef
+# and the field @defn is initialized as reference to 
+# the corresponding CoreDef instance.
+class CoreInst
+  include ERR
+
+
+
+  # The core-definition of this instance
+  # Please note: this field is initialized by 
+  # the method consistence_check
+  attr_accessor :defn
+
+  # The type (core-def. id), as symbol
+  attr_accessor :type
+
+  # (HDL) instance parameters 
+  attr_accessor :params 
+
+
+
+  #
+  # Constructor:
+  # there is one mandatory attributes +type+ and an optional one +params+.
+  #
+  # +type+::    The id of the core-definition, which is instanciated
+  # +params+::  Instanciation parameters
+  #
+  def initialize(  type, params = {} )
+    init_with(  'type'   => type,
+                'params' => params  )
+
+  end
+
+  # 
+  # Encoder method (to yaml)
+  #
+  # +coder+:: An instance of the Psych::Coder to encode this class to a YAML file
+  #
+  def encode_with( coder )
+    init_error_if !coder.is_a?( Psych::Coder ), 
+                'coder is not given as Psych::Coder'
+    coder[ "params" ] = @params
+    coder[ "type"   ] = @type.to_s
+  end
+
+  #
+  # Initialization method (from yaml)
+  #
+  # +coder+:: An instance of the Psych::Coder to init this class from a YAML file
+  #
+  #
+  def init_with( coder )
+    init_error_if !( coder.is_a?( Hash ) || coder.is_a?( Psych::Coder ) ), 
+                'coder is not given as Hash neither as Psych::Coder'
+
+    init_error_if( !( coder[ 'type' ].is_a?( String ) || 
+                      coder[ 'type' ].is_a?( Symbol ) ),
+      "core-type error: must be defined as String or Symbol", 
+      field: type  )
+
+    @type = coder[ 'type' ].to_sym
+
+    @params = coder[ 'params' ] || {} 
+    init_error_if  !@params.is_a?( Hash ), 
+        'Parameters are not given as hash',
+        field: 'params'
+
+  end
+
+
+
+
+  #
+  # Runs a consistence check and creates an internal 
+  # hash, which contains all evaluated ports.
+  # Because the core-definition may contain variable port sizes, 
+  # which depend on the instance, these sizes need to be evaluated.
+  # This is also done here and the result is stored in @_ifcs_evaluated.
+  #
+  #
+  def consistence_check
+
+    begin
+      @defn = SOCMaker::lib.get_core( @type )
+    rescue ProcessingError => e
+      consistence_error e.message
+    end
+
+
+    # check, if the instance parameters are in the core definition
+    @params.each do |param_name, value|
+      consistence_error_if(  
+          @defn.inst_parameters[ param_name ] == nil, 
+          "Parameter not found: " + param_name.to_s, 
+          field: 'params',
+          core_type: @defn.name )
+    end
+
+    ## auto-complete parameters with default values
+    @defn.inst_parameters.each do |param_name, param|
+
+      # auto-complete to default values
+      @params[ param_name ] ||= param.default
+    end
+
+    @_ifcs_evaluated ||= {}
+    @defn.interfaces.keys.each do |ifc_name|
+      @_ifcs_evaluated[ ifc_name ] = {}
+      @defn.ports( ifc_name.to_s ) do |port_name, port_dir, port_len, default, spc_ref, is_last |
+        if port_len.is_a?( String )
+          param_match = SOCMaker::conf[ :length_regex ].match( port_len ) 
+          if param_match and @params[ port_len.to_sym ] != nil
+            tmp =@params[ port_len.to_sym ]
+            tmp = tmp.to_i if tmp.is_a?( String )
+            @_ifcs_evaluated[ ifc_name ][ port_name.to_sym ] = { len: tmp, dir: port_dir, default: default, ref: spc_ref }
+          else
+            SOCMaker::logger.error( "Failed to evaluate #{port_len} for port #{port_name}" )
+          end
+        else 
+          @_ifcs_evaluated[ ifc_name ][ port_name.to_sym ] = { len: port_len, dir: port_dir, default: default, ref: spc_ref }
+        end 
+      end
+    end
+
+    @defn.consistence_check
+
+  end    
+
+
+
+
+
+
+
+  #
+  # Iterate over all ports and call the block with
+  # - port-name 
+  # - port length
+  # - default value
+  # - is-last value
+  #
+  # If no argument is given, all ports of this instance are processed.
+  # If arguments are given, each argument is supposed to the name of
+  # a interface. All specified interfaces with all ports are processed.
+  #
+  # +args+::  Optional list of interface names
+  #   
+  #
+  def ports( *args )
+
+    if args.size == 0
+      ifc_sel = @_ifcs_evaluated
+    else
+      ifc_sel = @_ifcs_evaluated.select{ |k,v| args.include?( k ) }
+    end
+
+    ifc_sel.values.each_with_index do |ifc, i_ifc|
+      ifc.each_with_index do |(port_name, port_def), i_port|
+        yield(  port_name.to_s, 
+                port_def[ :dir ], 
+                port_def[ :len ], 
+                port_def[ :default ], 
+                port_def[ :ref ],
+                i_port==ifc.size-1 && i_ifc == ifc_sel.size-1 )
+      end
+    end
+  end
+
+  #
+  # Iterate over all generics and call the block with
+  # - generic-name
+  # - generic-type
+  # - the value
+  # - is-last information
+  #
+  def generics
+    @defn.generics do |name, type, default_value, is_last|
+      value = @params[ name.to_sym ];
+      value = default_value if value == nil
+      yield( name.to_s, type, value, is_last )
+    end
+  end
+
+
+
+
+
+
+
+  #
+  # Returns a port, identified by the interface and port name
+  # 
+  # +ifc_name+::       name of the interface
+  # +port_ref+:: name of the port
+  # 
+  def port( ifc_name, port_ref )
+    tmp = @defn.interfaces[ ifc_name ].
+        ports.select{ |key,hash| hash.spc_ref == port_ref.to_s }.
+        keys.first
+    return [ tmp.to_s, @_ifcs_evaluated[ ifc_name ][ tmp ] ]
+  end
+
+  #
+  # Returns the length of a port within an interface.
+  # If no instance is given, we know that it is 
+  # a toplevel interface. 
+  # Otherwise we check for this and we do a recursive call.
+  # If this port is within a interface of a core, we 
+  # pass the call to the core-definition of this instance, which
+  # knows all cores.
+  #
+  # +ifc_name+::    name of the interface
+  # +port_ref+::    name of the port
+  # +inst+::        name of the instance (optional), default is nil
+  #
+  def port_length( ifc_name, port_ref, inst = nil )
+    if inst == nil
+      tmp = @defn.interfaces[ ifc_name ].
+          ports.select{ |key,hash| hash.spc_ref == port_ref.to_s }.
+          keys
+      return 0                                                 if tmp.size == 0 
+      return @_ifcs_evaluated[ ifc_name ][ tmp.first ][ :len ] if tmp.size == 1
+      # we ensure in SOCMaker::IfcDef that there is only one reference
+    else
+      if inst == @defn.toplevel.to_sym
+        return port_length( ifc_name, port_ref )
+      else
+        return @defn.port_length( ifc_name, port_ref, inst )
+      end
+    end
+  end
+
+
+  #
+  # Returns a string describing this instance
+  #
+  def to_s
+    "type:     #{type}\n"   +
+    "params:   #{params}\n" 
+  end
+
+  #
+  # Equality operator
+  #
+  def ==(o)
+    o.class     == self.class   && 
+    o.type      == self.type    &&
+    o.params    == self.params
+  end
+
+
+
+#  private :core_definition
+
+
+
+end # CoreInst
+end # SOCMaker
+
+
+
+# vim: noai:ts=2:sw=2

data/lib/soc_maker/err.rb

@@ -0,0 +1,211 @@
+###############################################################
+#   
+#  File:      err.rb
+#
+#  Author:    Christian Hättich
+#
+#  Project:   System-On-Chip Maker
+#
+#  Target:    Linux / Windows / Mac
+#
+#  Language:  ruby
+#
+#
+###############################################################
+#
+#
+#   Copyright (C) 2014  Christian Hättich  - feddischson [ at ] opencores.org
+#
+#   This program is free software: you can redistribute it and/or modify
+#   it under the terms of the GNU General Public License as published by
+#   the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   This 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 program.  If not, see <http://www.gnu.org/licenses/>.
+#
+#
+###############################################################
+module SOCMaker
+
+  #
+  # This sub-module contains some error-functionallity,
+  # which is used in different classes via mixins.
+  #
+  module ERR
+
+    #
+    # An error, which is thrown if YAML parsing fails
+    #
+    class YAMLParseError < RuntimeError
+    end
+
+
+
+    #
+    # Processing errors: occur during the the processing
+    # of SoCs.
+    # 
+    class ProcessingError < RuntimeError
+      #
+      # Optional error information
+      #
+      attr :optinal
+      #
+      # This constructor saves the message and optional infos and 
+      # adds a log entry via SOCMaker::logger.error
+      # +message+:: the error message
+      # +o+:: optional error information
+      #
+      def initialize( message, o={} )
+        super message
+        @optional = o
+        SOCMaker::logger.error( "Processing Error Raised: #{message}  #{ "\n\t\t" + o.inspect if o.size > 0}" )
+      end
+      #
+      # Returns a string describing this error
+      #
+      def to_s
+        "#{super} #{ "\n\t\t" + @optional.inspect if @optional.size > 0}"
+      end
+    end
+
+    #
+    # Method to raise a processing error
+    # +msg+:: error message
+    # +o+:: optional info
+    #
+    def processing_error( msg, o={} )
+      raise ProcessingError.new( msg, o )
+    end
+
+    # Method to raise a processing error
+    # if the condition is true
+    # +con+:: condition
+    # +msg+:: error message
+    # +o+:: optional info
+    def processing_error_if( res, msg, o={} )
+      if !!(res)
+        processing_error( msg, o )
+      end
+    end
+
+
+
+
+
+
+    #
+    # Consistence errors: occur during the consistence check
+    # of the classes or in a few methods, where a inconsistence
+    # can be caused by external call.
+    # A cause for this error could be, that a core or interface
+    # doesn't exist in the library. Or a port in of a IfcDef is
+    # not defined in the IfcSpc.
+    #
+    class ConsistenceError < RuntimeError
+      #
+      # Optional error information
+      #
+      attr :optinal
+      #
+      # This constructor saves the message and optional infos and 
+      # adds a log entry via SOCMaker::logger.error
+      # +message+:: the error message
+      # +o+:: optional error information
+      #
+      def initialize( message, o={} )
+        super message
+        @optional = o
+        SOCMaker::logger.error( "Consistence Error Raised: #{message}  #{ "\n\t\t" + o.inspect if o.size > 0}" )
+      end
+      #
+      # Returns a string describing this error
+      #
+      def to_s
+        "#{super} #{ "\n\t\t" + @optional.inspect if @optional.size > 0}"
+      end
+    end
+
+    #
+    # Method to raise a consistence error
+    # +msg+:: error message
+    # +o+:: optional info
+    #
+    def consistence_error( msg, o={} )
+      raise ConsistenceError.new( msg, o )
+    end
+
+    # Method to raise a consistence error
+    # if the condition is true
+    # +con+:: condition
+    # +msg+:: error message
+    # +o+:: optional info
+    def consistence_error_if( con, msg, o={} )
+      if !!(con)
+        consistence_error( msg, o )
+      end
+    end
+
+
+
+    #
+    # Initialization errors: occur during the initialization
+    # of the classes. A cause for this error could be a wrong structure 
+    # of the YAML file, for example wrong data types.
+    #
+    class InitError < RuntimeError
+      #
+      # Optional error information
+      #
+      attr :optinal
+      #
+      # This constructor saves the message and optional infos and 
+      # adds a log entry via SOCMaker::logger.error
+      # +message+:: the error message
+      # +o+:: optional error information
+      #
+      def initialize( message, o={} )
+        super message
+        @optional = o
+        if SOCMaker::logger
+          SOCMaker::logger.error( "Initialization Error Raised: #{message}  #{ "\n\t\t" + o.inspect if o.size > 0}" )
+        end
+      end
+      #
+      # Returns a string describing this error
+      #
+      def to_s
+        "#{super} #{ "\n\t\t" + @optional.inspect if @optional.size > 0}"
+      end
+    end
+
+    #
+    # Method to raise an initialization error
+    # +msg+:: error message
+    # +o+:: optional info
+    #
+    def init_error( msg, o={} )
+      raise InitError.new( msg, o )
+    end
+
+    # Method to raise an initialization error
+    # if the condition is true
+    # +con+:: condition
+    # +msg+:: error message
+    # +o+:: optional info
+    def init_error_if( con, msg, o={} )
+      if !!(con)
+        init_error( msg, o )
+      end
+    end
+
+
+  end # module ERR
+
+end # module SOCMaker