origen_testers 0.41.0 → 0.42.0

data/lib/origen_testers/vector_generator.rb

@@ -4,6 +4,7 @@ module OrigenTesters
     extend ActiveSupport::Concern
 
     require 'erb'
+    require 'origen_testers/decompiler'
 
     included do
       # When set to true vector and cycle number comments will be appended to pattern vectors.

data/pattern/decompile.rb

@@ -0,0 +1,4 @@
+Pattern.create do |options|
+  $DECOMPILER.execute($DECOMPILE_PATTERN)
+end
+

data/pattern/nvm/j750/timing.rb

@@ -35,8 +35,8 @@ Pattern.create do
   gen_vectors
 
   ss 'Test ability to call with a single array argument'
-  cc 'These vectors should use timeset nvm_slow'
-  $tester.set_timeset(['nvm_slow', 40]) do
+  cc 'These vectors should use timeset nvm_slow_40ns'
+  $tester.set_timeset(['nvm_slow_40ns', 40]) do
     gen_vectors
   end
   cc 'These vectors should use timeset nvm_fast'
@@ -51,10 +51,10 @@ Pattern.create do
   ss 'Test that delay calculations are based on the current timeset period'
 
   cc 'This should wait for 5 cycles, 1000/200'
-  $tester.set_timeset('nvm_slow', 200)
+  $tester.set_timeset('nvm_slow_200ns', 200)
   $tester.wait(:time_in_ns => 1000)
   cc 'This should wait for 25 cycles, 1000/40'
-  $tester.set_timeset('nvm_fast', 40)
+  $tester.set_timeset('nvm_fast_40ns', 40)
   $tester.wait(:time_in_ns => 1000)
 
   ss 'Test the period counter'

data/pattern/pin_flip.rb

@@ -0,0 +1,9 @@
+Pattern.create do
+  ENV['ORIGEN_TESTERS_BIT_FLIP_COUNT'].to_i.times do |i|
+    if i % 2 == 0
+      dut.pins(ENV['ORIGEN_TESTERS_BIT_FLIP_PIN'].to_sym).drive!(0)
+    else
+      dut.pins(ENV['ORIGEN_TESTERS_BIT_FLIP_PIN'].to_sym).drive!(1)
+    end
+  end
+end

data/pattern/simple.rb

@@ -0,0 +1,4 @@
+# Pattern to exercise just a bare-bones pattern generation.
+Pattern.create do
+end
+

data/templates/origen_guides/decompilation/decompilerapi.md.erb

@@ -0,0 +1,192 @@
+% render "layouts/guides.html" do
+
+% testers_api_url = 'https://origen-sdk.org/testers/api/OrigenTesters'
+
+`OrigenTesters` includes the 
+[OrigenTesters::Decompiler](<%= "#{testers_api_url}/Decompiler/API.html" %>)
+[mixin](https://ruby-doc.com/docs/ProgrammingRuby/html/tut_modules.html).
+In addition to [decompiling](#Decompiling), this mixin provides some shorthand methods
+for [adding pins](#Adding_Pins) and [executing](#Executing)
+
+A quick summary:
+
+~~~ruby
+# Decompile a pattern source from a file
+OrigenTesters.decompile('path/to/src')
+
+OrigenTesters.add_pins('path/to_src')
+  #=> Queries the pattern's pins and adds any missing pins to the DUT
+
+OrigenTesters.execute('path/to/src')
+  #=> Executes the pattern source in its entirety.
+~~~
+
+<div class="alert alert-warning" role="alert">
+Neither <code>#add_pins</code> nor <code>#execute</code> support input as
+a direct source. Use <code>#decompile_text</code> to get decompiled pattern,
+then call <code>#add_pins</code> or <code>#execute</code> on that, 
+<a href='<%= path "guides/decompilation/overview#Example_Decompilation" %>'>as shown in the example.</a>
+</div>
+
+### Decompiling
+
+Decompiling the pattern source is the first step to working with it in Origen. The
+`#decompile` method, when called on the `Decompiler API`, will do two things: 
+
+1. Using the pattern's extension, attempt to match the pattern source to the applicable decompiler.
+2. Decompile the source, returning the decompiled pattern object.
+ 
+For example, any input ending with `.atp` routes to the `IGXLBasedTester`
+decompiler and input ending with `.avc` routes to the `SmartestBasedTester`
+decompiler.
+
+~~~ruby
+pat = OrigenTesters.decompile('path/to/src.atp')
+  #=> OrigenTesters::IGXLBasedTester::Pattern
+pat.decompiled?
+  #=> true
+
+pat = OrigenTesters.decompile('path/to/src.avc')
+  #=> OrigenTesters::SmartestBasedTester::Pattern
+pat.decompiled?
+  #=> true
+~~~
+
+You can also a get a pre-decompiled pattern object using `#decompiled_pattern`:
+
+~~~ruby
+pat = OrigenTesters.decompiled_pattern('path/to/src.atp')
+  #=> OrigenTesters::IGXLBasedTester::Pattern
+pat.decompiled?
+  #=> false
+
+pat = OrigenTesters.decompiled_pattern('path/to/src.avc')
+  #=> OrigenTesters::SmartestBasedTester::Pattern
+pat.decompiled?
+  #=> false
+~~~
+
+If either method cannot find an applicable decompiler given the extension,
+an exception is raised:
+
+~~~ruby
+pat = OrigenTesters.decompiled_pattern('path/to/src.blah')
+  #=> OrigenTesters::Decompiler::NoSuitableDecompiler
+  #=> Fail in origen_testers: Cannot find a suitable decompiler for pattern source 'pat.blah' ('.blah')
+~~~
+
+If you want to decompile a source from a `String` object directly, use `#decompile_text`.
+You'll need to provide the applicable decompiler, as the `Decompiler API` is
+not able to map a text source to the appropriate decompiler:
+
+~~~ruby
+pat = OrigenTesters.decompile_text("src as string", decompiler: OrigenTesters::IGXLBasedTester::Pattern)
+  #=> OrigenTesters::SmartestBasedTester::Pattern
+pat.decompiled?
+  #=> true
+~~~
+
+#### Discerning Platform Decompilers
+
+Platforms can register themselves as an available `decompiler` during bootup.
+Discerning the appropriate decompiler boils down to asking each registered
+decompiler if it is available to decompile the given source. Each decompiler
+will respond _yes_ or _no_ and on the __first__ _yes_,
+that decompiler will be selected. If no decompilers respond _yes_,
+a `OrigenTesters::Decompiler::NoSuitableDecompiler` exception is raised.
+
+As a user of the decompiler, simply inputting an appropriately named source should
+trigger the correct decompiler, but the methods used underneath are available
+as well:
+
+~~~ruby
+### See the registered decompilers
+
+OrigenTesters.registered_decompilers
+  #=> <%= OrigenTesters.registered_decompilers %>
+
+### See if an applicable decompiler exists for the pattern source
+
+OrigenTesters.decompiler_for?("pat.atp")
+  #=> <%= OrigenTesters.decompiler_for?('pat.atp') %>
+
+OrigenTesters.decompiler_for?("pat.blah")
+  #=> <%= OrigenTesters.decompiler_for?('pat.blah') %>
+
+### Given the pattern source, select the appropriate decompiler, or return nil
+
+OrigenTesters.select_decompiler("pat.atp")
+  #=> <%= OrigenTesters.select_decompiler('pat.atp') %>
+
+OrigenTesters.select_decompiler("pat.blah")
+  #=> nil
+
+### Given the pattern source, select the appropriate decompiler or raise and exception
+### (Notice the '!')
+
+OrigenTesters.select_decompiler!("pat.atp")
+  #=> <%= OrigenTesters.select_decompiler('pat.atp') %>
+
+OrigenTesters.select_decompiler!("pat.blah")
+% begin
+%   OrigenTesters.select_decompiler!("pat.blah")
+% rescue Exception => e
+  #=> <%= e.class %>
+  #=> <%= e.message %>
+% end
+
+### See if the given module provides a decompiler
+
+OrigenTesters.registered_decompiler?(OrigenTesters::IGXLBasedTester)
+  #=> <%= OrigenTesters.registered_decompiler?(OrigenTesters::IGXLBasedTester) %>
+
+OrigenTesters.registered_decompiler?(Origen)
+  #=> <%= OrigenTesters.registered_decompiler?(Origen) %>
+~~~
+
+### Shorthand Methods
+
+The `Decompiler API` supports some short-hand calls to common methods. The calls
+here are equivalent to calling `#decompile`, then the corresponding method on
+that decompiled pattern.
+
+#### Adding Pins
+
+Recall that `#add_pins` compares the available pins between the pattern source and
+the `DUT` and adds any missing pins from the pattern source to the `DUT`, returning
+any pins that it added. The `Decompiler API` has a shorthand method to perform
+this operation: `OrigenTesters.add_pins('path/to/src')`. This will:
+
+1. Decompile the source, using the corresponding platform decompiler.
+2. Add any missing pins to the `DUT`.
+
+~~~ruby
+OrigenTesters.add_pins('pat.atp')
+  # Decompiles the pattern using the .atp decompiler
+  # Adds the pins to the DUT
+  # Returns any pins added to the DUT
+  #=> Array
+~~~
+
+#### Executing
+
+Recall that `#execute` will actually execute the decompiled pattern in the context
+of the current `DUT`.
+
+Assuming the current `DUT` has been instantiated and all timesets are defined,
+calling `OrigenTesters.execeute('path/to/src')` will:
+
+1. Decompile the source, using the corresponding platform decompiler.
+2. Add any missing pins to the `DUT`.
+3. Execute the pattern.
+
+~~~ruby
+OrigenTesters.execute('pattern.atp')
+  # Decompiles the pattern using the .atp decompiler
+  # Adds the pins to the DUT
+  # Execute the pattern source
+  # Returns the decompiled pattern object
+  #=> OrigenTesters::IGXLBasedTesters::Pattern
+~~~
+
+% end

data/templates/origen_guides/decompilation/overview.md.erb

@@ -0,0 +1,214 @@
+% render "layouts/guides.html" do
+
+% # Test pattern that'll be used throughout these guides.
+% # Using the actual pattern object itself to get real return values when possible.
+% class OrigenDecompilerDocDut
+%   include Origen::TopLevel
+% end
+% Origen.load_target('configurable', dut: OrigenDecompilerDocDut)
+% pat = OrigenTesters.decompile_text(OrigenTesters::IGXLBasedTester.sample_direct_source, decompiler: OrigenTesters::IGXLBasedTester::Pattern)
+
+Origen provides some basic functionality for decompiling, or reverse-compiling,
+a pattern from its text representation (e.g., `.atp` for the J750 platform),
+returning an object which Origen can work with.
+
+### Philosophy
+
+The decompiler attempts to support two, somewhat competing, goals:
+
+1. Provide a `universal API` for working with decompiled patterns from any platform.
+2. Allow platforms to implement the `universal API` in such a way that still maintains
+the aspects only present on that particular platform (_platform-specifics_).
+
+The aim is to provide the best of both worlds: a generic-enough,
+`universal API` to accomplish most tasks, without regard to platform-specifics,
+but not bar those platform-specifics completely in the event that such
+a generic method either isn't available, isn't possible, or wouldn't be applicable
+across more than a single platform.
+
+### Definitions
+
+In the context of the _decompilation_ sections, the following definition apply:
+
+* Pattern Source: The text-representation of the a pattern.
+* Platform: Producer of `Pattern Sources`. In most cases, this will be an ATE,
+such as `j750`, or `v93k`, but this also could be `STIL` or `WGL`.
+* Platform-Specifics: Any aspect which separates this platform from another,
+outside of the _actual_ parsing and grammar rules.
+* (Decompiled) Pattern: The instance of an object returned after successful
+decompilation of a `Pattern Source` by a `Decompiler`.
+  * Note, this will often be written fully as `decompiled pattern`, to avoid additional confusion.
+* Decompiler: The object that takes a `Pattern Source` and returns a `Pattern`.
+There are two _flavors_ of this:
+  * In some context, this will be the `generic Decompiler`, that is, the abstract base which, itself, can't actually decompile anything. 
+  * However, in most contexts this will refer to a specific platform.
+For example, _"the J750 decompiler"_, refers to the J750's implementation of the `generic decompiler`, or
+the `OrigenTesters::IGXLBasedTester::Pattern` class.
+
+### Example Decompilation
+
+This example shows some basic usage of the decompiler, without assuming you have
+a pattern source for a supported platform ready to go. This example makes use of the `J750` platform.
+If you aren't familiar with this platform, don't worry; understanding of the pattern source format is not a requirement
+for _using_ the decompiler, specifically in the sense of the `universal API`.
+
+#### Requirements
+
+In order to follow along with these examples, you will need:
+
+* Some `dut` object that does not have the pins `tclk`, `tms`, `tdo`, or `tdi`
+already defined (you can still follow along, but you will not receive identical
+return values from `#add_pins` (covered later) if these pins are already defined).
+
+#### Decompiling Direct Source
+
+The first step to working with a pattern source in Origen is to decompile said source.
+The decompiler is accessed directly on the `OrigenTesters` module, and contains
+methods to decompile a source from a given input string.
+Consider the source, from a J750 `.atp`, below:
+
+~~~
+<%= OrigenTesters::IGXLBasedTester.sample_direct_source %>
+~~~
+
+Placing this in a `String`, we can decompile this directly using the the
+`#decompile_text` method and providing the target decompiler:
+
+<div class="alert alert-success" role="alert">
+The source above is available as a <code>String</code> already:
+
+<code>OrigenTesters::IGXLBasedTester.sample_direct_source</code>
+</div>
+
+~~~ruby
+# A very basic, pre-defined .atp source for the J750 platform
+src = OrigenTesters::IGXLBasedTester.sample_direct_source
+
+# Decompile this source.
+pat = OrigenTesters.decompile_text(src, decompiler: OrigenTesters::IGXLBasedTester::Pattern)
+  #=> OrigenTesters::IGXLBasedTester::Pattern object
+~~~
+
+Since we've specified that this is an `IGXLBasedTester` source, the `#decompile_text` method
+will use that as the target decompiler and return an object corresponding to
+that specific platform's decompiler: `OrigenTesters::IGXLBasedTester::Pattern`.
+
+If you have your own pattern source you'd rather compile, the `#decompile` method
+will accept a filename either as a `String` or `Pathname` object:
+
+~~~ruby
+pat = OrigenTesters.decompile('path/to/src.atp')
+  #=> (for a source ending with .atp)
+  #=> OrigenTesters::IGXLBasedTester::Pattern object
+~~~
+
+<div class="alert alert-info" role="alert">
+The decompiler will try to match the platform based on the extension of the given
+filename. <a href='<%= path "guides/decompilation/decompilerapi#Discerning_Platform_Decompilers" %>'>See the decompilating section for additional details</a>.
+</div>
+
+Now, we can interact with our decompiled pattern. Some easy things we may want to do:
+
+* [Query which pins are present in the pattern source](#Discerning_Pattern_Source_Pins)
+* [Add those pins to the <code>DUT</code>](#Adding_Missing_Pins)
+* [Iterate through the vectors, printing the repeat count and the pin states](#Vectors)
+* [Execute the source in its entirety, in the context of the current <code>DUT</code>](#Executing_the_Pattern_Source)
+
+#### Discerning Pattern Source Pins
+
+There's two methods available to retrieve the pins: `#pins` and `#pin_sizes`.
+
+~~~ruby
+# Return an array of pins, in the order they appear in the pattern
+pat.pins
+  #=> <%= pat.pins %>
+
+# Return the pin names and their respective size
+pat.pin_sizes
+  #=> <%= pat.pin_sizes %>
+~~~
+
+#### Adding Missing Pins
+
+One of the most common operations with respect to the pins is to simply add any
+missing pins to the current `dut`. The decompiled pattern has a built-in method
+to do just that:
+
+~~~ruby
+# Assume the current dut has no pins
+dut.pins
+  #=> <%= dut.pins %>
+
+pat.add_pins
+  #=> <%= pat.add_pins %>
+
+dut.pins
+  #=> <%= dut.pins %>
+~~~
+
+`#add_pins` will return any pins it added to the `dut`. For example, if the `dut`
+already had all the pins from the pattern defined, `#add_pins` would've returned
+`an empty array`. Running the above a second time:
+
+~~~ruby
+# Assume the current dut has no pins
+dut.pins
+  #=> <%= dut.pins %>
+
+pat.add_pins
+  #=> <%= pat.add_pins %>
+
+dut.pins
+  #=> <%= dut.pins %>
+~~~
+
+#### Vectors
+
+We can iterate through each _'vector'_ in the decompiled pattern with `#each_vector`.
+This method takes a block and runs it for each _'vector'_ encountered. Notice the
+quotes around _'vector'_. Each `v` in the example above is actually a `VectorBodyElement` object
+that acts as a placeholder for any `element type` that could appear.
+Each `vector body element` has a `type` associated with it to discern exactly
+what it is:
+
+~~~ruby
+pat.each_vector { |v| puts v.type }
+% # Use the collect method to return an actual array that'll render in the docs.
+<%= pat.collect { |v| ":#{v.type}" }.join("\n") %>
+  #=> nil
+~~~
+
+Now that we have the `type`, we can access the underlying `element`.
+In the example below, we'll check the `type` first and, in the event of a `:vector`,
+access the underlying `element` and print its repeat count and pin states.
+
+~~~ruby
+pat.each_vector { |v| puts "(#{v.element.repeat}) #{v.element.pin_states}" if v.type == :vector }
+% # Use the collect method to return an actual array that'll render in the docs.
+<%= pat.select { |v| v if v.type == :vector }.map { |v| "(#{v.element.repeat}) #{v.element.pin_states}" } .join("\n") %>
+  #=> nil
+~~~
+
+<div class="alert alert-info" role="alert">
+Note that <code>#each_vector</code> returns <code>nil</code>, <b>NOT</b> an
+array containing all the vectors like a normal `each` method would do.
+<a href='<%= path "guides/decompilation/universalapi#Contextual_Notes_For_vector_at"%>'>See the section on working with vectors</a>
+for <i>why</i> this is the case.
+</div>
+
+There's much more to vectors and vector types.
+[See the vectors section](<%= path "guides/decompilation/universalapi#Vector_Body_Elements" %>)
+for further details.
+
+#### Executing the Pattern Source
+
+Now that we've added any missing pins to our `dut` and we've seen how to access
+the vectors themselves, we can `execute` the pattern source. The `#execute`
+method will iterate through each vector, apply the pin states, and 
+cycle the tester `repeat` number of times.
+
+~~~ruby
+pat.execute
+~~~
+
+% end