origen_sim 0.12.0 → 0.13.0

data/templates/origen_guides/simulation/introduction.md.erb

@@ -0,0 +1,35 @@
+% render "layouts/guides.html" do
+
+<img src="https://user-images.githubusercontent.com/158364/36662666-6b49d096-1adf-11e8-997e-889caba391b2.png" alt="origen_sim" style="
+    width: 100%;
+">
+
+OrigenSim is a plugin that enables semiconductor test patterns (and flows) written in Origen/Ruby to be run
+in a dynamic Verilog simulation, similar to what is commonly known as a _Virtual Test_ simulation in other workflows.
+
+It provides a simulation tester driver (which can be used as a direct replacement for Origen's
+conventional ATE tester drivers) which will
+pass requests to drive or expect pin values onto a simulator instead of rendering them to an ASCII file. Since
+the application-level Origen code is the same in both cases, it guarantees that what happens in the simulation
+and in the final pattern are the same and that ultimately they will work first time on silicon.
+
+For debugging, OrigenSim supports the injection of regular Ruby debugger breakpoints anywhere in the pattern
+source code. This will halt the simulation at the given point in time, allowing it to be interactively
+debugged at the Origen-source-code level.
+
+Similarly, an Origen interactive session (`origen i`) can be launched with an OrigenSim driver,
+allowing designers and test engineers to use Origen APIs to interactively manipulate a live simulation of their
+DUT while viewing the response in real time in a wave viewer.
+
+#### Adding OrigenSim To Your Application
+
+To enable your application to use OrigenSim, simply add the plugin to your Gemfile:
+
+~~~ruby
+gem "origen_sim"
+~~~
+
+and then [create a simulation environment setup](<%= path "guides/simulation/environment" %>).
+
+
+% end

data/templates/origen_guides/simulation/log.md.erb

@@ -0,0 +1,118 @@
+% render "layouts/guides.html" do
+
+Log output from simulations is often very verbose, which can make it hard to distinguish between messages
+that are important and those that can be safely ignored.
+
+By default, OrigenSim will automatically suppress all simulator log output except for any lines that
+contain the text _WARNING_ or _ERROR_ (case insensitive); both of these will be logged to the console and any occurrences of
+the latter will also make the result of the simulation be classed as a FAIL.
+
+All log output can be shown in the console by running with the `-d` or `--debug` switches, and the log files will
+always contain everything that was output by the simulator.
+
+OrigenSim will also consider any output from the simulator to STDERR as a sign that something has gone wrong
+and this will also cause the simulation result to be classed as a FAIL.
+
+If your simulation produces STDERR output which you don't care about (and which you don't want to make your
+simulation FAIL), then you can configure OrigenSim to ignore all STDERR messages via:
+
+~~~ruby
+OrigenSim.fail_on_stderr = false
+~~~
+
+Alternatively, a safer solution is to declare which specific messages on STDERR should be ignored.
+For example, say that in an early design build the ADC is not configured correctly and this results
+in a message about this being output to STDERR.
+However, since this problem does not affect the particular IP that we are testing we do
+not want our simulations to FAIL because of it.
+
+In such a case you can add strings to the `stderr_string_exceptions` array and any STDERR lines which contain
+the given text will be ignored:
+
+~~~ruby
+OrigenSim.stderr_string_exceptions << 'invalid adc config'    # Case in-sensitive match
+~~~
+
+**Note that in all of these cases the given text is considered to be case-insensitive when considering if
+it matches a log line.**
+
+If you need case-sensitivity (or more generally need more control of exactly what is considered to be a match), you can
+supply a regular expression instead of a string for all of the cases discussed here:
+
+~~~ruby
+OrigenSim.stderr_string_exceptions << /invalid adc config/    # Case sensitive match
+~~~
+
+Similarly, if you find that the default of matching for _ERROR_ in STDOUT messages is being overly aggressive,
+exceptions can be added in a similar way:
+
+~~~ruby
+OrigenSim.error_string_exceptions << 'uninitialized value in ROM at'
+~~~
+
+This means that a log line resembling <code>ERROR uninitialized value in ROM at 0x1000</code> will not fail the simulation,
+but the line `ERROR uninitialized value in RAM at 0x2000` will fail.
+
+On the other hand, if you find that simply matching for _ERROR_ is not catching some cases which you would
+like to cause a FAIL, you can add additional strings to watch out for like this:
+
+~~~ruby
+OrigenSim.error_strings << 'FAILED'
+~~~
+
+If you want to remove 'ERROR' from the list of error strings (in there by default), you can assign a new array
+instance:
+
+~~~ruby
+OrigenSim.error_strings << 'FAILED'
+
+OrigenSim.error_strings  # => ['ERROR', 'FAILED']
+
+OrigenSim.error_strings = ['FAILED']
+
+OrigenSim.error_strings  # => ['FAILED']
+~~~
+
+Similar variables exist to configure what you want to catch as a warning:
+
+~~~ruby
+OrigenSim.warning_strings            # => ['WARNING']
+
+OrigenSim.warning_string_exceptions  # => []
+~~~
+
+and also to match any output lines that you simply want to be shown in the console by default:
+
+~~~ruby
+OrigenSim.log_string  # => []
+~~~
+
+It is conventional to do all such configuration like this with `environment/sim.rb`, where you can decide
+to make it global (applies to all targets), target-specific, or a combination of both:
+
+~~~ruby
+# environment/sim.rb
+
+# Will apply to all targets
+OrigenSim.error_strings << 'FAILED'
+
+case Origen.target.name
+
+when "my_dut1"
+  OrigenSim.cadence do |sim|
+    # Configuration of Cadence simulator to be used for DUT1 here
+  end
+
+  # Known problem with this specific DUT only
+  OrigenSim.error_string_exceptions << 'uninitialized value in ROM at'
+
+when "my_dut2"
+  OrigenSim.synopsys do |sim|
+    # Configuration of Synopsys simulator to be used for DUT2 here
+  end
+
+# ...
+~~~
+
+
+% end

data/templates/origen_guides/simulation/patterns.md.erb

@@ -0,0 +1,193 @@
+% render "layouts/guides.html" do
+
+Patterns are simulated by simply generating the pattern with
+a [simulation environment](<%= path "guides/simulation/environment" %>)
+selected:
+
+~~~text
+origen g my_pattern -e environment/sim.rb
+~~~
+
+Most of the [common pattern API](<%= path "guides/pattern/common" %>) is supported
+by OrigenSim and therefore you should expect to find the simulation environment
+a drop-in replacement for your conventional ATE environment driver.
+
+If you come across an API that OrigenSim does not support but you think that
+it should, please raise a ticket here describing what you
+tried to do <https://github.com/Origen-SDK/origen_sim/issues>.
+
+
+#### Waiting For Events
+
+When your pattern invokes some DUT action and you need to wait for it to complete, you
+normally have two options:
+
+* Calculate how long it should take and wait for a fixed delay
+* Implement a match loop to dynamically wait for an expected response to occur
+
+Both of these are fully supported by OrigenSim, see the
+[Timing and Waiting guide](<%= path "guides/pattern/timing" %>) for more information on these APIs.
+
+However, if your pattern generation flow is going to be supported by simulation, then you also have
+a third option - to derive the required wait time from the simulation itself.
+
+OrigenSim makes this very easy via the following API:
+
+~~~ruby
+cc "Wait for the program command to complete"
+
+tester.sim_delay :program_command do
+  dut.pin(:done).assert!(1)
+end
+dut.pin(:done).dont_care  # Any pin assertions/reads created within the block will persist beyond it, so
+                          # remember to clear any assertions that you don't want to carryover afterwards
+~~~
+
+The `sim_delay` method provides the convenience of a match loop for the purposes of
+delay calculation but will still generate a static pattern for the ATE. It will automatically calculate how
+long the given block takes to pass and then insert that delay when later generating the pattern for an ATE.
+
+An ID must be given to each delay, `:program_command` in this example, and if the same ID is used in multiple
+calls to `sim_delay` then it means that the same delay will be used for each occurrence.
+
+When simulating a pattern that contains `sim_delay` block(s) for the first time, the delay will
+be calculated from the simulation and stored in an Org file (Origen native pattern format) within your
+application's pattern directory. These files should be committed to your revision control system and considered
+as part of your application.
+
+The next time that you simulate it, the previously calculated delay will be inserted into the
+pattern and therefore the simulation will be verifying that the delay is correct.
+
+If you want to re-calculate the delays during a simulation then run with the `--sim_capture` switch:
+
+~~~text
+origen g my_pattern -e environment/sim.rb --sim_capture
+~~~
+
+Additional padding can be added to the calculated delay like this (all the usual `time_in_us:` style
+of time options are supported):
+
+~~~ruby
+tester.sim_delay :program_command, padding: { time_in_cycles: 10 } do
+  dut.pin(:done).assert!(1)
+end
+dut.pin(:done).dont_care  # Any pin assertions/reads created within the block will persist beyond it, so
+                          # remember to clear any assertions that you don't want to carryover afterwards
+~~~
+
+By default, the block will be evaluated constantly until it passes when calculating the delay from
+the simulation.
+
+If the time is long and this is making your simulation run too slow, you can use lower resolution
+by supplying a `:resolution` option, either as a number of cycles:
+
+
+~~~ruby
+tester.sim_delay :program_command, resolution: 10 do
+  dut.pin(:done).assert!(1)
+end
+dut.pin(:done).dont_care  # Any pin assertions/reads created within the block will persist beyond it, so
+                          # remember to clear any assertions that you don't want to carryover afterwards
+~~~
+
+or by supplying a hash filled with the usual time options:
+
+~~~ruby
+tester.sim_delay :program_command, resolution: { time_in_ns: 50 } do
+  dut.pin(:done).assert!(1)
+end
+dut.pin(:done).dont_care  # Any pin assertions/reads created within the block will persist beyond it, so
+                          # remember to clear any assertions that you don't want to carryover afterwards
+~~~
+
+#### Capturing Responses from the Simulation
+
+Sometimes the response from your DUT maybe hard to predict and/or complicated to model in Origen, think about a digital data
+stream response from a pin when testing a communications protocol.
+
+OrigenSim provides an API for such a case which allows pin output values for a subset of pins/vectors
+to be sampled during a simulation. The response is then captured and converted into the corresponding
+expect data when the same pattern is later generated for the ATE.
+
+Capturing is really easy, just wrap the operation you want to capture in your pattern source code like this:
+
+~~~ruby
+tester.sim_capture :cmd55, :dout, :test_bus, :tdo do
+  dut.pins(:din_port).drive!(0x1234_5678)
+  dut.cmd.write!(0x55)
+  60.cycles
+end
+~~~
+
+The first argument is an ID for the capture, this can be anything but the user must assign it.
+Then supply a list of pin/pin_group IDs (or pin objects) that you want to capture.
+
+If you use the same ID more than once it means that the same captured data will be used in multiple places.
+
+When you add this to the pattern an error will be raised if you try to generate an ATE pattern, this will
+advise that the data has not been captured yet and it must be run in a simulation first.
+
+When you run it in a simulation for the first time, the data will be captured and stored to your application
+in the `pattern/sim_capture` directory. These files should be checked into your application as if they were regular patterns.
+
+On subsequent simulation runs, the data will not be captured but instead will be re-played from the simulation
+- i.e. the pattern will assert that the DUT output matches what is in the capture file.
+In other words, by adding this and then simulating twice using the same command, you are both capturing and
+then verifying the captured data.
+
+Add this switch to update the captures during a subsequent simulation run:
+
+~~~text
+origen g my_pattern --sim_capture
+~~~
+
+To use the captured data in an ATE pattern, simply switch to an ATE target and generate as normal.
+
+A known limitation of this feature is that the pin state data is currently captured at the end of a cycle, not
+at the point during the cycle where it will be read by the pattern.
+However, if this were to be a problem in a particular application, you would see it fail when re-playing the
+captured data in simulation.
+
+#### Creating Simulation-Only Assertions
+
+Users are of course encouraged to write patterns that test the DUT via its pin interface since such
+patterns will work in physical environments like the ATE.
+
+However, it can be useful to supplement your patterns with simulation-only assertions which peek inside
+the DUT to check that it is behaving as expected. Such assertions can report useful failure information
+back to the user which may help when debugging a failed pattern simulation.
+
+~~~ruby
+# This code must be skipped when the pattern is generating for an ATE target environment
+if tester.sim?
+  value = tester.simulator.peek("origen.dut.path.to.net").to_i[7..4]
+  if value != 0xA
+    OrigenSim.error "The internal node was #{value.to_hex} instead of 0xA!"
+  end
+end
+~~~
+
+Note the use of `OrigenSim.error` to report the error message, this will cause the simulation result
+to be reported as a FAIL, even if all pin level assertions otherwise pass.
+
+Also note that the value returned from the `peek` method is converted into an integer. This is because
+`peek` returns an instance of [Origen::Value](<%= path "api/Origen/Value.html" %>) which can also handle
+`X` or `Z` values.
+
+So for example, if you actually wanted a given bit to be `Z` you could write your assertion as:
+
+~~~ruby
+unless tester.simulator.peek("origen.dut.path.to.net")[4].z?
+  OrigenSim.error "Bit 4 of some net was not in hi-Z mode!"
+end
+~~~
+
+It is also possible to force nets within the DUT via a corresponding `poke` method:
+
+~~~ruby
+if tester.sim?
+  test.simulator.poke "path.to.some.net[15:8]", 0x51
+end
+~~~
+
+% end

data/templates/probe.tcl.erb

@@ -1,6 +1,9 @@
 database -open waves -into <%= options[:dir] %>/<%= options[:wave_file] %> -default -event
 probe -create -shm origen -depth <%= options[:depth] %> -database waves
 #probe -create -assertions -transaction origen -depth all -database waves
+% Array(options[:tcl_inputs]).each do |line|
+<%= line %>
+% end
 
 % Hash(options[:force]).each do |net, value|
 %   net = net.to_s.strip.sub(/^(origen\.|origen\.dut\.|\.)/, '')

data/templates/rtl_v/origen.v.erb

@@ -75,6 +75,8 @@ module pin_drivers(errors, <%= dut.rtl_pins.map { |n, p, o| "#{p.id}_o" }.join('
 
   output reg [31:0] errors = 0;
   reg sync = 0;
+  reg [31:0] match_errors = 0;
+  reg match_loop = 0;
 
   always @(
 
@@ -86,7 +88,10 @@ module pin_drivers(errors, <%= dut.rtl_pins.map { |n, p, o| "#{p.id}_o" }.join('
 %   end
 % end
   ) begin
-    errors[31:0] = errors[31:0] + 1;
+    if (match_loop == 1)
+      match_errors[31:0] = match_errors[31:0] + 1;
+    else
+      errors[31:0] = errors[31:0] + 1;
   end
 
 % dut.rtl_pins.each do |name, pin, options|
@@ -101,7 +106,9 @@ module debug(errors);
   input [31:0] errors;
 
   reg [1023:0] pattern = 0;
-  reg [1023:0] comments = 0;
+% OrigenSim::NUMBER_OF_COMMENT_LINES.times do |i|
+  reg [1023:0] comments<%= i %> = 'h20;  // Contain a space by default
+% end
 
   reg handshake;
 
@@ -170,7 +177,16 @@ module origen;
     $vcdplusmemon;
   end
 `endif
-    
+
+`ifdef ORIGEN_FSDB
+  initial
+  begin
+    $fsdbDumpfile("origen.fsdb");
+    $fsdbDumpvars(0, "+all");
+  end
+`endif
+
+
   always @(posedge finish) begin
     //$display("********************************");
     //$display("Finishing simulation...");

data/templates/web/layouts/_guides.html.erb

@@ -0,0 +1,15 @@
+---
+title: Origen - Guides
+---
+<%= render "templates/web/partials/navbar.html" %>
+
+%# Add/edit sections here, the code below will expand this with the correct markup,
+%# pass in the topic you want selected via the :tab option.
+% i = OrigenDocHelpers::GuideIndex.new
+% Origen.app.config.shared[:origen_guides_index].call(i)
+
+% render "doc_helpers/searchable.html", options.merge(index: i, root: "", prompt: "Search the guides...") do
+
+<%= yield %>
+
+% end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_sim
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-28 00:00:00.000000000 Z
+date: 2018-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.33.3
+        version: 0.35.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.33.3
+        version: 0.35.0
 - !ruby/object:Gem::Dependency
   name: origen_testers
   requirement: !ruby/object:Gem::Requirement
@@ -75,6 +75,7 @@ files:
 - ext/origen.h
 - ext/vpi_user.h
 - lib/origen_sim.rb
+- lib/origen_sim/artifacts.rb
 - lib/origen_sim/commands/build.rb
 - lib/origen_sim/commands/ci.rb
 - lib/origen_sim/commands/co.rb
@@ -98,12 +99,24 @@ files:
 - program/p1.rb
 - program/p2.rb
 - templates/empty.gtkw
+- templates/empty.rc
 - templates/empty.svcf
 - templates/empty.tcl
+- templates/origen_guides/simulation/app.md.erb
+- templates/origen_guides/simulation/artifacts.md.erb
+- templates/origen_guides/simulation/compiling.md.erb
+- templates/origen_guides/simulation/debugging.md.erb
+- templates/origen_guides/simulation/environment.md.erb
+- templates/origen_guides/simulation/flows.md.erb
+- templates/origen_guides/simulation/howitworks.md.erb
+- templates/origen_guides/simulation/introduction.md.erb
+- templates/origen_guides/simulation/log.md.erb
+- templates/origen_guides/simulation/patterns.md.erb
 - templates/probe.tcl.erb
 - templates/rtl_v/origen.v.erb
 - templates/web/index.md.erb
 - templates/web/layouts/_basic.html.erb
+- templates/web/layouts/_guides.html.erb
 - templates/web/partials/_navbar.html.erb
 - templates/web/release_notes.md.erb
 homepage: 
@@ -125,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.8.11
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.14.1
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: Plugin that provides a testbench environment to simulate Origen test patterns