origen_sim 0.15.0 → 0.16.0

data/pattern/test.rb

@@ -35,6 +35,7 @@ Pattern.create do
 
   ss "Now try and read and write a register"
   dut.cmd.write!(0x1234_5678)
+  tester.marker = 1
   dut.cmd.read!(0x1234_5678)
 
   if tester.sim?
@@ -44,6 +45,7 @@ Pattern.create do
 
   ss "Test storing a register"
   dut.cmd.write!(0x2244_6688)
+  Origen.log.info "Should be within 'Test storing a register'"
   dut.cmd.store!
 
   if tester.sim?

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

@@ -1,15 +1,132 @@
 % render "layouts/guides.html" do
 
+This guide describes some features that are useful for debugging a failing simulation
+or when running
+[an interactive ad-hoc simulation from the console.](<%= path "guides/simulation/app/#Starting_the_Simulator_in_an_Interactive_Session" %>)
+
+#### Identifying Points in Time
+
+All [major step comments](<%= path "guides/pattern/documenting/#Documenting_Major_Steps" %>) in pattern
+source code will be simulation time-stamped and output to the console as shown below:
+
+~~~ruby
+ss "Test basic 2-pin match loop"
+
+# ...
+
+ss "Test a block match loop"
+
+# ...
+~~~
+
+The above will produce this output where the simulation time when each operation occurs is given in ns:
+
+~~~text
+[INFO]       6.710[0.000]    ||      991700 ns: ===========================================================
+[INFO]       6.710[0.001]    ||      991700 ns: Test basic 2-pin match loop
+[INFO]       6.711[0.001]    ||      991700 ns: ===========================================================
+[INFO]       6.711[0.001]    ||     1207500 ns: ===========================================================
+[INFO]       6.712[0.000]    ||     1207500 ns: Test a block match loop
+[INFO]       6.712[0.000]    ||     1207500 ns: ===========================================================
+~~~
+
+All [log output](<%= path "guides/misc/logger" %>) created by application code will also be simulation
+time-stamped and synchronized to simulator progress:
+
+~~~ruby
+Origen.log.info "Something important is happening!"
+~~~
+
+~~~text
+[INFO]       6.712[0.000]    ||    24210200 ns: Something important is happening!
+~~~
+
+
+**Note that applications should avoid the use of `puts` to output debug or status information to the console
+because that will occur immediately and will not be time-stamped or synchronized with the simulator.**
+
+Additionally, the Origen testbench contains a register that can be used to mark events like this:
+
+~~~ruby
+tester.marker = 0x1234
+~~~
+
+You can then view signal `origen.debug.marker` in a wave viewer and search for the appropriate value to
+locate the specific point in time when the mark was applied.
+
+When generating for non-simulation tester targets that statement will do nothing and it can be
+safely left in production code.
+
+
+#### Failed Register Reads
+
+The following information is logged whenever a pin mis-compare occurs within a register read transaction:
+
+* The path (name) of the register
+* Expected data
+* Received (actual) data - requires support from the physical driver, see below
+* Application stack trace to identify where in the application code the read originated
+
+Here is an example:
+
+~~~ruby
+ss "Now try and read and write a register"
+dut.cmd.write!(0x1234_5678)
+dut.cmd.read!(0x1234_5078)  # Note that we just wrote ..567.. but are now expecting ..507..
+~~~
+
+~~~text
+[INFO]       4.098[0.000]    ||       86500 ns: ======================================================================
+[INFO]       4.098[0.001]    ||       86500 ns: Now try and read and write a register
+[INFO]       4.099[0.001]    ||       86500 ns: ======================================================================
+[ERROR]      4.100[0.001]    ||      117400 ns: Miscompare on pin tdo, expected 0 received 1
+[ERROR]      4.101[0.001]    ||      117600 ns: Miscompare on pin tdo, expected 0 received 1
+[ERROR]      4.102[0.001]    ||      129100 ns: Errors occurred reading register cmd:
+[ERROR]      4.102[0.001]    ||      129100 ns: cmd.d: expected 12345078 received 12345678
+[ERROR]      4.103[0.001]    ||      129100 ns:
+[ERROR]      4.104[0.001]    ||      129100 ns: /home/stephen/Code/github/origen_sim/pattern/test.rb:39:in `block in <top (required)>'
+[ERROR]      4.110[0.006]    ||      129100 ns: /home/stephen/Code/github/origen_sim/pattern/test.rb:1:in `<top (required)>'
+~~~
+
+The received data resolution does depend on the physical protocol driver supplying meta-data when
+creating pin assertions (reads) that correspond to register bits, like this:
+
+~~~ruby
+pin(:tdo).assert(bit.data, meta: { position: bit.position })
+~~~
+
+For reference, here is the update that was made to the JTAG driver to support this feature -
+[OrigenJTAG - Add meta data for OrigenSim](https://github.com/Origen-SDK/origen_jtag/pull/10/files)
+
+If the driver has not provided this then a warning will be output and no received data will be given.
+
+This feature will automatically be enabled for any reads launched via the register object itself, e.g.
+`my_reg.read!`, but not for reads launched by calling the `read_register` method manually,
+e.g. `dut.read_register(my_reg)`.
+
+If your application has a tendency to do the latter, then the following modification can be made to your
+`read_register` method to make OrigenSim aware of such transactions:
+
+~~~ruby
+def read_register(reg_or_value, options = {})
+  # Make OrigenSim aware of all transactions to enable failed transaction reporting
+  tester.read_register(reg_or_value, options) do
+
+    # Existing implementation here
+
+  end
+end
+~~~
+
+This feature will also work in the case of the read object being a value rather than a register object.
+
+
+#### Interactive Debugging
+
 The execution of an Origen simulation is fully controlled by Origen/Ruby, this means that if you
 insert a regular Ruby debugger breakpoint into your application code then you can step through the
 simulation in real time.
 
-This guide describes some features that are useful for interacting with the DUT from a simulation
-breakpoint, or when running
-[an interactive ad-hoc simulation from the console.](<%= path "guides/simulation/app/#Starting_the_Simulator_in_an_Interactive_Session" %>)
-
-#### Syncing & Flushing
-
 When a simulation is running most of the communication is one-way, Origen tells the simulator what to do,
 and for performance reasons there is no handshake between Origen and the simulator at every instruction. Instead,
 Origen fires off instructions into a buffer, the simulator executes them as fast as it can, and then Origen

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

@@ -37,12 +37,9 @@ OrigenSim.cadence do |sim|
   # simulation will be abandoned and considered failed. If a particular simulation is known to be slow to start,
   # the timeout can be extended as shown in this example (5 minutes):
   sim.startup_timeout 5 * 60
-  # Sometimes due to different Verilog timescale references, the time specified by Origen may not align to what
-  # is seen in the simulation. For example, your Origen application might define a cycle period of 40ns but in
-  # the simulation this manifests as 400ns. Such differences can be fixed by specifying this time factor which
-  # will be multiplied with all time advancements defined by Origen. This can be any value like 0.01, 0.1, 10,
-  # 100, 1000, etc. to make the cycle period seen in simulation bigger or smaller.
-  sim.time_factor 100
+  # Abort the simulation when this number of errors is reached (defaults to 100).
+  # This can also be overridden at runtime via the --max_errors switch.
+  sim.max_errors = 50
 end
 ~~~
 

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

@@ -7,7 +7,7 @@ By default, OrigenSim will automatically suppress all simulator log output excep
 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
+All log output can be shown in the console by running with the `-verbose` switch, 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

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

@@ -148,6 +148,41 @@ 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.
 
+#### Configuring the Capture Storage Location
+
+By default, both `sim_delay` and `sim_capture` will save their captured data to 
+Org files (Origen native pattern format) using the following file naming rule:
+`Origen.root/pattern/org/<target name>/<capture ID>.org`.
+
+If your application is a top-level application then the default setting should work fine unless you wish
+to share/re-use captured data between multiple targets.
+
+Another reason to change from the default would be if data is captured at plugin-level and this needs
+to be referenced later when running within a top-level application.
+There are potentially two issues in that case:
+
+* `Origen.root` will point to the top-level application's root instead of the plugin's
+* The target name used at the top-level could be different from the one that was used within the plugin to capture
+  the data
+
+In such cases, the default capture directory can be changed by setting the `OrigenSim.capture_dir` attribute.
+This can be set anytime before the first call is made to `sim_delay` or `sim_capture`.
+
+For example, a plugin that needs its captured data to work later as part of a top-level application,
+could set the capture directory in a [startup callback](<%= path "guides/misc/callbacks/#startup(options)" %>),
+like this:
+
+~~~ruby
+def startup(options)
+  # Only modify this if we are the current app or plugin
+  if Origen.app!.current? || Origen.app!.current_plugin?
+    # Use a directory within our root and named after the current IP block, rather than the target
+    OrigenSim.capture_dir = Origen.root!.join('pattern', 'org', dut.myip.name)
+  end
+end
+~~~
+
+
 #### Creating Simulation-Only Assertions
 
 Users are of course encouraged to write patterns that test the DUT via its pin interface since such

data/templates/rtl_v/origen.v.erb

@@ -17,15 +17,14 @@
 // 1 - Initialize drive and assign to 1
 // 2 - Don't initialize drive and assign to Z (default)
 // -1 - Don't initialize drive or assign. Pin will be left unknown
-module pin_driver(error, pin, sync, match_loop);
+module pin_driver(pin, sync);
   parameter init_drive = 2; // Which means don't drive initially, set to 0 or 1 to drive
   parameter pin_name = "undefined_name";
 
-  output reg error;
   inout pin;
   input sync;
-  input match_loop;
 
+  reg error;
   reg [1:0] data = 0;
   reg [1:0] force_data = 0;
   reg compare = 0;
@@ -52,9 +51,8 @@ module pin_driver(error, pin, sync, match_loop);
 
   // pin compare failure logger
   always @(posedge error) begin
-    if (match_loop != 1) begin
-      $display("OrigenSim Error: miscompare on pin %s, expected %d received %d at %t", pin_name, data[0], pin, $time);
-    end
+    //$display("!4![%t] Miscompare on pin %s, expected %d received %d", $time, pin_name, data[0], pin);
+    $bridge_on_miscompare(pin_name, data[0], pin);
   end
   
   // SMcG - needs more work, causes non-genuine fails in OrigenSim test case
@@ -77,7 +75,7 @@ module pin_driver(error, pin, sync, match_loop);
 
   initial begin
     // Set the timescale to ns (-9) with 0 decimal place precision, 20 chars
-    $timeformat(-9, 0, " ns", 20);
+    //$timeformat(-9, 0, "", 20);
     if (init_drive == 1) begin
       drive = 1;
       data[0] = 1;
@@ -89,39 +87,16 @@ module pin_driver(error, pin, sync, match_loop);
 
 endmodule
 
-module pin_drivers(errors, <%= dut.rtl_pins.map { |n, p, o| "#{p.id}_o" }.join(', ') %>);
+module pin_drivers(<%= dut.rtl_pins.map { |n, p, o| "#{p.id}_o" }.join(', ') %>);
 
 % dut.rtl_pins.each do |name, pin, options|
   output <%= pin.id %>_o;
 % end
 
-% dut.rtl_pins.each do |name, pin, options|
-  wire <%= pin.id %>_err;
-% end
-
-  output reg [31:0] errors = 0;
   reg sync = 0;
-  reg [31:0] match_errors = 0;
-  reg match_loop = 0;
-
-  always @(
-
-% dut.rtl_pins.each_with_index do |(name, pin, options), i|
-%   if i == 0
-    posedge <%= pin.id %>_err
-%   else
-    or posedge <%= pin.id %>_err
-%   end
-% end
-  ) begin
-    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|
-  pin_driver #(<%= pin.meta[:origen_sim_init_pin_state].nil? ? '' : ".init_drive(#{pin.meta[:origen_sim_init_pin_state]}), "%>.pin_name("<%= pin.id %>")) <%= pin.id %>(.pin(<%= pin.id %>_o), .error(<%= pin.id %>_err), .sync(sync), .match_loop(match_loop));
+  pin_driver #(<%= pin.meta[:origen_sim_init_pin_state].nil? ? '' : ".init_drive(#{pin.meta[:origen_sim_init_pin_state]}), "%>.pin_name("<%= pin.id %>")) <%= pin.id %>(.pin(<%= pin.id %>_o), .sync(sync));
 % end
 
 
@@ -157,8 +132,10 @@ module snapshot_details;
 
 endmodule
 
-module debug(errors);
-  input [31:0] errors;
+module debug;
+  reg [31:0] errors = 0;
+  reg [15:0] marker = 0;
+  reg [31:0] match_errors = 0;
 
   reg [1023:0] pattern = 0;
 % OrigenSim::NUMBER_OF_COMMENT_LINES.times do |i|
@@ -179,13 +156,10 @@ module origen;
   wire <%= pin.id %>;
 % end
 
-  wire [31:0] errors;
-
   pin_drivers pins (
 % dut.rtl_pins.each_with_index do |(name, pin, options), i|
-    .<%= pin.id %>_o(<%= pin.id %>),
+  .<%= pin.id %>_o(<%= pin.id %>)<%= i == dut.rtl_pins.size - 1 ? '' : ',' %>
 % end
-    .errors(errors)
   );
 
   // Instantiate the DUT
@@ -205,7 +179,7 @@ module origen;
 %       pin.primary_group.each_with_index do |pin, i|
       <%= pin.id %><%= i == (pin.primary_group.size - 1) ? '' : ',' %>
 %       end
-    })<%= i == (dut.rtl_pins.size - 1) ? '' : ',' %>
+    })<%= (i + pin.primary_group.size) == dut.rtl_pins.size ? '' : ',' %>
 %       seen_groups << pin.primary_group
 %     end
 %   else
@@ -214,17 +188,11 @@ module origen;
 % end
   );
 
-  debug debug (
-    .errors(errors)
-  );
+  debug debug ();
 
 `ifdef ORIGEN_VCD 
   initial
   begin
-    //$display("********************************");
-    //$display("Creating origen.vcd...");
-    //$display("********************************");
-    //$dumpfile("origen.vcd");
     $dumpvars(0,origen);
   end
 `endif
@@ -248,9 +216,6 @@ module origen;
 
 
   always @(posedge finish) begin
-    //$display("********************************");
-    //$display("Finishing simulation...");
-    //$display("********************************");
     $finish(2);
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_sim
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-11 00:00:00.000000000 Z
+date: 2019-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.41.0
+        version: 0.43.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.41.0
+        version: 0.43.0
 - !ruby/object:Gem::Dependency
   name: origen_testers
   requirement: !ruby/object:Gem::Requirement
@@ -143,7 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.8.11
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Plugin that provides a testbench environment to simulate Origen test patterns