origen_sim 0.12.0 → 0.13.0

data/templates/empty.tcl

@@ -7,8 +7,8 @@
 # 	TopLevel.1
 # 	TopLevel.2
 #   Source.1: origen.dut
-#   Wave.1: 3 signals
-#   Group count = 2
+#   Wave.1: 12 signals
+#   Group count = 3
 #   Group Debug signal count = 3
 #   Group DUT signal count = 0
 # End_DVE_Session_Save_Info
@@ -69,7 +69,7 @@ if {![gui_exist_window -window TopLevel.1]} {
 } else { 
     set TopLevel.1 TopLevel.1
 }
-gui_show_window -window ${TopLevel.1} -show_state normal -rect {{525 653} {2223 1819}}
+gui_show_window -window ${TopLevel.1} -show_state normal -rect {{529 678} {2226 1843}}
 
 # ToolBar settings
 gui_set_toolbar_attributes -toolbar {TimeOperations} -dock_state top
@@ -149,7 +149,7 @@ if {![gui_exist_window -window TopLevel.2]} {
 } else { 
     set TopLevel.2 TopLevel.2
 }
-gui_show_window -window ${TopLevel.2} -show_state normal -rect {{293 121} {2365 1172}}
+gui_show_window -window ${TopLevel.2} -show_state normal -rect {{297 146} {2368 1196}}
 
 # ToolBar settings
 gui_set_toolbar_attributes -toolbar {TimeOperations} -dock_state top
@@ -241,15 +241,42 @@ set _session_group_1 Debug
 gui_sg_create "$_session_group_1"
 set Debug "$_session_group_1"
 
-gui_sg_addsignal -group "$_session_group_1" { origen.debug.pattern origen.debug.comments origen.debug.errors }
+gui_sg_addsignal -group "$_session_group_1" { origen.debug.pattern origen.debug.errors }
 gui_set_radix -radix {ascii} -signals {V1:origen.debug.pattern}
 gui_set_radix -radix {unsigned} -signals {V1:origen.debug.pattern}
-gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments}
-gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments}
 
-set _session_group_2 DUT
+set _session_group_2 $_session_group_1|
+append _session_group_2 Comments
 gui_sg_create "$_session_group_2"
-set DUT "$_session_group_2"
+set Debug|Comments "$_session_group_2"
+
+gui_sg_addsignal -group "$_session_group_2" { origen.debug.comments0 origen.debug.comments1 origen.debug.comments2 origen.debug.comments3 origen.debug.comments4 origen.debug.comments5 origen.debug.comments6 origen.debug.comments7 origen.debug.comments8 origen.debug.comments9 }
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments0}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments0}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments1}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments1}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments2}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments2}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments3}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments3}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments4}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments4}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments5}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments5}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments6}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments6}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments7}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments7}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments8}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments8}
+gui_set_radix -radix {ascii} -signals {V1:origen.debug.comments9}
+gui_set_radix -radix {unsigned} -signals {V1:origen.debug.comments9}
+
+gui_sg_move "$_session_group_2" -after "$_session_group_1" -pos 1 
+
+set _session_group_3 DUT
+gui_sg_create "$_session_group_3"
+set DUT "$_session_group_3"
 
 
 # Global: Highlighting
@@ -317,6 +344,7 @@ gui_list_create_group_when_add -wave -disable
 gui_marker_set_ref -id ${Wave.1}  C1
 gui_wv_zoom_timerange -id ${Wave.1} 0 353973502
 gui_list_add_group -id ${Wave.1} -after {New Group} {Debug}
+gui_list_add_group -id ${Wave.1}  -after {origen.debug.pattern[1023:0]} {Debug|Comments}
 gui_list_add_group -id ${Wave.1} -after {New Group} {DUT}
 gui_seek_criteria -id ${Wave.1} {Any Edge}
 

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

@@ -0,0 +1,131 @@
+% render "layouts/guides.html" do
+
+Generally speaking, an Origen application setup is the same whether you are generating
+a pattern/flow for the ATE or if you wish to simulate it.
+
+Therefore, the rest of the guides are applicable for how to setup a [model](<%= path "guides/models/introduction" %>) and a
+[controller](<%= path "guides/controllers/introduction" %>) for your DUT,
+and how to create a [pattern](<%= path "guides/patterns/introduction" %>).
+
+However, there are still a few simulation-specific points that are worth noting to help
+make your application simulation-ready.
+
+#### Pin Definitions
+
+To simulate, you will at the very least need a model that corresponds to your DUT and which
+defines the pins that you want to wiggle.
+
+It is not necessary to define all the pins of your DUT in the model, but for those that you do
+define the IDs should match up between the model and the top-level Verilog module for your
+DUT.
+
+The easiest way to achieve this is to define your model's pins by importing the pins that were
+extracted from the design (using `sim:build` as described in the 
+[Compiling the DUT section](<%= path "guides/simulation/compiling" %>)).
+
+This will guarantee that your model exactly matches the design, and if you want
+to use different pin names in the ATE patterns you can define these as aliases and add a
+[`pin_pattern_order` statement](<%= path "guides/pattern/pins/#Controlling_the_Pattern_Pin_Order" %>)
+to choose the alias instead of the h/ware names:
+
+~~~ruby
+module MyApp
+  class MyDUT
+    include Origen::TopLevel
+
+    def initialize(options = {})
+      import 'my_dut', dir: "#{Origen.root!}/vendor/pins", namespace: nil
+
+      # Add aliases if you want to use different names in your application and in ATE patterns
+      add_pin_alias :resetn, :reset_neg_async
+    end
+  end
+end
+~~~
+
+Alternatively, if you already have your pins defined manually in the application and you need to
+reconcile these with what they are called in the design, then you can add the `rtl_name` attribute
+to your definition:
+
+~~~ruby
+add_pin :resetn, rtl_name: :reset_neg_async
+~~~
+
+Once you have your pins defined, you can immediately create a pattern and simulate it
+to see if you can see the pins wiggling!
+
+~~~ruby
+# pattern/sign_of_life.rb
+
+Pattern.create do
+  10.times do
+    dut.pin(:my_pin).drive!(1)
+    dut.pin(:my_pin).drive!(0)
+  end
+end
+~~~
+
+To simulate it:
+
+~~~text
+origen g sign_of_life -e environment/sim.rb
+~~~
+
+#### Simulation Startup
+
+When simulating a pattern, the same [startup callback](<%= path "guides/misc/callbacks/#Pattern_Generation" %>)
+(that you might use to implement a mode entry or other setup sequence) will be called as it would
+when you are generating for an ATE.
+
+However, sometimes you may need to do some additional setup in simulation, for example to drive
+some power pins that would be handled by a power supply on an ATE - i.e. they are not normally
+cared about in the pattern.
+
+A simulation-specific callback exists for this purpose, this will be called immediately upon a
+simulation starting and before the pattern or flow creation gets underway - i.e. it will be
+called before the regular `startup` callback.
+
+~~~ruby
+def simulation_startup
+  # Drive these power pins to 1, these are not included in the ATE patterns and will be handled
+  # be a power supply on the tester
+  pin(:vdd).drive(1)
+  pin(:vddc).drive(1)
+  pin(:vss).drive(0)
+end
+~~~
+
+**Note that if multiple patterns are being generated back-back in a single simulation, then the
+`simulation_startup` will only be called once at the very start of the simulation. In contrast,
+the `startup` method will be called at the start of every individual pattern within the simulation.**
+
+#### Simulation Specific Code
+
+Any simulation-specific code in your application can be gated as shown below:
+
+~~~ruby
+if tester.sim?
+  # Only executed when simulating
+end
+~~~
+
+#### Starting the Simulator in an Interactive Session
+
+When in an interactive session (`origen i`) the simulator can be started by typing
+`tester.start`.
+
+If you want this to happen automatically every time you start an interactive session when
+the simulation environment is selected, add this to the [interactive startup callback](<%= path "guides/misc/callbacks/#interactive_startup" %>):
+
+~~~ruby
+def interactive_startup
+  # Always start the simulator immediately if I open an interactive session with the
+  # simulation environment selected
+  tester.start if tester.sim?
+end
+~~~
+
+See [the debugging guide](<%= path "guides/simulation/debugging" %>) for details about APIs
+that are useful when interacting with your DUT in a live ad-hoc simulation from the console.
+
+% end

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

@@ -0,0 +1,115 @@
+% render "layouts/guides.html" do
+
+When OrigenSim runs, it will change the current directory to run the simulator. This is not necessarily the
+same directory that the compiled snapshot resides in and will most likely break relative paths compiled into the
+snapshot.
+
+OrigenSim provides an <code>artifacts</code> API to handle this problem. <code>Artifacts</code> are just files or
+directories that need to be available in the run directory prior to the simulation start. This can be used to
+reconstruct the run directory regardless of vendor or target configurations, and without requiring you to build in the
+logic into the application itself.
+
+OrigenSim will automatically look for artifacts in the directory <code>#{Origen.app.root}/simulation/application/artifacts</code>.
+Anything in the this folder will be moved to the run directory and placed in <code>application/artifacts</code> just before the
+simulation process starts. These artifacts will be populated across targets. You can override an artifact with one
+specific to your target by placing an artifact with the same name in <code>simulation/TARGET/artifacts</code>. 
+
+For example, if I have an artifact <code>simulation/application/artifacts/startup.sv</code> that I need for 
+three targets, <code>rtl</code>, <code>part_analog</code>, and <code>all_analog</code>, this same artifact will be used
+whenever any of those targets are used. Then, consider I have a new target <code>gate</code>, which has a different
+<code>startup.sv</code> to run. By placing this at <code>simulation/gate/artifacts/startup.sv</code>, OrigenSim
+will replace the artifact in <code>simulation/application/artifacts</code> with this one, in the same run directory.
+
+Warning: Default artifacts only go a single level deep. Directories placed at <code>simulation/TARGET/artifacts</code>
+will override an entire directory at <code>application/artifacts</code>. If you need more
+control over the artifacts, you can see further down in this guide for manually adding artifacts.
+
+OrigenSim provides two further customizations to the default setup. Like the target directory, you can pass additional
+<code>user_artifact_dirs</code>, which will override any artifacts found at either the default or target artifact levels.
+These artifacts will override each other in the order of the Array definition.
+
+All of these artifacts have different sources, but they are placed in the same <code>artifact_run_dir</code>, which
+defaults to <code>application/artifacts</code>. This location is customizable as well with the <code>artifact_run_dir</code>
+option.
+
+~~~ruby
+OrigenSim::cadence do |sim|
+  # Add a user artifact directory
+  sim.user_artifact_dirs ["#{Origen.app.root}/simulation/testbench"]
+
+  # Change the artifact target location, within the context of the run directory.
+  # NOTE: this is relative to the run directory. This expands to /path/to/run/dir/testbench
+   sim.artifact_run_dir "./testbench"
+end
+~~~
+
+Note here that the <code>artifact_run_dir</code> is <b>implicitly relative</b> to the
+run directory. Relative paths are expanded in the context of the run directory, <b>not</b> relative to
+the current script location.
+
+Artifacts can be populated either by symlinks or by copying the contents directly. By default, Linux will symlink the
+contents and unlink to clean them. However, due to the elevated priveledges required by later Windows systems to symlink objects,
+the default behavior for Windows is to just copy files. This does mean that larger, and/or a large number, of artifacts
+may take longer. This behavior can be changed however:
+
+~~~ruby
+OrigenSim::cadence do |sim|
+  # Force all artifacts to be copied
+  artifact_populate_method :copy
+	
+  # Force all artifacts to be symlinked
+  artifact_populate_method :symlink
+end
+~~~
+
+OrigemSim's artifacts can be queried, populated, or cleaned, directly by accessing the <code>OrigenSim.artifact</code>
+object (note: the exclusion of the <i>s</i>). Some methods also exist to retrieve and list the current artifacts:
+
+~~~ruby
+# Populate all the artifacts
+tester.simulator.artifact.populate
+
+# Clean the currently populated artifacts
+tester.simulator.artifact.clean
+
+# List the current artifact names
+tester.simulator.list_artifacts
+
+# Retrieve the current artifact instances (as a Hash whose keys are the names returned above)
+tester.simulator.artifacts
+
+# Retrieve a single artifact
+tester.simulator.artifacts[my_artifact]
+tester.simulator.artifact[my_artifact]
+~~~
+
+The <code>OrigenSim::Artifacts</code> class inherits from
+[Origen::Componentable](http://origen-sdk.org/origen/guides/models/componentable/#The_Parent_Class),
+so any of the <i>componentable</i> methods are available.
+
+Additional single-artifact items can be added manually:
+
+~~~ruby
+# in environment/sim.rb
+
+tester = OrigenSim::cadence do |sim|
+end
+
+tester.simulator.artifact(:my_artifact) do |a|
+  # Point to a custom target
+  a.target "/path/to/my/artifact.mine"
+
+  # Point to a custom run target
+  # Recall this will expand to /path/to/run/dir/custom_artifacts
+  # This ultimately places the artifact at /path/to/run/dir/custom_artifacts/artifact.mine
+  a.run_target "./custom_artifacts"
+
+  # Indicate this artifact should be copied, regardlesss of global/OS settings.
+  a.populate_method :copy
+end
+~~~
+
+Note that this takes place <b>outside</b> of the initial tester instantiation, but can still occur in the environment
+file.
+
+% end

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

@@ -0,0 +1,190 @@
+% render "layouts/guides.html" do
+
+The details of how to build a given IP or SoC design can be complicated and can vary significantly
+from case to case; it is something that is best managed by the design or verification team for
+a given design under test (DUT).
+
+Therefore, OrigenSim does not attempt to manage the simulation build process but instead provides
+components that should be integrated into the target DUT's existing design build flow in order to
+produce an output that is compatible with OrigenSim.
+
+#### High-Level Flow
+
+The high-level flow that we are aiming for here is as follows:
+
+1. The design flow owner runs an Origen command to create the Origen components, the top-level Verilog
+   is supplied as an input to this command and this will be used to create a DUT-specific Origen testbench
+2. The design flow owner incorporates these components into their build flow and executes it, stopping
+   after elaboration to create the Origen simulation object
+3. The design flow owner delivers the Origen simulation object to the Origen flow owner (e.g. the test engineer)
+4. The Origen flow owner integrates this simulation object into an Origen application
+
+This process should be repeated from step 1 anytime either of the following occur:
+
+* Changes are made to the top-level pin interface of the DUT
+* A new version of OrigenSim is available with some new features that need to be compiled into the DUT
+
+The process should be repeated from step 2 anytime:
+
+* Changes have been made to the internal operation of the DUT (design changes) and you wish to be included
+  in Origen simulations
+
+
+#### Creating the Origen Components
+
+The OrigenSim plugin provides a command called `sim:build` to create the Origen components that should
+be incorporated into the design build process.
+
+To check if this is available, run the `origen` command outside of an application workspace, you should
+see something like this:
+
+~~~text
+> origen
+
+Usage: origen COMMAND [ARGS]
+
+The following commands are available:
+ new                Create a new Origen application or plugin. "origen new my_app" creates a
+                    new origen application workspace in "./my_app"
+ interactive        Start an interactive Origen console (short-cut alias: "i"), this is just
+                    IRB with the 'origen' lib loaded automatically
+
+The following global commands are provided by plugins:
+ sim:build          Build an Origen testbench and simulator extension for a given design
+
+Many commands can be run with -h (or --help) for more information.
+~~~
+
+Note the `sim:build` command is noted as being provided by a plugin at the bottom. If you don't see that
+then it means that OrigenSim needs to be installed into your global Ruby, if you have the required admin
+rights you can do this by simply executing:
+
+~~~text
+gem install origen_sim
+~~~
+
+If you don't have the required permission then speak to your system administrator to have them do this.
+More detailed information on how to manage your globally available plugins like this can be found in
+the [advanced guide on how Origen is invoked](<%= path "guides/advanced/invocations" %>).
+
+If the `origen` command does not work at all, then first refer
+to [the guide on how to install Origen](<%= path "guides/starting/installing" %>).
+
+Once you have verified that you have the `sim:build` command available, execute it by supplying the
+path to your top-level Verilog file like this:
+
+~~~text
+origen sim:build path/to/my_top_level.v
+~~~
+
+**It is highly recommended that you supply a stub model here, all that Origen needs to know about is the
+top-level pin interface and reducing the amount of superfluous design code will reduce the chance
+of parse errors during this step.**
+
+Multiple files can be passed in, for example to include a defines file:
+
+~~~text
+origen sim:build path/to/my_defines.v path/to/my_top_level.v
+~~~
+
+If you prefer, it also works by supplying the source file directory path(s) separately:
+
+~~~text
+origen sim:build my_defines.v my_top_level.v -s path/to
+~~~
+
+The `sim:build` command does have some rudimentary support for evaluating and applying Verilog compiler
+directive rules, though at the time of writing it does not evaluate Verilog parameters.
+
+If you find that it does choke on your design files please do enter a ticket describing the code
+which failed to parse here - <https://github.com/Origen-SDK/origen_verilog/issues>
+
+In most cases any parse issues can be resolved by moving to a stub model or by simply removing the
+offending code to create a partial stub.
+
+Once you see a message like this, you are ready to move onto the next step:
+
+~~~text
+-----------------------------------------------------------
+
+Testbench and VPI extension created!
+
+This file can be imported into an Origen top-level DUT model to define the pins:
+
+  /path/to/origen/my_top_level.rb
+
+See above for what to do now to create an Origen-enabled simulation object for your particular simulator.
+
+~~~
+
+#### Building the Design
+
+We need to start from a command which can compile and elaborate the DUT only, so any 3rd party testbench
+should be removed from the build process before we go any further.
+
+The output from the previous step contains compiler-specific instructions on what files and switches
+should be added to your build command, here for example for Cadence:
+
+
+~~~text
+-----------------------------------------------------------
+Cadence (irun)
+-----------------------------------------------------------
+
+Add the following to your build script to create an Origen-enabled simulation object (AND REMOVE ANY OTHER TESTBENCH!):
+
+  /path/to/my/origen/origen.v \
+  /path/to/my/origen/*.c \
+  -ccargs "-std=c99" \
+  -top origen \
+  -elaborate  \
+  -snapshot origen \
+  -access +rw \
+  -timescale 1ns/1ns
+
+The following files should then be used for Origen integration:
+
+  /home/nxa21353/Code/my_origen/origen/my_design_top.rb
+  INCA_libs/ (created by irun)
+~~~
+
+At the time of writing Cadence, Synopsys and Icarus Verilog simulators are supported.
+
+Simply add the files and switches as instructed to your baseline build command and it should then create
+a snapshot of your design that is ready to talk to Origen.
+
+The compiler-specific notes also mention what files should be given to the Origen application integrator, in
+this case for Cadence the `INCA_libs` directory and an Origen file that defines the DUT's pins.
+
+Once you are in possession of these files, you are ready for the final step:
+
+
+#### Integrating the Simulation Object
+
+One of the generated components from the `sim:build` command is an Origen file that defines the DUT's pins. If you wish to use this
+in your model (optional, you can define them in the model by hand or any other way you like), then check it
+into your application's `vendor` directory and import it within your model's `initialize` method like this:
+
+~~~ruby
+# Import pin definitions as extracted from the design
+import 'my_top_level', dir: "#{Origen.root!}/vendor/wherever/i/like", namespace: nil
+~~~
+
+Note that `'my_top_level'` corresponds to the name of the file.
+
+Your application should already have a target setup that corresponds to this DUT, if not create one.
+
+The copy the compiled design files into `simulation/TARGET/SIMULATOR/.`, where `TARGET` is the name
+of the target, e.g. `my_dut` and `SIMULATOR` is either `cadence`, `synopsys` or `icarus`.
+
+For example, the `INCA_libs` directory in this Cadence example might be copied to `simulation/my_dut/cadence/INCA_libs`.
+
+You can check these simulation files into your application's revision control system, but since they can be very large binaries
+it is recommended that you add the `simulation` directory to your `.gitignore` and use an alternative revision control
+tool like DesignSync to store them.
+
+This will be further discussed in the environment setup, which is the [next section](<%= path "guides/simulation/environment" %>)
+of this guide to simulation...
+
+
+% end