origen_testers 0.19.0 → 0.19.2

data/templates/origen_guides/pattern/creating.md.erb

@@ -0,0 +1,133 @@
+% render "layouts/guides.html" do
+
+Patterns are generated by regular Ruby files that should live within the <code>pattern</code>
+directory - a sub-directory within there is fine and is in fact encouraged to help
+keep things organized as the number of patterns increases.
+However keep in mind that each pattern should be uniquely named - i.e. no other files of the
+same name should live in
+any of the sub-directories of <code>pattern</code>.
+
+Each pattern file should have the following structure:
+
+~~~ruby
+Pattern.create do
+  # Pattern specific content goes here
+end
+~~~
+
+#### Startup and Shutdown Sequences
+
+Startup and shutdown sequences will generally be the same for all patterns and these should
+be implemented by using the [callbacks](<%= path "guides/misc/callbacks" %>) that support
+[pattern generation](<%= path "guides/misc/callbacks/#pattern_generation" %>).
+
+Any options supplied to <code>Pattern.create</code> will be passed into the <code>startup</code> and
+<code>shutdown</code> methods when they are called, thereby providing a mechanism for per-pattern
+customization of the startup/shutdown sequences.
+
+Here is an example of an SoC controller with some startup and shutdown callbacks implemented:
+
+~~~ruby
+class MyDeviceController
+  include Origen::Controller
+
+  def startup(options)
+    options = {
+      mode: :functional_test,
+    }.merge(options)
+    if options[:mode] == :functional_test
+      enter_functional_test_mode
+    elsif options[:mode] == :bist
+      enter_bist_test_mode
+    else
+      raise "Unknown mode requested - #{options[:mode]}"
+    end
+  end
+
+  def shutdown(options)
+    options = {
+      reset: true,
+    }.merge(options)
+    reset_device if options[:reset]
+  end
+end
+~~~
+
+So by default this pattern will enter functional test mode at the start and reset the device at the end:
+
+~~~ruby
+Pattern.create do
+  # Pattern specific content goes here
+end
+~~~
+
+This one will enter BIST mode instead at the start:
+
+~~~ruby
+Pattern.create(mode: :bist) do
+  # Pattern specific content goes here
+end
+~~~
+
+and this one would exit without resetting the device:
+
+~~~ruby
+Pattern.create(mode: :bist, reset: false) do
+  # Pattern specific content goes here
+end
+~~~
+
+<div class="alert alert-info">
+  <strong>Note</strong> - The top-level is guaranteed to be called first and last for the startup and shutdown
+      callbacks respectively. However the calling order of lower level startup/shutdown listeners is undefined, if
+      you have multiple and care about the order you should designate one as the master which will be called by Origen, it
+      should then co-ordinate calling any additional startup/shutdown methods as required.
+</div>  
+
+#### The Golden Rules for Building Maintainable Patterns
+
+Origen provides a framework in which you can build very complex patterns that remain
+easy to maintain, but as with any tool it is also possible to use it to create something
+with which to hang yourself!
+
+In order to avoid going down a path that will lead to an unmaintainable mess, it is
+strongly recommended that the following rules are observed:
+
+* Patterns should not talk to the current tester object directly
+* Patterns should not attempt to control pin states
+* Patterns should not attempt to access registers directly
+
+Probably the most tempting one to break is the last one, however
+generally manipulating register states outside of the owning model is a sign of poor
+application design and breaking the encapsulation that should be provided by a model
+representing a silicon module.
+Instead the model's controller should provide an external interface which would remain constant even if the
+internal operation of a given operation changes significantly from one silicon revision to the next.
+See the [Controller guides](<%= path "guides/controllers/introduction" %>) for more.
+
+If the above rules are followed pattern source files should typically be very small and should
+generally only call a handful of methods on the target object(s), here are a few examples:
+
+~~~ruby
+# Pattern to measure the output of the Vreg module
+Pattern.create do
+  $dut.vreg.measure
+end
+~~~
+
+~~~ruby
+# Pattern to measure the output of the Vreg module for a specific setting
+Pattern.create do
+  $dut.vreg.measure(setting: 12)
+end
+~~~
+
+~~~ruby
+# Pattern to program a checkerboard and then read it
+Pattern.create do
+  $dut.nvm.program(pattern: :ckbd)
+  $dut.nvm.read(pattern: :ckbd)
+end
+~~~
+
+% end

data/templates/origen_guides/pattern/custom.md.erb

@@ -0,0 +1,5 @@
+% render "layouts/guides.html" do
+
+<%= render "partials/placeholder.md" %>
+
+% end

data/templates/origen_guides/pattern/documenting.md.erb

@@ -0,0 +1,431 @@
+% render "layouts/guides.html" do
+
+Origen encourages an agile approach to documentation and pattern generation is
+no exception.
+Tools are provided to create test patterns that are self-documenting and by taking
+a little care you can produce very detailed (and of course 100% accurate) documentation
+of your test patterns for free.
+
+The pattern generation command has the following switches:
+
+~~~text
+origen g bistcom           # Generate a regular pattern
+origen g bistcom --doc     # Output documentation of that pattern to the terminal
+origen g bistcom --html    # Generate pre-formatted HTML documentation for inclusion in a web page
+~~~
+
+The following methods are available to control the documentation output from the pattern
+generator...
+
+#### Debug Documentation
+
+Comments that may help with debug of patterns on the tester can be injected into
+the pattern via the <code>cc</code> method, as with all methods related to
+pattern documentation this is globally available.
+
+~~~ruby
+cc "Entering test mode now"
+test.mode.write!(RAMBIST_MODE)
+reset!
+~~~
+
+The method argument is a regular string and dynamic segments can be embedded and
+formatted using any regular Ruby.
+
+~~~ruby
+delay_cycles = 100
+cc "Wait for #{delay_cycles} cycles for the mode to latch"
+
+address = 0x12
+cc "Set the target address to: 0x%04X" % address
+~~~
+
+This will produce pattern output that looks like this:
+
+~~~text
+// Wait for 100 cycles for the mode to latch
+// Set the target address to 0x0012
+~~~
+
+<code>c1</code> is an alias for <code>cc</code>.
+
+These low level comments will appear in the pattern but they will not be included
+when a document of the pattern is generated.
+
+A <code>c2</code> method is available to elevate the importance of a subset of
+these low level comments
+such that they will be included in generated documentation.
+
+~~~ruby
+cc "You won't see me in the docs"
+c1 "Or me"
+c2 "But you will see me!"
+~~~
+
+#### Documenting Major Steps
+
+Major steps in the pattern can be highlighted using the <code>ss</code> method.
+
+~~~ruby
+ss "Enter RAM BIST mode"
+
+# A block form is also available
+ss do
+  vdd_core = 1.7
+  cc "Enter RAM BIST mode with the following options:"
+  cc "  Vdd core - #{vdd_core}v"
+end
+~~~
+
+This will produce the following output in the pattern:
+
+~~~text
+// #######################################################################
+// # Enter RAM BIST mode
+// #######################################################################
+
+// #######################################################################
+// # Enter RAM BIST mode with the following options:
+// #   Vdd core - 1.7v
+// #######################################################################
+~~~
+
+Any comments defined in this way are considered more important than the regular
+<code>cc</code> comments and they will be automatically included in the
+generated documentation.
+
+#### Documenting Structure
+
+When presenting documentation it is useful to know something about the structure
+of the pattern, this allows vectors to be grouped into sections like 'startup', 
+'shutdown', etc.
+
+Such structure can be described using the <code>pp</code> method:
+
+~~~ruby
+pp "Startup" do
+  $dut.enter_ram_bist_mode
+  $dut.ram.configure_for_test
+end
+
+def enter_ram_bist_mode
+  pp "Enter RAM BIST mode" do
+    # Mode entry code here...
+  end
+end  
+~~~
+
+This would produce comments in the pattern that look like this:
+
+~~~text
+// #######################################################################
+// # Startup
+// #######################################################################
+
+// #######################################################################
+// # Enter RAM BIST mode
+// #######################################################################
+~~~
+
+However this difference vs. the <code>ss</code> method is that information about
+the structure has been provided - it can be determined that the enter RAM bist
+section is a sub-section of the wider startup sequence.
+
+This comes into play when the pattern documentation is generated as HTML,
+now we will see something like this (click to expand):
+
+<div class="panel-group">
+<div class="panel panel-default">
+<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment1">
+<a class="no-underline">
+Startup
+</a>
+</div>
+<div id="collapseComment1" class="panel-collapse collapse">
+<div class="panel-body" markdown="1">
+
+<div class="panel panel-default">
+<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment2">
+  <a class="no-underline">
+  Enter RAM BIST mode
+  </a>
+</div>
+<div id="collapseComment2" class="panel-collapse collapse">
+<div class="panel-body" markdown="1">
+
+~~~text
+# Some comments generated by the RAM BIST entry sequence
+~~~
+
+</div>
+</div>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+#### Adding Annotations
+
+Sometimes it will be helpful to add some annotations to describe what sections
+of the pattern are doing, this can be done via the <code>annotate</code>
+method.
+
+Any annotations will not be output in the actual pattern but will be included
+in generated documentation.
+
+Here is the above example with some annotations added:
+
+~~~ruby
+pp "Startup" do
+  annotate "Perform startup operations that are common to all patterns."
+  $dut.enter_ram_bist_mode
+  $dut.ram.configure_for_test
+end
+
+def enter_ram_bist_mode
+  pp "Enter RAM BIST mode" do
+
+    annotate <<-END
+      This is an example of a multi-line annotation. Anything you write here
+      will be parsed as markdown, so you can do things like:
+
+      * Create bullet
+      * Lists
+
+      ~~~ruby
+      # Embed some code examples
+      $dut.enter_ram_bist_mode
+      ~~~
+
+      Or create [links](http://origen.freescale.net)
+    END
+
+    # Mode entry code here...
+  end
+end  
+~~~
+
+This would produce the following snippet of documentation:
+
+
+
+<div class="panel-group">
+<div class="panel panel-default">
+<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment3">
+<a class="no-underline">
+Startup
+</a>
+</div>
+<div id="collapseComment3" class="panel-collapse collapse">
+<div class="panel-body" markdown="1">
+
+Perform startup operations that are common to all patterns.
+
+<div class="panel panel-default">
+<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment4">
+<a class="no-underline">
+Enter RAM BIST mode
+</a>
+</div>
+<div id="collapseComment4" class="panel-collapse collapse">
+<div class="panel-body" markdown="1">
+
+This is an example of a multi-line annotation. Anything you write here
+will be parsed as markdown, so you can do things like:
+
+* Create bullet
+* Lists
+
+~~~ruby
+# Embed some code examples
+$dut.enter_ram_bist_mode
+~~~
+
+Or create [links](http://origen.freescale.net)
+
+~~~text
+# Some comments generated by the RAM BIST entry sequence
+~~~
+
+</div>
+</div>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+#### Summarizing Long Sections
+
+Sometimes it is not necessary to list out every comment or operation when documenting 
+a pattern. For example if the pattern downloads some functional code to be executing
+on the chip it is not really necessary to include the entire code download in the
+pattern document.
+
+For these scenarios a <code>snip</code> method is available which will output the
+given number of documentation lines and then enter a message to indicate that
+the remainder of the output has been snipped for efficiency.
+
+Here is an example of how to use it, here the comments generated by the contained
+section will be limited to 10 lines:
+
+~~~ruby
+  snip 10 do
+    # Download some verbose LRE code here
+  end
+~~~
+
+#### Pattern Headers
+
+When you generate a pattern, you'll notice the top section contains some useful information, such as the user that generated the pattern, a
+timestamp, the current environment, version of the application, the gems used, etc.  This section is called the <code>pattern header</code> and may look something
+like this:
+
+~~~
+// ***************************************************************************
+// GENERATED:
+//   Time:    24-Jun-2018 10:06AM
+//   By:      coreyeng
+//   Mode:    debug
+//   Command: origen g iterator_postfix_test_x_bx -t debug.rb
+// ***************************************************************************
+// ENVIRONMENT:
+//   Application
+//     Source:    git@github.com:Origen-SDK/origen.git
+//     Version:   0.33.1
+//     Branch:    fixes(c4e8e1d0db0) (+local edits)
+//   Origen
+//     Source:    https://github.com/Origen-SDK/origen
+//     Version:   0.33.1
+//   Plugins
+//     atp:                      1.1.0
+//     origen_core_support:      0.2.3
+//     origen_debuggers:         0.6.0
+//     origen_doc_helpers:       0.5.2
+//     origen_testers:           0.16.1
+//     origen_updater:           0.7.0
+// ***************************************************************************
+~~~
+
+The pattern header can also serve as place for the application, current plugin, or other shared plugins, to add specific comments that relate to
+how that pattern was generated or how it should be used.
+
+Three [configuration attributes](<%= path "guides/plugins/app/" %>)
+exist that will inject additional comments into the pattern header: <code>shared_pattern_header</code>, <code>application_pattern_header</code>,
+and <code>current_plugin_pattern_header</code>.
+
+These configuration attributes should be <code>blocks</code> that accept an <code>options hash</code> and return either a <code>String</code>,
+<code>Array of Strings</code>, or another <code>block</code>. <code>Strings</code> and <code>Arrays</code> will have the formatting handled
+for you, but <code>blocks</code> can handle the formatting themselves and can provide custom header comment formatting.
+
+Assume we have two plugins, <code>plugin1</code> and <code>plugin2</code> that are each needed to generate a pattern located in the
+application <code>my_app</code>. With <u>no plugin set</u> and with the configuration attributes set as follows:
+
+~~~ruby
+# plugin1/config/application.rb
+
+config.shared_pattern_header do
+  "Hi from shared #{Origen.app!.name}!"
+end
+
+config.current_plugin_pattern_header do
+  "Hi from current plugin: #{Origen.app!.name}!"
+end
+
+# plugin2/config/application.rb
+
+config.shared_pattern_header do
+  "Hi from shared #{Origen.app!.name}!"
+end
+
+config.current_plugin_pattern_header do
+  "Hi from current plugin: #{Origen.app!.name}!"
+end
+
+# my_app/config/application.rb
+
+config.shared_pattern_header do
+  "Hi from application #{Origen.app!.name}!"
+end
+~~~
+
+generating a pattern, will yield the following appended to the pattern header:
+
+~~~
+// ***************************************************************************
+// Header Comments From Shared Plugins:
+//   Header Comments From Shared Plugin: plugin1:
+//     Hi from shared plugin1!
+//   Header Comments From Shared Plugin: plugin2:
+//     Hi from shared plugin2!
+// ***************************************************************************
+// Header Comments From Application: my_app:
+//   Hi from application my_app!
+// ***************************************************************************
+~~~
+
+You'll notice here that there's no <code>current_plugin_pattern_header</code> printed. This will be printed when
+the current plugin is set to a plugin that has this configuration attribute. Setting the current plugin to
+<code>plugin1</code>, you'll now get both shared headers, the current plugin's header, and the application header:
+
+~~~
+// ***************************************************************************
+// Header Comments From Shared Plugins:
+//   Header Comments From Shared Plugin: plugin1:
+//     Hi from shared plugin1!
+//   Header Comments From Shared Plugin: plugin2:
+//     Hi from shared plugin2!
+// ***************************************************************************
+// Header Comments From The Current Plugin: plugin1:
+//   Hi from current plugin plugin1!
+// ***************************************************************************
+// Header Comments From Application: my_app:
+//   Hi from application my_app!
+// ***************************************************************************
+~~~
+
+As previously said, you can provide either a <code>block, proc, or lambda</code> (anything that responds to <code>call</code> will work) and use 
+<code>cc, ss, c2</code>, etc. to handle arbitrary headers or formatting. For example, changing <code>shared_pattern_header</code> in <code>plugin2</code>:
+
+~~~ruby
+# plugin2/config/application.rb
+
+config.shared_pattern_header do
+  proc do 
+    c2 "Hi from block in #{Origen.app!.name}"
+  end
+end
+~~~
+
+Will show the following in the pattern header:
+
+~~~
+// ***************************************************************************
+// Header Comments From Shared Plugins:
+//   Header Comments From Shared Plugin: plugin1:
+//     Hi from shared plugin1!
+//   Header Comments From Shared Plugin: plugin2:
+// Hi from block in plugin2!
+// ***************************************************************************
+// Header Comments From The Current Plugin: plugin1:
+//   Hi from current plugin plugin1!
+// ***************************************************************************
+// Header Comments From Application: my_app:
+//   Hi from application my_app!
+// ***************************************************************************
+~~~
+
+<div class ="alert alert-info" role="alert">
+  <strong>Info:</strong> Although the guides here show an <code>option hash</code>, there are currently no options <i>actually</i> being passed in, i.e., its just
+  an empty hash. This is only because this is a new feature, and by using an options hash here, future versions of Origen will be able to add any options that should
+  go to the pattern header without affecting the method prototype.
+</div>
+
+<div class="alert alert-warning" role="alert">
+  <strong>Deprecated:</strong> You may see <code>config.pattern_header</code> in some legacy applications. <code>config.pattern_header</code> is limited to only the
+  current plugin and must handle formatting itself. This is now deprecated but is left in for legacy purposes.
+</div>
+
+% end