Scripts: Generics, Waveform Files, and Run Length

On GitHub Issues, I had the following question, “With OSVVM scripting (.pro), is there a way to specify testbench generics, waveform files, and length of time to run a simulation.”

So lets take a look at these. Lets add to that, where do I get help on OSVVM from?

Specifying Generics

Every simulator has their own format for specifying generics. With OSVVM, we specify generics by calling the function generic (as shown below) and it takes care of specifying the generic in the proper format for your simulator.

library default
simulate Tb [generic WIDTH 8] 
simulate Tb [generic G1 5] [generic G2 7]

This was first added in release 2022.05d and prior to release 2022.09 quotes were required as shown below.

simulate Tb "[generic G1 5] [generic G2 7]"

Creating Waveform Files

Often with simulations, we need to add a custom waveform file. This may be for all designs or just one particular design. During simulate (or RunTest), if any of the following files exist, they will be run:

– {ToolVendor}.tcl
– {ToolName}.tcl
– {wave}.do
– {LibraryUnit}.tcl
– {LibraryUnit_ToolName}.tcl
– {TestCaseName}.tcl
– {TestCaseName_ToolName}.tcl

Note that these are tcl script files, so they can do more than just specify what waveforms you want to display.

ToolVendor is one of {Aldec, Siemens, Cadence, Synopsys}.
ToolName is one of {QuestaSim, ModelSim, RivieraPRO, ActiveHDL, VCS, Xcelium}.
LibraryUnit is the name specified to simulate.
TestCaseName is the name specified to TestCase.

It will search for these files in the following directories
– OsvvmLibraries/Scripts
– CurrentSimulationDirectory
– CurrentWorkingDirectory

CurrentSimulationDirectory is the directory in which the simulator is running.
CurrentWorkingDirectory is the directory of the script that calls either
RunTest or simulate.

Creating Waveform Files – GHDL is Special

Currently GHDL does not run any extra scripts since it is a batch simulator. Instead, in your OSVVM script, call

SetSaveWaves

This will add the following option to the GHDL simulator:

--wave=${LocalReportDirectory}/${LibraryUnit}.ghw

Nominally this means it will save your results in reports/MyTestbenchName.ghw

Creating Waveform Files – What If I want something different?

Many things in OSVVM can be customized by creating a file named LocalScripts.tcl in the directory OsvvmLibraries/Scripts. If you do not already have this file, copy the file Example_LocalScriptDefaults.tcl to this file. In LocalScripts.tcl, after the “namespace eval ::osvvm {“, overload the procedure SimulateRunScripts. See below for a sketch of this.

namespace eval ::osvvm {
  proc SimulateRunScripts {LibraryUnit} {
    variable TestCaseName
    variable SCRIPT_DIR
    variable CurrentSimulationDirectory
    variable CurrentWorkingDirectory

    #   Run your simulation time scripts here
    #   variables above are optional
  }

  # Other settings you can override in this file continue …
}

Note, while I have tested out similar capability, I have not tested this. So if you try it, be sure to let us know how it goes.

Specifying Simulation Time

During simulate, OSVVM tells your simulator to run until the testbench stays stop. This allows you to manage the amount of time a testbench runs in one place – the testbench itself.

As a result, OSVVM testbenches typically use a control process to setup tests, determine when the test is done, and finalize the tests. For a simple testbench that only uses OSVVM scripts and not other parts of OSVVM, the control process would be as shown below. The “wait for 1 ms;” sets the run length of this tesbench.

ControlProc : process
begin
  wait for 1 ms ; -- Length of time to run.
  std.env.stop ;
  wait ;
end process ControlProc ;

For tests that use OSVVM Error and Messaging capability (the AlertLogPkg), the control process will be as shown below. This is from the testcase, TbAxi4_MemoryReadWriteDemo1.vhd, which is in the directory OsvvmLibraries/AXI4/Axi4/TestCases.

ControlProc : process
begin
  -- Initialization of test
  SetAlertLogName("TbAxi4_MemoryReadWriteDemo1") ; -- Set the test name
  SetLogEnable(PASSED, TRUE) ; -- Enable PASSED logs
  SetLogEnable(INFO,   TRUE) ; -- Enable INFO logs
  SetLogEnable(DEBUG,  TRUE) ; -- Enable INFO logs

  -- Wait for testbench initialization
  wait for 0 ns ; wait for 0 ns ; -- avoid saving time 0 alerts as they are erroneous.
  TranscriptOpen("TbAxi4_MemoryReadWriteDemo1.txt") ;
  SetTranscriptMirror(TRUE) ; -- display messages in console for interactive sims.

  -- Wait for Design Reset
  wait until nReset = '1' ;
  ClearAlerts ; -- Do not count alerts until after reset

  -- Wait for test to finish
  WaitForBarrier(TestDone, 1 ms) ; -- Coordinate test done with test sequencers
  AlertIf(now >= 1 ms, "Test finished due to timeout") ;
  AlertIf(GetAffirmCount < 1, "Test is not Self-Checking"); -- If no checking, do not print passed

  TranscriptClose ;
  -- Printing may differ in different simulators due to differences in process order execution
  AlertIfDiff("TbAxi4_MemoryReadWriteDemo1.txt", RESULTS_PATH & "TbAxi4_MemoryReadWriteDemo1.txt", "") ;

  EndOfTestReports ; -- Generate OSVVM reports (text, HTML, and JUnit)
  std.env.stop ;
  wait ;
end process ControlProc ;

Finding Help on OSVVM

There are a number of ways to get help on OSVVM. These include, written documentation, OSVVM Forums, Gitter Chat, GitHub Issues, and direct email.

OSVVM has a considerable amount of written documentation. If you have the all of OsvvmLibraries, you will find the documentation in the directory: OsvvmLibraries/Documentation. The user guides provide detailed documentation on a given feature – such as Scripts_user_guide.pdf. Most OSVVM features have a user guide (ends with _user_guide.pdf). Many OSVVM features also have a quick reference (short 1 or 2 pages).

Once you have checked the documenation, another great place to get help is the OSVVM forums.
See: https://osvvm.org/forums/forum/os-vvm

If you prefer chat, we also have a gitter chat for OSVVM at https://gitter.im/OSVVM/Lobby.

The OSVVM repository is at https://github.com/osvvm/OsvvmLibraries. You can submit bugs or feature requests via GitHub issues. There is an issues page for each repository, but if you are not sure, use the one for OsvvmLibraries which is at: https://github.com/OSVVM/OsvvmLibraries/issues

If you have something that is not suitable for posting in one of the above, you are welcome to send me email. Keep in mind that sometimes email gets lost, so if you don’t get a reply, resend your email.