origen_testers 0.19.0 → 0.19.2

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

@@ -0,0 +1,125 @@
+% render "layouts/guides.html" do
+
+The control of pin states represents the lowest level of Origen's pattern generation
+API.
+
+Generally for most modern applications you should need to do this very rarely
+and mainly when creating mode entry and reset sequences for your
+device.
+For most applications a [plugin](<%= path "plugins" %>)
+such as the [JTAG driver](http://origen-sdk.org/jtag) should be used to
+abstract much of the lower level details about the values to be applied to a given
+pin by a given test vector.
+If your application uses a proprietary interface then it is recommended that you
+create a dedicated class to implement the interface
+protocol and to deal with all of the manipulation of pin states.
+
+#### Basic Concept
+
+All of Origen's vector-based tester models will support a <code>cycle</code> method
+which will drive or expect the current values held by all pins for one clock cycle.
+In other words the cycle method takes a snapshot of the current pin states and then
+applies them to the DUT.
+
+Origen's pin API provides models that represent a DUT's pins and pin groups
+and methods with which to manipulate their states between tester cycles.
+
+See the [Pins](<%= path "guides/models/pins" %>) section of
+the [Models](<%= path "guides/models/introduction" %>) guide for details and examples
+of how to add and manipulate pin states within your model logic.
+
+#### Recommended Architecture
+
+Here are the key components of the recommended architecture:
+
+1. All pins and aliases are defined within the top-level models only, the top-level model is the only object
+   that owns pins in the entire application for a given target setup.
+2. Functions should be added to the pins to represent the different functionality available
+   on the pins depending on the mode.
+3. The availability of the required functions is a contract between a given sub-model
+   and the top-level, i.e. the NVM models and test logic assume that all top-level models will
+   provide functions named *nvm_fail* and *nvm_done*.
+4. Each model only refers to the pins using the name/function that it understands.
+5. The test block/plugin that is primarily responsible for a given test pattern
+   can still control the pin order of the created pattern by using the <code>pin_pattern_order</code>
+   method.
+
+The above approach has the benefits of encapsulating all pin definitions within the top-level model, so
+that a device's TE could implement the details straight from the top-level DFT guide for example, while the lower level
+modules can talk to the pins/signals that they know about.
+
+Here is an example of how to implement this scheme in a top-level SoC model:
+
+~~~ruby
+class MySoC
+  include Origen::TopLevel
+
+  def initialize(options)
+    instantiate_pins(options)
+  end
+
+  def instantiate_pins(options)
+    # Common pins required by all to support mode entry sequences
+    add_pin :tclk,      reset: :drive_lo
+    add_pin :trst,      reset: :drive_hi
+    add_pin :extal
+    add_pin :xtal,      reset: :drive_lo
+    add_pin :tms
+    add_pin :tdo
+    add_pin :tdi
+    add_pin :resetb
+
+    add_pins :data, size: 8
+
+    # Add NVM BIST mode functions
+    pin(:extal).add_function :nvm_clk
+    pin(:data)[2].add_function :nvm_fail
+    pin(:data)[3].add_function :nvm_done
+    pin(:data)[4].add_function :nvm_invoke
+
+    # Add additional function groups here... 
+  end
+end
+~~~
+
+#### Controlling the Pattern Pin Order
+
+As a test engineer for a specific test module you may want more importance to be given to some pins
+than others, or to otherwise order them to make them most readable for debugging the target module.
+
+This can be achieved by calling the <code>pin_pattern_order</code> method:
+
+~~~ruby
+class NVM
+  include Origen::Model
+
+  def initialize
+    # Unspecified pins will appear in arbitrary order at the end
+    pin_pattern_order :nvm_clk, :nvm_invoke, :nvm_done, :nvm_fail
+  end
+end
+~~~
+
+Aside from specifying the order of the pins this also specifies what the name should be, i.e. if a given
+pin/pin group has multiple aliases then the one used to refer to the pin in the <code>pin_pattern_order</code>
+is that one that will appear in the generated pattern.
+
+By default any unspecified pins will appear in arbitrary order at the end. To include only the pins
+specified then append the <code>:only</code> option at the end:
+
+~~~ruby
+# Only include these pins in the output pattern and in this order
+pin_pattern_order :nvm_clk, :nvm_invoke, :nvm_done, :nvm_fail, only: true
+~~~                      
+
+Alternatively specific pins or pin groups can be excluded from appearing in the output file via
+the <code>pin_pattern_exclude</code> method:
+
+~~~ruby
+# Don't include these pins in the pattern
+pin_pattern_exclude :porte, :portf
+~~~
+
+An error will be raised if the same pin appears in both <code>pin_pattern_order</code> and <code>pin_pattern_exclude</code>.
+
+% end

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

@@ -0,0 +1,300 @@
+% render "layouts/guides.html" do
+
+The majority of patterns are concerned with reading and writing to registers to make the
+DUT do something and consequently 
+more than 90% of your time developing an Origen test application should be concerned with
+writing code at the register level.
+
+All test [transaction drivers](<%= path "plugins/#Transaction_Protocol_Drivers" %>)
+such as the [ARM Debug driver](http://origen-sdk.org/arm_debug) are expected to support the basic
+Origen register API. This allows the test engineer to develop code at register level and
+independently of the underlying test communication protocol which can be easily changed
+to something else as required.
+
+#### Basic Concept
+
+See the [Registers](<%= path "guides/models/registers" %>) section of
+the [Models](<%= path "guides/models/introduction" %>) guide for details and examples
+of how to add and manipulate register states within your model logic.
+
+Interaction with the registers should be limited to the [model's controller](<%= path "guides/controllers/introduction" %>)
+- no one else should reach into a model to manipulate its register state (this is not prevented
+but recommended), and the controllers should instead expose interface methods for the outside
+world to use. Internally such methods will work by manipulating registers in a sequence.
+
+The <code>read!</code> and <code>write!</code> methods when called on a register (or bit) will
+automatically fire off a request for the register to be written using the following
+rules:
+
+* If the model or controller that owns the register implements a <code>write_register</code> method
+  then call this with the target register passed in as the argument
+* Otherwise if the object that owns the register implements an <code>owner</code> method,
+  then see if the object that this returns provides a suitable <code>write_register</code>
+  method
+* If not then if a currently instantiated model includes the <code>Origen::TopLevel</code>
+  module then see if it (or its controller) has a <code>write_register</code> method available
+* If the request has still not been fulfilled then raise an error  
+
+Read works in the same way except that it looks for a method called <code>read_register</code>.
+
+What this all means is that within a controller you will build your
+test logic from methods that look like this:
+
+~~~ruby
+def measure_vref(setting=nil)
+  if setting
+    ss "Measure the Vref voltage for setting #{setting}"
+    vref.level.write(setting)
+  else
+    ss "Measure the default Vref voltage"
+  end
+  vref.test_enable.write!(1)
+end
+
+# From a pattern call like this:
+Pattern.create do
+  $dut.nvm.measure_vref(5)
+end
+~~~
+
+The actual mechanism for how the registers are written is abstracted away from the
+test logic itself and therefore the test logic is generally independent from the communication
+protocol. This is a very powerful concept that allows plugins to be created that provide 
+test sequences for a specific silicon module and these can then be re-used on DUTs that
+employ completely different register access protocols.
+
+#### Recommended Architecture
+
+This is the recommended architecture for modern Origen applications that will lend itself
+to working well within a plugin-based environment.
+
+Define registers in the child models that own them and create test methods to manipulate them
+in the controller:
+
+~~~ruby
+class NVM
+  include Origen::Model
+
+  def initialize
+    reg :vref, 0x0003, size: 16 do |reg|
+      reg.bit 15,   :test_enable
+      reg.bit 7..0, :level
+    end
+  end
+end
+
+class NVMController
+  include Origen::Controller
+
+  def measure_vref(setting=nil)
+    if setting
+      ss "Measure the Vref voltage for setting #{setting}"
+      vref.level.write(setting)
+    else
+      ss "Measure the default Vref voltage"
+    end
+    vref.test_enable.write!(1)
+  end
+end
+~~~
+
+Defer how to actually write the register to the top-level SoC controller and normally this would
+be done via one of the available protocol plugins.
+Here for example is an SoC which will write the register via the [Nexus protocol](http://origen-sdk.org/nexus):
+
+~~~ruby
+class MySoC
+  include Origen::TopLevel  # Indicate to Origen that this model represents a top-level device object
+end
+
+class MySoCController
+  include Origen::Controller
+  include Nexus
+
+  # Process register reads using the Nexus protocol
+  def read_register(reg, options={})
+    nexus.read_register(reg, options)
+  end
+
+  # As above for write requests
+  def write_register(reg, options={})
+    nexus.write_register(reg, options)
+  end
+end
+~~~
+
+And that is all that is required, Origen takes care of the hook up and the behind the scenes
+communication to make it all work.
+
+Another target may then instantiate a different SoC model which could use a completely different
+protocol like [ARM Debug](http://origen-sdk.org/arm_debug), in which case the NVM test module would
+still work although the generated pattern would look completely different.
+
+#### Bit Level Access
+
+All registers support bit level updates, we have seen an example of this already: 
+
+~~~ruby
+vref.test_enable.write!(1)
+~~~
+
+What this will do is update the value held by the given bits and then send the parent
+register object to the <code>write_register</code> method for processing.
+All other bits in the register will maintain the state that they had prior to this
+operation commencing.
+
+Since it is not generally possible to update only a subset of bits on a device the entire
+register will still be updated on silicon.
+However in the case of performing a bit-level read things get a bit more interesting.
+
+The equivalent read operation will update the data values of the bits in the same way, but
+it will also set a flag on those bits marking that they have been requested for read.
+
+~~~ruby
+vref.test_enable.read!(1)
+~~~
+
+The protocol driver can then look out for this flag when generating the readout vectors
+and only enable a compare on the vectors that correspond to the bits marked for read.
+Generally this takes a lot of the cognitive overhead out of writing patterns since you
+can mentally disregard the state of all bits except the ones that you care about.
+
+All standard Origen protocol plugins are expected to support this feature.
+
+The same is true for store (meaning capture the value on the tester) or overlay operations:
+
+~~~ruby
+# Capture the value of the level bits
+vref.level.store!
+
+# Dynamically overlay the value written to the level bits
+vref.level.overlay("vref_setting")
+vref.write!
+~~~
+
+#### Combining Multiple Bit Level Accesses Into A Single Transaction
+
+Multiple individual bits within a register can be accessed/manipulated within a single
+transaction by making multiple bit-level calls to `read` (or `write`), followed by a single
+register-level `read!` (or `write!`) operation:
+
+~~~ruby
+my_reg.my_bits_x.read(1)
+my_reg.my_bits_z.read(0b101)
+my_reg.read!
+~~~
+
+Sometimes you will see application code that combines the final transaction request with the
+final bit-level operation, this will do the same thing as the above example:
+
+~~~ruby
+my_reg.my_bits_x.read(1)
+my_reg.my_bits_z.read!(0b101)
+~~~
+
+If you prefer, an equivalent block form API is also available, this is equivalent to the above example:
+
+~~~ruby
+my_reg.read! do |reg|
+  reg.my_bits_x.read(1)
+  reg.my_bits_z.read(0b101)
+end
+~~~
+
+#### Writing a Driver
+
+Generally the code for an existing driver should be reviewed to see how to go about this,
+the [JTAG driver](http://origen-sdk.org/jtag) would be a good example to look at,
+but here are some basic pointers on good driver design.
+
+All drivers should implement read and write register methods:
+
+~~~ruby
+def write_register(reg, options={})
+end
+
+def read_register(reg, options={})
+end
+~~~
+
+The write methods are usually fairly simple, here is a basic example of how to do a parallel
+and a serial protocol write:
+
+~~~ruby
+# Writing on a parallel port, let's say we have a 16-bit register and the
+# data needs to be written on a pin group called data which is 8-bits
+def write_register(reg, options={})
+  pin(:din).drive(1)   # Let's say when this pin is high data is captured
+  # Drive the data in MSB -> LSB order
+  pins(:data).drive!(reg[15..8].data)
+  pins(:data).drive!(reg[7..0].data)
+  pin(:din).drive(0)   # Turn off capture
+end
+
+# Writing on a serial port, same as above only this time the :data port is
+# only 1-bit wide
+def read_register(reg, options={})
+  pin(:din).drive(1)   # Let's say when this pin is high data is captured
+  # Drive the data in MSB -> LSB order
+  reg.shift_out_left do |bit|
+    pin(:data).drive!(bit.data)
+  end
+  pin(:din).drive(0)   # Turn off capture
+end
+~~~
+
+Read methods are usually a bit more involved to implement the bit-specific read and
+capture operations.
+Here is a parallel and serial protocol example which supports bit-level read operations:
+
+~~~ruby
+# Reading on a parallel port, let's say we have a 16-bit register and the
+# data needs to be read on a pin group called data which is 8-bits
+def write_register(reg, options={})
+  pin(:dout).drive(1)   # Let's say when this pin is high data is presented
+
+  # Compare the data in MSB
+  8.times do |i|
+    bit = reg.bit(i + 8)
+    if bit.is_to_be_read?
+      pins(:data)[i].assert(bit.data)
+    else
+      pins(:data)[i].dont_care
+    end
+  end
+  $tester.cycle
+
+  # Now the data in LSB
+  8.times do |i|
+    bit = reg.bit(i)
+    if bit.is_to_be_read?
+      pins(:data)[i].assert(bit.data)
+    else
+      pins(:data)[i].dont_care
+    end
+  end
+  $tester.cycle
+
+  pin(:dout).drive(0)   # Turn off read out
+end
+
+# Reading on a serial port, same as above only this time the :data port is
+# only 1-bit wide
+def read_register(reg, options={})
+  pin(:dout).drive(1)   # Let's say when this pin is high data is presented
+
+  # Drive the data in MSB -> LSB order
+  reg.shift_out_left do |bit|
+    if bit.is_to_be_read?
+      pin(:data).assert!(bit.data)
+    else
+      pin(:data).dont_care!
+    end
+  end
+
+  pin(:dout).drive(0)   # Turn off read out
+end
+~~~
+
+
+% end

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

@@ -0,0 +1,105 @@
+% render "layouts/guides.html" do
+
+The pattern generator is launched via the Origen generate command, see the command line
+help to get details of the most up to date options:
+
+~~~text
+origen generate -h
+~~~
+
+As this is such a commonly used command it has a short cut alias:
+
+~~~text
+origen g -h
+~~~
+
+The generator can be run on a single file:
+
+~~~text
+origen g pattern/ram/march.rb
+~~~
+
+It can also be run without a path and by just supplying a name, Origen is also pretty flexible
+with regards to file extensions and pre and post fixes and in most cases it should do a good
+job of finding the pattern that you want:
+
+~~~text
+origen g march
+~~~
+
+It can also run on a whole directory:
+
+~~~text
+origen g pattern/ram
+~~~
+
+Pattern list files can also be used, by convention these should be kept in the list directory
+and should have the extension <code>.list</code>:
+
+~~~text
+origen g list/production.list
+~~~
+
+Here is an example of a list file:
+
+~~~text
+# List files can be commented like this
+# Simply list the name of the patterns that you would use on the command line
+march.rb
+data_retention.rb
+# List files can also call other lists
+probe.list
+~~~
+
+By default the generated patterns will be put in <code>output</code> or whatever directory
+is returned by the <code>config.output_directory</code> attribute in <code>application.rb</code>.
+
+Submit to the LSF by appending <code>-l</code> and optionally interactively
+wait for completion:
+
+~~~text
+origen g list/production.list -l -w
+~~~
+
+#### Regression Testing
+
+Every time Origen generates a pattern it will check to see if it has generated it before, and
+if so it will compare the current version to the previous version and alert if there is a
+difference. This can be used to check for regressions when making changes that you don't want
+to affect the output, or to verify that the change is what you intended in cases where you
+are intentionally modifying the output.
+
+The diff is a smart diff and will not care about any changes to comments, only about changes
+that will affect the pattern's operation.
+
+In the case of a difference being found Origen will automatically present you with the diff command
+to run if you want to view the change.
+
+To accept changes or to start tracking the differences in a pattern (or patterns) run the following command
+after generating:
+
+~~~text
+origen save all
+~~~
+
+#### Programmatically Launching the Generator
+
+If you start writing your own [commands](<%= path "guides/misc/commands" %>) you may want
+to launch the generator from Ruby, do that as follows:
+
+~~~ruby
+Origen.app.runner.launch action: :generate,
+                       files: "list/production.list"
+~~~
+
+This can be combined with [Target Loops](<%= path "guides/runtime/programming" %>) to run the
+generator for multiple targets.
+
+A generate job can also be posted to the LSF by supplying the same options that you would use
+on the command line like this:
+
+~~~ruby
+Origen.lsf.submit_origen_job("g march")
+~~~
+
+% end