origen 0.0.1 → 0.0.2

data/lib/origen/tester/doc/doc.rb

@@ -0,0 +1,226 @@
+module Origen
+  module Tester
+    # Tester model to generate test program documentation from your pattern sources.
+    # This is intended to be a drop in replacement for existing testers and instead
+    # of generating patterns or test program sheets it will generate a document object
+    # which you can then render out via a template or manually.
+    class Doc
+      include Tester
+
+      autoload :Generator, 'origen/tester/doc/generator'
+      autoload :Model, 'origen/tester/doc/model'
+
+      attr_accessor :html_mode
+
+      def generate?
+        html_mode
+      end
+
+      def initialize(*_args)
+        @pat_extension = 'md'
+        @indent = 0
+        @snip_counters = []
+      end
+
+      # Snip the number of comment lines generated by the contained block
+      # to the number given, this is useful for keeping files sizes down and
+      # is typically used to snip sections like downloading LRE code.
+      def snip(number, _options = {})
+        @snip_counters.push number + 1
+        yield
+        @snip_counters.pop
+      end
+
+      def pc(msg)
+        if @snip_counters.last
+          if @snip_counters.last == 1
+            @snip_counters[@snip_counters.size - 1] = 0
+            msg = '  ...snipped'
+          elsif @snip_counters.last == 0
+            return
+          else
+            @snip_counters[@snip_counters.size - 1] -= 1
+          end
+        end
+        if html_mode
+          push_comment(msg)
+        else
+          Origen.log.info((' ' * @indent) + msg)
+        end
+      end
+
+      def c1(msg, options = {})
+        if generating_program?
+          Origen.interface.doc_comments_capture(msg)
+        else
+          unless @inhibit_comments
+            options = {
+              prefix: true
+            }.merge(options)
+            if @step_comment_on
+              open_text_block
+              if options[:prefix]
+                pc "# #{msg}"
+              else
+                pc "#{msg}"
+              end
+            end
+          end
+        end
+      end
+
+      def c2(msg, options = {})
+        unless @inhibit_comments
+          options = {
+            prefix: true
+          }.merge(options)
+          open_text_block
+          if options[:prefix]
+            pc "# #{msg}"
+          else
+            pc "#{msg}"
+          end
+        end
+      end
+
+      def annotate(msg, _options)
+        unless @inhibit_comments
+          if html_mode
+            pc ''
+            lines = msg.split("\n")
+            leading_spaces = lines.first[/\A */].size
+            lines.each do |line|
+              pc line.gsub(/^.{#{leading_spaces}}/, '')
+            end
+            pc ''
+          end
+        end
+      end
+
+      def open_text_block
+        if html_mode
+          unless @text_block_open
+            pc ''
+            pc '~~~text'
+            @text_block_open = true
+          end
+        end
+      end
+
+      def close_text_block
+        if html_mode
+          if @text_block_open
+            pc '~~~'
+            pc ''
+            @text_block_open = false
+          end
+        end
+      end
+
+      def pattern_name
+        Origen.app.current_job.output_pattern_filename.gsub('.md', '')
+      end
+
+      def pre_header
+        # pc "---"
+        # pc "layout: bootstrap"
+        # pc "title: #{pattern_name}"
+        # pc "gzip: false"
+        # pc "---"
+        # pc ""
+        # pc "# #{pattern_name}"
+        # pc ""
+      end
+
+      def pattern_section(msg)
+        unless @inhibit_comments
+          if generating_program?
+            Origen.interface.flow.start_section(name: msg)
+            yield
+            Origen.interface.flow.stop_section
+          else
+            if html_mode
+              counter = next_accordion_counter
+              close_text_block
+              pc ''
+              pc "<div class=\"accordion-group\">"
+              pc "<div class=\"accordion-heading\">"
+              pc "<a class=\"accordion-toggle\" data-toggle=\"collapse\" data-parent=\"#accordion2\" href=\"#collapseComment#{counter}\">"
+              pc "#{msg}"
+              pc '</a>'
+              pc '</div>'
+              pc "<div id=\"collapseComment#{counter}\" class=\"accordion-body collapse\">"
+              pc "<div class=\"accordion-inner\" markdown=\"1\">"
+              yield
+              close_text_block
+              pc '</div>'
+              pc '</div>'
+              pc '</div>'
+            else
+              pc ''
+              pc "#{msg}"
+              pc ''
+              @indent += 4
+              yield
+              @indent -= 4
+            end
+          end
+        end
+      end
+
+      def next_accordion_counter
+        @accordion_counter ||= 0
+        @accordion_counter += 1
+      end
+
+      def ss(msg = nil)
+        unless @inhibit_comments
+          @step_comment_on = true
+          if block_given?
+            yield
+          else
+            c2(msg)
+          end
+          @step_comment_on = false
+        end
+      end
+
+      def self.generate_program_model(files, options = {})
+        options = {
+          action:       :program,
+          return_model: true,
+          skip_diff:    true
+        }.merge(options)
+        Origen.app.with_doc_tester do
+          Origen.target.temporary = options[:target] if options[:target]
+          Origen.app.load_target!
+          Origen.interface.reset_globals
+          options[:files] = files
+          Origen.file_handler.preserve_and_clear_state do
+            Origen.app.runner.launch(options)
+          end
+        end
+        model.target = Origen.target.name
+        model
+      end
+
+      def self.model
+        @model ||= Model.new
+      end
+
+      def doc?
+        true
+      end
+
+      def cycle(_options = {})
+      end
+
+      # Ignore any tester-specific methods
+      def method_missing(_method, *_args, &_block)
+        if block_given?
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/origen/tester/doc/generator/flow.rb

@@ -0,0 +1,71 @@
+module Origen
+  module Tester
+    class Doc
+      module Generator
+        class Flow
+          include Origen::Tester::Generator
+          include Origen::Tester::Generator::FlowControlAPI
+
+          OUTPUT_POSTFIX = 'flow'
+          OUTPUT_EXTENSION = 'yaml'
+
+          def add(type, options = {})
+            preserve_comments = options.delete(:preserve_comments)
+            line = track_relationships(options) do |options|
+              FlowLine.new(type, options)
+            end
+            collection << line unless Origen.interface.resources_mode?
+            if preserve_comments
+              line.description = Origen.interface.doc_comments
+            else
+              line.description = Origen.interface.doc_comments_consume
+            end
+            line
+          end
+
+          def start_section(options = {})
+            l = FlowLine.new(:section_start, options)
+            if options[:name]
+              desc = [options[:name]]
+            else
+              desc = []
+            end
+            l.description = desc + Origen.interface.doc_comments_consume
+            collection << l
+          end
+
+          def stop_section(options = {})
+            collection << FlowLine.new(:section_stop, options)
+          end
+
+          def test(instance, options = {})
+            options = save_context(options)
+            add(:test, { test: instance }.merge(options))
+          end
+
+          def set_device(options = {})
+            add(:set_device, options)
+          end
+
+          def to_yaml(options = {})
+            collection.map { |l| l.to_yaml(options) }
+          end
+
+          def render(file, options = {})
+            options[:file] = file
+            add(:render, options)
+          end
+
+          def skip(identifier = nil, options = {})
+            identifier, options = nil, identifier if identifier.is_a?(Hash)
+            identifier = generate_unique_label(identifier)
+            options[:test] = identifier
+            add(:branch, options)
+            yield
+            add(:label, test: identifier)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen/tester/doc/generator/flow_line.rb

@@ -0,0 +1,203 @@
+module Origen
+  module Tester
+    class Doc
+      module Generator
+        class FlowLine
+          attr_accessor :type, :id, :test, :context, :attributes, :description
+
+          def initialize(type, attrs = {})
+            @type = type
+            @test = attrs.delete(:test)
+            @context = {}
+            @attributes = {}
+            flow_control_options = Origen.interface.extract_flow_control_options!(attrs)
+            flow_control_options.each do |opt, val|
+              send("#{opt}=", val)
+            end
+            attrs.each do |attribute, val|
+              @attributes[attribute] = val
+            end
+          end
+
+          def to_yaml(options = {})
+            options = {
+              include_descriptions: true
+            }.merge(options)
+            y = {
+              'type'        => @type,
+              'description' => description,
+              'instance'    => test_to_yaml(options),
+              'flow'        => {
+                'attributes' => attributes_to_yaml(options),
+                'context'    => context_to_yaml(options)
+              }
+            }
+            y.delete('description') unless options[:include_descriptions]
+            y
+          end
+
+          def attributes_to_yaml(_options = {})
+            a = {}
+            @attributes.each do |name, val|
+              a[name.to_s] = val if val
+            end
+            a
+          end
+
+          def context_to_yaml(_options = {})
+            # Turn attribute keys into strings for prettier yaml, this includes all
+            # relationship meta data
+            c = @context.reduce({}) { |memo, (k, v)| memo[k.to_s] = v; memo }
+            # Now add job/enable word data
+            if @enable
+              c['if_enable'] = @enable
+            end
+            if @unless_enable
+              c['unless_enable'] = @unless_enable
+            end
+            unless if_jobs.empty?
+              c['if_jobs'] = if_jobs
+            end
+            unless unless_jobs.empty?
+              c['unless_jobs'] = unless_jobs
+            end
+            c
+          end
+
+          def test_to_yaml(options = {})
+            if @test
+              if @test.is_a?(String) || @test.is_a?(Symbol)
+                {
+                  'attributes' => {
+                    'name' => @test.to_s
+                  }
+                }
+              else
+                @test.to_yaml(options)
+              end
+            end
+          end
+
+          def method_missing(method, *args, &_block)
+            method = method.to_s
+            if method.gsub!('=', '')
+              @attributes[method] = args.first
+            else
+              @attributes[method]
+            end
+          end
+
+          def job
+            if !if_jobs.empty? && !unless_jobs.empty?
+              fail "Both if and unless jobs have been defined for test: #{parameter}"
+            elsif !if_jobs.empty?
+              if_jobs.join(',')
+            elsif !unless_jobs.empty?
+              unless_jobs.map { |j| "!#{j}" }.join(',')
+            else
+              ''
+            end
+          end
+          alias_method :jobs, :job
+
+          def if_jobs
+            @if_jobs ||= []
+          end
+
+          def unless_jobs
+            @unless_jobs ||= []
+          end
+
+          def if_enable=(val)
+            @enable = val
+          end
+          alias_method :enable=, :if_enable=
+          alias_method :if_enabled=, :if_enable=
+
+          def unless_enable=(val)
+            @unless_enable = val
+          end
+          alias_method :unless_enabled=, :unless_enable=
+
+          def if_job=(jobs)
+            [jobs].flatten.compact.each do |job|
+              job = job.to_s.upcase
+              if job =~ /!/
+                self.unless_job = job
+              else
+                if_jobs << job unless if_jobs.include?(job)
+              end
+            end
+          end
+          alias_method :if_jobs=, :if_job=
+          alias_method :add_if_jobs, :if_job=
+          alias_method :add_if_job, :if_job=
+
+          def unless_job=(jobs)
+            [jobs].flatten.compact.each do |job|
+              job = job.to_s.upcase
+              job.gsub!('!', '')
+              unless_jobs << job unless unless_jobs.include?(job)
+            end
+          end
+          alias_method :unless_jobs=, :unless_job=
+          alias_method :add_unless_jobs, :unless_job=
+          alias_method :add_unless_job, :unless_job=
+
+          def run_if_failed(id)
+            @context[:if_failed] = id
+          end
+
+          def run_if_passed(id)
+            @context[:if_passed] = id
+          end
+
+          def run_if_ran(id)
+            @context[:if_ran] = id
+          end
+
+          def run_unless_ran(id)
+            @context[:unless_ran] = id
+          end
+
+          def run_if_any_passed(parent)
+            @context[:if_any_passed] = parent.id
+          end
+
+          def run_if_all_passed(parent)
+            @context[:if_all_passed] = parent.id
+          end
+
+          def run_if_any_failed(parent)
+            @context[:if_any_failed] = parent.id
+          end
+
+          def run_if_all_failed(parent)
+            @context[:if_all_failed] = parent.id
+          end
+
+          def continue_on_fail
+            @attributes[:continue] = true
+          end
+
+          def id
+            @id || "#{parameter}_#{unique_counter}"
+          end
+
+          def unique_counter
+            @unique_counter ||= self.class.unique_counter
+          end
+
+          def self.unique_counter
+            @ix ||= -1
+            @ix += 1
+          end
+
+          def test?
+            @type == :test
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen/tester/doc/generator/test.rb

@@ -0,0 +1,68 @@
+module Origen
+  module Tester
+    class Doc
+      module Generator
+        class Test
+          attr_accessor :name, :index, :version, :append_version, :attributes
+
+          def initialize(name, attrs = {})
+            attrs = {}.merge(attrs)  # Important to keep this to clone the original options
+            # so that the caller's copy if not affected by stripping
+            # out the flow/relation options
+            @attributes = {}
+            @append_version = true
+            self.name = name
+            Origen.interface.extract_relation_options!(attrs)
+            Origen.interface.extract_flow_control_options!(attrs)
+            attrs.each do |attribute, val|
+              @attributes[attribute] = val
+            end
+          end
+
+          def to_yaml(options = {})
+            {
+              'attributes' => attributes_to_yaml(options)
+            }
+          end
+
+          def attributes_to_yaml(_options = {})
+            a = {}
+            @attributes.each do |name, val|
+              a[name.to_s] = val if val
+            end
+            a['name'] = name
+            a
+          end
+
+          def method_missing(method, *args, &_block)
+            method = method.to_s
+            if method.gsub!('=', '')
+              @attributes[method] = args.first
+            else
+              @attributes[method]
+            end
+          end
+
+          def ==(other_test)
+            self.class == other_test.class &&
+              unversioned_name.to_s == other_test.unversioned_name.to_s &&
+              attributes.size == other_test.attributes.size &&
+              attributes.all? { |name, val| other_test.attributes[name] == val }
+          end
+
+          def name
+            if version && @append_version
+              "#{@name}_v#{version}"
+            else
+              @name.to_s
+            end
+          end
+
+          def unversioned_name
+            @name.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen/tester/doc/generator/test_group.rb

@@ -0,0 +1,66 @@
+module Origen
+  module Tester
+    class Doc
+      module Generator
+        class TestGroup
+          attr_accessor :name, :version, :append_version
+
+          include Enumerable
+
+          def initialize(name, _options = {})
+            @name = name
+            @store = []
+            @append_version = true
+          end
+
+          def name
+            if unversioned_name
+              if version && @append_version
+                "#{unversioned_name}_v#{version}"
+              else
+                unversioned_name.to_s
+              end
+            end
+          end
+
+          def to_yaml(options = {})
+            y = {}
+            y['group'] = @store.map { |t| t.to_yaml(options) }
+            y
+          end
+
+          def unversioned_name
+            if @name
+              if @name =~ /grp$/
+                @name
+              else
+                "#{@name}_grp"
+              end
+            end
+          end
+
+          def <<(instance)
+            @store << instance
+          end
+
+          def size
+            @store.size
+          end
+
+          def each
+            @store.each { |ins| yield ins }
+          end
+
+          def ==(other_instance_group)
+            self.class == other_instance_group.class &&
+              unversioned_name.to_s == other_instance_group.unversioned_name.to_s &&
+              size == other_instance_group.size &&
+              self.all? do |ins|
+                other_instance_group.any? { |other_ins| ins == other_ins }
+              end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen/tester/doc/generator/tests.rb

@@ -0,0 +1,47 @@
+module Origen
+  module Tester
+    class Doc
+      module Generator
+        class Tests
+          attr_accessor :collection
+
+          def initialize
+            @collection = []
+          end
+
+          class IndexedString < ::String
+            attr_accessor :index
+
+            def name
+              self
+            end
+          end
+
+          def add(name, attrs = {})
+            test = Test.new(name, attrs)
+            if @current_group
+              @current_group << test
+            else
+              collection << test
+            end
+            test
+          end
+
+          # Arbitrarily group a subset of tests together, see the J750 API for details on how to use
+          # this.
+          def group(name = nil, options = {})
+            name, options = nil, name if name.is_a?(Hash)
+            @current_group = TestGroup.new(name, options)
+            collection << @current_group
+            yield @current_group
+            @current_group = nil
+          end
+          alias_method :add_group, :group
+
+          def render(_file, _options = {})
+          end
+        end
+      end
+    end
+  end
+end