origen_testers 0.41.0 → 0.42.0

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

@@ -0,0 +1,291 @@
+% render "layouts/guides.html" do
+
+% testers_api_url = 'https://origen-sdk.org/testers/api/OrigenTesters'
+
+<table>
+  <!-- Headers -->
+  <tr>
+    <th>Platform</th>
+    <th>File Extension(s)</th>
+    <th>Decompiled Pattern Class</th>
+    <th>Module Name</th>
+    <th>Vector Body Elements</th>
+    <th>Vector Platform Nodes</th>
+    <th>Additional Information</th>
+  </tr>
+  <!-- J750 -->
+  <tr>
+    <td>J750</td>
+    <td><code>.atp</code></td>
+    <td><code>OrigenTesters::IGXLBasedTester::Pattern</code></td>
+    <td><code>OrigenTesters::IGXLBasedTester</code></td>
+    <td><code>:start_label</code>, <code>:global_label</code>, <code>:vector</code>, <code>:label</code></td>
+    <td><code>opcode</code>, <code>opcode_arguments</code></td>
+    <td><a href='#Teradyne_J750_and_Ultraflex'>J750 & Ultraflex</a></td>
+  </tr>
+  <!-- Uflex -->
+  <tr>
+    <td>Ultraflex</td>
+    <td><code>.atp</code></td>
+    <td><code>OrigenTesters::IGXLBasedTester::Pattern</code></td>
+    <td><code>OrigenTesters::IGXLBasedTester</code></td>
+    <td><code>:start_label</code>, <code>:global_label</code>, <code>:vector</code>, <code>:label</code></td>
+    <td><code>opcode</code>, <code>opcode_arguments</code></td>
+    <td><a href='#Teradyne_J750_and_Ultraflex'>J750 & Ultraflex</a></td>
+  </tr>
+  <!-- V93K -->
+  <tr>
+    <td>V93K</td>
+    <td><code>.avc</code></td>
+    <td><code>OrigenTesters::SmartestBasedTester::Pattern</code></td>
+    <td><code>OrigenTesters::SmartestBasedTester</code></td>
+    <td><code>:sequencer_instruction</code>, <code>:vector</code></td>
+    <td><b>N/A</b></td>
+    <td><a href='#Advantest_V93K'>V93K</a></td>
+  </tr>
+</table>
+
+### Teradyne J750 and Ultraflex
+
+Both supported Teradyne platforms share the same decompiler. It's assumed, at
+this early stage, that the differences in decompiling are negligible, but
+future enhancements will most likely split the two at some point.
+
+Although all opcodes and arguments, including match loops, should decompile
+correctly, they are not yet supported for execution and are simply ignored. In fact,
+all opcodes (except `repeat`) are ignored, __including__ `end_module`.
+
+#### Platform Nodes
+
+##### Frontmatter
+
+<table>
+  <tr>
+    <th>Platform Node</th>
+    <th>Description</th>
+    <th>Return Class</th>
+    <th>Default Value</th>
+    <th>Example Output</th>
+    <th>Additional Information</th>
+  </tr>
+  <tr>
+    <td><code>variable_assignments</code></td>
+    <td>Any global variable assignments or settings</td>
+    <td><code>Hash</code></td>
+    <td><code>{}</code></td>
+    <td><code>{'opcode_mode' => 'extended'}</code></td>
+    <td><b>N/A</b></td>
+  </tr>
+  <tr>
+    <td><code>imports</code></td>
+    <td>Imported attributes, e.g., <code>timesets</code></td>
+    <td><code>Hash</code></td>
+    <td><code>{}</code></td>
+    <td><code>{'tp0' => 'tset'}</code></td>
+    <td>
+      In the source, the imports are written as <i>type of import</i> then <i>name of import.</i>
+      In the retuned Hash, the keys are the <i>name of the imports</i> and the values are the <i>import types</i>.
+    </td>
+  </tr>
+</table>
+
+##### Vector
+
+<table>
+  <tr>
+    <th>Platform Node</th>
+    <th>Description</th>
+    <th>Return Class</th>
+    <th>Default Value</th>
+    <th>Example Output</th>
+    <th>Additional Information</th>
+  </tr>
+  <tr>
+    <td><code>opcode</code></td>
+    <td>The opcode, if present in the vector.</td>
+    <td><code>String</code>, <code>NilClass</code></td>
+    <td><code>nil</code></td>
+    <td><code>"repeat"</code></td>
+    <td><b>N/A</b></td>
+  </tr>
+  <tr>
+    <td><code>opcode_arguments</code></td>
+    <td>Any comman-separated, opcode arguments, if present.</td>
+    <td><code>Array</code></td>
+    <td><code>[]</code></td>
+    <td><code>['5']</code></td>
+    <td><b>N/A</b></td>
+  </tr>
+</table>
+
+Note that `repeat` is actually an `opcode` for this platform. Many, many vectors
+will have `opcode` and `opcode_arguments` that simply duplicate the generic `repeat`
+accessor.
+
+#### Vector Body Elements
+
+<table>
+  <tr>
+    <th>Vector Body Element</th>
+    <th>Description</th>
+    <th>Type</th>
+    <th>Platform Nodes</th>
+    <th>Additional Information</th>
+  </tr>
+  <tr>
+    <td>Start Label</td>
+    <td>Label that signifies the start of the vector body. Required by <code>.atp</code> sources.</td>
+    <td><code>:start_label</code></td>
+    <td>
+      <table>
+        <tr>
+          <th>Platform Node</th>
+          <th>Description</th>
+          <th>Return Class</th>
+          <th>Default Value</th>
+          <th>Example Output</th>
+          <th>Additional Information</th>
+        </tr>
+        <tr>
+          <td><code>start_label</code></td>
+          <td>Name of the pattern's start label</td>
+          <td><code>String</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>"pattern_st"</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+      </table>
+    </td>
+    <td><b>N/A</b></td>
+  </tr>
+  <tr>
+    <td>Global Label</td>
+    <td>Defines a global label.</td>
+    <td><code>:global_label</code></td>
+    <td>
+      <table>
+        <tr>
+          <th>Platform Node</th>
+          <th>Description</th>
+          <th>Return Class</th>
+          <th>Default Value</th>
+          <th>Example Output</th>
+          <th>Additional Information</th>
+        </tr>
+        <tr>
+          <td><code>label_type</code></td>
+          <td>Type, or function, of the label.</td>
+          <td><code>String</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>"subr"</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+        <tr>
+          <td><code>label_name</code></td>
+          <td>Name of the label.</td>
+          <td><code>String</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>"global_label_1"</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+      </table>
+    </td>
+    <td><b>N/A</b></td>
+  </tr>
+  <tr>
+    <td>Label</td>
+    <td>Defines a label internal to the current pattern.</td>
+    <td><code>:label</code></td>
+    <td>
+      <table>
+        <tr>
+          <th>Platform Node</th>
+          <th>Description</th>
+          <th>Return Class</th>
+          <th>Default Value</th>
+          <th>Example Output</th>
+          <th>Additional Information</th>
+        </tr>
+        <tr>
+          <td><code>label_name</code></td>
+          <td>Name of the label</td>
+          <td><code>String</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>"label1"</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+      </table>
+    </td>
+    <td><b>N/A</b></td>
+  </tr>
+</table>
+
+### Advantest V93K
+
+Similarly to the Teradyne platforms, sequencer instructions, other than `repeat`,
+are not supported and are ignored.
+
+#### Platform Nodes
+
+This decompiler does not provide any `platform nodes`.
+
+#### Vector Body Elements
+<table>
+  <tr>
+    <th>Vector Body Element</th>
+    <th>Description</th>
+    <th>Type</th>
+    <th>Platform Nodes</th>
+    <th>Additional Information</th>
+  </tr>
+  <tr>
+    <td>Sequencer Instruction</td>
+    <td>Inter-pattern call to the V93K sequencer.</td>
+    <td><code>:sequencer_instruction</code></td>
+    <td>
+      <table>
+        <tr>
+          <th>Platform Node</th>
+          <th>Description</th>
+          <th>Return Class</th>
+          <th>Default Value</th>
+          <th>Example Output</th>
+          <th>Additional Information</th>
+        </tr>
+        <tr>
+          <td><code>instruction</code></td>
+          <td>Instruction code</td>
+          <td><code>String</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>"MACT"</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+        <tr>
+          <td><code>arguments</code></td>
+          <td>Arguments for the instruction.</td>
+          <td><code>Array</code>, <code>NilClass</code></td>
+          <td><code>nil</code></td>
+          <td><code>['1737']</code></td>
+          <td><b>N/A</b></td>
+        </tr>
+      </table>
+    </td>
+    <td><b>N/A</b></td>
+  </tr>
+</table>
+
+#### No First Vector
+
+The V93K supports patterns of just _sequencer instructions_ (see the approved
+`simple.avc` pattern), which __does not__ contain a `first_vector`. In such
+cases, calls to many of the methods will raise an exception. For example,
+calls to `#add_pins`, `#execute`, and anything on the `Pinlist` will fail. As
+only vector support is available at the moment, there is not much that can
+be done with these types of pattern anyway.
+
+That said, these patterns can still be decompiled, with full
+[EnumerableExt](<%= path "guides/decompilation/universalapi#EnumerableExt" %>)
+functionality. Any custom execution or conversion implementations, or custom
+processing methods, can still be used.
+
+% end

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

@@ -0,0 +1,598 @@
+% 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.
+% Origen.load_target('configurable', dut: OrigenDecompilerDocDut)
+% pat = OrigenTesters::IGXLBasedTester::Pattern.new(OrigenTesters::IGXLBasedTester.sample_source_atp)
+% direct_pat = OrigenTesters::IGXLBasedTester::Pattern.new(OrigenTesters::IGXLBasedTester.sample_direct_source, direct_source: true)
+% testers_api_url = 'https://origen-sdk.org/testers/api/OrigenTesters'
+
+The `Universal API` attempts to tie all supported platforms together and provide
+a generic yet flexible interface with which decompiled patterns from any source
+or any platform can be treated the same.
+
+This obvisously has its limitations and various hooks are in place to still allow
+for platform-specifics to peek through the `universal API` but the API detailed
+in this section should be applicable across all supported platforms.
+
+The [OrigenTesters::Decompiler::Pattern](<%= "#{testers_api_url}//Decompiler/Pattern.html" %>)
+base class provides this interface. All supported platforms should return
+a class which inherits from this. For example,
+
+~~~ruby
+OrigenTesters::IGXLBasedTester::Pattern.ancestors.include?(OrigenTesters::Decompiler::Pattern)
+  #=> <%= OrigenTesters::IGXLBasedTester::Pattern.ancestors.include?(OrigenTesters::Decompiler::Pattern) %>
+~~~
+
+### Decompiling
+
+The preferred method to decompile a pattern source is to use the 
+[Decompiler API](<%= path "guides/decompilation/decompilerapi/#Decompiling" %>)
+but you can choose to instantiate the decompiler yourself, provided you know the
+decompiler you want to use.
+
+To decompile a source from the `J750`, we'll instantiate a new
+`OrigenTesters::IGXLBasedTester::Pattern` class:
+
+~~~ruby
+pat = OrigenTesters::IGXLBasedTester::Pattern.new('path/to/src.atp')
+~~~
+
+Instantiating the decompiler __does not__ automatically decompile it. However,
+a call to `#decompile` will do just that.
+
+~~~ruby
+pat.decompiled?
+  #=> <%= pat.decompiled? %>
+
+pat.decompile
+pat.decompiled?
+% pat.decompile
+  #=> <%= pat.decompiled? %>
+~~~
+
+<div class="alert alert-success" role="alert">
+Recall that <code>#decompile</code> on the 
+<a href='<%= path "guides/decompilation/decompilerapi/#Decompiling" %>'>Decompiler API</a> does this automatically.
+</div>
+
+Any decompiler will accept the pattern source as either:
+
+1. A `string` containing the filename of the pattern source.
+2. A `Pathname` containing the filename of the pattern source.
+
+At times, [such as in the example](<%= path "guides/decompilation/overview#Example_Decompilation" %>),
+you'll want to decompile a text source directly. Indicate this by providing
+the `direct_source: true` option during instantiation:
+
+~~~ruby
+direct_pat = OrigenTesters::IGXLBasedTester::Pattern.new('path/to/src.atp', direct_source: true)
+~~~
+
+The decompiled pattern will keep track of its source and whether it was direct
+or not:
+
+~~~ruby
+pat.direct_source?
+  #=> <%= pat.direct_source? %>
+pat.source
+  #=> /home/origen_stuff/origen_testers/approved/j750/decompiler/sample/sample.atp
+
+direct_pat.direct_source?
+  #=> <%= direct_pat.direct_source? %>
+direct_pat.source
+  #=>
+"<%= direct_pat.source %>"
+~~~
+
+<div class="alert alert-warning" role="alert">
+The entire direct source is stored in the decompiler as the <code>source</code>,
+so its not recommended to use direct sources for large patterns.
+</div>
+
+<div class="alert alert-info" role="alert">
+Although it is <i>possible</i> to instantiate a <code>OrigenTesters::Decompiler::Pattern</code>
+object yourself, this is just the base class and has no grammars. Any attempts
+to actually work with this class directly will not end well.
+
+<a href='<%= path "guides/decompilation/platformspecifics" %>'>See the supported platforms page</a>
+for the class names of the actual decompiler implementations.
+</div>
+
+### Adding Pins and Executing
+
+Both of these have been covered [in the example](<%= path "guides/decompilation/overview#Example_Decompilation" %>),
+but for a quick review:
+
+~~~ruby
+# Add any missing pins to the DUT, returning the pins that were added
+dut.pins
+  #=> <%= dut.pins %>
+pat.add_pins
+  #=> <%= pat.add_pins %>
+dut.pins
+  #=> <%= dut.pins %>
+
+# Execute the vectors
+pat.execute
+~~~
+
+### Sections
+
+As also shown [in the example](<%= path "guides/decompilation/overview#Example_Decompilation" %>),
+the pattern is divided into sections: the `frontmatter`, the `pinlist`, and the `vector body elements`.
+
+The `frontmatter` and `pinlist` are parsed fully, stored in memory, and can be
+accessed directly.
+
+~~~ruby
+# Access the pattern's frontmatter
+pat.frontmatter
+  #=> <%= pat.frontmatter %>
+
+# Retrieve the pattern header
+pat.frontmatter.pattern_header
+  #=> <%= pat.frontmatter.pattern_header %>
+~~~
+
+~~~ruby
+# Access the pattern's pinlist
+pat.pinlist
+  #=> <%= pat.pinlist %>
+
+# pat.pinlist.pins
+  #=> <%= pat.pinlist.pins %>
+~~~
+
+Methods to retrieve the pins are also available directly on the decompiled pattern:
+
+~~~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 %>
+~~~
+
+See the [OrigenTesters API](<%= testers_api_url %>)
+for full details on the [Frontmatter](<%= "#{testers_api_url}/Decompiler/Pattern/Frontmatter.html" %>)
+and the [Pinlist](<%= "#{testers_api_url}/Decompiler/Pattern/Pinlist.html" %>).
+
+##### Platform Specifics
+
+The `frontmatter` and `pinlist` may contain _platform-specific_ setup information. Any
+platform-specifics should be documented 
+[on the supported platforms page](<%= path "guides/decompilation/platformspecifics" %>),
+but some methods are provided to programmatically check what's available.
+[For the example pattern](<%= path "guides/decompilation/overview#Example_Decompilation" %>),
+using the `J750 decompiler`:
+
+~~~ruby
+pat.frontmatter.platform_nodes
+  #=> <%= pat.frontmatter.platform_nodes %>
+
+pat.pinlist.platform_nodes
+  #=> <%= pat.pinlist.platform_nodes %>
+~~~
+
+Any `platform node` will have an accessor associated with it:
+
+~~~ruby
+pat.frontmatter.imports
+  #=> <%= pat.frontmatter.imports %>
+
+pat.frontmatter.variable_assignments
+  #=> <%= pat.frontmatter.variable_assignments %>
+~~~
+
+Obviously, these nodes are _decompiler specific_, but <u>what's less obvious is
+that the implementation, and return values, are not defined by the <code>universal API</code>.</u>
+Two decompilers that both implement the same `platform node` may do so
+differently and even have different meanings.
+
+<div class="alert alert-info" role="alert">
+This is also used in conjunction with <a href="#Vectors">vectors</a>.
+</div>
+
+#### Initial State
+
+For some functions, it'll be essential to know the _initial state_ of the pattern.
+This may include the [initial pin states](<%= "#{testers_api_url}/Decompiler/Pattern.html#first_pin_states-instance_method" %>),
+the [initial timeset](<%= "#{testers_api_url}/Decompiler/Pattern.html#first_timeset-instance_method" %>),
+or the [first vector](<%= "#{testers_api_url}/Decompiler/Pattern.html#first_vector-instance_method" %>), in its entirety.
+
+##### First Vector
+
+An exception to the _don't store vectors in memory_ rule is the `first vector`.
+The first vector contains the initial state of the pattern, the initial timeset,
+and, in many text representations, the sizes of the pins in the pinlist. This
+vector is always available:
+
+~~~ruby
+# Access the first vector
+pat.first_vector
+  #=> <%= pat.first_vector.class %>
+~~~
+
+An important observation is that this returns the _first vector_, __not__ the
+first _vector body element_.
+
+<div class="alert alert-warning" role="alert">
+Some platforms, such as the <code>v93k</code>, do not actually require a vector
+in the pattern source. In these cases, retrieving the first vector or querying
+aspects of the decompiled pattern that relies on the first vector will raise
+an <code>OrigenTesters::Decompiler::ParseError</code> exception with a
+message containing <code>"Could not locate the first vector"</code>.
+
+<a href="https://github.com/Origen-SDK/origen_testers/tree/master/approved/v93k/simple.avc">See the approved V93K simple pattern</a>
+for an example of such a pattern.
+</div>
+
+##### First Pin States and First Timeset
+
+Assuming the first vector is available, you can retrieve the _first pin states_
+and the _first timeset_ directly.
+[In the context of the example pattern](<%= path "guides/decompilation/overview#Example_Decompilation" %>):
+
+~~~ruby
+# Retrieve the initial pin states
+pat.initial_pin_states
+  #=> <%= pat.initial_pin_states %>
+
+# Retrieve the initial timeset
+pat.initial_timeset
+  #=> <%= pat.initial_timeset %>
+~~~
+
+### Vector Body Elements
+
+The final section is the `vector body elements`. This is a collection of not
+just the vectors, but everything that may appear interweaved with them.
+
+The most common non-vector will most likey be `comment blocks` which may be
+scattered about among the actual vectors. Other non-vectors will be platform
+specific. Some examples include [labels](<%= path "guides/decompilation/platformspecifics#Teradyne_J750_and_Ultraflex" %>),
+on the `J750` or `Ultraflex`, or [sequencer instructions](<%= path "guides/decompilation/platformspecifics#Advantest_V93K" %>),
+on the `V93K`.
+
+Anything in the `vector body` will have a class of 
+[OrigenTesters::Decompiler::VectorBodyElement](<%= "#{testers_api_url}/Decompiler/Pattern/VectorBodyElement.html" %>),
+which serves as a placeholder for anything that may come along and provides the
+means to further decide how this particular element should be interfaced with.
+
+#### Types
+
+Every `vector body element` will have a `type`, which is assigned during
+decompilation - all you need to do is retrieve it, using the `#type` method.
+For a `comment` this will be `:comment_block`. For a bonafide
+vector, this will be `:vector`.
+
+Platforms can, and will, interject their own types. A `label` in a `.atp` pattern
+source will have type `:label`. Retrieving and interacting with element
+types will be shown throughout the remainder of this section.
+
+#### Retrieving the Element
+
+Knowing what `type` the element is lets you know what kind of accessors this
+element should have. You would expect anything of type `:vector` to have `pin_states`,
+but you would not expect the `:comment_block` type to. However, the `vector body element`
+is just a placeholder, so the `#element` method must be used to retrieve the
+underlying element that _actually_ contains the content. Examples of this are
+shown in the sections below.
+
+### Elements
+
+The `universal API` supports two built-in vector types: 
+[comment blocks](<%= "#{testers_api_url}/Decompiler/Pattern/CommentBlock.html" %>)
+and [vectors](<%= "#{testers_api_url}/Decompiler/Pattern/Vector.html" %>).
+
+#### Comments
+
+The simplest vector body element to start working with is a `comment_block`.
+The decompiler will mash sequential comment lines in the pattern together to
+form a single `vector body element` of type `:comment block`. A shorthand
+method is provided to indicate when a `comment block` is encountered:
+
+~~~ruby
+vector_body_element.is_a_comment?
+  #=> true/false
+~~~
+
+There's only so much which can be done with comments. The main operation will be retrieving them:
+
+~~~ruby
+comment_block.comments
+  #=> [
+  #=>   "Any comments in the block..."
+  #=>   "Separated by newlines (or whatever the platform separator is)"
+  #=>   "Will be its own array entry."
+  #=> ]
+~~~
+
+Note that the comments are returned as an `Array` of all the comments mashed
+together. This is standard though, so a standalone, single-line comment will be an `Array`
+of size `1`.
+
+[You can view the API here](<%= "#{testers_api_url}/Decompiler/Pattern/CommentBlock.html" %>),
+but there's not much more to `comment blocks` than that.
+
+#### Vectors
+
+`Vectors`, on the other hand, have a bit more going on.These will have
+type `:vector` and a `vector body element` shorthand method is available here as well:
+
+~~~ruby
+vector_body_element.is_a_vector?
+  #=> true/false
+~~~
+
+Any vector, from any platform,
+is expected to provide a `timeset`, `repeat`, `pin_states`, and `comment` accessor.
+The `comment` in this case is a end-of-line comment, sharing the same line with the vector.
+
+Each of these can be retrieved for any `vector`, but its best to see it as an example.
+Returning [to the example pattern](<%= path "guides/decompilation/overview#Example_Decompilation" %>),
+we can retrieve all this content from the [first vector](#Initial_State):
+
+~~~ruby
+pat.first_vector.timeset
+  #=> <%= pat.first_vector.timeset %>
+
+pat.first_vector.pin_states
+  #=> <%= pat.first_vector.pin_states %>
+
+pat.first_vector.repeat
+  #=> <%= pat.first_vector.repeat %>
+
+pat.first_vector.comment
+  #=> <%= pat.first_vector.comment %>
+~~~
+
+Every `vector` is expected to contain _at least_ these accessors. Some may
+be empty, but the accessor should always _work_ (no `undefined method...` errors).
+
+The platform, will likey want to throw in its own content that it considers part of
+a standard `vector`, such as `opcodes`, for the J750.
+The platform will register these as `platform nodes`, and any `platform node` will
+have a corresponding accessor. For example, the J750 registers
+`opcode` and `opcode_arguments` as platform nodes so, when we've decompiled
+using the `J750` decompiler, we'll have access those as well:
+
+~~~ruby
+pat.first_vector.opcode
+  #=> <%= pat.first_vector.opcode %>
+
+pat.first_vector.opcode_arguments
+  #=> <%= pat.first_vector.opcode_arguments %>
+~~~
+
+Trying these platform nodes on other decompilers __is not__ guaranteed to
+give you anything. [Check the platform specifics](<%= path "guides/decompilation/platformspecifics" %>)
+for any additional platform nodes placed on the `vector` type.
+
+You can also list the platform nodes
+programmatically using `#platform_nodes`:
+
+~~~ruby
+pat.first_vector.platform_nodes
+  #=> <%= pat.first_vector.platform_nodes %>
+~~~
+
+##### Platform
+
+The question of _'what was the decompiler?'_ may come up for complex scripts
+geared towards handling different pattern sources or supporting various platforms.
+The `#decompiler` method will return the decompiler used (which is, not coincidentally,
+the `class` of the decompiled pattern object).
+
+~~~ruby
+pat.decompiler
+  #=> <%= pat.decompiler %>
+~~~
+
+In cases where decisions are made depending on the decompiler, the `#decompiler?(<platform>)`
+method queries if the decompiled pattern was decompiled using the given platform:
+
+~~~ruby
+pat.decompiler?(OrigenTesters::IGXLBasedTester::Pattern)
+  #=> <%= pat.decompiler?(OrigenTesters::IGXLBasedTester::Pattern) %>
+
+pat.decompiler?(OrigenTesters::SmartestBasedTester::Pattern)
+  #=> <%= pat.decompiler?(OrigenTesters::SmartestBasedTester::Pattern) %>
+~~~
+
+Now that we have all the tools to deal with vector types and the underlying elements,
+we can begin to interface with the vector body itself.
+
+#### Iterating Through Vectors
+
+The simplest operation is just to iterate through all the available vector body
+elements. The given block will be run for each one sequentially:
+
+~~~ruby
+# Iterate through all vector body elements, running the given block for each one.
+# For example, to print the type of each vector body element:
+pat.each_vector { |v| puts v.type }
+<%= pat.collect { |v| ":#{v.type}" }.join("\n") %>
+
+# Do the above, but with the index
+pat.each_vector_with_index { |v, i| puts "Type at index #{i}: #{v.type}" }
+<%= pat.collect_with_index { |v, i| "Type at index #{i}: #{v.type}" }.map { |v| "\"#{v}\"" }.join("\n") %>
+~~~
+
+This is the basis for working with the `vector body elements` section and from this
+more complex operations are derived. For example, to cycle the tester for each
+`vector` in the vector body:
+
+~~~ruby
+pat.each_vector do |v|
+  if v.is_a_vector?
+    tester.cycle(repeat: v.element.repeat)
+  end
+end
+~~~
+
+#### EnumerableExt
+
+Due to the non-standard `#each` method implementation, the
+[Enumerable](https://ruby-doc.org/core-2.6.3/Enumerable.html) mixin cannot be used
+directly. However, some select `Enumerable` methods are implemented:
+
+~~~ruby
+# Collect all the vectors, after having run the given block.
+# For example, to collect all the types that appear in the example pattern:
+pat.collect { |v| v.type }
+  #=> <%= pat.collect { |v| v.type } %>
+
+# Filting out duplicates...:
+pat.collect { |v| v.type }.uniq
+  #=> <%= pat.collect { |v| v.type }.uniq %>
+
+# Find the first vector for which the block returns true.
+# For example, to find the first vector body element that is of type vector:
+pat.find { |v| v.is_a_vector? }
+  #=> <%= pat.find { |v| v.is_a_vector? }.class %>
+pat.find { |v| v.is_a_vector? }.type
+  #=> :<%= pat.find { |v| v.is_a_vector? }.type %>
+
+# Find all the vectors for which the block returns true:
+# For example, to find the all vector body elements that are of type vector:
+pat.find_all { |v| v.is_a_vector? }
+  #=> <%= pat.find_all { |v| v.is_a_vector? }.map { |v| v.class } %>
+
+# Find all the vectors after filting out those for which the block returns true:
+# For example, to find the all vector body elements that are NOT of type vector:
+pat.reject { |v| v.is_a_vector? }
+  #=> <%= pat.reject { |v| v.is_a_vector? }.map { |v| v.class } %>
+~~~
+
+[See the API for a full listing.](<%= "#{testers_api_url}/Decompiler/Pattern/EnumerableExt.html" %>)
+
+<div class="alert alert-warning" role="alert">
+If <code>#collect</code> is used without any block provided, <b>all</b>
+<code>vector body elements</code> will be returned. This may not bode well
+for large patterns that contain thousands, or even hundreds of thousands, of vectors.
+</div>
+
+#### Vector At
+
+At times, you may want to grab a `vector body element`
+at a specific index. The method `#vector_at(i)` decompiles and returns
+the vector at the index, `i`:
+
+~~~ruby
+pat.vector_at(3)
+  #=> <%= pat.vector_at(3).class %>
+
+pat.vector_at(3).type
+  #=> :<%= pat.vector_at(3).type %>
+
+pat.vector_at(3).element
+  #=> <%= pat.vector_at(3).element.class %>
+
+pat.vector_at(3).element.repeat
+  #=> <%= pat.vector_at(3).element.repeat %>
+
+pat.vector_at(4).element.repeat
+  #=> <%= pat.vector_at(4).element.repeat %>
+~~~
+
+<u>Observe that <code>#vector_at</code> is a bit of a misnomer</u>, as it actually
+returns the `vector body elements` at `i`, not necessary one of type `vector`.
+
+<div class="alert alert-danger" role="alert">
+Please, <u>please</u>, <b><u>please</u></b> see the contextual notes below if planning to use <code>#vector_at(i)</code>
+extensively.
+</div>
+
+#### Contextual Notes For vector_at
+
+Recall that the vector body __is not__ stored in memory, so direct access to a given
+vector index is not inheritently supported.
+Therefore, each time `#vector_at(i)` is called, the decompiler
+simply runs `#each_vector_with_index` and bails once the given index is hit,
+returning the `vector body element` at that index. This gives the desired behavior,
+but comes at a cost...
+
+That cost being __runtime__. In
+a normal array, you'd expect to retrieve a `vector body element` in constant time, `O(1)`;
+however, iterating through the vector body behaves akin to that of a
+[linked list](https://en.wikipedia.org/wiki/Linked_list#Linked_lists_vs._dynamic_arrays),
+where the retrieval time for an arbitrary `vector body element` is `O(n)`.
+
+Extending this a bit: if using
+`#each_vector`, to iterate over `vector body elements` from `0` to `n`, you'll get `O(n)` runtime. However, if
+using `#vector_at(i)` where `i` __is__ the range from `0` to `n`, you'll actually get a
+`O(n^2)` runtime, as it starts from the beginning each time it retrieves a vector.
+
+<div class="alert alert-success" role="alert">
+Recall that the goal of not decompiling and storing the entire vector body at once
+is to decouple the peak memory and CPU usage with the size of pattern source.
+<br><br>
+
+So, although more complex operations that require working with single vectors may take a drastic
+<i>runtime</i> hit as compared to storing all vectors in memory, the <i>resource</i>
+requirements of such operations will not, allowing the decompiler to operate on
+absolutely massive patterns, even when run on sub-optimal machines.
+<br><br>
+
+If you have the computational resources (such as access to a distributed system,
+as most corporations will have) or you know that the pattern sizes you'll be working
+with are limited to what your system can handle, the
+<a href='<%= "#{testers_api_url}/Decompiler/Pattern/EnumerableExt.html#collect-instance_method"%>'>enumerable method <code>#collect</code></a>
+can be used to grab the entire vector body and store it in memory.
+</div>
+
+<b>tl;dr:</b> if jumping around the vector body, pre-processing, or otherwise working
+with the entire vector body simultaneously, please be prepared to take a runtime hit.
+
+#### Platform Specific Elements
+
+Its quite likely that you'll encounter platform-specific elements when iterating
+through the vector body. Recall the `type` attribute on each `vector body element`.
+This, in conjunction with the [platform's documentation](<%= path "guides/decompilation/platformspecifics" %>)
+will tell you what other elements may be encountered.
+
+From a programmatic perspective, the `vector body element` in question knows if
+it is platform-specific.
+[Returning to the example pattern:](<%= path "guides/decompilation/overview#Example_Decompilation" %>)
+
+~~~ruby
+pat.vector_at(0).type
+  #=> :<%= pat.vector_at(0).type %>
+pat.vector_at(0).is_platform_specific?
+  #=> <%= pat.vector_at(0).is_platform_specific? %>
+
+pat.vector_at(1).type
+  #=> :<%= pat.vector_at(1).type %>
+pat.vector_at(1).is_platform_specific?
+  #=> <%= pat.vector_at(1).is_platform_specific? %>
+~~~
+
+For platform-specific nodes, same as `vectors`, the parsed nodes from the decompilation
+process are retrievable:
+
+~~~ruby
+pat.vector_at(0).platform_nodes
+  #=> <%= pat.vector_at(0).platform_nodes %>
+~~~
+
+Any `platform nodes` can be retrieved using the accessor:
+
+~~~ruby
+pat.vector_at(0).start_label
+  #=> "<%= pat.vector_at(0).start_label %>"
+~~~
+
+<div class="alert alert-info" role="alert">
+Although these programmatic methods are provided, platform specifics should be documented and
+any supported platform in which such documentation is either missing, incorrect, or unclear
+should be addressed.
+
+<a href="https://github.com/Origen-SDK/origen_testers/issues">Please open an issue at the OrigenTesters Github repository</a>
+so corrections can be made.
+</div>
+
+% end