origen_sim 0.12.0 → 0.13.0

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

@@ -0,0 +1,135 @@
+% render "layouts/guides.html" do
+
+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
+periodically waits for the simulator to catch up if it is running too far ahead.
+
+If you have entered a breakpoint and you suspect that the simulator may be still catching up, you can run:
+
+~~~ruby
+tester.sync_up
+~~~
+
+When that method returns you are guaranteed that the simulator is at the same point.
+
+Note that most of the time you will not need to do this manually since Origen will automatically sync up for
+any operation that involves reading data from the simulation, e.g. peeking or reading registers.
+
+If you have a wave viewer open during the debug session it may still look like the simulation is running behind, or the
+wave viewer may appear to hang if you have tried to refresh it.
+This is because the simulator is buffering output that has yet to be written to the wave dump.
+
+You can force it to flush the buffer and update the wave viewer by running:
+
+~~~ruby
+tester.flush
+~~~
+
+Note that flushing will internally call a `sync_up` so you don't have to do both of these manually.
+
+#### Accessing the DUT's Internal Nets
+
+The methods `tester.simulator.peek` and `tester.simulator.poke` are available for reading and writing values
+to internal DUT nets respectively.
+
+See the section on [Creating Simulation-Only Assertions](<%= path "guides/simulation/patterns/#Creating_Simulation-Only_Assertions" %>)
+for more details on these.
+
+#### Register Reading (and Writing)
+
+Referencing a register from the console will show you what Origen thinks the register currently contains:
+
+~~~text
+dut.my_block.my_reg
+
+=>
+0x10008000 - :my_reg
+   ===============================================================================================================
+  │     15      │     14      │     13      │     12      │     11      │     10      │      9      │      8      │
+  │                                                    d[15:8]                                                    │
+  │                                                      0x0                                                      │
+  ├─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
+  │      7      │      6      │      5      │      4      │      3      │      2      │      1      │      0      │
+  │                                                    d[7:0]                                                     │
+  │                                                      0x0                                                      │
+  └─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘
+
+~~~
+
+However, this may not be what the simulation currently reflects. To see what the simulation holds, call `sync`
+on the register:
+
+~~~text
+dut.my_block.my_reg.sync
+
+=>
+0x10008000 - :my_reg
+   ===============================================================================================================
+  │     15      │     14      │     13      │     12      │     11      │     10      │      9      │      8      │
+  │                                                    d[15:8]                                                    │
+  │                                                     0x8E                                                      │
+  ├─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
+  │      7      │      6      │      5      │      4      │      3      │      2      │      1      │      0      │
+  │                                                    d[7:0]                                                     │
+  │                                                     0xFF                                                      │
+  └─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘
+
+~~~
+
+A convenience API exists for this by appending `!` to the register name:
+
+~~~text
+dut.my_block.my_reg!
+~~~
+
+Note that this works by firing off a conventional `read_register` request to your DUT model/controller.
+
+That means that it should work for breakpoints in the majority of application code, however if you have stopped it
+or stepped into a place in low-level code, such as in the middle of a prior transaction, then this feature may not work.
+
+#### Advancing Time
+
+If you have just written to a register, it may kick off some operation within the DUT and time (clock cycles)
+will be required before you will be able to observe the response.
+
+It is important to understand that the simulator is also paused during a breakpoint and therefore simulation time
+is not continuing to run while you are at the console.
+
+Simulation time can be advanced by calling the usual `tester.wait` API, however these convenience APIs exist for advancing
+time during a debugger breakpoint (and they can also be used in source code if you wish):
+
+~~~ruby
+10.cycles
+
+10.ns!
+
+10.us!
+
+10.ms!
+
+10.s!
+~~~
+
+Note that 10 is just used as an example here, you can apply any number that you want.
+
+
+#### Checking The Error Count
+
+You can query the current error count by running:
+
+~~~ruby
+tester.simulator.error_count   # => 0
+~~~
+
+% end

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

@@ -0,0 +1,217 @@
+% render "layouts/guides.html" do
+
+By convention, the OrigenSim simulator driver is configured within the file `environment/sim.rb`.
+
+Usually the simulator configuration may be different for each DUT target, so often this file is structured like this
+to enable a single Origen simulation environment setup file to support multiple DUT targets within the
+application:
+
+~~~ruby
+# environment/sim.rb
+
+case Origen.target.name
+
+when "my_dut1"
+  OrigenSim.cadence do |sim|
+    # Configuration of Cadence simulator to be used for DUT1 here
+  end
+
+when "my_dut2"
+  OrigenSim.synopsys do |sim|
+    # Configuration of Synopsys simulator to be used for DUT2 here
+  end
+
+else
+  Origen.log.error "No simulation environment has been setup for target #{Origen.target.name}, edit environment/sim.rb to add one."
+  exit 1
+end
+~~~
+
+#### Configuring The Simulator
+
+Here is an example of configuring the simulator with some generic options that are supported by all simulators:
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  # By default a simulation will be given 60 seconds to startup, if it fails to start within this time the
+  # 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
+end
+~~~
+
+Note that defining a configuration like this will also instantiate an instance of `OrigenSim::Tester` and assign it to
+the global variable `tester`.
+This `tester` object will behave like any other Origen tester driver and your application will be unaware that it is
+driving a simulator rather than an ATE-specific pattern renderer.
+
+Note also that the `post_process_run_cmd` option is available for all simulators, however it is reserved for discussion
+later in this guide since it is more of an advanced topic.
+
+#### Cadence (irun) Specific Configuration
+
+Additionally, a Cadence simulator setup supports the following vendor-specific options:
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  # By default the simulation will be run by calling 'irun', this can be changed to anything you want, but it
+  # is usually a good idea to use this option to lock to a specific version of irun (the same version that was
+  # used to compile the DUT snapshot)
+  sim.irun '/tools/cadence/15.10.023/bin/irun'
+  # The default wave viewer is 'simvision', this can also be changed
+  sim.simvision '/tools/cadence/15.10.023/bin/simvision'
+  # The cadence simulator configuration does support the use of forces, though this is generally discouraged
+  sim.force {
+    'origen.dut.vref_0v8' => 1,
+    'origen.dut.pmc.some.internal.node' => 1,
+  }
+  # Custom probes can be specified, e.g. to include memory contents in the wave dump
+  sim.tcl_inputs %Q(
+    probe -create -shm origen.dut.mems.user -all -memories -variables -unpacked 262144 -depth all
+    probe -create -shm origen.dut.mems.cache -all -memories -variables -unpacked 262144 -depth all
+  )
+end
+~~~
+
+#### Synopsys Specific Configuration
+
+Here are the vendor-specific options for Synopsys:
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  # By default the simulation will be run by calling 'vcs', this can be changed to anything you want, but it
+  # is usually a good idea to use this option to lock to a specific version of vcs (the same version that was
+  # used to compile the DUT snapshot)
+  sim.vcs "/tools/synopsys/L-2016.06/bin/vcs"
+  # The default wave viewer is 'dve', this can also be changed
+  sim.dve "/tools/synopsys/L-2016.06/bin/dve"
+end
+~~~
+
+Origen Sim also offers the option to use Verdi as a wave viewer instead of 'dve', the vendor-specific options for Synopsys w/Verdi would be: 
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  sim.vcs "/tools/synopsys/L-2016.06/bin/vcs"
+  sim.verdi "/tools/synopsys/L-2016.06/bin/verdi"
+end
+~~~
+
+#### Icarus Verilog Specific Configuration
+
+Here are the vendor-specific options for Icarus Verilog:
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  # By default the simulation will be run by calling 'vvp', this can be changed to anything you want, but it
+  # is usually a good idea to use this option to lock to a specific version of vvp (the same version that was
+  # used to compile the DUT snapshot)
+  sim.vvp "/tools/icarus/0.9.7/bin/vvp"
+  # The default wave viewer is 'gtkwave', this can also be changed
+  sim.gtkwave "/tools/gtkwave/3.3.66/bin/gtkwave"
+end
+~~~
+
+#### Generic and Advanced Simulator Configuration
+
+A generic simulator configuration allows you to use a tool that is not supported out of the box by <code>OrigenSim</code>. For these, it 
+is your responsibility to provide the command to start the simulation process, however, this allows for arbitrary commands to
+start the process and allows end users to still use <code>origen g</code> as if with a fully <code>OrigenSim</code> supported
+simulator configuration.
+
+An example of such a configuration could be:
+
+~~~ruby
+OrigenSim.generic do |sim|
+  sim.generic_run_cmd do |s|
+    # Return the command to start the simulation
+    "path/to/custom/sim/script +socket+#{s.socket_id}"
+  end
+end
+~~~
+
+Here is an example using the predecessor of the supported Cadence tool <code>irun</code>, <code>ncsim</code>:
+
+~~~ruby
+OrigenSim.generic do |sim|
+  sim.testbench_top 'na_origen'
+  sim.generic_run_cmd do |s|
+    "ncsim na_origen -loadpli origen.so:bootstrap +socket+#{s.socket_id}"
+  end
+end
+~~~
+
+The following commonly used options are available to a generic simulation configuration:
+
+* `testbench_top` - Defines the testbench name if different from <code>origen</code>.
+* `view_waveform_cmd` - Required for generic configurations - prints out this statement following a simulation instructing the
+user on how to open the waveforms for viewing. For supported simulators, this is already provided, but can be overwritten.
+* `generic_run_cmd` - Either a string, array to be joined by ' && ', or a block returning either of the aforementioned that
+the generic configuration will use to launch the simulation.
+* `post_process_run_cmd` - Block object to post-process the command that OrigenSim will launch the simulation with. This can be used
+to post-process the command for any supported vendor. This block should return the command to run, as a string.
+
+An example of the <code>post_process_run_cmd</code> usage is:
+
+~~~ruby
+OrigenSim.cadence do |sim|
+  sim.post_process_run_cmd do |cmd, s|
+    # cmd is the current command that will be run. s is the simulator object, same as sim in this case.
+    # this should return either a string or an array to be joined by ' && ' (chain commands)
+    # note that we must RETURN the string. We cannot just edit it.
+    
+    # add an environment variable and run setup script as an example
+    return "export PROJECT=my_rtl && source #{Origen.app.root.join('settings.sh')} && #{cmd}"
+    
+    # or, we could return
+    return [
+      'export PROJECT=my_rtl',
+      "source #{Origen.app.root.join('settings.sh')}",
+      cmd
+    ]
+    #=> "export PROJECT=my_rtl && source #{Origen.app.root.join('settings.sh')} && #{cmd}"
+  end
+end
+~~~
+
+#### Simulation Object Checkin/Checkout
+
+Environment setups can also include information on the url and version of where the compiled simulation object
+is to be stored - often this will not be checked into the same repository as the main application code since
+for example Git, which is good for application code storage, is not really so good for storing large binaries
+like the simulation objects.
+
+Here is an example setup:
+
+~~~ruby
+OrigenSim.synopsys do |sim|
+  sim.rc_dir_url 'sync://sync-12345:12345/Projects/origen_sim_snapshots'
+  sim.rc_version 'Trunk'
+end
+~~~
+  
+The `rc_dir_url` option should point to a directory in the repository where the snapshot files should be
+stored, not to the snapshot file itself.
+
+The `rc_version` can be set to the version to use, which can be a pointer to latest like 'Trunk' or 'master' or
+to an absolute version.
+
+The object should be committed to the repository by running the `origen sim:ci` command with the environment/target
+setup to select the object to be checked in.
+Origen Sim will then automatically tar up the object and check it in.
+
+This same command can be run again in future to check in new versions.
+
+Origen Sim will then automatically check for the presence of the object in the local workspace and will fetch
+it as required - i.e. if not present or if the `rc_version` has been updated.
+
+Note that when a latest pointer is used as the version, the remote repository is not automatically checked for updates.
+If you want to fetch the latest version or force a re-checkout at anytime you can run the `origen sim:co` command.
+
+% end

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

@@ -0,0 +1,69 @@
+% render "layouts/guides.html" do
+
+A flow, meaning a sequence of patterns, can be simulated in two ways - by supplying
+a list of patterns or by configuring a test program generator flow to support simulation.
+
+#### Simulating a Pattern List
+
+If you were to run this:
+
+~~~text
+origen g my_pat_1 my_pat_2 -e environment/sim.rb
+~~~
+
+then it would run the two patterns as two independent simulations, creating two waveforms named after each pattern.
+
+They can be combined into a single simulation by adding a `--flow` option:
+
+~~~text
+origen g my_pat_1 my_pat_2 -e environment/sim.rb --flow my_flow
+~~~
+
+This will simulate the given patterns back-back and dump them to a waveform named after the flow option, in this case "my_flow".
+
+The list of patterns can also be supplied via a list file:
+
+
+~~~text
+origen g list/regression.list -e environment/sim.rb --flow regression
+~~~
+
+#### Simulating a Test Program Flow
+
+To simulate a pattern sequence defined by a [test program flow](<%= path "guides/program/flows" %>), it is necessary
+to [setup your interface](<%= path "guides/program/interface" %>) to support the simulation tester driver
+as if it were another ATE.
+
+The simulation tester driver has no concept of test methods, suites or instances, so its interface setup is very simple -
+once you have the pattern name simply pass that to the `test` method:
+
+~~~ruby
+# Example interface method
+def func(name, options = {})
+  # Resolve the pattern name as required
+  pattern = extract_pattern_name(name, options)
+
+  if tester.sim?
+    test(pattern, options)
+
+  elsif tester.v93k?
+    t = test_suites.add(:vreg_func)
+    t.test_method = test_methods.origen.functional_test
+    t.pattern = pattern
+    test(t, options)
+
+  else
+    fail "The test program interface has not been setup for #{tester.class}!"
+  end
+end
+~~~
+
+To simulate the flow, run the program generator as normal but with the simulation environment selected:
+
+~~~text
+origen p program/my_flow.rb -e environment/sim.rb
+~~~
+
+The generated wave will be named after the flow, _my_flow_ in this example.
+
+% end

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

@@ -0,0 +1,64 @@
+% render "layouts/guides.html" do
+
+Here are some technical details on how OrigenSim works which should provide some context when it comes
+to [compiling your DUT design to work with OrigenSim](<%= path "guides/simulation/compiling" %>).
+
+Origen provides components that can be compiled into a simulation object along with the design under test (DUT),
+a high level view of the process looks like this:
+
+<img src="https://user-images.githubusercontent.com/158364/28324051-6a149088-6bd2-11e7-936d-49ec87b2c0bb.png" alt="origen_sim" style="
+    width: 100%;
+">
+
+The main Origen Ruby process is invoked by generating a pattern as usual, e.g. <code>origen g my_pattern</code>,
+but with the environment setup to instantiate an instance of <code>OrigenSim::Tester</code> instead of say
+<code>OrigenTesters::V93K</code>.
+The OrigenSim tester will start off a Verilog process in parallel which will run a simulation on an object that
+has been created beforehand. This simulation object contains the DUT wrapped in an OrigenSim testbench, and which
+has been compiled into a snapshot/object that also includes a [Verilog VPI](https://en.wikipedia.org/wiki/Verilog_Procedural_Interface)
+extension which provides a communication interface between Origen and the simulation world.
+
+When the simulation process starts, the VPI extension immediately takes control and halts the simulator while it
+listens for further instructions from a Linux socket which was setup by OrigenSim before the simulation was started.
+As the Origen pattern generation process executes, the <code>OrigenSim::Tester</code> will translate any requests
+to drive or expect pin values, or to generate a cycle, into messages which are passed into the Linux socket.
+Upon receving these messages, the VPI process will manipulate the testbench's pin drivers to drive or read from
+the DUT and it will advance time by a cycle period every time a cycle is generated in the pattern.
+The testbench to wrap and instantiate the DUT is generated by OrigenSim and it provides a standard interface through
+which Origen can access any DUT.
+
+In principle the DUT object can be any design view that is wrapped by a conventional top-level Verilog module, meaning that
+OrigenSim can be used to run RTL or gate-level simulations depending on what has been compiled into the snapshot.
+
+**Note also that the DUT can be either an IP-block or an SoC, and so OrigenSim can be used equally well for running
+both IP-level and top-level simulations.**
+
+### The Testbench
+
+The testbench is quite simple and it does little more than instantiate the DUT module and connect all of its pins to
+instances of [this pin driver module](https://github.com/Origen-SDK/origen_sim/blob/master/templates/rtl_v/origen.v.erb#L14).
+The testbench module is named `origen` by default and all OrigenSim simulation dumps will have this same top-level structure:
+
+~~~text
+.
+└── my_pattern
+    └── origen
+        ├── debug     // Contains an error count, pattern name and comments, and other debug aids
+        ├── dut       // Your DUT
+        └── pins
+           ├── tdi    // Driver for the TDI pin (for example)
+           ├── tdo
+           └── tck
+~~~
+
+
+The driver contains a number of registers which are written to directly by the VPI process, allowing it to drive or expect a
+given data value (stored in <code>origen.pins.MYPIN.data</code>) by writing a 1 to <code>origen.pins.MYPIN.drive</code>
+or <code>origen.pins.MYPIN.compare</code> respectively.
+If the value being driven by the pin does not match the expect data during a cycle, then an error signal will be asserted by the
+driver and this will increment an error counter that lives in <code>origen.debug.errors[31:0]</code>.
+
+An error count > 0 will result in the pattern simulation status being reported as a FAIL by Origen and this can be used
+to create simulation-based regression test suites for your application.
+
+% end