Test Program Generator

J750 API

Be sure to read and understand the guide to Creating an Interface before reading this section. This guide will describe the API to generate J750/IG-XL test program components from within an interface file.

To re-cap this is the shell required to implement an interface:

# lib/vreg/interface.rb
module Vreg
  class Interface
    include OrigenTesters::ProgramGenerators

    # An example method that can be called from your test flow to generate a functional test
    def func(name, options={})
      # If your interface supports multiple platforms, add conditional logic like this, if you
      # only ever want to support one platform then you don't need this
      if tester.j750?
        # Functional test implementation for J750
      elsif tester.v93k?
        # Functional test implementation for V93K
      end
    end

  end
end

The OrigenTesters::ProgramGenerators will provide the interface with access to all of the platform generator APIs for the platforms that it supports.

If your interface supports multiple platforms then add conditional logic to separate them as shown above.

When generating a J750 program most of the effort is in generating the test instances. To start with the basic method of creating and decorating test instance objects will be discussed and then at the end of this section some recommendations will be given on how to structure your test instance generation methods.

The method test_instances returns an instance of OrigenTesters::IGXLBasedTester::J750::TestInstances which provides additional methods to generate new test instances. The API should be consulted for the most up to date information on the methods available.

A new test instance can be instantiated like this:

test_instances.add(:vreg_func, :functional)

This one line of code does a lot of things:

• Creates a new test instance sheet if one doesn’t exist already
• Instantiates a new test instance object
• Sets its name to ‘vreg_func’
• Applies the default attributes for a J750 functional test instance (basically the same attributes that would be present when you added a new functional test instance within IG-XL)
• Adds the new test instance to the test instance sheet

If you were to add that line and generate your program you would now get a test instance sheet generated with a single functional test instance in it called ‘vreg_func’. Not bad.

Convenience methods exist where you can call a method named after the type of the test instance, this is equivalent:

test_instances.functional(:vreg_func)

You will of course want to decorate your new test instance with attributes that are specific to your application, to do that you simply assign the returned instance to a variable and then you can programmatically set the attributes that you want. For example:

ins = test_instances.functional(:vreg_func)
ins.ac_category = "Spec"
ins.ac_selector = "Default"
ins.time_sets = "Tim"
ins.pin_levels = "Lvl"

The name of these methods is the underscored (to align with general Ruby conventions) version of the name in the IG-XL columns headers and they should hopefully be very intuitive.

Note that you don’t need to do anything here to save or push the instance into the sheet, this will all be done automatically.

Attributes can also be passed in when instantiating the new instance, this is equivalent if you prefer:

ins = test_instances.functional :vreg_func, ac_category: "Spec",
                                            ac_selector: "Default",
                                            time_sets: "Tim",
                                            pin_levels: "Lvl"

Additional methods will be available depending on the instance type that you specified. For example in our functional instance we can set the pattern and call a pre-test interpose function like this:

ins.pattern = "vreg_functional"
ins.pre_test_func = "someInterposeFunc"

Again the method names should hopefully be intuitive and should correspond to the IG-XL names.

To see what the method names are called refer to the TEST_INSTANCE_ALIASES constant definition at the top of the J750 TestInstance API.

Currently supported test instance types are (although check the API for the latest information):

• functional
• board_pmu (bpmu)
• pin_pmu (ppmu)
• other
• empty

The add_til method is available to describe a custom instance. An example is below.

# app_interface

def initialize(options = {})
  add_til :my_lib,
    test_a: {
      # Basic arg
      input1: :arg0,
      # Arg with default value
      input2: [:arg1, 'default'],
      # Arg with default and list of predefined allowed values
      input3: [:arg2, 'volt', %w(volt curr)],
      # Attribute aliases can be defined like this:
      aliases: {
        some_alias_name: :input1,
	another_alias:   :input2
      },
      # Define any methods you want for the instance like this
      methods: {
        # An optional finalize method can be supplied, this method will be called
	# immediately before the test instance is rendered. The test object itself
	# will be passed as an argument.
	finalize: lambda do |ti|
	  ti.proc_name = 'blah_blah'
	  ti.proc_called_as = ''
	end,
	set_some_arg: lambda do |ti, val|
	  ti.input1 = val
	end
      }
    },
    
    test_b: {
      # ...
    }
end

# Here's how to use the custom library
def do_test_a(name, options = {})
  ti = test_instances.my_lib.test_a name
  ti.input1 = 50.0
  ti.input3 = 'curr'
  
  # ...
end

If you need a different type you can still call the add method, the difference in the returned instance for an unrecognized type is:

• The instance will be completely empty and all attributes will need to be added by your application code.
• The named attribute methods will not be available.

The latter means that instead of using convenience methods to set the attributes you will need to use argX format instead, where argX corresponds to the column name in IG-XL.

So the previous example of adding a pattern and interpose function call to our functional instance could be re-written as shown below:

ins.arg0 = "vreg_functional"
ins.arg3 = "someInterposeFunc"

You would also need to configure the basic attributes such as the template type and name. To get an idea of what is required refer to the TEST_INSTANCE_DEFAULTS constant definition near the top of the J750 TestInstance API.

If you do find yourself in this situation please get in touch via the community channels and we can quickly work with you to add the new instance type to Origen, then the names attribute methods will be available for everyone.

Generally the test instance defaults should match exactly what you get from IG-XL (that is the intention at least).

To see what the defaults are for a given test instance type refer to the TEST_INSTANCE_DEFAULTS constant definition near the top of the J750 TestInstance API.

A number of helper methods are available to make test instance generation easier.

A good example is setting the current range of a parametric test instance where the value stored in the IG-XL workbook is not at all intuitive and bears little resemblance to the numeric range value that it represents. A set_irange method is available to help, here are some examples:

ins.set_irange(:smart)
ins.set_irange(ua: 2)
ins.set_irange(2.uA) # Same as above
ins.set_irange(ma: 200)
ins.set_irange(0.2) # Same as above
ins.set_irange(a: 0.2) # Same as above

A useful pattern when using this method is just to set the range to the test upper spec limit, Origen will then take care of rounding this to the correct range.

See the J750 TestInstance API for details on the currently available helper methods.

If you have a good helper method in your application that you think would be a useful addition to Origen please do create a pull request with the additions to the Origen Testers plugin.

Your interface does not need to keep track of duplicate instances, Origen will automatically get rid of them. See the discussion “Avoiding Duplicate Tests” in the Creating an Interface guide.

IG-XL has the concept of a test instance group, that is a group of test instances that you can call from a single line in the test flow. However the syntax for this in the test instance sheet does not lend itself to easy generation - that is a test instance with the same name as an existing one will be treated as a group if they occur next to each other, whereas it will be a validation error if they are apart. This poses some problems for Origen when it comes to test instance generation - how does it know when the instance your application has requested is a duplicate that should be screened vs. an intentional generation of a group?

To avoid pushing responsibility of duplicate tracking to the application there is a dedicated method for generating groups. Any instances generated within the given block of code will be treated as a group:

test_instances.group("vreg_func_all") do |group|
  $dut.vregs.each_with_index do |vreg, i|
    test_instances.functional("vreg_func")
  end
end

See the group method API for more details and examples.

As mentioned at the start the vast majority of your J750 interface code will be concerned with generating test instances, so it pays to spend a bit of time up front thinking about how to organize this code into a maintainable architecture.

The following techniques have proved to be useful in organizing the test instance generation for some very large and complex test flows.

Create Base Instances

Add methods to create base test instances, that is test instances which contains all of the attributes that every instance in your application will have.

def base_instance(name, type, options={})
  ins = test_instances.add(name, type)
  ins.dc_category = "VREG"
  if options[:vdd]
    ins.dc_selector = options[:vdd].to_s.capitalize  # If :min, :max for example
  else
    ins.dc_selector = "Typ"
  end
  ins.ac_category = "Spec"
  ins.ac_selector = "Default"
  ins.time_sets = "Tim"
  ins.pin_levels = "Lvl"
  ins    # Remember to return the newly created instance object to the caller
end

def func(name, options={})
  ins = base_instance(name, :functional, options)
  # Additional functional specific configuration here
end

This pattern can be extended to provide additional methods like “base_functional_instance”, “base_bpmu_instance” and so on.

Use Decorator Methods

A decorator method is a method that decorates (or adds to) a test instance with specific functionality. For example in the flagship Origen application, some of our functional test instances required match loop support while others did not, so we created a decorator that we could call to add this feature:

def add_match(ins)
  ins.post_test_f = "MatchBinFails"
  ins.pat_flag_f = "MatchLoopPatFlagFunc"
  ins.set_wait_flags :a
end

def func(name, options={})
  ins = base_instance(name, :functional, options)
  ins.add_match(ins) if some_logic_to_gate_this
end

Split Your Application Instances into Logical Groups

In the flagship application we found it best to conceptually split our test instance generators by application-specific types rather than by sticking to the IG-XL types like functional, BPMU, PPMU, etc.

It is hard to give a universal example here since this area is so application specific, but to hopefully give you some food for thought…

In the flagship application we had a lot of parametric tests and initially we went down the path of having an instance generation method for all BPMU tests and one for all PPMU tests. However within those groups some of the tests were very different and it led to a lot of complexity within those methods.

When we took a step back and looked at our application our tests were not really split into 2 types, rather they were comprised of 4 types - a high-voltage measurement, a high-voltage calibration, a low-voltage measurement and a low-voltage calibration. When we continued this process through our test flow as a whole we ended up with 14 different test classifications and we then added a method dedicated to generating the test instance for each one.

You should probably not go down this path initially, but once you get a feel for the generation process and if your interface is starting to get complex, then this is a step to consider.

The hard part is over, creating pattern sets and groups is trivial by comparison to creating test instances. A similar API is provided to generate pattern resources in your test program and a nice by product is that Origen will keep track of the referenced patterns and will produce a required list of patterns at the end (which you can then pass to the pattern generator).

As with test instance generation Origen will deal with the suppression of duplicates in all cases.

To add a pattern set call as follows:

patsets.add("vreg_func_pset", pattern: "patterns/VREG/vreg_func.PAT")

Multiple patterns can be specified by passing an array as the 2nd argument:

patsets.add("vreg_func_pset", [{pattern: "patterns/VREG/vreg_func.PAT"},
                               {pattern: "patterns/VREG/vreg_global_subs.PAT", start_label: "subr"}
                              ])

Creating pattern groups is identical, just substitute patsets with patgroups.

Normally you would create a dedicated method for creating pattern sets to avoid duplication, something like this:

def add_patset(name)
  patsets.add("#{name}_pset", pattern: "patterns/VREG/#{name}.PAT")
end

The pattern set or group object can be assigned to the pattern attribute of a test instance directly:

def func(name, options={})
  ins = test_instances.functional(name)
  ins.pattern = add_patset(name)
end

If you just want to add a pattern reference outside of a pattern set or group then add it to the referenced_patterns array to ensure that it gets added to the list of required patterns that is output from the program generation process:

referenced_patterns << "some_vreg_pattern"

Within your interface the flow method will return an instance of the J750 flow generator which provides methods for adding tests and other entries to your test flow. See the API for full details.

So for example to enter a log print statement in the flow you can call:

flow.logprint "Start of the vreg test section"

Going back to the earlier example from the Creating Flows guide we had this in our flow:

log "Vreg test module"

This is probably the simplest method to implement in our interface:

def log(msg)
  flow.logprint(msg)
end

The most common call will be to the test method which will insert a call to a test instance in the flow. Note that it is recommended that you pass all options from the test flow into any flow methods, this ensures that any flow control logic will get implemented.

Here is a complete interface method for the first time that will generate a test instance, add a pattern set reference to it, and now finally call the instance from the test flow:

def func(name, options={})
  ins = test_instances.functional(name)
  ins.pattern = add_patset(name)
  flow.test(ins, options)
end

The object returned from flow.test is an instance of OrigenTesters::IGXLBasedTester::J750::FlowLine and this does provide a few methods that may be of use. However in general most of the methods are there to support flow control and it is not recommended that you use these directly, rather use the flow control API to do this.

However it is recommended that you look at the TESTER_FLOWLINE_ATTRS, ALIASES, and DEFAULTS definitions as this will tell you what the generator calls the IG-XL attributes. For example you can see that the test number attribute is called tnum and that this is also aliased to 'number'.

This means that you can set this attribute via this style (which is most useful for passing attributes through directly from the flow file):

flow.test(ins, tnum: 10000)

Or it can also be set via a method call:

flow_line = flow.test(ins)
flow_line.tnum = 10000

It is recommended that you create a dedicated method for flow insertion as this gives you a single place to implement defaults and to perform any translation between what the flow has called an attribute and what the J750 generator would call it:

def add_flow_entry(ins, options)
  # Defaults
  options = {
    bin: 5,
    tname: options[:tname] || options[:name] || ins.name,
  }.merge(options)

  # Some translations
  options[:softbin] = options[:sbin] if options[:sbin]

  # Add the flow entry
  flow_line = flow.test(ins, options)

  # Some final decoration
  flow_line.continue_on_fail if options[:continue]

  flow_line
end

Here is an example interface method using this add to flow method:

def func(name, options={})
  ins = test_instances.functional(name, options)
  ins.pattern = add_patset(name)
  add_flow_entry(ins, options)
end

Finally you may on occasion wish to call a test from your flow where the instance is not available - maybe the instance is generated by another test module for example. In this case the :instance_not_available option can be set to true to prevent Origen from trying to match up the flow with an instance object.

flow.test("POR_INSTANCE", instance_not_available: true)

The common flow-control API will generate content into the IG-XL flow sheet’s device columns, meaning that the flow execution branching will be specific to each site.

However, IG-XL also provides the ability to control test execution based on the test results across multiple sites via the group columns and Origen provides some additional IG-XL-only APIs to work with that feature.

The following flow-control options/methods are available which can be used in the same way as the common site-level options such as if_failed, if_passed, etc:

• if_any_sites_failed - Run the test(s) on all sites if ANY site failed the referenced upstream test
• if_all_sites_failed - Run the test(s) on all sites if ALL sites failed the referenced upstream test
• if_any_sites_passed - Run the test(s) on all sites if ANY site passed the referenced upstream test
• if_all_sites_passed - Run the test(s) on all sites if ALL sites passed the referenced upstream test

These inverse forms are also available:

• unless_any_sites_failed
• unless_all_sites_failed
• unless_any_sites_passed
• unless_all_sites_passed

Here is an example of how to use in both block and in-line forms:

func :read1, id: :ta1, bin: 10, number: 60000
func :erase1, if_any_site_failed: :ta1, bin: 12, number: 60010

func :read2, id: :ta2, bin: 10, number: 60020
if_any_site_failed :ta2 do
  func :erase2, number: 60030
  func :erase2, number: 60040
end

Other IG-XL sheets do not currently have generators available, although that is likely to change in the future.

For now though the existing Origen-based applications have found that the other sheets tend to be simple enough that they can be easily handled via a template-based approach.

To create a template simply build the sheet in IG-XL, export it to ASCII and this becomes your initial template, then add Ruby snippets as required to make parts of it dynamic.

See the Dynamic Custom Code guide for more details on how to compile a template automatically during a program generation process.