origen_testers 0.47.0 → 0.48.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: df7294cf891812cfb78d98b161891a459391abb07841eb66d14929185385df22
-  data.tar.gz: 2d0bfcc2c6862a2f10abc60136dbba9099f6f1ae0deeecb099b4700d34d95121
+SHA1:
+  metadata.gz: aab714d801c978890bf63dcf475ccf275b87b54e
+  data.tar.gz: 37d3ef0d30281f9e467ba8475957aacebdb2959a
 SHA512:
-  metadata.gz: c42eacdbe39b6eb35eddf8dcbeb08e49eab49bca4425c20f2c0474c8b5f977fdbeec9ed5b799001f7b8b7f5e6e87fc3293e3ac9c0ecc7012bc8eea8b7d86183b
-  data.tar.gz: f17d9f4f1c7bdb90e58a0f2e6791e406bbf5b80b8ec8b5986a0e2e49e3e5d4145167c81a39773e560fbb8c8392a5b2dbbcf88efc52940e77301c6b4341a88a3a
+  metadata.gz: b2abd50fe57675fa06d61afe99ca4930a36bdfeaf172b8f166c40e0af190cf57b90a5e01ce366471a5aec5dd3a9be7957c09bb089c9922bdf07891f12226a9d6
+  data.tar.gz: b53c79a3dbc31a29fd74a984b4dc5111c245032d093d099a66195c08404f7d12980dd1f33d2f454ec4df1759a72c775aeb612c578dcfe4155af12f3cbe9d8b54

data/config/application.rb

@@ -31,6 +31,7 @@ class OrigenTestersApplication < Origen::Application
         section.page :interface, heading: "Creating an Interface"
         section.page :resources, heading: "Additional Resources"
         section.page :code, heading: "Dynamic Custom Code"
+        section.page :charz, heading: "Characterization API"
         section.page :j750, heading: "J750 API"
         section.page :v93k, heading: "V93K Common API"
         section.page :v93ksmt7, heading: "V93K SMT7 API"

data/config/version.rb

@@ -1,6 +1,6 @@
 module OrigenTesters
   MAJOR = 0
-  MINOR = 47
+  MINOR = 48
   BUGFIX = 0
   DEV = nil
   VERSION = [MAJOR, MINOR, BUGFIX].join(".") + (DEV ? ".pre#{DEV}" : '')

data/lib/origen_testers.rb

@@ -24,6 +24,7 @@ module OrigenTesters
   autoload :NoInterface,        'origen_testers/no_interface'
   autoload :MemoryStyle,        'origen_testers/memory_style'
   autoload :ATP,                'origen_testers/atp'
+  autoload :Charz,              'origen_testers/charz'
 
   # not yet autoload :Time,     'origen_testers/time'
 

data/lib/origen_testers/charz.rb

@@ -0,0 +1,421 @@
+Dir.glob("#{File.dirname(__FILE__)}/charz/**/*.rb").sort.each do |file|
+  require file
+end
+module OrigenTesters
+  module Charz
+    # @!attribute charz_stack
+    #   @return [Array] FILO queue of charz session defining data
+    # @!attribute charz_routines
+    #   @return [Hash] user defined charz routines
+    # @!attribute charz_profiles
+    #   @return [Hash] user defined charz profiles
+    # @!attribute charz_session
+    #   @return [Session] current charz session, based on data in the top of the charz_stack
+    # @!attribute eof_charz_tests
+    #   @return [Array] charz tests to be added at the end of the flow
+    # @!attribute skip_group_eof_charz_tests
+    #   @return [Boolean] whether or not to wrap eof charz tests in a group
+    # @!attribute eof_charz_tests_group_name
+    #   @return [String, Symbol] group name to be used to for eof charz tests
+    attr_accessor :charz_stack, :charz_routines, :charz_profiles, :charz_session, :eof_charz_tests, :skip_group_eof_charz_tests, :eof_charz_tests_group_name
+
+    def charz_stack
+      @charz_stack ||= []
+    end
+
+    def charz_profiles
+      @charz_profiles ||= {}
+    end
+
+    def charz_routines
+      @charz_routines ||= {}
+    end
+
+    def charz_session
+      @charz_session ||= Session.new
+    end
+
+    def eof_charz_tests
+      @eof_charz_tests ||= []
+    end
+
+    # Add a new charz routine to @charz_routines
+    # A charz routine is a object that contains all the necessary info specific to a characterization test
+    # Its intended to be used in combination with an existing point test (regular non charz test) to create
+    # a characterization version of the point test
+    #
+    # @example create a 1d search routine that searches vdd, from 900mv to 300mv, resolution of 5mv
+    #   add_charz_routine :my_routine, type: search do |rt|
+    #     rt.start = 900.mv
+    #     rt.stop  = 300.mv
+    #     rt.res   = 5.mv
+    #     rt.spec  = 'vdd'
+    #   end
+    #
+    # @param [Symbol] id charz_routine id, will be the key value in the @charz_routines hash. Must not have been previously used
+    # @param [Hash] options charz_routine options
+    # @option options [Symbol] :type :search or :'1d' will create a SearchRoutine, :shmoo or :'2d' will create a ShmooRoutine, nil will create a Routine
+    def add_charz_routine(id, options = {}, &block)
+      if charz_routines.ids.include?(id)
+        Origen.log.error("Cannot create charz routine '#{id}', it already exists!")
+        fail
+      end
+      case options[:type]
+      when :search, :'1d'
+        charz_routines[id] = SearchRoutine.new(id, options, &block)
+      when :shmoo, :'2d'
+        charz_routines[id] = ShmooRoutine.new(id, options, &block)
+      else
+        charz_routines[id] = Routine.new(id, options, &block)
+      end
+    end
+
+    # Add a new charz profile to @charz_profiles
+    # A charz profile is a collection of one or more charz routines, as well as flow control and placement data for
+    # the charz tests generated by those routines
+    #
+    # @example create a profile containing 2 routines, end of flow placement, whose tests are only ran if the parent fails
+    #   add_charz_profile :my_profile do |prof|
+    #     prof.routines  = [:my_routine1, :my_routine2]
+    #     prof.placement = :eof
+    #     prof.on_result = :on_fail
+    #   end
+    #
+    # @param [Symbol] id charz_profile id, will be the key value in the @charz_profiles hash. Must not have been previously used
+    # @param [Hash] options charz_profile options
+    def add_charz_profile(id, options = {}, &block)
+      if charz_profiles.ids.include?(id)
+        Origen.log.error("Cannot create charz profile '#{id}', it already exists!")
+        fail
+      end
+      charz_profiles[id] = Profile.new(id, options.merge(defined_routines: charz_routines.ids), &block)
+    end
+
+    # Queries the current charz session to see if its active, indicating point tests should be generating charz tests
+    def charz_active?
+      charz_session.active
+    end
+
+    # Queries the current charz session to see if point tests should skip generation, only adding the resulting charz test
+    def charz_only?
+      charz_active? && charz_session.charz_only
+    end
+
+    # Pauses the current charz session, preventing point tests from generating charz tests even if the session is valid
+    def charz_pause
+      charz_session.pause
+    end
+
+    # Resumes the current charz session. If the session isn't valid (ie charz_resume before setting up the session) then nothing will happen
+    def charz_resume
+      charz_session.resume
+    end
+
+    # Removes the current session generating data off the charz stack
+    # If charz data is still on the stack afterward, the session will update to reflect the new data
+    # if not, the session will become inactive
+    def charz_off
+      charz_stack.pop
+      if charz_stack.empty?
+        update_charz_session(nil)
+      else
+        update_charz_session(*charz_stack.last)
+      end
+    end
+
+    # Pushes a charz object (either a profile or a routine) onto the stack, along with any optional updates to modify the current session
+    # Once pushed, the charz_session will attempt to update itself with the new data, failing if the resulting session is invalid
+    #
+    # If a block is passed, yield the block of tests to enable charz for those tests, then disable charz with a charz_off call
+    #
+    # @param [Symbol] charz_id either a routine or profile id. Method fails if the id can't be found in @charz_routines or @charz_profiles
+    # @param [Hash] options charz_on options
+    # @option options [Symbol] :type (:profile) whether the charz_id refers to a charz profile or routine
+    def charz_on(charz_id, options = {})
+      options = {
+        type: :profile
+      }.merge(options)
+      case options[:type]
+      when :profile
+        charz_obj = charz_profiles[charz_id]
+      when :routine
+        if charz_id.is_a?(Array)
+          charz_obj = charz_routines[charz_id.first]
+          options[:routines] = charz_id
+        else
+          charz_obj = charz_routines[charz_id]
+          options[:routines] = [charz_id]
+        end
+      else
+        Origen.log.error "Unknown charz object type #{options[:type]}, valid types: :profile, :routine"
+        fail
+      end
+      if charz_obj.nil?
+        Origen.log.error "No #{options[:type]} found for charz_id: #{charz_id}"
+        fail
+      end
+      charz_stack.push([charz_obj, options])
+      unless update_charz_session(*charz_stack.last)
+        Origen.log.error 'charz_on failed to create a valid charz session'
+        fail
+      end
+      if block_given?
+        yield
+        charz_off
+      end
+    end
+
+    # An optional helper method to automatically assign an id to tests that will be generating charz tests that depend on the result of the parent test
+    # @param [Hash] options the options for a test before its created and added to the flow
+    # @param [TestInstance, #name] instance <Optional> the test instance whose name is stored in .name, alternatively pass the name in the options hash under :parent_test_name
+    def set_conditional_charz_id(*args)
+      case args.size
+      when 1
+        options = args[0]
+        parent_test_name = options[:parent_test_name]
+      when 2
+        instance = args[0]
+        options = args[1]
+        parent_test_name = instance.name
+      else
+        Origen.log.error 'Too many arguments passed to set_conditional_charz_id. Pass either (test_instance, options), or just (options)'
+        fail
+      end
+      unless options[:id]
+        if charz_active?
+          if charz_session.on_result
+            options[:id] = "#{parent_test_name}_charz_#{charz_session.name}".to_sym
+          end
+        end
+      end
+    end
+
+    # Called after the relevant point test has been inserted into the flow
+    # Takes the options used to build the previous point test as well as insert_charz_test specific options to then
+    # drill down to the point of the flow where the charz test would go, at which point control is handed back to the user's
+    # interface to handle creating and inserting the test
+    #
+    # By default, this method will handle:
+    #   - the placement of the test (inline aka right after the point test, end of flow, or other)
+    #   - wrapping the created charz tests in a group (skippable, group name defaults to <point test name> charz <session name>)
+    #   - conditionally executing the charz tests based on if the point test passed or failed (see set_conditional_charz_id)
+    #   - conditionally executing some/all charz tests based on a mix of enables and flags
+    #
+    # After the above is determined, the user regains control on a per-routine (if multiple routines) basis to then process generating the charz test
+    def insert_charz_tests(options, &block)
+      if charz_active?
+        if options[:id]
+          # two purposes:
+          # 1) prevent all charz tests inadverntently using the same ID as their parent
+          # 2) used in on_result behavior
+          current_id = options.delete(:id)
+          options[:last_test_id] ||= current_id
+        end
+        case charz_session.placement
+        when :inline
+          create_charz_group(options, &block)
+        when :eof
+          # collect the current session and options into a proc, stored in eof_charz_tests to be called later
+          current_session = charz_session.clone
+          eof_charz_tests << proc do
+            @charz_session = current_session
+            create_charz_group(options, &block)
+          end
+        else
+          # inline is the default behavior, and eof (end of flow) has built in support.
+          if respond_to?(:"create_#{charz_session.placement}_charz_tests")
+            send(:"create_#{charz_session.placement}_charz_tests", options, &block)
+          elsif respond_to?(:"insert_#{charz_session.placement}_charz_tests")
+            send(:"insert_#{charz_session.placement}_charz_tests", options, &block)
+          else
+            Origen.log.error "No handling specified for #{charz_session.placement} placement charz tests"
+            fail
+          end
+        end
+      end
+    end
+
+    # called automatically right after a top_level shutdown, generates end of flow charz tests
+    # user should not have to reference this call explicitly
+    def generate_eof_charz_tests
+      unless eof_charz_tests.empty?
+        if skip_group_eof_charz_tests
+          eof_charz_tests.map(&:call)
+        else
+          group_name = eof_charz_tests_group_name || 'End of Flow Charz Tests'
+          group group_name do
+            eof_charz_tests.map(&:call)
+          end
+        end
+      end
+    end
+
+    private
+
+    # called by charz_on, updates the current session, and passes the available routines in for validity checks
+    def update_charz_session(charz_obj, options = {})
+      charz_session.update(charz_obj, options.merge(defined_routines: charz_routines.ids))
+    end
+
+    # called by insert_charz_tests
+    #
+    # if insert_charz_tests was called with the skip group option, then skip to processing the sessions on_result functionality
+    # otherwise, on_result processing occurs within the created group
+    #
+    # group name defaults to <point test name> charz <session name>, but can be set by the user by passing :group_name in the options
+    def create_charz_group(options, &block)
+      if options[:skip_group]
+        process_on_result(options, &block)
+      else
+        group_name = options[:group_name] || "#{options[:parent_test_name]} charz #{charz_session.name}"
+        group group_name.to_sym do
+          process_on_result(options, &block)
+        end
+      end
+    end
+
+    # called by create_charz_group
+    #
+    # Handles the case where the session indicates these charz tests' execution depend on the point test's result
+    # Requires that the id of the point test has been passed to use this functionality. Otherwise, make sure that
+    # charz_session.on_result == nil
+    #
+    # on_fail and on_pass results are built-in, but if the user has a different check to make, it can be handled
+    # by defining the method process_<custom result>_charz_tests
+    #
+    # @see set_conditional_charz_id
+    def process_on_result(options, &block)
+      if charz_session.on_result
+        case charz_session.on_result
+        when :on_fail, :fail, :failed
+          last_test_id = options[:last_test_id] || @last_test_id
+          if_failed last_test_id do
+            process_gates(options, &block)
+          end
+        when :on_pass, :pass, :passed
+          last_test_id = options[:last_test_id] || @last_test_id
+          if_passed last_test_id do
+            process_gates(options, &block)
+          end
+        else
+          if respond_to?(:"process_#{charz_session.placement}_charz_tests")
+            send(:"process_#{charz_session.on_result}_charz_tests", options, &block)
+          else
+            Origen.log.error "No handling specified for result #{charz_session.on_result} charz tests"
+            fail
+          end
+        end
+      else
+        process_gates(options, &block)
+      end
+    end
+
+    # called by process_on_result
+    #
+    # Handles the case where charz_session.enables or charz_session.flags have been set
+    # referring to enables and flags both as gates, gates can wrap all routines in a session if they're in the form of an
+    # array, symbol, or a string (think of the normal use case of if_enable or if_flag)
+    #
+    # If the gate is a Hash, then that means different routines are getting different gate wrappers.
+    # Also if a routine is not indicated in the values of the gate, then that means that routine should not be gated at all
+    #
+    # This is the final method of handling the insert_charz_test usecases, where the block thats been passed around is finally called
+    # the user's provided block is passed the current routine (one at a time) to then take its info to generate a charz test
+    def process_gates(options, &block)
+      if options[:skip_gates] || !(charz_session.enables || charz_session.flags)
+        charz_session.routines.each do |routine|
+          block.call(options.merge(current_routine: routine))
+        end
+      else
+        if charz_session.enables && charz_session.flags
+          if charz_session.enables.is_a?(Hash) && !charz_session.flags.is_a?(Hash)
+            # wrap all tests in flags, wrap specific tests in enables
+            if_flag charz_session.flags do
+              insert_hash_gates(options, charz_session.enables, :if_enable, &block)
+            end
+          elsif !charz_session.enables.is_a?(Hash) && charz_session.flags.is_a?(Hash)
+            # wrap all tests in enables, wrap specific tests in flags
+            if_enable charz_session.enables do
+              insert_hash_gates(options, charz_session.flags, :if_flag, &block)
+            end
+          elsif charz_session.enables.is_a?(Hash) && charz_session.flags.is_a?(Hash)
+            # first insert the tests that are not tied to an enable or flag gate
+            ungated_routines = charz_session.routines - (charz_session.enables.values.flatten | charz_session.flags.values.flatten)
+            ungated_routines.each do |routine|
+              block.call(options.merge(current_routine: routine))
+            end
+            # wrap tests in an enable gate, flag gate, or both
+            gated_routines = charz_session.routines - ungated_routines
+            gated_routines.each do |routine|
+              enable = charz_session.enables.find { |gates, routines| routines.include?(routine) }&.first
+              flag = charz_session.flags.find { |gates, routines| routines.include?(routine) }&.first
+              if enable && flag
+                if_enable enable do
+                  if_flag flag do
+                    # wrap test in both enable and flag gate
+                    block.call(options.merge(current_routine: routine))
+                  end
+                end
+              elsif enable
+                if_enable enable do
+                  # enable only
+                  block.call(options.merge(current_routine: routine))
+                end
+              elsif flag
+                if_flag flag do
+                  # flag only
+                  block.call(options.merge(current_routine: routine))
+                end
+              end
+            end
+          else
+            # both enable and flag is set, and both apply to all routines in session
+            if_enable charz_session.enables do
+              if_flag charz_session.flags do
+                charz_session.routines.each do |routine|
+                  block.call(options.merge(current_routine: routine))
+                end
+              end
+            end
+          end
+        else
+          # only enables or flags is set, not both
+          if charz_session.enables
+            gates = charz_session.enables
+            gate_method = :if_enable
+          elsif charz_session.flags
+            gates = charz_session.flags
+            gate_method = :if_flag
+          end
+          if gates.is_a?(Hash)
+            # wrap some tests in specific gates
+            insert_hash_gates(options, gates, gate_method, &block)
+          else
+            # wrap all tests in the indicated gates
+            send(gate_method, gates) do
+              charz_session.routines.each do |routine|
+                block.call(options.merge(current_routine: routine))
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # helper method for the process gates method above
+    # handles wrapping routines in specific gates, and passing ungated routines back to the user
+    def insert_hash_gates(options, gate_hash, gate_method, &block)
+      ungated_routines = charz_session.routines - gate_hash.values.flatten
+      ungated_routines.each do |routine|
+        block.call(options.merge(current_routine: routine))
+      end
+      gate_hash.each do |gate, gated_routines|
+        send(gate_method, gate) do
+          gated_routines.each do |routine|
+            block.call(options.merge(current_routine: routine))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen_testers/charz/profile.rb

@@ -0,0 +1,120 @@
+module OrigenTesters
+  module Charz
+    # A Charz Profile
+    # Used to store characterization routines as well as flow control, conditional execution, and test placement meta data
+    class Profile
+      # @!attribute id
+      #   @return [Symbol] the id of the current profile, used as a key in OrigenTesters::Charz#charz_profiles hash
+      # @!attribute name
+      #   @return [Symbol] the value used (if the user decides) to generate the name of the created charz test. defaults to the value of @id
+      # @!attribute placement
+      #   @return [Symbol] placement of the to be created charz tests, defaults to inline, accepts :eof as well. Other placements can be used as well if @valid_placements is altered
+      # @!attribute on_result
+      #   @return [Symbol] indicates if the resulting charz tests are depending on the point tests result, valid values include :on_fail, and :on_pass
+      # @!attribute enables
+      #   @return [Symbol, String, Array, Hash] enable gates to be wrapped around the resulting charz tests
+      # @!attribute flags
+      #   @return [Symbol, String, Array, Hash] flag gates to be wrapped around the resulting charz tests
+      # @!attribute routines
+      #   @return [Array] list of charz routines to be called under this profile
+      # @!attribute charz_only
+      #   @return [Boolean] indicates if the point tests should or shouldn't be added to the flow
+      attr_accessor :id, :name, :placement, :on_result, :enables, :flags, :routines, :charz_only
+
+      def initialize(id, options, &block)
+        @id = id
+        @id = @id.symbolize unless id.is_a? Symbol
+        options.each { |k, v| instance_variable_set("@#{k}", v) }
+        (block.arity < 1 ? (instance_eval(&block)) : block.call(self)) if block_given?
+        @name ||= id
+        @placement ||= :inline
+        @defined_routines = options.delete(:defined_routines)
+        attrs_ok?
+      end
+
+      def attrs_ok?
+        return if @quality_check == false
+
+        unknown_routines = @routines - @defined_routines
+        unless unknown_routines.empty?
+          Origen.log.error "Profile #{id}: unknown routines: #{unknown_routines}"
+          fail
+        end
+
+        @valid_placements ||= [:inline, :eof]
+        unless @valid_placements.include? @placement
+          Origen.log.error "Profile #{id}: invalid placement value, must be one of: #{@valid_placements}"
+          fail
+        end
+
+        if @on_result
+          @valid_on_results ||= [:on_fail, :fail, :failed, :on_pass, :pass, :passed]
+          unless @valid_on_results.include?(@on_result)
+            Origen.log.error "Profile #{id}: invalid on_result value, must be one of: #{@valid_on_results}"
+            fail
+          end
+        end
+
+        if @charz_only && @on_result
+          Origen.log.error "Profile #{id}: @charz_only is set, but @on_result (#{@on_result}) requires the parent test to exist in the flow"
+          fail
+        end
+
+        unless @gate_checks == false
+          gate_check(@enables, :enables) if @enables
+          gate_check(@flags, :flags) if @flags
+        end
+      end
+
+      def gate_check(gates, gate_type)
+        case gates
+        when Symbol, String
+          return
+        when Array
+          unknown_gates = gates.reject { |gate| [String, Symbol].include? gate.class }
+          if unknown_gates.empty?
+            return
+          else
+            Origen.log.error "Profile #{id}: Unknown #{gate_type} type(s) in #{gate_type} array."
+            Origen.log.error "Arrays must contain Strings and/or Symbols, but #{unknown_gates.map(&:class).uniq } were found in #{gates}"
+            fail
+          end
+        when Hash
+          gates.each do |gate, gated_routines|
+            if gate.is_a? Hash
+              Origen.log.error "Profile #{id}: #{gate_type} Hash keys cannot be of type Hash, but only Symbol, String, or Array"
+              fail
+            end
+            gate_check(gate, gate_type)
+            gated_routines = [gated_routines] unless gated_routines.is_a? Array
+            unknown_routines = gated_routines - @defined_routines
+            unless unknown_routines.empty?
+              Origen.log.error "Profile #{id}: unknown routines found in @#{gate_type}[#{gate.is_a?(Symbol) ? ':' : ''}#{gate}]: #{unknown_routines}"
+              fail
+            end
+          end
+        else
+          Origen.log.error "Profile #{id}: Unknown #{gate_type} type: #{gates.class}. #{gate_type} must be of type Symbol, String, Array, or Hash"
+          fail
+        end
+      end
+
+      def method_missing(m, *args, &block)
+        ivar = "@#{m.to_s.gsub('=', '')}"
+        ivar_sym = ":#{ivar}"
+        if m.to_s =~ /=$/
+          define_singleton_method(m) do |val|
+            instance_variable_set(ivar, val)
+          end
+        elsif instance_variables.include? ivar_sym
+          instance_variable_get(ivar)
+        else
+          define_singleton_method(m) do
+            instance_variable_get(ivar)
+          end
+        end
+        send(m, *args, &block)
+      end
+    end
+  end
+end

data/lib/origen_testers/charz/routine.rb

@@ -0,0 +1,38 @@
+module OrigenTesters
+  module Charz
+    # A Generic charz routine
+    # Used to store characterization test specific meta data, values of which are used by the user to determine test parameter values
+    class Routine
+      # @!attribute id
+      #   @return [Symbol] charz routine symbol, used as a key in OrigenTesters::Charz#charz_routines
+      # @!attribute name
+      #   @return [Symbol] the value used (if the user decides) to generate the name of the created charz test. defaults to the value of @id
+      attr_accessor :id, :name
+
+      def initialize(id, options = {}, &block)
+        @id = id
+        @id = @id.symbolize unless id.is_a? Symbol
+        options.each { |k, v| instance_variable_set("@#{k}", v) }
+        (block.arity < 1 ? (instance_eval(&block)) : block.call(self)) if block_given?
+        @name ||= @id
+      end
+
+      def method_missing(m, *args, &block)
+        ivar = "@#{m.to_s.gsub('=', '')}"
+        ivar_sym = ":#{ivar}"
+        if m.to_s =~ /=$/
+          define_singleton_method(m) do |val|
+            instance_variable_set(ivar, val)
+          end
+        elsif instance_variables.include? ivar_sym
+          instance_variable_get(ivar)
+        else
+          define_singleton_method(m) do
+            instance_variable_get(ivar)
+          end
+        end
+        send(m, *args, &block)
+      end
+    end
+  end
+end

data/lib/origen_testers/charz/routines/search_routine.rb

@@ -0,0 +1,42 @@
+module OrigenTesters
+  module Charz
+    # a 1D search routine
+    class SearchRoutine < Routine
+      # @!attribute start
+      #   @return [Numeric] search start value
+      # @!attribute stop
+      #   @return [Numeric] search stop value
+      # @!attribute res
+      #   @return [Numeric] search resolution
+      # @!attribute spec
+      #   @return [Numeric] spec parameter to be searched
+      attr_accessor :start, :stop, :res, :spec
+
+      # Runs the same initialization as Routine
+      # performs some rudimentary quality checks, which can be disabled by setting @quality_check = false
+      def initialize(id, options = {}, &block)
+        super
+        attrs_ok?
+      end
+
+      def attrs_ok?
+        return if @quality_check == false
+
+        @required_attrs ||= [:start, :stop, :res, :spec]
+        attrs = @required_attrs.map { |attr| instance_variable_get("@#{attr}") }
+        if attrs.compact.size != @required_attrs.size
+          Origen.log.error "SearchRoutine #{@id}: unspecified attributes, each of #{@required_attrs} must have a value"
+          fail
+        end
+
+        return if @attr_value_check == false
+        if [@start, @stop, @res].all? { |attr| attr.is_a? Numeric }
+          unless @res <= (@start - @stop).abs
+            Origen.log.error "SearchRoutine #{@id}: Search resolution (#{@res}) is larger than the search range: #{(@start - @stop).abs}"
+            fail
+          end
+        end
+      end
+    end
+  end
+end

data/lib/origen_testers/charz/routines/shmoo_routine.rb

@@ -0,0 +1,62 @@
+module OrigenTesters
+  module Charz
+    # A 2D search or "Shmoo" routine
+    class ShmooRoutine < Routine
+      # @!attribute x_start
+      #   @return [Numeric] the starting search value for the x dimension's spec search
+      # @!attribute x_stop
+      #   @return [Numeric] the stopping search value for the x dimension's spec search
+      # @!attribute x_res
+      #   @return the search resolution value for the x dimension's spec search
+      # @!attribute x_spec
+      #   @return [Symbol, String] the spec parameter of interest for the x dimension
+      attr_accessor :x_start, :x_stop, :x_res, :x_spec
+      # @!attribute y_start
+      #   @return [Numeric] the starting search value for the x dimension's spec search
+      # @!attribute y_stop
+      #   @return [Numeric] the stopping search value for the x dimension's spec search
+      # @!attribute y_res
+      #   @return the search resolution value for the x dimension's spec search
+      # @!attribute y_spec
+      #   @return [Symbol, String] the spec parameter of interest for the x dimension
+      attr_accessor :y_start, :y_stop, :y_res, :y_spec
+
+      def initialize(id, options = {}, &block)
+        super
+        attrs_ok?
+      end
+
+      def attrs_ok?
+        return if @quality_check == false
+
+        @required_attrs ||= [:x_start, :x_stop, :x_res, :x_spec, :y_start, :y_stop, :y_res, :y_spec]
+        attrs = @required_attrs.map { |attr| instance_variable_get("@#{attr}") }
+        if attrs.compact.size != @required_attrs.size
+          Origen.log.error "ShmooRoutine #{@id}: unspecified attributes, each of #{@required_attrs} must have a value"
+          fail
+        end
+
+        return if @attr_value_check == false
+
+        # not sure if I want this check, if so need to scope out if step count is common
+
+        # if [@x_start, @x_stop, @x_res].all? { |attr| attr.is_a? Numeric }
+        #   unless @x_res <= (@x_start - @x_stop).abs
+        #     Origen.log.error "ShmooRoutine #{@id}: Search x_resolution (#{@x_res} is larger than the search x_range (#{@x_start - @x_stop).abs})"
+        #     fail
+        #   end
+        # end
+        # if [@y_start, @y_stop, @y_res].all? { |attr| attr.is_a? Numeric }
+        #   unless @y_res <= (@y_start - @y_stop).abs
+        #     Origen.log.error "ShmooRoutine #{@id}: Search y_resolution (#{@y_res} is larger than the search y_range (#{@y_start - @y_stop).abs})"
+        #     fail
+        #   end
+        # end
+        unless @x_spec != @y_spec
+          Origen.log.error "ShmooRoutine #{@id}: Search x_spec is identical to y_spec"
+          fail
+        end
+      end
+    end
+  end
+end

data/lib/origen_testers/charz/session.rb

@@ -0,0 +1,100 @@
+module OrigenTesters
+  module Charz
+    # A charz session
+    # contains the final combination of charz object (routines/profiles) and user options to determine how and what charz tests should be created
+    # the session should be checked in your interface to determine the current status and can be queried to make charz generation decisions
+    class Session < Profile
+      # @!attribute defaults
+      #   @return [Hash] list of values to instantiate the inherited attributes from Profile with if not altered by the session update
+      attr_accessor :defaults
+
+      def initialize(options = {})
+        @id = :current_charz_session
+        @active = false
+        @valid = false
+        if options[:defaults]
+          @defaults = options[:defaults]
+        else
+          @defaults = {
+            placement:  :inline,
+            on_result:  nil,
+            enables:    nil,
+            flags:      nil,
+            name:       'charz',
+            charz_only: false
+          }
+        end
+      end
+
+      # Pauses the current session's activity while maintaining everthing else about the sessions state
+      def pause
+        @active = false
+      end
+
+      # Resume activity, if the session is valid
+      def resume
+        if @valid
+          @active = true
+        end
+      end
+
+      # Takes a Routine or Profile, and queries it to setup the session's attributes
+      # the attributes values can be set from 3 different sources, in order of priority (first is most important):
+      #   - options
+      #   - charz object
+      #   - defaults
+      #
+      # If the resulting session is invalid, @valid will turn false. Otherwise, the session becomes active
+      def update(charz_obj, options)
+        @valid = false
+        if charz_obj.nil?
+          @active = false
+          @valid = false
+          return @valid
+        end
+        @defined_routines = options.delete(:defined_routines)
+        assign_by_priority(:placement, charz_obj, options)
+        assign_by_priority(:on_result, charz_obj, options)
+        assign_by_priority(:enables, charz_obj, options)
+        assign_by_priority(:flags, charz_obj, options)
+        assign_by_priority(:routines, charz_obj, options)
+        assign_by_priority(:name, charz_obj, options)
+        assign_by_priority(:charz_only, charz_obj, options)
+        attrs_ok?
+        massage_gates
+        @active = true
+        @valid = true
+      end
+
+      private
+
+      # convert hash gates to set convert their routines to type array if not already
+      def massage_gates
+        if @enables.is_a?(Hash)
+          @enables = {}.tap do |new_h|
+            @enables.each { |gates, routines| new_h[gates] = [routines].flatten }
+          end
+        end
+        if @flags.is_a?(Hash)
+          @flags = {}.tap do |new_h|
+            @flags.each { |gates, routines| new_h[gates] = [routines].flatten }
+          end
+        end
+      end
+
+      # see initialize
+      def assign_by_priority(ivar, charz_obj, options)
+        if options.keys.include?(ivar)
+          instance_variable_set("@#{ivar}", options[ivar])
+        elsif charz_obj.send(ivar)
+          instance_variable_set("@#{ivar}", charz_obj.send(ivar))
+        elsif @defaults.keys.include?(ivar)
+          instance_variable_set("@#{ivar}", @defaults[ivar])
+        else
+          Origen.log.error "Charz Session: No value could be determined for #{ivar}"
+          fail
+        end
+      end
+    end
+  end
+end

data/lib/origen_testers/origen_ext/generator/flow.rb

@@ -138,6 +138,7 @@ module Origen
           end
           Origen.interface.startup(options) if Origen.interface.respond_to?(:startup)
           interface.instance_eval(&block)
+          Origen.interface.generate_eof_charz_tests if Origen.interface.respond_to?(:generate_eof_charz_tests)
           Origen.interface.shutdown(options) if Origen.interface.respond_to?(:shutdown)
           interface.at_flow_end if interface.respond_to?(:at_flow_end)
           Origen.app.listeners_for(:on_flow_end).each do |listener|

data/lib/origen_testers/test/interface.rb

@@ -2,6 +2,7 @@ module OrigenTesters
   module Test
     class Interface
       include OrigenTesters::ProgramGenerators
+      include OrigenTesters::Charz
 
       attr_accessor :include_additional_prb2_test
       attr_reader :environment
@@ -10,6 +11,45 @@ module OrigenTesters
       # desired to configure your interface
       def initialize(options = {})
         @environment = options[:environment]
+        add_charz
+      end
+
+      def add_charz
+        add_charz_routine :routine1 do |routine|
+          routine.name = '_cz__rt1'
+        end
+        add_charz_routine :routine2 do |routine|
+          routine.name = '_cz__rt2'
+        end
+        add_charz_routine :routine3 do |routine|
+          routine.name = '_cz__rt3'
+        end
+        add_charz_routine :routine4 do |routine|
+          routine.name = '_cz__rt4'
+        end
+        add_charz_routine :routine5 do |routine|
+          routine.name = '_cz__rt5'
+        end
+        add_charz_routine :routine6 do |routine|
+          routine.name = '_cz__rt6'
+        end
+        add_charz_profile :cz do |profile|
+          profile.routines = [:routine3]
+        end
+        add_charz_profile :cz_only do |profile|
+          profile.charz_only = true
+          profile.routines = [:routine1]
+        end
+        add_charz_profile :simple_gates do |profile|
+          profile.flags = :my_flag
+          profile.enables = :my_enable
+          profile.routines = [:routine1]
+        end
+        add_charz_profile :complex_gates do |profile|
+          profile.flags = { ['$MyFlag1'] => [:routine1, :routine2], ['$MyFlag2'] => [:routine3], '$MyFlag3' => :routine4 }
+          profile.enables = { ['$MyEnable1'] => [:routine1], ['$MyEnable2'] => [:routine2, :routine3], '$MyEnable3' => :routine5 }
+          profile.routines = [:routine1, :routine2, :routine3, :routine4, :routine5, :routine6]
+        end
       end
 
       # Test that the block form of flow control methods like this can
@@ -86,6 +126,46 @@ module OrigenTesters
         end
       end
 
+      def func_with_charz(name, options = {})
+        options = {
+          duration: :static
+        }.merge(options)
+
+        if tester.v93k?
+          if tester.smt7?
+            tm = test_methods.ac_tml.ac_test.functional_test
+            ts = test_suites.run(name, options)
+            ts.test_method = tm
+            ts.pattern = 'charz_example'
+
+            test_level_charz = false
+            if options[:charz]
+              charz_on(*options[:charz])
+              test_level_charz = true
+            end
+
+            unless charz_only? && !options[:charz_test]
+              options[:parent_test_name] = name
+              set_conditional_charz_id(options)
+              flow.test ts, options
+            end
+
+            unless options[:charz_test]
+              insert_charz_tests(options.merge(parent_test_name: name, charz_test: true)) do |options|
+                charz_name = :"#{name}_#{charz_routines[options[:current_routine]].name}"
+                func_with_charz(charz_name, options)
+              end
+            end
+
+            charz_off if test_level_charz
+          else
+            fail 'Only SMT7 is Implemented for Charz'
+          end
+        else
+          fail "Tester #{tester.name} Not Yet Implemented for Charz"
+        end
+      end
+
       def func_with_comment(name, options = {})
         if tester.v93k?
           options = {

data/program/charz.rb

@@ -0,0 +1,48 @@
+# An instance of the interface is
+# passed in here, iterators and other
+# argument passing will be supported
+# similar to Pattern.create.
+Flow.create interface: 'OrigenTesters::Test::Interface' do
+  flow.flow_description = '' if tester.v93k?
+
+  if tester.v93k? && tester.smt7?
+    charz_on :complex_gates, { on_result: :fail }
+    func_with_charz :func_complex_gates_on_fail
+    charz_off
+
+    charz_on :complex_gates, { enables: :my_enable }
+    func_with_charz :func_complex_flag_simple_enable
+    charz_off
+
+    charz_on :complex_gates, { flags: :my_flag } do
+      func_with_charz :func_complex_enable_simple_flag
+    end
+
+    charz_on :cz_only, { placement: :eof }
+    func_with_charz :func_charz_only
+    charz_off
+
+    func_with_charz :func_test_level_routine, charz: [:routine1, { type: :routine }]
+
+    charz_on :cz
+    func_with_charz :func_skip_group, skip_group: true
+    charz_pause
+    func_with_charz :func_pause_charz
+    charz_resume
+    func_with_charz :func_resume_charz
+    charz_off
+
+    charz_on :simple_gates, { on_result: :pass } do 
+      func_with_charz :func_simple_gates_on_pass
+    end
+    
+    charz_on :simple_gates, { enables: nil }
+    func_with_charz :func_simple_flags
+    charz_off
+
+    charz_on :simple_gates, { flags: nil }
+    func_with_charz :func_simple_enables
+    charz_off
+  end
+
+end

data/templates/origen_guides/program/charz.md.erb

@@ -0,0 +1,221 @@
+% render "layouts/guides.html" do
+
+Be sure to read and understand the guide to
+[Creating an Interface](<%= path "guides/program/interface" %>) before
+reading this guide.
+This guide covers aspects of the Characterization (charz) API. 
+
+Currently, the charz API has only been proven out for V93K SMT7, but isn't inherently designed around working only for that environment.
+
+The Charz API is enabled by including the Charz module in your interface:
+
+~~~ruby
+# app/lib/my_app/interface.rb
+module MyApp
+  class Interface
+    include OrigenTesters::ProgramGenerators
+    include OrigenTesters::Charz
+~~~
+
+Note this guide assumes the audience is familiar with interface creation and custom test methods, and will not go into detail explaining those topics.
+
+## Overview
+
+The Characterization API allows a flow to add characterization to existing production tests with little additional overhead.
+
+First specify charz routines to set charz test options, then create a profile with flow creation meta for the resulting tests.
+Afterwards, the `charz_on` method can be called in the flow to activate charz profiles, which is explained below.
+
+### Charz Routines
+
+Charz routines contain relevant charz data thats specific to a charz test to be created. Created routines are stored in the `@charz_routines` attribute.
+The data stored within a routine will be used in combination with the options used to make a production test to make a charz variant of the production test.
+
+The interface adds charz routines by calling the `add_charz_routine` method:
+
+~~~ruby
+add_charz_routine :vmin do |routine|
+  routine.name = 'cz_vmin_vdd'
+  routine.start = 1.0.V
+  routine.stop = 0.5.V
+  routine.res = 5.mV
+  routine.spec = 'VDD'
+end
+~~~
+
+### Charz Profiles
+
+Charz profiles contain a collection of routines, as well as test creation meta data related to test placement, production test result dependence, and conditional execution.
+
+The interface adds charz profiles by calling the `add_charz_profile` method. To create a profile that contains previously defined vmin and vmax search routines, whose resulting searches
+only run if the production test failed, and sets the vmax search routine to only run if the 'VmaxEnable' variable is set:
+
+~~~ruby
+add_charz_profile :fail_searches do |profile|
+  profile.name = 'fail_searches'
+  profile.on_result = :on_fail
+  profile.routines = [:vmin, :vmax]
+  profile.enables = { ['$VmaxEnable'] => [:vmax] }
+end
+~~~
+
+### Charz Session
+
+The charz session (stored in your interfaces `@charz_session` attribute) monitors the current state of characterization at a given point in flow generation.
+
+The API provides some key methods for querying that state during generation, such as:
+
+ * `charz_active?` : indicates if applicable productions tests should be generating charz tests as well
+ * `charz_only?`   : indicates if the production tests should be added to the flow or not, only generating the resulting charz test
+
+## Interface Considerations
+
+A couple of enhancements will need to be added to your interface to take advantage of the API in addition to adding `include OrigenTesters::Charz` as shown above.
+The charz routines and profiles will need to be added, and your flow methods will need to be updated to know what to do when a charz session is active.
+
+### Adding charz routines and profiles
+
+As long as the desired routines and profiles exist in the interface's @charz_routines and @charz_profiles hashes, the rest of the API will work as expected.
+One option is to add them during the interface initialization:
+
+~~~ruby
+# app/lib/my_app/interface.rb
+module MyApp
+  class Interface
+    include OrigenTesters::ProgramGenerators
+    include OrigenTesters::Charz
+
+    def add_charz
+      add_charz_routine :my_routine do |routine|
+        routine.name = 'cz_vmin_vdd'
+        routine.start = 1.0.V
+        routine.stop = 0.5.V
+        routine.res = 5.mV
+        routine.spec = 'VDD'
+      end
+      add_charz_profile :my_profile do |profile|
+        profile.name = 'vmin_search'
+        profile.routines = [:vmin]
+      end
+    end
+
+    def initialize(options = {})
+      add_charz
+    end
+~~~
+
+### Configuring Existing Flow Methods
+
+Now that your interface has defined some routines and profiles, the flow methods needs to be updated to work with an active charz session.
+
+Lets take a simplistic example functional flow method defined in `MyApp::Interface`:
+
+~~~ruby
+# V93K SMT7 example
+def func(name, options = {})
+  tm = test_methods.ac_tml.ac_test.functional_test
+  ts = test_suites.run(name, options)
+  ts.test_method = tm
+  ts.pattern = 'example'
+  flow.test ts, options
+end
+~~~
+
+And now we'll add the ability for this flow method to generate a charz test as well:
+
+~~~ruby
+# V93K SMT7 example
+def func(name, options = {})
+  if options[:routine]
+    tm = test_methods.ac_tml.ac_test.spec_search
+  else
+    tm = test_methods.ac_tml.ac_test.functional_test
+  end
+  ts = test_suites.run(name, options)
+  ts.test_method = tm
+  ts.pattern = 'example'
+
+  if options[:routine]
+    ts.spec = options[:routine].spec
+    ts.min = options[:routine].stop
+    ts.max = options[:routine].start
+    ts.resolution = options[:routine].res
+  end
+
+  flow.test ts, options
+
+  unless options[:charz_test]
+    insert_charz_tests(options.merge(parent_test_name: name, charz_test: true)) do |options|
+      charz_name = :"#{name}_#{charz_routines[options[:current_routine]].name}"
+      options[:routine] = charz_routines[options[:current_routine]]
+      func(charz_name, options)
+    end
+  end
+end
+~~~
+
+### #insert_charz_tests
+
+The `insert_charz_tests` method handles everything regarding adding the charz test into the flow except determining the actual name and parameters of the test, which is
+done by the local interface in the block passed to the `insert_charz_tests` method. This method handles:
+
+ * querying the charz session
+ * test placement
+ * charz test grouping
+ * production test result dependency
+ * gate processing (enables, flags) 
+
+The block that gets passed is yielded the latest options (with id removed if passed for the production test, so it doesn't get re-used for charz tests).
+Routines in the current session are yielded one at a time, with their id being returned in `options[:current_routine]`.
+
+#### Company Plugin Oppurtunity
+
+If your company is already using a plugin to distribute the definitions of these flow methods, this is a good oppurtunity to add charz variants of those methods
+that take routine as an input. This can really streamline the process, for example if you combine the charz flow methods plugin with a central flow entry point method called by
+all flow methods, then the implementation becomes:
+
+~~~ruby
+def add_to_flow(ts, options = {})
+  flow.test ts, options
+
+  unless options[:charz_test]
+    insert_charz_tests(options.merge(parent_test_name: name, charz_test: true)) do |options|
+      insert_current_charz_test(options)
+    end
+  end
+end
+~~~
+
+Where insert_current_charz_test is a method defined in the company charz flow method plugin.
+
+### Flow Usage Examples
+
+Now that the interface has charz routines and profiles, lets look at how to use the API within the flow itself:
+
+~~~ruby
+Flow.create(interface: 'MyApp:Interface') do
+
+  # regular non charz test
+  func :my_test1
+
+  # create charz test variants of my_test2 following the production
+  # version of my_test2 using the routines in :my_profile
+  charz_on :my_profile do
+    func :my_test2
+  end
+
+  # conditional charz enablement
+  # besides dut.enable_charz? check, identical to above
+  charz_on :my_profile if dut.enable_charz?
+  func :my_test3
+  charz_off if dut.enable_charz?
+
+  # override session values at the flow level
+  charz_on :my_profile, placement: :eof do
+    func :my_test4
+  end
+
+end
+~~~
+
+% end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_testers
 version: !ruby/object:Gem::Version
-  version: 0.47.0
+  version: 0.48.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-05 00:00:00.000000000 Z
+date: 2020-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -16,14 +16,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.44.0
+        version: 0.57.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.44.0
+        version: 0.57.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: simplecov-html
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: require_all
   requirement: !ruby/object:Gem::Requirement
@@ -175,6 +203,12 @@ files:
 - lib/origen_testers/atp_deprecation.rb
 - lib/origen_testers/basic_test_setups.rb
 - lib/origen_testers/callback_handlers.rb
+- lib/origen_testers/charz.rb
+- lib/origen_testers/charz/profile.rb
+- lib/origen_testers/charz/routine.rb
+- lib/origen_testers/charz/routines/search_routine.rb
+- lib/origen_testers/charz/routines/shmoo_routine.rb
+- lib/origen_testers/charz/session.rb
 - lib/origen_testers/command_based_tester.rb
 - lib/origen_testers/decompiler.rb
 - lib/origen_testers/decompiler/decompiler_api.rb
@@ -474,6 +508,7 @@ files:
 - program/_erase_vfy.rb
 - program/_iv_resources.rb
 - program/basic_interface.rb
+- program/charz.rb
 - program/components/_deep_nested.rb
 - program/components/_prb1_main.rb
 - program/components/_prb2_main.rb
@@ -509,6 +544,7 @@ files:
 - templates/origen_guides/pattern/timing.md.erb
 - templates/origen_guides/pattern/ultraflex.md.erb
 - templates/origen_guides/pattern/v93k.md.erb
+- templates/origen_guides/program/charz.md.erb
 - templates/origen_guides/program/code.md.erb
 - templates/origen_guides/program/custom.md.erb
 - templates/origen_guides/program/doc.md.erb
@@ -549,7 +585,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.6.14.4
 signing_key: 
 specification_version: 4
 summary: This plugin provides Origen tester models to drive ATE type testers like