origen_testers 0.19.0 → 0.19.2

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

@@ -0,0 +1,281 @@
+% render "layouts/guides.html" do
+
+A common workflow is to have a tester timing file defined and managed outside of Origen, in
+which case the main concern within your Origen source code is simply to refer to required
+timeset(s) by name.
+
+However, Origen does also support a more complex timing definition where waveforms
+can be defined and mastered in Origen source code. That is discussed later on in the 
+[Complex Timing](<%= path "guides/pattern/timing/#Complex_Timing" %>) section.
+
+
+### Simple Timing
+
+This guide gives an overview of some of the most common timing related
+methods, but to get a complete overview of what is available consult
+the [OrigenTesters::Timing API](http://origen-sdk.org/testers/api/OrigenTesters/Timing.html).
+
+A timeset declaration is used to provide information to Origen about what
+timeset to use for future test cycles and what period of time each
+cycle represents.
+
+Normally this would be initialized within the startup method before generating any
+vectors as shown below:
+
+~~~ruby
+class MySoCController
+  include Origen::Controller
+
+  def startup(options)
+    $tester.set_timeset("mode_entry", 40)
+  end
+end
+~~~
+
+The first argument is the name of the timeset, this should correspond to
+how the timeset will be named within the test program, and the second argument
+is the cycle period in nano-seconds.
+
+This method also accepts a block in which case the contained vectors will generate
+with the supplied timeset and subsequent vectors will return to the previous timeset
+automatically. 
+
+~~~ruby
+$tester.set_timeset("bist_50mhz", 20) do
+  # Any cycles generated in here will use 20ns for the period
+end
+~~~
+
+The arguments can also be supplied as a single array, or not at all. In the latter case
+the existing timeset will simply be preserved. This is useful if you have timesets that
+can be conditionally set based on the target.
+
+~~~ruby
+# Target 1
+$dut.readout_timeset = ["readout", 120]
+# Target 2
+$dut.readout_timeset = false
+
+# This code is compatible with both targets, in the first case the timeset will switch
+# over, in the second case the existing timeset will be preserved.
+$tester.set_timeset($dut.readout_timeset) do
+  # Generate readout vectors...
+end
+~~~
+
+#### Creating a Timing Set
+
+Currently the creation of the timing set for a given test platform must be
+done independently of Origen, however adding an Origen API for this is on the roadmap.
+
+#### Waiting
+
+All $tester models will support the following API to generate wait states
+in the test patterns.
+
+Wait for specific number of cycles:
+
+~~~ruby
+$tester.wait(cycles: 1000)
+~~~
+
+Wait for a period of time:
+
+~~~ruby
+$tester.wait(time_in_us: 500)
+$tester.wait(time_in_ms: 10)
+~~~
+
+A shorthand for the above cases is available:
+
+~~~ruby
+500.us!  # Wait for 500us
+10.ms!   # Wait for 10ms
+~~~
+
+Multiple times specified in different units will be added together, this can be useful
+if the delay is based on a complex calculation:
+
+~~~ruby
+# Wait for 500us + 100 cycles
+$tester.wait(time_in_us: 500, cycles: 100)
+~~~
+
+#### Waiting for an Event
+
+All testers provide an API for generating match loops, these can be used to
+make the pattern wait dynamically for a pin-based or even a register-based
+event.
+
+To do this enable the <code>:match</code> option and supply a block, within the block
+generate the vectors that will test if the condition has been met.
+Any time options passed in will be applied as a timeout, i.e. the maximum time to
+wait for the required condition to resolve.
+
+Here are some examples:
+
+~~~ruby
+# Wait for up to 1 second for the done bit to be set
+$tester.wait(match: true, time_in_s: 1) do
+  reg(:status_reg).bit(:done).read!(1)
+end
+
+# Wait for up to 1 second for the done pin to be set
+$tester.wait(match: true, time_in_s: 1) do
+  pin(:done).assert!(1)
+end
+~~~
+
+### Complex Timing
+
+#### Defining Timesets
+
+A wave object defines the waveform that should be applied to a pin, and each pin will
+have two wave objects assigned to it - one for drive cycles and one for cycles where the
+pin is being read/compared.
+
+A timeset object is used to collect the wave objects for all pins. Multiple timesets can
+be defined and therefore the waveforms being applied to the pins can be changed by changing
+the timeset.
+The API to change the timeset is the same as that already discussed above:
+
+~~~ruby
+tester.set_timeset('func', 100)
+~~~
+
+The period of the timeset can be referenced in the wave definitions to make the waveforms
+keep the same shape with different period settings.
+
+Here is the most basic timeset definition, this will give all pins a default waveform which
+drives for the whole period on drive cycles, and strobes at 50% of compare cycles:
+
+~~~ruby
+# Simple definition, all pins have default waves
+add_timeset :t1
+~~~
+
+Here is a more complex definition, which changes the default compare for all pins to be at
+25% of the period, and which adds a unique drive wave to the :tck pin to create a clock:
+
+~~~ruby
+# Complex definition, defines an alternative default compare wave and specific timing for :tck
+timeset :func do |t|
+  t.compare_wave do |w|
+    w.compare :data, at: "period / 4"
+  end
+
+  t.drive_wave :tck do |w|
+     w.drive :data, at: 0
+     w.drive 0, at: 25
+     w.dont_care at: "period - 10"  # Just to show that dont_care can be used
+  end
+end
+~~~
+
+Pin groups can also be referenced in the timeset definition, here to add common drive timing
+to all pins in :gpio, and with a special compare waveform for :gpio5 only:
+
+~~~ruby
+# Another timeset to show the wave assignment to pin groups
+timeset :t2 do |t|
+  t.compare_wave :gpio5 do |w|
+    w.compare :data, at: 100
+  end
+
+  t.drive_wave :gpio do |w|
+    w.drive :data, at: 200
+  end
+end
+~~~
+
+Note that the API currently only supports edge compares, i.e. window compares cannot be defined.
+
+Additional drive and compare waves can be defined for any pin by giving them a code which can
+be used to select the given waveform in a pattern - i.e. [the approach used by the 
+V93K tester to select from multiple available waveforms.](<%= path "guides/pattern/v93k" %>)
+
+Here is an example with a single pulse waveform defined for a clk pin which will be applied
+when the pin is driven to <code>1</code>, and a double pulse waveform that will be applied when the pin
+is drive to <code>T</code>:
+
+~~~ruby
+timeset :func do |t|
+  t.drive_wave :tck do |w|
+    w.drive 1, at: 0
+    w.drive 0, at: 20
+  end
+
+  t.drive_wave :tck, code: 'T' do |w|
+    w.drive 1, at: 0
+    w.drive 0, at: 10
+    w.drive 1, at: 20
+    w.drive 0, at: 30
+  end
+end
+~~~
+
+#### Consuming Timeset Data
+
+The currently selected timeset can be retrieved via the following methods which are aliases:
+
+~~~ruby
+dut.timeset               # => instance of Origen::Pins::Timing::Timeset
+dut.current_timeset
+~~~
+
+Using the plural returns a hash containing all timesets, thereby allowing access to specific timesets
+regardless of the current selection:
+
+~~~ruby
+dut.timesets          # => Hash
+dut.timesets[:func]   # => instance of Origen::Pins::Timing::Timeset
+# This will also work:
+dut.timeset(:func)   
+~~~
+
+Each timeset stores the waves in two arrays, one for drive waves and another for the compare waves:
+
+~~~ruby
+dut.timeset(:func).drive_waves    # => Array containing instances of Origen::Pins::Timing::Wave
+dut.timeset(:func).compare_waves
+~~~
+
+Each wave object has an events array, and the pins assigned to it can also be retrieved:
+
+~~~ruby
+drive_wave = dut.timeset(:func).drive_waves.first
+compare_wave = dut.timeset(:func).compare_waves.first
+
+drive_wave.events    # => [[0, :data], [50, 0], [75, :x]]
+drive_wave.pins      # => Array of Origen::Pins::Pin instances
+
+compare_wave.events  # => [["period / 2", :data]]
+~~~
+
+The method evaluated_events can be used to get the events with the formulas evaluated based on the
+current period:
+
+~~~ruby
+compare_wave.events            # => [["period / 2", :data]]
+compare_wave.evaluated_events  # => [[50, :data]]
+~~~
+
+The waves assigned to a given pin by the current timeset can also be accessed via the pin API:
+
+~~~ruby
+dut.pin(:tms).compare_wave.events[0]   # => ["period / 2", :data]
+~~~
+
+The waveform associated with a particular code can be accessed as follows:
+
+~~~ruby
+# The wave for driving 0 and 1 is returned by default, these are all aliases:
+dut.pin(:clk).drive_wave.events       # => [[0, 1], [20, 0]]
+dut.pin(:clk).drive_wave(0).events    # => [[0, 1], [20, 0]]
+dut.pin(:clk).drive_wave(1).events    # => [[0, 1], [20, 0]]
+
+dut.pin(:clk).drive_wave('T').events  # => [[0, 1], [10, 0], [20, 1], [30, 0]]
+~~~
+
+
+% end

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

@@ -0,0 +1,10 @@
+% render "layouts/guides.html" do
+
+This page will be used to document any UltraFLEX-only APIs related to pattern generation,
+however the goal is to have as few of these as possible so that Origen pattern source code can re-target
+automatically to any supported platform.
+
+There are no significant APIs in this category currently, therefore refer to the
+[Common Pattern API](<%= path "guides/pattern/common" %>) which can fully target the UltraFLEX.
+
+% end

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

@@ -0,0 +1,41 @@
+% render "layouts/guides.html" do
+
+All of the
+[Common Pattern API](<%= path "guides/pattern/common" %>) can be used to target the V93K.
+
+This page is used to document any additional V93K-specific APIs related to pattern generation,
+however the goal is to have as few of these as possible so that Origen pattern source code can re-target
+automatically to any supported platform.
+
+
+#### Driving Custom Waveforms
+
+The V93K has a very powerful waveform generator and it is common to use many more pin state codes than
+other platforms in order to select particular waveforms.
+
+Say for example that we have various waveforms defined to drive a clock pin, where a '1' on the pin
+will drive a single pulse and a code of 'P' will select a different waveform which will create 4 pulses
+per cycle.
+
+The 'P' code (or any other letter) can be driven very easily as shown below:
+
+~~~ruby
+                        #      Example vectors
+pin(:clk).drive!(1)     #     1 X XXXX 10100001
+1.cycle                 #     1 X XXXX 10100001
+pin(:clk).drive!('P')   #     P X XXXX 10100001
+1.cycle                 #     P X XXXX 10100001
+pin(:clk).drive!(1)     #     1 X XXXX 10100001
+~~~
+
+The above vectors would produce the following waveform per the earlier description of 'P':
+
+~~~text
+            _______         _______   _   _   _   _   _   _   _   _         _______
+clk _______|       |_______|       |_| |_| |_| |_| |_| |_| |_| |_| |_______|       |
+
+~~~
+
+
+
+% end

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

@@ -0,0 +1,78 @@
+% render "layouts/guides.html" do
+
+A big advantage that the Origen program generator has over other
+tools is that even if you need to generate a test program file that is not
+officially supported by the generator you can easily work around it 
+by dropping down to a template for that specific section of the program.
+
+A nice offshoot of this capability is that any custom code in your
+test program (such as custom Visual Basic or C++ code for example) can be
+dynamically generated via code templates.
+
+#### A Dynamic VB Example
+
+Generally using templates within the context of a test program is the same
+as using them in any other context and therefore the
+[Compiler Guide](<%= path "guides/compiler/introduction" %>) should be consulted
+for more details on the compiler syntax that should be used.
+
+For a tester oriented example here is a snippet of some VB code that has been
+marked up with Origen compiler directives:
+
+~~~eruby
+NUM_VREGS = <%= "<" + "%= $dut.vregs.size %" + ">" %>
+
+' Now initialize DUT variables for each site
+For lSite = 0 To lSiteCnt
+  With oDUTData(lSite)
+    Call .Clear
+<%= "%" %> $dut.vregs.each do |vreg|
+    Call .AddVreg(<%= "<" + "%= vreg.nominal_level %" + ">" %>)
+<%= "%" %> end
+  End With
+Next
+~~~  
+
+So for a device with a 1.2V and a 3V regulator this would compile to:
+
+~~~text
+NUM_VREGS = 2
+
+' Now initialize DUT variables for each site
+For lSite = 0 To lSiteCnt
+  With oDUTData(lSite)
+    Call .Clear
+    Call .AddVreg(1.2)
+    Call .AddVreg(3)
+  End With
+Next
+~~~  
+
+Whereas for a device with only a single 1.2V regulator we would end up with:
+
+~~~text
+NUM_VREGS = 1
+
+' Now initialize DUT variables for each site
+For lSite = 0 To lSiteCnt
+  With oDUTData(lSite)
+    Call .Clear
+    Call .AddVreg(1.2)
+  End With
+Next
+~~~  
+
+#### Building Dynamic Code
+
+Compiling any templates that form part of your test program can be co-ordinated
+within a Resources file by calling the <code>compile</code> method.
+Any option arguments passed in will be available within the <code>options</code>
+hash within the template.
+
+~~~ruby
+Resources.create do
+  compile "templates/j750/vreg_funcs.bas", max_vdd: 5.V
+end
+~~~
+
+% end

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

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

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

@@ -0,0 +1,402 @@
+% render "layouts/guides.html" do
+
+Origen allows test descriptions to be entered quickly and easily within the
+test flow source file, enabling a test program document to be produced that is extremely
+accurate due to it being derived from the same source as the program itself.
+
+The application must also define a documentation interface in order to do the translation
+between the application-specific flow API and the Origen test program documentation back end -
+this is the exact same principle as generating an interface for a specific ATE platform.
+
+Typically creating a documentation interface is much easier than creating an ATE platform
+interface and is discussed
+[later in this guide](<%= path "guides/program/doc/#Creating_A_Documentation_Interface" %>).
+Note that if you don't initially have time to set up the documentation interface you should still
+try and document the program as described here since the code it produces will still be
+compatible with any tester interface. Then when time allows you can setup the documentation
+interface with the hard part of actually describing the tests already done.
+
+The [Documentation Helpers](http://origen-sdk.org/doc_helpers) plugin provides off
+the shelf [test flow helpers](http://origen-sdk.org/doc_helpers/examples/test/flow)
+to render such documentation metadata as a well formatted web document.
+
+#### Flow Markup
+
+Flow sections and individual tests should be documented like this:
+
+~~~ruby
+# A Test Sub Module
+# Test flow modules like this will collapse and nest when they are included in a parent
+# flow via the import command. The first line will be the name assigned to the collapsible
+# area, the rest of these comments will be shown when it expands. **It will be parsed for
+# markdown.**
+Flow.create do
+  # Any comments in here will attach as a description to the next test
+  func :measure_vreg, bin: 45, vdd: min
+
+  # This is a description of what this test does
+  #- Prefixing the line with a '-' will cause it to be private, so this is how you would
+  #- record some implementation detail that is of interest to engineers working on this
+  #- flow, but which is not relevant to its overall operation
+  func :vreg_func1, bin: 50
+
+  # All comments can contain markdown, for example
+  #
+  # * A bulleted
+  # * list
+  func :vreg_func2, bin: 55, iload: 50.uA
+end
+~~~
+
+When generated against an appropriate documentation interface and passed to the
+[Documentation Helpers](http://origen-sdk.org/doc_helpers) plugin, this would generate a
+flow section like this (click to expand):
+
+<div class="panel-group" id="test_flow1">
+
+  <div class="panel panel-default">
+    <a href="#_" class="expandcollapse btn btn-mini pull-right" state="0"><i class="icon-plus-sign"></i></a>
+    <div class="panel-heading clickable" style="background:whitesmoke" data-toggle="collapse" data-parent="#blah2" href="#collapseAccordion3">
+      <a class="no-underline">
+        A Test Sub Module
+      </a>
+    </div>
+    <div id="collapseAccordion3" class="panel-collapse collapse">
+      <div class="panel-body">
+        <p>
+          Test flow modules like this will collapse and nest when they are included in a parent
+          flow via the import command. The first line will be the name assigned to the collapsible
+          area, the rest of these comments will be shown when it expands. <strong>It will be parsed for
+          markdown.</strong>
+        </p>
+
+        <table class="table table-condensed table-bordered flow-table">
+          <thead><tr>
+          <th class="col1">Test</th>
+          <th class="col2">Number</th>
+          <th class="col3">HBin</th>
+          <th class="col3">SBin</th>
+          <th class="col5">Attributes</th>
+          <th class="col6">Description</th>
+          </tr></thead>
+          <tbody>
+            <tr>
+              <td class="col1">
+                <div>measure_vreg</div>  
+              </td>
+              <td class="col2">#45000</td>
+              <td class="col3">B45</td>
+              <td class="col4"></td>
+              <td class="col5 attributes">
+                <ul>
+                  <li><strong>Vdd</strong>: min</li>
+                </ul>
+              </td>
+              <td class="col6">
+                <p>Any comments in here will attach as a description to the next test</p>
+              </td>
+            </tr>
+
+            <tr>
+              <td class="col1">
+                <div>vreg_func1</div>  
+              </td>
+              <td class="col2">#50000</td>
+              <td class="col3">B50</td>
+              <td class="col4"></td>
+              <td class="col5 attributes">
+                <ul>
+                </ul>
+              </td>
+              <td class="col6">
+                <p>This is a description of what this test does</p>
+              </td>
+            </tr>
+
+            <tr>
+              <td class="col1">
+                <div>vreg_func2</div>  
+              </td>
+              <td class="col2">#55000</td>
+              <td class="col3">B55</td>
+              <td class="col4"></td>
+              <td class="col5 attributes">
+                <ul>
+                  <li><strong>iload</strong>: 50E-06</li>
+                </ul>
+              </td>
+              <td class="col6">
+                <p>All comments can contain markdown, for example</p>
+                <ul>
+                  <li>A bulleted</li>
+                  <li>list</li>
+                </ul>
+              </td>
+            </tr>
+          </tbody>  
+        </table>
+      </div>
+    </div>
+  </div>
+</div>
+
+
+#### Documenting Structure
+
+Tests can be grouped together by wrapping them with the <code>pp</code> helper, here are
+the two functional tests grouped together with some description added about what the
+group contains:
+
+~~~ruby
+# A Test Sub Module
+# Test flow modules like this will collapse and nest when they are included in a parent
+# flow via the import command. The first line will be the name assigned to the collapsible
+# area, the rest of these comments will be shown when it expands. **It will be parsed for
+# markdown.**
+Flow.create do
+  # Any comments in here will attach as a description to the next test
+  func :measure_vreg, bin: 45, vdd: min
+
+  # Within flow sections should be marked like this (this is the same API to indicate
+  # structure in pattern logic to). This text will appear when the collapsible area is
+  # shown and will be parsed for markdown.
+  pp "Functional Tests" do
+    # This is a description of what this test does
+    #- Prefixing the line with a '-' will cause it to be private, so this is how you would
+    #- record some implementation detail that is of interest to engineers working on this
+    #- flow, but which is not relevant to its overall operation
+    func :vreg_func1, bin: 50
+
+    # All comments can contain markdown, for example
+    #
+    # * A bulleted
+    # * list
+    func :vreg_func2, bin: 55, iload: 50.uA
+  end
+end
+~~~
+
+The functional tests will now be nested in a collapsible group:
+
+<div class="panel-group" id="test_flow2">
+
+  <div class="panel panel-default">
+    <a href="#_" class="expandcollapse btn btn-mini pull-right" state="0"><i class="icon-plus-sign"></i></a>
+    <div class="panel-heading clickable" style="background:whitesmoke" data-toggle="collapse" data-parent="#blah2" href="#collapseAccordion4">
+      <a class="no-underline">
+        A Test Sub Module
+      </a>
+    </div>
+    <div id="collapseAccordion4" class="panel-collapse collapse">
+      <div class="panel-body">
+        <p>
+          Test flow modules like this will collapse and nest when they are included in a parent
+          flow via the import command. The first line will be the name assigned to the collapsible
+          area, the rest of these comments will be shown when it expands. <strong>It will be parsed for
+          markdown.</strong>
+        </p>
+
+        <table class="table table-condensed table-bordered flow-table">
+          <thead><tr>
+          <th class="col1">Test</th>
+          <th class="col2">Number</th>
+          <th class="col3">HBin</th>
+          <th class="col3">SBin</th>
+          <th class="col5">Attributes</th>
+          <th class="col6">Description</th>
+          </tr></thead>
+          <tbody>
+            <tr>
+              <td class="col1">
+                <div>measure_vreg</div>  
+              </td>
+              <td class="col2">#45000</td>
+              <td class="col3">B45</td>
+              <td class="col4"></td>
+              <td class="col5 attributes">
+                <ul>
+                  <li><strong>Vdd</strong>: min</li>
+                </ul>
+              </td>
+              <td class="col6">
+                <p>Any comments in here will attach as a description to the next test</p>
+              </td>
+            </tr>
+          </tbody>  
+        </table>
+
+        <div class="panel panel-default">
+          <a href="#_" class="expandcollapse btn btn-mini pull-right" state="0"><i class="icon-plus-sign"></i></a>
+          <div class="panel-heading clickable" style="background:whitesmoke" data-toggle="collapse" data-parent="#blah2" href="#collapseAccordion5">
+            <a class="no-underscore">
+              Functional Tests
+            </a>
+          </div>
+          
+          <div id="collapseAccordion5" class="panel-collapse collapse">
+            <div class="panel-body">
+              <p>
+                Within flow sections should be marked like this (this is the same API to indicate
+                structure in pattern logic to). This text will appear when the collapsible area is
+                shown and will be parsed for markdown.
+              </p>  
+
+              <table class="table table-condensed table-bordered flow-table">
+                <thead><tr>
+                <th class="col1">Test</th>
+                <th class="col2">Number</th>
+                <th class="col3">HBin</th>
+                <th class="col3">SBin</th>
+                <th class="col5">Attributes</th>
+                <th class="col6">Description</th>
+                </tr></thead>
+                <tbody>
+                  <tr>
+                    <td class="col1">
+                      <div>vreg_func1</div>  
+                    </td>
+                    <td class="col2">#50000</td>
+                    <td class="col3">B50</td>
+                    <td class="col4"></td>
+                    <td class="col5 attributes">
+                      <ul>
+                      </ul>
+                    </td>
+                    <td class="col6">
+                      <p>This is a description of what this test does</p>
+                    </td>
+                  </tr>
+
+                  <tr>
+                    <td class="col1">
+                      <div>vreg_func2</div>  
+                    </td>
+                    <td class="col2">#55000</td>
+                    <td class="col3">B55</td>
+                    <td class="col4"></td>
+                    <td class="col5 attributes">
+                      <ul>
+                        <li><strong>iload</strong>: 50E-06</li>
+                      </ul>
+                    </td>
+                    <td class="col6">
+                      <p>All comments can contain markdown, for example</p>
+                      <ul>
+                        <li>A bulleted</li>
+                        <li>list</li>
+                      </ul>
+                    </td>
+                  </tr>
+                </tbody>  
+              </table>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+
+#### Dynamic Documentation From Helpers
+
+Helper methods can be added to your interface to generate multiple tests or to otherwise dynamically generate a
+section of the flow.
+
+Within these methods the <code>cc</code> method can be used to stage comments that will be attached to
+the next test to be generated:
+
+~~~ruby
+def program_sequence
+  cc "Issue a pulse"
+  func :program_20us
+  cc "Do a verify"
+  func :read_margin0
+end
+~~~
+
+#### Creating A Documentation Interface
+
+A documentation interface can be thought of as an interface for a really simple tester which only has the
+concept of a flow and a collection of tests.
+
+Here is the basic starting point for any documentation interface:
+
+~~~ruby
+class DocInterface
+  include OrigenTesters::Doc::Generator
+
+  # Add a test to the collection
+  def add_test(name, options)
+    tests.add(name, options)
+  end
+
+  # Add a flow entry
+  def add_flow_entry(test, options)
+    flow.test(test, options)
+  end
+end
+~~~
+
+As with any interface it is then required to create methods to translate your domain specific
+flow API into calls to these two key methods to add a test and a flow entry.
+
+Our example flow here has a <code>func</code> method, we might implement the handler for that like this:
+
+~~~ruby
+def func(name, options={})
+  add_test(name, options)
+  add_flow_entry(name, options)
+end
+~~~
+
+Over and above that what happens next is very domain specific and depends if any processing
+or sanitizing of the options or names are required to produce an accurate document.
+Some domain specific examples from the simple flow in this guide would be:
+
+By default any options passed to the <code>add_test</code> method will be rendered into the
+attributes column. In our case we are supplying the bin as a flow line option and that will
+already be displayed in the dedicated column when it is passed to the flow entry. To inhibit
+the bin appearing in the test attributes we can screen the options like this:
+
+~~~ruby
+# Add a test to the collection
+def add_test(name, options)
+  # Delete any keys that we don't want to assign to the instance, this keeps
+  # the attributes column clean, flow control keys will be screened by Origen automatically
+  [:bin, :some, :other, :keys,
+  ].each { |k| options.delete(k) }
+  tests.add(name, options)
+end
+~~~
+
+As noted in the above comment any keys related to [flow control](<%= path "guides/program/flowapi" %>)
+will be automatically screened and handled by Origen (doc helpers knows how to display this
+information to).
+
+Another convention from the above example was that we did not supply a test number and it was
+automatically set to a multiple of the bin number,
+we can handle that like this:
+
+~~~ruby
+# Add a flow entry
+def add_flow_entry(test, options)
+  options = sanitize_flow_options(options)
+  flow.test(test, options)
+end
+
+def sanitize_flow_options(options)
+  # If the number has not been set in the flow then set it to a multiple of the bin, if present
+  options[:number] ||= options[:bin] ? options[:bin] * 1000 : nil
+  options
+end
+~~~
+
+Note that many of the methods involved in processing the test options such as the
+<code>sanitize_flow_options</code> method here would be common to all
+interfaces and therefore should not need special handling specifically for documentation.
+Rather you
+should create a common module that gets included into all interfaces to handle the non-tester-platform
+specific concerns like these.
+
+% end