% 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
~~~

The default behavior for gates is to "OR" them if multiple are defined. The below will result in each routine being nested inside 'my_enable1 or my_enable2'.
~~~ruby
add_charz_profile :enables do |profile|
  profile.name = 'enables'
  profile.routines = [:vmin, :vmax]
  profile.enables = [:my_enable1, :my_enable2]
end
~~~

The profile can be updated to "AND" together multiple enables or flags. To set up this functionality
create a hash which maps a routine name to multiple flags and set the corresponding "and_" profile attribute to true.
~~~ruby
add_charz_profile :anded_enables do |profile|
  profile.name = 'anded_enables'
  profile.routines = [:vmin, :vmax]
  profile.and_enables = true
  profile.enables = { vmin: [:overall_enable, :vmin_enable], vmax: [:overall_enable, :vmax_enable]}
end
~~~

### Flow API

Once your profiles and routines are initialized, the primary way of using the Charz API are through charz on/off calls as well as their append/truncate counterparts:

#### charz_on / charz_off

Pushes/pops 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. The updates will be stored as an "instance" which
is essentially a dummy Profile, and placed inside the sessions instance stack, effectively making the charz_stack a 2D array.

Once an instance is pushed onto the stack, the session becomes active and valid, allowing your apps hooks to query that state to know if a charz test needs to be inserted.

Basic Usage:

~~~ruby
# pushes the profile :my_profile onto the charz stack
charz_on :my_profile
# after you've updated your app to insert charz tests,
# this line will make two tests: point test and charz variant
func :my_test
# pops :my_profile off the charz stack
charz_off

# alternate block form, functionally identical
charz_on :my_profile do
  func :my_test
end
~~~

#### charz_on_append / charz_off_truncate

Very similar to the previous charz_on/off, the append/truncate instead operates in the 2nd dimension of the 2D array that is the charz stack.
Pushes/pops a charz object (either a profile or a routine) onto the current sessions instance stack, along with any optional updates to modify that instance.
This will result in subsequent charzable point tests in being processed against each of the current instances. In other words, this new push will not take
priority over the current stack head, but instead append to it.

Basic Usage:

~~~ruby
# pushes the profile :my_profile onto the charz stack
charz_on :my_profile
# after you've updated your app to insert charz tests, this line will make two tests:
# point test and charz variant
func :my_test
# instead of pushing onto the charz stack itself,
# this will push :my_other_profile onto the instance stack of the current session,
# which is the at the head of the charz stack
charz_on_append :my_other_profile
# this line now makes 3 tests: the point test, a charz variant
# per :my_profile, and another per :my_other_profile
func :my_other_test
# pops the session of the stack, meaning both :my_profile and :my_other_profile
# are gone since they were in the same session alternately run charz_off_truncate
# to only remove :my_other_profile
charz_off
~~~

### 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. Basic usage is to make charz_on/off calls, which will set the
session to contain the called profile as the current instance to generate against.

Additionally if you would like to add additional profiles to the current session, you can use the `charz_on_append` (and its counter part: `charz_off_truncate`) to do so.

~~~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

  # create profileA charz test variants of my_test5, as well as profileA and profileB charz variants of my_test6
  # this would produce the following tests in order:
  # my_test5
  # my_test5_routineA
  # my_test6
  # my_test6_routineA
  # my_test6_routineB
  charz_on :profileA do
    func :my_test5
    charz_on_append :profileB
    func :my_test6
  end

end
~~~

% end