cross_origen 0.5.0

data/lib/cross_origen/xml_doc.rb

@@ -0,0 +1,252 @@
+require 'kramdown'
+require 'sanitize'
+
+module CrossOrigen
+  # This is the base class of all doc formats that are
+  # XML based
+  class XMLDoc
+    CreationInfo = Struct.new(:author, :date, :revision, :source)
+
+    ImportInfo = Struct.new(:name, :date)
+
+    attr_accessor :creation_info, :import_info
+
+    # These (in many cases illegal) tags will be forced to their valid equivalents
+    # These will be executed in the defined order, so for later xfrms you can for example
+    # assume that all 'rows' have already been converted to 'tr'
+    # valid equivalents
+    HTML_TRANSFORMS = {
+      'table/title'  => 'caption',
+      'table//row'   => 'tr',
+      'thead//entry' => 'th',
+      'table//entry' => 'td',
+      'td/p'         => 'span',
+      'th/p'         => 'span'
+    }
+
+    # This can be used to perform additional by-node transformation if required, normally
+    # this should be used if transform of a node attribute is required
+    HTML_TRANSFORMER = lambda do |env|
+      if env[:node_name] == 'td' || env[:node_name] == 'th'
+        if env[:node].attr('nameend')
+          first = env[:node].attr('namest').sub('col', '').to_i
+          last = env[:node].attr('nameend').sub('col', '').to_i
+          env[:node].set_attribute('colspan', (last - first + 1).to_s)
+        end
+      end
+    end
+
+    # Defines the rules for sanitization of any HTML strings that will be converted
+    # to markdown for representation within Origen
+    HTML_SANITIZATION_CONFIG = {
+      # Only these tags will be allowed through, everything else will be stripped
+      # Note that this is applied after the transforms listed above
+      elements:     %w(b em i strong u p ul ol li table tr td th tbody thead),
+      attributes:   {
+        'td' => ['colspan'],
+        'th' => ['colspan']
+      },
+      # Not planning to allow any of these right now, but keeping around
+      # as an example of how to do so
+      #:protocols => {
+      #  'a' => {'href' => ['http', 'https', 'mailto']}
+      # }
+      transformers: HTML_TRANSFORMER
+    }
+
+    # Returns the object that included the CrossOrigen module
+    attr_reader :owner
+
+    def initialize(owner)
+      @owner = owner
+      @creation_info = CreationInfo.new
+      @import_info = ImportInfo.new
+    end
+
+    # Tries the given methods on the owner and returns the first one to return a value,
+    # ultimately returns nil if no value is found.
+    #
+    # To test an object other than the owner pass it as the first argument.
+    def try(*methods)
+      if methods.first.is_a?(Symbol)
+        obj = owner
+      else
+        obj = methods.shift
+      end
+      methods.each do |method|
+        if obj.respond_to?(method)
+          val = obj.send(method)
+          return val if val
+        end
+      end
+      nil
+    end
+
+    # This returns the doc wrapped by a Nokogiri doc
+    def doc(path, _options = {})
+      require 'nokogiri'
+
+      File.open(path) do |f|
+        yield Nokogiri::XML(f)
+      end
+    end
+
+    def extract(element, path, options = {})
+      options = {
+        format:   :string,
+        hex:      false,
+        default:  nil,
+        downcase: false,
+        return:   :text,
+        # A value or array or values which are considered to be nil, if this is the value
+        # to be returned then nil will be returned instead
+        nil_on:   false
+      }.merge(options)
+      node = element.at_xpath(path)
+      if node
+        if options[:format] == :string
+          str = node.send(options[:return]).strip
+          str = str.downcase if options[:downcase]
+          if options[:nil_on] && [options[:nil_on]].flatten.include?(str)
+            nil
+          else
+            str
+          end
+        elsif options[:format] == :integer
+          val = node.send(options[:return])
+          if val =~ /^0x(.*)/
+            Regexp.last_match[1].to_i(16)
+          elsif options[:hex]
+            val.to_i(16)
+          else
+            val.to_i(10)
+          end
+        else
+          fail "Unknown format: #{options[:format]}"
+        end
+      else
+        options[:default]
+      end
+    end
+
+    # Freescale register descriptions are like the wild west, need to do some pre-screening
+    # to approach valid HTML before handing off to other off the shelf sanitizers
+    def pre_sanitize(html)
+      html = Nokogiri::HTML.fragment(html)
+      HTML_TRANSFORMS.each do |orig, new|
+        html.xpath(".//#{orig}").each { |node| node.name = new }
+      end
+      html.to_html
+    end
+
+    # Does its best to convert the given html fragment to markdown
+    #
+    # The final markdown may still contain some HTML tags, but any weird
+    # markup which may break a future markdown -> html conversion will
+    # be removed
+    def to_markdown(html, _options = {})
+      cleaned = html.scrub
+      cleaned = pre_sanitize(cleaned)
+      cleaned = Sanitize.fragment(cleaned, HTML_SANITIZATION_CONFIG)
+      Kramdown::Document.new(cleaned, input: :html).to_kramdown.strip
+    rescue
+      'The description could not be imported, the most likely cause of this is that it contained illegal HTML markup'
+    end
+
+    # Convert the given markdown string to HTML
+    def to_html(string, _options = {})
+      # Escape any " that are not already escaped
+      string.gsub!(/([^\\])"/, '\1\"')
+      # Escape any ' that are not already escaped
+      string.gsub!(/([^\\])'/, %q(\1\\\'))
+      html = Kramdown::Document.new(string, input: :kramdown).to_html
+    end
+
+    # fetch an XML snippet passed and extract and format the data
+    def fetch(xml, options = {})
+      options = {
+        type:          String,
+        downcase:      false,
+        symbolize:     false,
+        strip:         false,
+        squeeze:       false,
+        squeeze_lines: false,
+        rm_specials:   false,
+        whitespace:    false,
+        get_text:      false,
+        to_i:          false,
+        to_html:       false,
+        to_bool:       false,
+        children:      false,
+        to_dec:        false,
+        to_f:          false,
+        underscore:    false
+      }.update(options)
+      options[:symbolize] = options[:to_sym] if options[:to_sym]
+      # Check for incompatible options
+      xml_orig = xml
+      numeric_methods = [:to_i, :to_f, :to_dec]
+      if options[:get_text] == true && options[:to_html] == true
+        fail 'Cannot use :get_text and :to_html options at the same time, exiting...'
+      end
+      if options[:symbolize] == true
+        fail 'Cannot convert to a number of any type and symbolize at the same time' if numeric_methods.reject { |arg| options[arg] == true }.size < 3
+      end
+      fail 'Cannot select multiple numeric conversion args at the same time' if numeric_methods.reject { |arg| options[arg] == true }.size < 2
+      if xml.nil?
+        Origen.log.debug 'XML data is nil!'
+        return nil
+      end
+      xml = xml.text if options[:get_text] == true
+      # Sometimes XML snippets get sent as nodes or as Strings
+      # Must skip this code if a String as it is designed to change
+      # the XML node into a string
+      unless xml.is_a? String
+        if options[:to_html] == true
+          if xml.children
+            # If there are children to this XMl node then grab the content there
+            if xml.children.empty? || options[:children] == false
+              xml = xml.to_html
+            else
+              xml = xml.children.to_html
+            end
+          end
+        end
+      end
+      unless xml.is_a? options[:type]
+        Origen.log.debug "XML data is not of correct type '#{options[:type]}'"
+        Origen.log.debug "xml is \n#{xml}"
+        return nil
+      end
+      if options[:type] == String
+        if xml.match(/\s+/) && options[:whitespace] == false
+          Origen.log.debug "XML data '#{xml}' cannot have white space"
+          return nil
+        end
+        xml.downcase! if options[:downcase] == true
+        xml = xml.underscore if options[:underscore] == true
+        xml.strip! if options[:strip] == true
+        xml.squeeze!(' ') if options[:squeeze] == true
+        xml = xml.squeeze_lines if options[:squeeze_lines] == true
+        xml.gsub!(/[^0-9A-Za-z]/, '_') if options[:rm_specials] == true
+        if options[:symbolize] == true
+          return xml.to_sym
+        elsif options[:to_i] == true
+          return xml.to_i
+        elsif options[:to_dec] == true
+          return xml.to_dec
+        elsif options[:to_f] == true
+          return xml.to_f
+        elsif [true, false].include?(xml.to_bool) && options[:to_bool] == true
+          # If the string can convert to Boolean then return TrueClass or FalseClass
+          return xml.to_bool
+        else
+          return xml
+        end
+      else
+        # No real examples yet of non-string content
+        return xml
+      end
+    end
+  end
+end

data/lib/cross_origen.rb

@@ -0,0 +1,108 @@
+require 'origen'
+require_relative '../config/application.rb'
+require_relative '../config/environment.rb'
+
+module CrossOrigen
+  if RUBY_VERSION < '2.0.0'
+    require 'scrub_rb'
+  end
+  extend ActiveSupport::Concern
+
+  included do
+    include Origen::Model
+  end
+
+  def instance_respond_to?(method_name)
+    public_methods.include?(method_name)
+  end
+
+  def cr_import(options = {})
+    file = cr_file(options)
+    cr_translator(file, options).import(file, options)
+  end
+
+  def to_ralf(options = {})
+    cr_ralf.owner_to_ralf(options)
+  end
+
+  def to_ip_xact(options = {})
+    cr_ip_xact.owner_to_xml(options)
+  end
+  alias_method :to_ipxact, :to_ip_xact
+
+  def to_origen(options = {})
+    options[:obj] = self
+    cr_to_origen(options)
+  end
+
+  def to_header(options = {})
+    cr_headers.owner_to_header(options)
+  end
+
+  # Tries the given methods and returns the first one to return a value,
+  # ultimately returns nil if no value is found.
+  def cr_try(*methods)
+    methods.each do |method|
+      if self.respond_to?(method)
+        val = send(method)
+        return val if val
+      end
+    end
+    nil
+  end
+
+  # Returns an instance of the DesignSync interface
+  def cr_design_sync
+    @cr_design_sync ||= DesignSync.new(self)
+  end
+
+  def cr_headers
+    @cr_headers ||= Headers.new(self)
+  end
+
+  # Creates Ruby files necessary to model all sub_blocks and registers found (recursively) owned by options[:obj]
+  # The Ruby files are created at options[:path] (app output directory by default)
+  def cr_to_origen(options = {})
+    options = {
+      obj:  $dut,
+      path: Origen.app.config.output_directory
+    }.update(options)
+    # This method assumes and checks for $self to contain Origen::Model
+    error "ERROR: #{options[:obj].class} does not contain Origen::Model as required" unless options[:obj].class < Origen::Model
+    # Check to make sure there are sub_blocks or regs directly under $dut
+    error "ERROR: options[:obj]ect #{options[:obj].object_id} of class #{options[:obj].class} does not contain registers or sub_blocks" unless options[:obj].owns_registers? || options[:obj].instance_respond_to?(:sub_blocks)
+    OrigenFormat.new(options).export
+  end
+
+  def cr_ralf
+    @cr_ralf ||= Ralf.new(self)
+  end
+
+  def cr_ip_xact
+    @cr_ip_xact ||= IpXact.new(self)
+  end
+
+  private
+
+  # Returns an instance of the translator for the format of the given file
+  def cr_translator(file, _options = {})
+    snippet = IO.read(file, 2000)  # Read first 2000 characters
+    case snippet
+    when /spiritconsortium/
+      cr_ip_xact
+    else
+      fail "Unknown file format for file: #{file}"
+    end
+  end
+
+  # Returns a local path to the given file defined by the options.
+  def cr_file(options = {})
+    if options[:path]
+      options[:path]
+    elsif options[:vault]
+      cr_design_sync.fetch(options)
+    else
+      fail 'You must supply a :path or :vault option pointing to the import file!'
+    end
+  end
+end

data/templates/headers/default.h.erb

@@ -0,0 +1,18 @@
+% full_name = cr_try(:full_name, :ip_name, :name, :pdm_part_name) || self.class.to_s
+//---------------------------------------------------------------------------------------------
+// <%= full_name %> Registers Memory Map
+//---------------------------------------------------------------------------------------------
+% regs.each do |name, reg|
+#define <%= name.to_s.upcase.ljust(30) %>                     (REG<%= reg.size %>(0x<%= reg.address.to_s(16).upcase %>))
+% end
+
+//---------------------------------------------------------------------------------------------
+// <%= full_name %> Registers Bit Definition
+//---------------------------------------------------------------------------------------------
+% regs.each do |reg_name, reg|
+// <%= reg_name.to_s.upcase %>
+%   reg.named_bits do |name, bits|
+#define <%= "#{reg_name}_#{name}".upcase.ljust(30) %>         (<%= bits.sort_by{ |bit| bit.position }.reverse.map{ |bit| "BIT#{bit.position}"}.join(" + ") %>)
+%   end
+
+% end

data/templates/ralf/_register.ralf.erb

@@ -0,0 +1,21 @@
+% reg = options[:reg]
+register <%= options[:name].to_s.downcase %> (<%= reg.path(:relative_to => options[:parent]) + options[:reg_path_postfix] %>) @'h<%= reg.offset.to_s(16).upcase %> {
+    bytes <%= reg.size / 8 %>;
+%   reg.named_bits do |name, bits|
+%   if bits.size == 1
+    field <%= name %> ([<%= bits.position %>]) {
+%   else
+    field <%= name %> ([<%= bits.position + bits.size - 1 %>:<%= bits.position %>]) {
+%   end
+%     if bits.is_readable? && bits.is_writable?                
+        access rw;
+%     elsif bits.is_writable?                
+        access wo;
+%     else bits.is_writable?                
+        access ro;
+%     end
+        bits <%= bits.size %>;
+        reset 'b<%= bits.reset_val.to_s(2) %>;
+    }
+%   end
+}

data/templates/ralf/default.ralf.erb

@@ -0,0 +1,37 @@
+% # The following options are available:
+% options[:reg_path_postfix] ||= ""
+%
+system <%= (cr_try(:path, :ip_name, :name) || self.class.to_s.split("::").last).downcase %> {
+% unless regs.empty?
+%   # Mapping this to the size of all registers, correct?
+    bytes <%= regs.inject(0){ |sum, reg| sum + reg[1].size } / 8 %>;
+%   regs.each do |reg_name, reg|
+<%= render "register", options.merge(name: reg_name, reg: reg, parent: self, indent: 4) %>
+
+%   end
+% end
+
+% sub_blocks.each do |name, block|
+%   # Should this be the address?    
+    block <%= name %> (<%= block.path(:relative_to => self) %>) @'h<%= block.reg_base_address.to_s(16).upcase %> {
+%       # Mapping this to the size of all registers, correct?
+        bytes <%= regs.inject(0){ |sum, reg| sum + reg[1].size } / 8 %>;
+%       block.regs.each do |reg_name, reg|
+<%= render "register", options.merge(name: reg_name, reg: reg, parent: block, indent: 8) %>
+
+%       end
+%       block.domains.each do |domain_name, domain|
+        domain <%= domain_name %> {
+            bytes 1;
+            endian <%= domain.endian %>;
+%           block.regs.each do |reg_name, reg|
+<%= render "register", options.merge(name: "#{reg_name}_#{domain_name}", reg: reg, parent: block, indent: 12) %>
+
+%       end
+        }
+
+%       end
+    }
+
+% end
+}

data/templates/test/default.ralf.erb

@@ -0,0 +1 @@
+<%= $dut.to_ralf %>

data/templates/test/headers_default.h.erb

@@ -0,0 +1 @@
+<%= $dut.to_header %>

data/templates/test/ip_xact.xml.erb

@@ -0,0 +1 @@
+<%= $dut.to_ip_xact format: :uvm %>