origen 0.0.1 → 0.0.2

data/lib/origen/specs/doc_resource.rb

@@ -0,0 +1,91 @@
+module Origen
+  module Specs
+    # This class is used to store text information to help with documentation processes
+    class Doc_Resource
+      attr_accessor :mode, :type, :sub_type, :audience, :table_title
+      attr_accessor :note_refs, :exhibit_refs, :before_table, :after_table, :doc_options
+
+      def initialize(selector = {}, table_title = {}, text = {}, options = {})
+        @mode = selector[:mode]
+        @type = selector[:type]
+        @sub_type = selector[:sub_type]
+        @audience = selector[:audience]
+        @table_title = table_title[:title]
+        @note_refs = table_title[:note_refs]
+        @exhibit_refs = table_title[:exhibit_refs]
+        @before_table = text[:before]
+        @after_table = text[:after]
+        @doc_options = options
+      end
+
+      def to_xml
+        tmp = {}
+        tmp['mode'] = @mode unless @mode.nil?
+        tmp['type'] = @type unless @type.nil?
+        tmp['sub_type'] = @sub_type unless @sub_type.nil?
+        tmp['audience'] = @audience unless @audience.nil?
+        doc_resource_ml = Nokogiri::XML::Builder.new do |xml|
+          xml.doc_resource(tmp.each do |t, d|
+            "#{t}=\"#{d}\""
+          end
+                          ) do
+            unless @table_title.nil? && @note_refs.size == 0 && @exhibit_refs.size == 0
+              unless @note_refs.first.to_s.size == 0
+                unless @exhibit_refs.first.to_s.size == 0
+                  xml.title do
+                    unless @table_title.nil?
+                      xml.Text @table_title.to_s
+                    end
+                    unless @note_refs.size == 0
+                      unless @note_refs.first.to_s.size == 0
+                        xml.noteRefs do
+                          @note_refs = [@note_refs] unless @note_refs.is_a? Array
+                          @note_refs.each do |note_ref|
+                            unless note_ref.to_s.size == 0
+                              xml.noteRef(href: note_ref.to_s)
+                            end # unless note_ref.to_s.size == 0
+                          end # @note_refs.each do |note_ref|
+                        end # xml.noteRefs do
+                      end # unless @note_refs.first.to_s.size == 0
+                    end # unless @note_refs.size == 0
+                    unless @exhibit_refs.size == 0
+                      unless @exhibit_refs.first.to_s.size == 0
+                        xml.exhibitRefs do
+                          @exhibit_refs = [@exhibit_refs] unless @exhibit_refs.is_a? Array
+                          @exhibit_refs.each do |exhibit_ref|
+                            unless exhibit_ref.to_s.size == 0
+                              xml.exhibitRef(href: exhibit_ref.to_s)
+                            end # unless exhibit_ref.to_s.size == 0
+                          end # @exhibit_refs.each do |exhibit_ref|
+                        end # xml.exhibitRefs do
+                      end # unless @exhibit_refs.first.to_s.size == 0
+                    end # unless @exhibit_refs.size == 0
+                  end # xml.title.done
+                end # unless @exhibit_refs.to_s.size == 0
+              end  # unless @note_refs.to_s.size == 0
+            end # unless @table_title.nil? && @note_refs.size == 0 && @exhibit_refs.size == 0
+            unless @before_table.nil? && @after_table.nil?
+              xml.paragraphs do
+                unless @before_table.nil?
+                  if @before_table.is_a? Nokogiri::XML::Node
+                    xml.before_table @before_table.inner_html
+                  else
+                    xml.before_table @before_table
+                  end
+                end
+                unless @after_table.nil?
+                  if @after_table.is_a? Nokogiri::XML::Node
+                    xml.after_table after_table.inner_html
+                  else
+                    xml.after_table @after_table
+                  end
+                end
+              end # xml.paragraphs do
+            end # unless @before_table.nil? && @after_table.nil?
+          end # xml.doc_resource
+        end # doc_resource_ml = Nokogiri::
+        doc_resource_ml
+      end  # to_xml
+    end
+  end
+end

data/lib/origen/specs/exhibit.rb

@@ -0,0 +1,17 @@
+module Origen
+  module Specs
+    # This class is used to store spec exhibit information used to document IP
+    class Exhibit
+      attr_accessor :id, :type, :title, :description, :reference, :markup
+
+      def initialize(id, type, options = {})
+        @id = id
+        @type = type
+        @title = options[:title]
+        @description = options[:description]
+        @reference = options[:reference]
+        @markup = options[:markup]
+      end
+    end
+  end
+end

data/lib/origen/specs/mode_select.rb

@@ -0,0 +1,16 @@
+module Origen
+  module Specs
+    # This class is used to store mode select for IP
+    class Mode_Select
+      attr_accessor :block, :usage, :mode, :supported, :location
+
+      def initialize(blk, use, mode_ref, support, loc)
+        @block = blk
+        @usage = use
+        @mode = mode_ref
+        @supported = support
+        @location = loc
+      end
+    end
+  end
+end

data/lib/origen/specs/note.rb

@@ -0,0 +1,17 @@
+module Origen
+  module Specs
+    # This class is used to store spec note information used to document IP
+    class Note
+      attr_accessor :id, :type, :mode, :audience, :text, :markup
+
+      def initialize(id, type, options = {})
+        @id = id
+        @type = type
+        @mode = options[:mode]
+        @audience = options[:audience]
+        @text = options[:text]
+        @markup = options[:markup]
+      end
+    end
+  end
+end

data/lib/origen/specs/override.rb

@@ -0,0 +1,21 @@
+module Origen
+  module Specs
+    # This class is used to store override information for specified specs on instantiated IP
+    class Override
+      attr_accessor :block, :usage, :spec_ref, :mode_ref, :sub_type, :audience, :minimum, :maximum, :typical, :disable
+
+      def initialize(block_options = {}, find_spec = {}, values = {}, options = {})
+        @block = block_options[:block]
+        @usage = block_options[:usage]
+        @spec_ref = find_spec[:spec_id]
+        @mode_ref = find_spec[:mode_ref]
+        @sub_type = find_spec[:sub_type]
+        @audience = find_spec[:audience]
+        @minimum = values[:min]
+        @maximum = values[:max]
+        @typical = values[:typ]
+        @disable = options[:disable]
+      end
+    end
+  end
+end

data/lib/origen/specs/power_supply.rb

@@ -0,0 +1,13 @@
+module Origen
+  module Specs
+    # This class is used to store Power Supply Information at the SoC Level
+    class Power_Supply
+      attr_accessor :generic, :actual
+
+      def initialize(gen, act)
+        @generic = gen
+        @actual = act
+      end
+    end
+  end
+end

data/lib/origen/specs/spec.rb

@@ -0,0 +1,226 @@
+module Origen
+  module Specs
+    class Spec
+      autoload :Note, 'origen/specs/note'
+      autoload :Exhibit, 'origen/specs/exhibit'
+      require_relative 'checkers'
+
+      SpecAttribute = Struct.new(:name, :type, :required, :author, :description)
+
+      Limit = Struct.new(:exp) do
+        def value
+          Origen::Specs::Spec.send(:evaluate_limit, exp)
+        end
+      end
+
+      TYPES = Origen::Specs::SPEC_TYPES
+
+      ATTRS = {
+        ip_name:                    SpecAttribute.new(:ip_name, Symbol, true, :design, 'The parent IP object of the specification'),
+        name:                       SpecAttribute.new(:name, Symbol, true, :design, 'Specification Name'),
+        type:                       SpecAttribute.new(:type, Symbol, true, :design, "Specification Type, acceptable values: #{TYPES}"),
+        sub_type:                   SpecAttribute.new(:sub_type, Symbol, true, :design, 'Specification sub-type (e.g. :max_operating_condition)'),
+        mode:                       SpecAttribute.new(:mode, Symbol, true, :design, 'Specification mode, inherited from the owning parent object'),
+        symbol:                     SpecAttribute.new(:symbol, String, false, :design, 'Specification symbol, can contain HTML'),
+        description:                SpecAttribute.new(:description, String, false, :design, 'Specification description'),
+        audience:                   SpecAttribute.new(:audience, Symbol, false, :design, 'Specification audience, acceptable values are :internal and :external'),
+        min:                        SpecAttribute.new(:min, Limit, false, :design, 'Specification minimum limit. The limit expression is displayed, not a resolved value'),
+        min_ovr:                    SpecAttribute.new(:min_ovr, Limit, false, :design, 'Specification minimum limit at SoC level.  The limit expression is displaye,d not a resolved value'),
+        max:                        SpecAttribute.new(:max, Limit, false, :design, 'Specification maximum limit. The limit expression is displayed, not a resolved value'),
+        max_ovr:                    SpecAttribute.new(:max_ovr, Limit, false, :design, 'Specification maximum limit at SoC level.  The limit expression is displaye,d not a resolved value'),
+        typ:                        SpecAttribute.new(:typ, Limit, false, :design, 'Specification typical limit. The limit expression is displayed, not a resolved value'),
+        typ_ovr:                    SpecAttribute.new(:typ_ovr, Limit, false, :design, 'Specification typical limit at SoC level.  The limit expression is displaye,d not a resolved value'),
+        unit:                       SpecAttribute.new(:unit, String, false, :design, 'Specification unit of measure'),
+        constraints:                SpecAttribute.new(:constraints, String, false, :design, "Single logical expression or a CSV list of logical expressions required for the spec to be valid (e.g. 'GVDD == 1.2V'"),
+        limit_type:                 SpecAttribute.new(:limit_type, Symbol, false, :design, 'Auto-generated attribute based on analysis of the spec limits. Acceptable values are :single_sided and :double_sided'),
+        notes:                      SpecAttribute.new(:notes, Hash, false, :design, 'Specification notes'),
+        disposition_required:       SpecAttribute.new(:disposition_required, TrueClass, false, :pde, 'Boolean representation of whether a specification needs a disposition based on silicon results or customer input'),
+        priority:                   SpecAttribute.new(:priority, TrueClass, false, :pde, 'Integer value (1-4) to indicate which priority the cz for this spec will be:  1. Highest priority, for critical or historically risky specs   2. Medium priority, relatively low risk. Not required until all priority 1 specs have been handled  3. Lowest priority, very low risk, low performance specs  4. No plans to characterize'),
+        target:                     SpecAttribute.new(:target, String, false, :pde, 'Specification target limit.  Not used for pass/fail results but for data analysis'),
+        guardband:                  SpecAttribute.new(:guardband, Limit, false, :pde, 'Specification guardband limit'),
+        testable:                   SpecAttribute.new(:testable, TrueClass, false, :pde, 'Boolean representation of whether a specification is testable'),
+        tested_at_probe:            SpecAttribute.new(:tested_at_probe, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at probe'),
+        tested_at_ft_hot:           SpecAttribute.new(:tested_at_ft_hot, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at final test hot temperature'),
+        tested_at_ft_ext_hot:       SpecAttribute.new(:tested_at_ft_ext_hot, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at final test extended hot temperature'),
+        tested_at_ft_cold:          SpecAttribute.new(:tested_at_ft_cold, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at final test cold temperature'),
+        tested_at_ft_ext_cold:      SpecAttribute.new(:tested_at_ft_ext_cold, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at final test extended cold temperature'),
+        tested_at_ft_room:          SpecAttribute.new(:tested_at_ft_room, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested at final test room temperature'),
+        guaranteed_by_prod_test:    SpecAttribute.new(:guaranteed_by_prod_test, TrueClass, false, :pde, 'Boolean representation of whether a specification is guaranteed by production test'),
+        guaranteed_by_proxy_test:   SpecAttribute.new(:guaranteed_by_proxy_test, TrueClass, false, :pde, 'Boolean representation of whether a specification is guaranteed by production test via a proxy test such as BIST'),
+        guaranteed_by_construction: SpecAttribute.new(:guaranteed_by_construction, TrueClass, false, :pde, 'Boolean representation of whether a specification is guaranteed by physical construction, design documentation required'),
+        guaranteed_by_simulation:   SpecAttribute.new(:guaranteed_by_simulation, TrueClass, false, :pde, 'Boolean representation of whether a specification is tested guaranteed by simulation, design documentation required'),
+        cz_on_ate:                  SpecAttribute.new(:cz_on_ate, TrueClass, false, :pde, 'Boolean representation of whether a specification is characterized on ATE'),
+        cz_ate_sample_size:         SpecAttribute.new(:cz_ate_sample_size, Integer, false, :pde, 'Integer number representing the sample size of the split used for customer Cpk calculation as tested on ATE'),
+        cz_ate_cpk:                 SpecAttribute.new(:cz_ate_cpk, Float, false, :pde, 'Float number representing the customer or representative Cpk of the specification as tested on ATE'),
+        cz_on_bench:                SpecAttribute.new(:cz_on_bench, TrueClass, false, :pde, 'Boolean representation of whether a specification is characterized on a bench setup'),
+        cz_bench_sample_size:       SpecAttribute.new(:cz_bench_sample_size, Integer, false, :pde, 'Integer number representing the sample size of the split used for customer Cpk calculation on a bench setup'),
+        cz_bench_cpk:               SpecAttribute.new(:cz_bench_cpk, Float, false, :pde, 'Float number representing the customer or representative Cpk of the specification as tested on a bench setup'),
+        cz_on_system:               SpecAttribute.new(:cz_on_system, TrueClass, false, :pde, 'Boolean representation of whether a specification is characterized in a system setup'),
+        cz_system_sample_size:      SpecAttribute.new(:cz_system_sample_size, Integer, false, :pde, 'Integer number representing the sample size of the split used for customer Cpk calculation in a system'),
+        cz_system_cpk:              SpecAttribute.new(:cz_system_cpk, Float, false, :pde, 'Float number representing the customer or representative Cpk of the specification as tested in a system')
+      }
+
+      ATTRS.each do |_id, spec_attr|
+        class_eval("def #{spec_attr.name}(param=nil); param.nil?  ? @#{spec_attr.name} : (@#{spec_attr.name} = param); end")
+      end
+
+      # There are at least three attributes needed to define a unique spec.
+      #   1) name (e.g. :vdd)
+      #   2) type (e.g. :dc)  Possible values are [:dc, :ac, :temperature]
+      #   3) mode (e.g. :global).  mode defaults to the current mode found for the parent object
+      # A mode is defined as a device state that requires some sequence of actions to be enabled.
+      # A type is a classification moniker that exists without any stimulus required.
+      # Some specs require a fourth attribute sub_type to be uniquely defined.
+      # For example, a global device level VDD specification would require four attributes to be unique.
+      # Here is an example of two spec definitions for a VDD power supply
+      #   name = :vdd, type: :dc, mode: :global, sub_type: typical_operating_conditions, typ = "1.0V +/- 30mV"
+      #   name = :vdd, type: :dc, mode: :global, sub_type: maximum_operating_conditions, min = -0.3V, max = 1.8V
+      # Whereas a typical DDR timing specification might only need three attributes to be unique
+      #   name: :tddkhas, type: :ac, mode: ddr4dr2400, sub_type: nil
+
+      def initialize(name, type, mode, owner_name, &block)
+        @name = name_audit(name)
+        fail 'Specification names must be of types Symbol or String and cannot start with a number' if @name.nil?
+        @type = type
+        @sub_type = nil # not necessary to be able to find a unique spec, but required for some specs
+        @mode = mode
+        @ip_name = owner_name
+        @symbol = nil # Meant to be populated with HTML representing the way the spec name should look in a document
+        @description = nil
+        @min, @typ, @max, @target = nil, nil, nil, nil
+        @min_ovr, @typ_ovr, @typ_ovr = nil, nil, nil
+        @audience = nil
+        @notes = {}
+        @exhibits = {}
+        @testable = nil
+        @guardband = nil
+        (block.arity < 1 ? (instance_eval(&block)) : block.call(self)) if block_given?
+        fail "Spec type must be one of #{TYPES.join(', ')}" unless TYPES.include? type
+        @min = Limit.new(@min)
+        @max = Limit.new(@max)
+        @typ = Limit.new(@typ)
+        @min_ovr = Limit.new(@min_ovr)
+        @max_ovr = Limit.new(@max_ovr)
+        @typ_ovr = Limit.new(@typ_ovr)
+        @guardband = Limit.new(@guardband)
+        fail "Spec #{name} failed the limits audit!" unless limits_ok?
+      end
+
+      def method_missing(method, *args, &block)
+        ivar = "@#{method.to_s.gsub('=', '')}"
+        ivar_sym = ":#{ivar}"
+        if method.to_s =~ /=$/
+          define_singleton_method(method) do |val|
+            instance_variable_set(ivar, val)
+          end
+        elsif instance_variables.include? ivar_sym
+          instance_variable_get(ivar)
+        else
+          define_singleton_method(method) do
+            instance_variable_get(ivar)
+          end
+        end
+        send(method, *args, &block)
+      end
+
+      # Do a 'diff' from the current spec (self) and the compare spec
+      # Returns a hash with attribute as key and an array of the
+      # attribute values that differed
+      def diff(compare_spec)
+        diff_results = Hash.new do |h, k|
+          h[k] = []
+        end
+        # Loop through self's isntance variables first
+        instance_variables.each do |ivar|
+          ivar_sym = ivar.to_s.gsub('@', '').to_sym
+          next if ivar_sym == :notes # temporarily disable until notes diff method written
+          ivar_str = ivar.to_s.gsub('@', '')
+          if compare_spec.respond_to? ivar_sym
+            # Check if the instance variable is a Limit and if so then find
+            # all instance_variables and diff them as well
+            if instance_variable_get(ivar).class == Origen::Specs::Spec::Limit
+              limit_diff_results = diff_limits(instance_variable_get(ivar), compare_spec.instance_variable_get(ivar))
+              # Extract the limit diff pairs and merge with updated keys with the diff_results hash
+              limit_diff_results.each do |k, v|
+                limit_diff_key = "#{ivar_str}_#{k}".to_sym
+                diff_results[limit_diff_key] = v
+              end
+            else
+              unless instance_variable_get(ivar) == compare_spec.instance_variable_get(ivar)
+                diff_results[ivar_sym] = [instance_variable_get(ivar), compare_spec.instance_variable_get(ivar)]
+                Origen.log.debug "Found spec difference for instance variable #{ivar} for #{self} and #{compare_spec}"
+              end
+            end
+          else
+            # The compare spec doesn't have the current instance variable
+            # so log a difference
+            if instance_variable_get(ivar).class == Origen::Specs::Spec::Limit
+              limit_diff_results = diff_limits(instance_variable_get(ivar), compare_spec.instance_variable_get(ivar))
+              # Extract the limit diff pairs and merge with updated keys with the diff_results hash
+              limit_diff_results.each do |k, v|
+                limit_diff_key = "#{ivar_str}_#{k}".to_sym
+                diff_results[limit_diff_key] = v
+              end
+            else
+              Origen.log.debug "Instance variable #{ivar} exists for #{self} and does not for #{compare_spec}"
+              diff_results[ivar_sym] = [instance_variable_get(ivar), '']
+            end
+          end
+        end
+        # Loop through unique instance variables for compare_spec
+        diff_results
+      end
+
+      # Monkey patch of hash/array include? method needed because
+      # Origen::Specs#specs can return a single Spec instance or an Array of Specs
+      def include?(s)
+        s == @name ? true : false
+      end
+
+      # Add a specification note
+      def add_note(id, options = {})
+        options = {
+          type: :spec
+        }.update(options)
+        # Create the Note instance and add to the notes attribute
+        @notes[id] = Origen::Specs::Note.new(id, options[:type], options)
+      end
+
+      # Returns a Note object from the notes hash
+      def notes(id = nil)
+        return nil if @notes.nil?
+        @notes.filter(id)
+      end
+
+      # Returns the number of notes as an Integer
+      def note_count
+        @notes.size
+      end
+
+      private
+
+      # This assumes the limit objects are Structs
+      def diff_limits(limit_one, limit_two = nil)
+        diff_results = Hash.new do |h, k|
+          h[k] = []
+        end
+        # Only need to loop through limit one ivars because the Limit class cannot
+        # be changed in 3rd party files like the Spec class can be
+        limit_one.members.each do |m|
+          if limit_two.respond_to? m
+            unless limit_one.send(m) == limit_two.send(m)
+              diff_results[m] = [limit_one.send(m), limit_two.send(m)]
+              Origen.log.debug "Found limit difference for member #{m} for #{limit_one} and #{limit_two}"
+            end
+          else
+            # Limit two doesn't have the current instance variable or was not provided
+            # as an argument so log a difference
+            Origen.log.debug "Member #{m} exists for #{limit_one} and does not for #{limit_two}"
+            diff_results[m] = [limit_one.send(m), '']
+          end
+        end
+        diff_results
+      end
+    end
+  end
+end

data/lib/origen/specs/version_history.rb

@@ -0,0 +1,14 @@
+module Origen
+  module Specs
+    # This class is used to store spec exhibit information used to document IP
+    class Version_History
+      attr_accessor :date, :author, :changes
+
+      def initialize(date, author, changes)
+        @date = date
+        @author = author
+        @changes = changes
+      end
+    end
+  end
+end