diff --git a/OsvvmScriptsCore.tcl b/OsvvmScriptsCore.tcl index 79aa6bc..9b3e300 100644 --- a/OsvvmScriptsCore.tcl +++ b/OsvvmScriptsCore.tcl @@ -92,8 +92,9 @@ proc StartUp {} { namespace eval ::osvvm { - - + variable _ruff_preamble { + Here could be some documentation for the namespace. + } # ------------------------------------------------- # IterateFile @@ -970,6 +971,25 @@ proc ListLibraries {} { # Library # proc library {LibraryName {PathToLib ""}} { + # Set the active VHDL library to *LibraryName* (working library). + # + # LibraryName - Name of the active VHDL library. + # PathToLib - If not specified, use the library directory specified by :ref:`RUFF/osvvm/SetLibraryDirectory`. |br| + # + # If a VHDL library named *LibraryName* doesn't exist, create a new VHDL library *LibraryName* in the specified + # library directory. + # + # This command influences how :ref:`RUFF/osvvm/analyze` behaves. + # + # .. todo:: + # + # * Make *LibraryName* found in library directory specified by path the active library. + # + # .. seealso:: + # + # * :ref:`RUFF/osvvm/SetLibraryDirectory` + # * :ref:`RUFF/osvvm/GetLibraryDirectory` + # variable VhdlWorkingLibrary variable LibraryList variable VhdlLibraryFullPath @@ -1100,26 +1120,27 @@ proc LinkCurrentLibraries {} { # proc analyze {FileName args} { # Analyze an HDL source file. - # + # # FileName - Path to the HDL source file. # args - Further options. - # - # This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used - # analyze option depend on the current context. For example the use VHDL library this source file and its design units - # are compiled into, depend on the last [library] call. - # - # **Procedures influencing the context for the `analyze` command:** - # - # * [library] - set the VHDl working library - # * [SetVHDLVersion] - tbd - # * [SetExtendedAnalyzeOptions] - tbd - # * [SetVhdlAnalyzeOptions] - tbd - # + # + # This procedure executes a tool-specific analyze command depending on what tool was detected. Some of the used + # analyze option depend on the current context. For example the use VHDL library this source file and its design units + # are compiled into, depend on the last [library] call. + # + # **Procedures influencing the context for the `analyze` command:** + # + # * [library] - set the VHDL working library + # * [SetVHDLVersion] - tbd + # * [SetExtendedAnalyzeOptions] - tbd + # * [SetVhdlAnalyzeOptions] - tbd + # # **Supported HDL sourcefile languages:** - # * VHDL `*.vhd`/`*.vhdl` - # * Verilog `*.v` - # * SystemVerilog `*.sv` - variable AnalyzeErrorCount + # * VHDL `*.vhd`/`*.vhdl` + # * Verilog `*.v` + # * SystemVerilog `*.sv` + # + variable AnalyzeErrorCount variable AnalyzeErrorStopCount variable ConsecutiveAnalyzeErrors @@ -1501,7 +1522,7 @@ proc RunTest {FileName {SimName ""} args} { puts "RunTest $RunArgs" ; # EchoOsvvmCmd set CompoundCommand TRUE - if {$SimName eq ""} { + if {$SimName eq ""} { set SimName [file rootname [file tail $FileName]] TestName $SimName } else { @@ -1835,13 +1856,35 @@ proc GetSimulatorResolution {} { # SetLibraryDirectory # proc SetLibraryDirectory {{LibraryDirectory "."}} { + # Set the directory into which VHDL libraries will be created. + # + # LibraryDirectory - Directory to use. |br| If not set, use :ref:`UG/Concepts/CurrentSimulationDirectory`. |br| + # + # By default, VHDL libraries are created in :file:`/VHDL_LIBS//`. + # + # This command influences how :ref:`RUFF/osvvm/library` behaves. + # + # .. seealso:: + # + # * :ref:`RUFF/osvvm/library` + # * :ref:`RUFF/osvvm/GetLibraryDirectory` + # variable VhdlLibraryParentDirectory set VhdlLibraryParentDirectory [file normalize $LibraryDirectory] - } proc GetLibraryDirectory {} { + # Get the Library directory. + # + # Returns the directory into which VHDL libraries will be created. |br| + # If not modified by :ref:`RUFF/osvvm/SetLibraryDirectory` it defaults to :file:`/VHDL_LIBS//`. + # + # .. seealso:: + # + # * :ref:`RUFF/osvvm/library` + # * :ref:`RUFF/osvvm/SetLibraryDirectory` + # variable VhdlLibraryParentDirectory if {[info exists VhdlLibraryParentDirectory]} { diff --git a/doc/CoSim/PCIe.rst b/doc/CoSim/PCIe.rst new file mode 100644 index 0000000..7125ed0 --- /dev/null +++ b/doc/CoSim/PCIe.rst @@ -0,0 +1,4 @@ +.. _COSIM/PCIe: + +PCIe +#### diff --git a/doc/CoSim/index.rst b/doc/CoSim/index.rst new file mode 100644 index 0000000..ff88e0b --- /dev/null +++ b/doc/CoSim/index.rst @@ -0,0 +1,4 @@ +.. _COMSIM: + +Co-Simulation +############# diff --git a/doc/Glossary.rst b/doc/Glossary.rst index c571ee6..35866e1 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -3,8 +3,52 @@ Glossary .. glossary:: - OSVVM + GTKWave tbd - TCL + .. rubric:: Further reading + + * GitHub: https://github.com/gtkwave/gtkwave + * Website: https://gtkwave.github.io/gtkwave/ |br| https://gtkwave.sourceforge.net/ + + MIT + **M**\ odel **I**\ ndependent **T**\ ransactions + + * :ref:`MIT` + + OSVVM + **O**\ pen-**S**\ ource **V**\ HDL **V**\ erification **M**\ ethodology + + .. rubric:: Further reading + + * GitHub: https://github.com/OSVVM/OsvvmLibraries + * Website: https://osvvm.github.io/ + + Surfer tbd + + .. rubric:: Further reading + + * Website: https://surfer-project.org/ + + Tcl + **T**\ ool **C**\ ommand **L**\ anguage + + .. rubric:: Further reading + + * Wikipedia: https://en.wikipedia.org/wiki/Tcl + * Website: https://www.tcl-lang.org/ + + VC + **V**\ erification **C**\ omponent + + VTI + **V**\ irtual **T**\ ransaction **I**\ nterface + + YAML + **Y**\ AML **A**\ in't **M**\ arkup **L**\ anguage + + .. rubric:: Further reading + + * Wikipedia: https://en.wikipedia.org/wiki/YAML + * Website: https://yaml.org/ diff --git a/doc/Installation.rst b/doc/Installation.rst index c74cddb..6179bad 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -3,17 +3,114 @@ Installation/Updates #################### -Clone OSVVM Libraries -********************* +.. image:: https://img.shields.io/badge/OSVVM-OSVVM--Scripts-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 + :alt: Sourcecode on GitHub + :height: 22 + :target: https://github.com/OSVVM/OSVVM-Scripts +.. image:: https://img.shields.io/github/v/tag/OSVVM/OsvvmLibraries + :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest + :alt: GitHub Release + +OSVVM is hosted and developed at https://github.com/OSVVM. It's components are split into multiple Git repositories, +which can be used individually or as a group. The all-in-one repository is called +`OsvvmLibraries `__. **OSVVM-Scripts** is part of **OsvvmLibraries**. + +See :ref:`INSTALL/Download` for downloadable archives. + + +.. _INSTALL/Clone: + +Clone OsvvmLibraries +******************** + +OsvvmLibraries aggregates all OSVVM repositories into a single parent repository, which has OSVVM's components +registered as Git submodules. |br| +When cloning ensure to append the ``–recursive`` flag. + +.. code-block:: bash + + git clone --recursive https://github.com/OSVVM/OsvvmLibraries.git + +.. seealso:: + + Git Documentation: `git clone `__ + + +.. _INSTALL/Submodule: + +Register OsvvmLibraries as Git Submodule +**************************************** + +Usually, OSVVM will be part of a bigger HDL project structure also maintained in Git. Therefore, it's best to integrate +OSVVM as a submodule into that project. The following commands assume, OSVVM gets added into ``./lib/OsvvmLibraries``. + +.. code-block:: bash + + cd /lib + git submodule add https://github.com/OSVVM/OsvvmLibraries.git + git submodule update --init --recursive + +.. seealso:: + + Git Documentation: `git submodule add `__ + + +.. _INSTALL/IndividualSubmodules: + +Register Individual VCs as Git Submodule +**************************************** + +.. todo:: + + describe individual submodule workflow + + +.. _INSTALL/Updating: + +Updating OSVVM or OSVVM Components +********************************** + +.. todo:: + + describe update process using Git + + +.. _INSTALL/Download: Download OSVVM Libraries ************************ -OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page. +.. image:: https://img.shields.io/github/v/release/OSVVM/OsvvmLibraries + :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest + :alt: GitHub Release -On GitHub, all OSVVM libraries are a submodule of the repository OsvvmLibraries. Download all OSVVM libraries using -``git clone`` with the ``–recursive`` flag: +OsvvmLibraries is also offered as an archive at https://github.com/OSVVM/OsvvmLibraries/releases/latest -.. code-block:: bash +* ``https://github.com/OSVVM/OsvvmLibraries/releases/download//OsvvmLibraries-.tar.gz`` +* ``https://github.com/OSVVM/OsvvmLibraries/releases/download//OsvvmLibraries-.tar.zstd`` +* ``https://github.com/OSVVM/OsvvmLibraries/releases/download//OsvvmLibraries-.zip`` + +.. attention:: + + Downloading the archive provided by GitHub's source code download doesn't include the submodule's code. Therefore + OSVVM added a CI job for packaging all sources (incl. submodules) into a single archive. + + +.. todo:: + + OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page. + + `Downlaods from osvvm.org `__ + +.. _INSTALL/BusinessContinuity: + +Business Continuity Planning +**************************** + +.. todo: + + describe fork structure - git clone --recursive https://github.com/osvvm/OsvvmLibraries + 1. fork on GitHub + 2. mirror to local Git server (e.g. GitLab) + 3. clone to local machine diff --git a/doc/QuickStartGuide.rst b/doc/QuickStartGuide.rst index 4749aed..c0c1e8d 100644 --- a/doc/QuickStartGuide.rst +++ b/doc/QuickStartGuide.rst @@ -3,6 +3,10 @@ Quick Start Guide ################# +.. important:: + + If you haven't installed OsvvmLibraries yet, please get OSVVM using one of the described methods in :ref:`INSTALL` + Create a Simulation directory ***************************** @@ -15,6 +19,13 @@ The following assumes you have created a directory named :file:`sim` in the :fil Alternately, you can run simulations out of the Scripts, but cleanup is a mess as a simulator tends to create numerous temporaries. +.. todo:: + + Is :file:`sim_vendor-name` still valid? + + What about :file:`temp`? + + Start the Script environment in the Simulator ********************************************* @@ -52,3 +63,93 @@ Do the actions appropriate for your simulator. tbd + + +Run the Demos +************* + +Run the following commands in your simulator's command line: + +.. code-block:: + + # analyze OSVVM's packages and verification components + build ../OsvvmLibraries + # analyze and run demo tests + build ../OsvvmLibraries/RunDemoTests.pro + +These will produce some reports, such as :file:`OsvvmLibraries_RunDemoTests.html`. + +.. todo:: We will discuss these in the next section, OSVVM Reports. + + +Writing Scripts by Example +************************** + +OSVVM Scripts are an API layer that is build on top of :term:`Tcl`. The API layer simplifies the +steps of analyzing and running simulations. For most applications you will not need any Tcl, however, it is there if you +need more capabilities. + +Scripts are named in the form :file:`\.pro`. The scripts are Tcl code that is augmented with the OSVVM script +API. The script API is created using Tcl procedures. + +.. rubric:: Basic Script Commands + +:tclcode:`library ` + Make this library the active library. Create it if it does not exist. +:tclcode:`analyze ` + Compile (aka analyze) the design into the active library. +:tclcode:`simulate ` + Simulate (aka elaborate + run) the design using the active library. +:tclcode:`include .pro` + Include another project script. +:tclcode:`build .pro` + Start a script from the simulator. It is ``include`` + start a new log file and report for this script. + +.. todo:: For more details, see Command Summary later in this document. + +.. topic:: First Script + + At the heart of running a simulation is setting the library, compiling files, and starting the simulation. + To do this, we use ``library``, ``analyze``, and vsimulate``. + + The following is an excerpt from the scripts used to run OSVVM verification component library regressions. + + .. admonition:: ``testbench_MultipleMemory.pro`` + + .. code-block:: tcl + + library osvvm_TbAxi4_MultipleMemory + analyze TestCtrl_e.vhd + analyze TbAxi4_MultipleMemory.vhd + analyze TbAxi4_Shared1.vhd + TestName TbAxi4_Shared1 + simulate TbAxi4_Shared1 + + In OSVVM scripting, calling ``library`` activates the library. An ``analyze`` or ``simulate`` that follows + ``library`` uses the specified library. This is consistent with VHDL’s sense of the *working library*. + + .. note:: + + Note that there are no directories to the files. For OSVVM commands that use paths, the path is always relative to + the directory the script is located in unless an absolute path is specified. + + The above script is in :file:`testbench_MultipleMemory.pro`. It can be run by specifying: + + .. code-block:: tcl + + build ../OsvvmLibraries/AXI4/Axi4/testbench_MultipleMemory/testbench_MultipleMemory.pro + + .. hint:: + + If you were to open :file:`testbench_MultipleMemory.pro`, you would find that ``RunTest`` is used instead as it is + an abbreviation for the ``analyze``, ``TestName`` and ``simulate`` when the names are the same. + + +Regression.tcl +************** + +.. todo:: + + Show how a regression.tcl could look like assuming OSVVM is a git submodule. + + diff --git a/doc/Reports/HTML.rst b/doc/Reports/HTML.rst new file mode 100644 index 0000000..a342969 --- /dev/null +++ b/doc/Reports/HTML.rst @@ -0,0 +1,230 @@ +.. _RPT/HTML: + +HTML Reports +############ + + + +Overview +******** + +OSVVM produces the following reports: + +* HTML Build Summary Report for human inspection that provides test completion status. +* HTML Test Case Detailed report for each test case with Alert, Functional Coverage, and Scoreboard reports. +* HTML based simulator transcript/log files (simulator output) +* Text based test case transcript file (from TranscriptOpen) + + +Build Index +*********** + +.. todo:: + + Experimental Feature - Undocumented + + +Build Summary Report +******************** + +The Build Summary Report allows us to quickly confirm if a +build passed or quickly identify which test cases did not PASS. + +The Build Summary Report has three distinct pieces: + +- Build Status +- Test Suite Summary +- Test Case Summary + +For each Test Suite and Test Case, there is additional information, +such as Functional Coverage and Disabled Alert Count. + +In the sim directory, the Build Summary Report is +in the file OsvvmLibraries_RunDemoTests.html. +It can be opened by typing OpenBuildHtml at the simulator command line. + +.. figure:: images/DemoBuildSummaryReport.png + :name: BuildSummaryReportFig + :scale: 25 % + :align: center + + Build Summary Report + +Note that any place in the report there is a triangle preceding text, +pressing on the triangle will rotate it and either hide or reveal +additional information. + +Build Status +============ + +The Build Status, shown below, is in a table at the top of the +Build Summary Report. +If code coverage is run, there will be a link to +the results at the bottom of the Build Summary Report. + +.. figure:: images/DemoBuildStatus.png + :name: BuildStatusFig + :scale: 50 % + :align: center + + Build Status + +Test Suite Summary +================== + +When running tests, test cases are grouped into test suites. +A build can include multiple test suites. +The next table we see in the Build Summary Report is the +Test Suite Summary. +The figure below shows +that this build includes the test suites Axi4Full, AxiStream, and UART. + +.. figure:: images/DemoTestSuiteSummary.png + :name: TestSuiteSummaryFig + :scale: 50 % + :align: center + + Test Suite Summary + + +Test Case Summary +================= + +The remainder of the Build Summary Report is Test Case Summary, see below. +There is a seprate Test Case Summary for each test suite in the build. + +.. figure:: images/DemoTestCaseSummaries.png + :name: TestCaseSummaryFig + :scale: 50 % + :align: center + + Test Case Summary + +Testcase Detailed Report +************************ + +For each test case that is run (simulated), +a Test Case Detailed Report is produced that +contains consists of the following information: + +- Test Information Link Table +- Alert Report +- Functional Coverage Report(s) +- Scoreboard Report(s) +- Link to Test Case Transcript (opened with Transcript Open) +- Link to this test case in HTML based simulator transcript + +After running one of the regressions, open one of the HTML files +in the directory ./reports/. An example one is shown below. + +.. figure:: images/DemoTestCaseDetailedReport.png + :name: TestCaseDetailedFig + :scale: 50 % + :align: center + + Test Case Detailed Report + + +Note that any place in the report there is a triangle preceding text, +pressing on the triangle will rotate it and either hide or reveal +additional information. + + +Test Information Link Table +=========================== + +The Test Information Link Table is in a table at the top of the +Test Case Detailed Report. +The figure below has links to the Alert Report (in this file), +Functional Coverage Report (in this file), +Scoreboard Reports (in this file), +a link to simulation results (if the simulation report is in HTML), +and a link to any transcript files opened by OSVVM. + +.. figure:: images/DemoTestCaseLinks.png + :name: TestInfoFig + :scale: 50 % + :align: center + + Test Information Link Table + + +Alert Report +============ + +The Alert Report, shown below, provides detailed information for each AlertLogID +that is used in a test case. Note that in the case of expected errors, the errors +still show up as FAILED in the Alert Report and are rectified in the total error count. + +.. figure:: images/DemoAlertReport.png + :name: AlertFig + :scale: 50 % + :align: center + + Alert Report + + +Functional Coverage Report +========================== + +The Test Case Detailed Report contains a +Functional Coverage Report, shown below, for each +functional coverage model used in the test case. +Note this report is not from the demo. + +.. figure:: images/CoverageReport.png + :name: FunctionalCoverageFig + :scale: 50 % + :align: center + + Functional Coverage Report + +Scoreboard Report +================= + +The Test Case Detailed Report contains a +Scoreboard Report, shown below. There is +a row in the table for each +scoreboard model used in the test case. + +.. figure:: images/DemoScoreboardReport.png + :name: ScoreboardFig + :scale: 50 % + :align: center + + Scoreboard Report + + +Test Case Transcript +==================== + +OSVVM's transcript utility facilitates collecting all +test output to into a single file, as shown below. + +.. figure:: images/DemoVHDLTranscript.png + :name: TestCaseTranscriptFig + :scale: 50 % + :align: center + + Test Case Transcript + + +Simulator Transcript +******************** + +Simulator transcript files can be long. +The basic OSVVM regression test (OsvvmLibraries/RunAllTests.pro), +produces a log file that is 84K lines long. +As a plain text file, this is not browsable, however, +when converted to an html file it is. +OSVVM gives you the option to create either html (default), shown below, or plain text. +In the html report, any place there is a triangle preceding text, +pressing on the triangle will rotate it and either hide or reveal +additional information. + +.. figure:: images/DemoSimTranscript.png + :name: SimTranscriptFig + :scale: 50 % + :align: center + + HTML Simulator Transcript \ No newline at end of file diff --git a/doc/Reports/XML.rst b/doc/Reports/XML.rst new file mode 100644 index 0000000..a5ca434 --- /dev/null +++ b/doc/Reports/XML.rst @@ -0,0 +1,27 @@ +.. _RPT/XML: + +Reports (XML) +############# + +.. _RPT/XML/jUnit: + +JUnit Test Summary Report +************************* + +The JUnit XML Build Summary Report works with +continuous integration (CI/CD). +The CI/CD tools use this to understand if the test +is passing or not. +They also have facilities for displaying the +report - however, the OSVVM HTML format provides +a superset of information. + +OSVVM runs regressions on GitHub. + +.. todo:: + + * XML example + * schema reference + * tested consumers + * publishing tools + * merge tools diff --git a/doc/Reports/YAML.rst b/doc/Reports/YAML.rst new file mode 100644 index 0000000..32354a6 --- /dev/null +++ b/doc/Reports/YAML.rst @@ -0,0 +1,7 @@ +.. _RPT/YAML: + +Reports (YAML) +############## + +The reports in YAML format are an intermediate format used within OSVVM Script. These are the data source for generating +HTML and XML reports. A detailed YAML data format description can be found in :ref:`YAML` diff --git a/doc/Reports/index.rst b/doc/Reports/index.rst index 3fdcbca..7cea53e 100644 --- a/doc/Reports/index.rst +++ b/doc/Reports/index.rst @@ -3,4 +3,36 @@ Reports ####### +Good reports simplify debug and help find problems quickly. This is important as according to the +`2020 Wilson Verification Survey FPGA `__ +verification engineers spend 46% of their time debugging. +OSVVM produces the following reports: + +* HTML Build Summary Report for human inspection that provides test completion status. +* JUnit XML Build Summary Report for use with continuous integration (CI/CD) tools. +* HTML Test Case Detailed report for each test case with Alert, Functional Coverage, and Scoreboard reports. +* HTML based simulator transcript/log files (simulator output) +* Text based test case transcript file (from TranscriptOpen) + +The best way to see the reports is to look at the ones from the demo. + +.. seealso:: + + .. todo:: + + If you have not already done ``build OsvvmLibraries/RunDemoTests.pro``, then do so now. + +.. todo:: + + * generated by :ref:`RUFF/osvvm/analyze` command + * can be manually triggered via ????? + * processes YAML files (``*.yml``) created by OSVVM Utility Library (information exported from VHDL code) and created + runtime information from OSVVM Scripts (information from Tcl test runner). + +.. toctree:: + :hidden: + + HTML + XML + YAML diff --git a/doc/RequirementsTracking.rst b/doc/RequirementsTracking.rst new file mode 100644 index 0000000..0f67f6c --- /dev/null +++ b/doc/RequirementsTracking.rst @@ -0,0 +1,10 @@ +.. _REQ: + +Requirements Tracking +##################### + +When requirements are tracked in a test case, a requirements +report is automatically created for that test case. +If any test case in a build generates a requirements report, +when the build completes the requirements for each text case +are merged and an html requirements report is produced. diff --git a/doc/Support.rst b/doc/Support.rst new file mode 100644 index 0000000..b72e8d9 --- /dev/null +++ b/doc/Support.rst @@ -0,0 +1,43 @@ + +.. _SUPPORT: + +Support +####### + +Get support for OSVVM at `osvvm.org `__. + +See also the following resources. + + +.. topic:: OSVVM Forum + + OSVVM offers a `forum `__ with an active community. + + .. todo:: + + Redit? + + +.. topic:: OSVVM Discussions + + For interactive discussion, see OSVVM's Gitter channel at + `OSVVM Lobby `__ + + +.. topic:: Reporting Bugs + + In case of a "bug" please create a **problem report** at + `OSVVM's Issue Tracker `__ + +.. topic:: Suggesting Enhancements + + In case of missing features or feature suggestions, please create a **feature request** at + `OSVVM's Issue Tracker `__. + + OSVVM is open for suggestions via GitHub **Pull Requests**. + + .. hint:: + + In case of bigger contributions or modifications to OSVVM's code base, please first start a **feature request** via + issue tracker to discuss the proposed solution and how to integrate the intended changes best into OSVVM's + existing code. diff --git a/doc/ToolSpecific.rst b/doc/ToolSpecific.rst new file mode 100644 index 0000000..9a9a16b --- /dev/null +++ b/doc/ToolSpecific.rst @@ -0,0 +1,229 @@ +.. _SIM: + +Simulator Specifics +################### + +.. rubric:: Support Simulators (in alphabetic order) + +.. grid:: 6 + + .. grid-item-card:: Aldec + :columns: 2 + + * :ref:`SIM/Aldec/ActiveHDL` + * :ref:`SIM/Aldec/RivieraPRO` + + .. grid-item-card:: AMD (Xilinx) + :columns: 2 + + * :ref:`SIM/AMD/xSim` + + .. grid-item-card:: Cadence + :columns: 2 + + * :ref:`SIM/Cadence/Xcelium` + + .. grid-item-card:: Open-Source + :columns: 2 + + * :ref:`SIM/GHDL` + * :ref:`SIM/NVC` + + .. grid-item-card:: Siemens EDA + :columns: 2 + + * :ref:`SIM/Siemens/ModelSim` + * :ref:`SIM/Siemens/Questa` + * :ref:`SIM/Siemens/Visualizer` + + .. grid-item-card:: Synopsys + :columns: 2 + + * :ref:`SIM/Synopsys/VCS` + + +Quick Overview +************** + +.. tab-set:: + + .. tab-item:: Aldec Riviera-PRO + :sync: Riviera + + Initialize the OSVVM Script environment by sourcing :file:`StartUp.tcl` within Riviera-PRO's GUI or Tcl console: + + .. code-block:: tcl + + source /Scripts/StartUp.tcl + + .. tab-item:: Siemens Visualizer + :sync: Visualizer + + TODO + + .. code-block:: tcl + + source /Scripts/StartUp.tcl + + .. tab-item:: Siemens EDA Questa / QuestaSim + :sync: Questa + + TODO + + .. code-block:: tcl + + source /Scripts/StartUp.tcl + + .. tab-item:: Siemens EDA ModelSim + :sync: ModelSim + + TODO + + .. code-block:: tcl + + source /Scripts/StartUp.tcl + + +.. _SIM/Aldec: + +Aldec +***** + +.. _SIM/Aldec/ActiveHDL: + +Active-HDL +========== + +Initialize the OSVVM Script environment with the following commands: + +.. code-block:: tcl + + scripterconf -tcl + do -tcl /Scripts/StartUp.tcl + +Want to avoid doing this every time? For ActiveHDL, edit :file:`/script/startup.do` and add above to it. Similarly for +**VSimSA**, edit :file:`/BIN/startup.do` and add the above to it. + +.. note:: + + Note, with 2021.02, you no longer need to set the "Start In" directory to the OSVVM Scripts directory. + +.. _SIM/Aldec/RivieraPRO: + +Riviera-PRO +=========== + +.. _SIM/AMD: +.. _SIM/Xilinx: + +AMD (Xilinx) +************ + +.. _SIM/AMD/xSim: +.. _SIM/Xilinx/xSim: + +xSim +==== + +.. _SIM/Cadence: + +Cadence +******* + +.. _SIM/Cadence/Xcelium: + +Xcelium +======= + +.. _SIM/GHDL: + +GHDL +**** + +.. _SIM/GHDL/Windows: + +GHDL on Windows in MSYS2/UCRT64 +=============================== + +Initialize the OSVVM Script environment within **tclsh**: + +.. code-block:: tcl + + winpty tclsh + source /Scripts/StartUp.tcl + +To simplify the startup process, put :file:`source /Scripts/StartUp.tcl` into +:file:`.tclshrc` and add a Windows short cut that calls ``C:\msys64\ucrt64.exe winpty tclsh``. This will open a UCRT64 +console window with a Tcl shell and pre-loaded OSVVM Script environment. + +.. hint:: + + ``tclsh`` and ``tcllib`` might be missing in a fresh MSYS2/UCRT64 environment. |br| + Use **pacman** to install the necessary Tcl dependencies: + + .. code-block:: Bash + + pacman -S ucrt64/mingw-w64-ucrt-x86_64-winpty + pacman -S ucrt64/mingw-w64-ucrt-x86_64-tcl ucrt64/mingw-w64-ucrt-x86_64-tcllib + +.. _SIM/GHDL/Linux: +.. _SIM/GHDL/macOS: + +GHDL on Linux/macOS +=================== + +Initialize the OSVVM Script environment within **tclsh**: + +.. code-block:: tcl + + rlwrap tclsh + source /Scripts/StartUp.tcl + +To simplify this, put :file:`source /Scripts/StartUp.tcl` in the :file:`.tclshrc` +file and in Bash add ``alias gsim='rlwrap tclsh'`` to your :file:`.bashrc`. + +.. _SIM/NVC: + +NVC +*** + +.. _SIM/NVC/Windows: + +NVC on Windows in MSYS2/UCRT64 +============================== + +.. _SIM/NVC/Linux: +.. _SIM/NVC/macOS: + +NVC on Linux +============ + +.. _SIM/Siemens: + +Siemens EDA +*********** + +.. _SIM/Siemens/ModelSim: + +ModelSim +======== + +.. _SIM/Siemens/Questa: + +Questa / QuestaSim +================== + +.. _SIM/Siemens/Visualizer: + +Visualizer +========== + +.. _SIM/Synopsys: + +Synopsys +******** + +.. _SIM/Synopsys/VCS: + +VCS +=== diff --git a/doc/UserGuide.rst b/doc/UserGuide.rst new file mode 100644 index 0000000..a8af0e4 --- /dev/null +++ b/doc/UserGuide.rst @@ -0,0 +1,467 @@ +.. _UG: + +User Guide +########## + +Overview +******** + +.. todo:: + + anaylze + simulate + + build + testsuite + testcase + + context + +Concepts +======== + +.. _UG/Concepts/CurrentSimulationDirectory: + +CurrentSimulationDirectory +-------------------------- + +.. todo:: explain :file:`CurrentSimulationDirectory` + + +.. admonition:: Naming Style + + Commands are case sensitive. |br| + Single word names are all lower case. |br| + Multiple word names are CamelCase. + + +Basic Commands +************** + +* build +* TestSuite +* library +* analyze +* simulate +* TestName +* RunTest + +build +===== + +Build is a layer on top of include (it calls include) that creates a logging point. +In general, build is called from the simulator API (when we run something) +and include is called from scripts. + +By default, OSVVM creates collects all tool output for a build into +an html based log file in ./logs/-/.html. + +To compile all of the OSVVM libraries, use build as shown below. + +.. code-block:: tcl + + build ../OsvvmLibraries/OsvvmLibraries.pro + + Build sets the tcl variables $::ARGC and $::ARGV (an array). + +VHDL Library Handling +********************* + +:ref:`RUFF/osvvm/SetLibraryDirectory` +:ref:`RUFF/osvvm/SetLibraryDirectory` + sdbsbfs dfvdfvggdy +:tclcode:`SetLibraryDirectory [LibraryDirectory]` + - Set the directory in which the libraries will be created to ``LibraryDirectory``. + - If ``LibraryDirectory`` is not specified, use the ``CurrentSimulationDirectory``. + - By default, libraries are created in :file:`/VHDL_LIBS//`. +:tclcode:`GetLibraryDirectory` + - Get the Library Directory. +:tclcode:`library []` + - Make LibraryName found in library directory specified by path the active library. + - Create the LibraryName if it does not exist. + - If path is not specified, use the library directory specified by SetLibraryDirectory. +:tclcode:`LinkLibrary []` + - Create a mapping to a library that is in the library directory specified by path. + - If path is not specified, use the library directory specified by SetLibraryDirectory. +:tclcode:`LinkLibraryDirectory [LibraryDirectory]` + - Map all of the libraries in the specified ``LibraryDirectory``. + If ``LibraryDirectory`` is not specified, use the library directory specified by SetLibraryDirectory. +:tclcode:`LinkCurrentLibraries` + - If you use ``cd``, then use LinkCurrentLibraries immediately after + to map all current visible libraries to the new CurrentSimulationDirectory. +:tclcode:`RemoveLibrary LibraryName []` + - Remove the named library. + Path is only used to find and delete libraries that have not been mapped in OSVVM. +:tclcode:`RemoveLibraryDirectory []` + - Remove the Library specified in path. + - If path is not specified, the library directory specified by SetLibraryDirectory is used. +:tclcode:`RemoveAllLibraries` + - Call RemoveLibraryDirectory on all library directories known to OSVVM. + +Discouraged Tcl Commands +************************ + +Tcl's **source** / EDA Tool's **do** +==================================== + +.. caution:: + + Do not use Tcl's ``source``! + Do not use Tcl's EDA tool's ``do``! + +OSVVM uses :ref:`RUFF/osvvm/include` since it helps manage the path of where the script files are located. Include uses +Tcl's ``source`` internally. However, if you use Tcl's ``source`` (or EDA tool's ``do``) instead, you will not get +include's directory management features and your scripts will need to manage the directory paths themselves. + +Tcl's **cd** +============ + +.. caution:: + + Do not use Tcl's ``cd`` + +Simulators create files containing library mappings and other information in the simulation directory. If you use ``cd`` +you lose all of this information. OSVVM tracks the simulation directory in the ``::osvvm::CurrentSimulationDirectory`` +variable. + +OSVVM tracks the directory in which scripts run as ``CurrentWorkingDirectory``. All OSVVM API commands run relative to +``CurrentWorkingDirectory``. When you call a script in another directory using :ref:`RUFF/osvvm/include`, +``CurrentWorkingDirectory`` is automatically updated to be the directory that contains the script. When +:ref:`RUFF/osvvm/include` finishes it restores ``CurrentWorkingDirectory`` to be its value before +:ref:`RUFF/osvvm/include` was called. + +If while running a script, you need to adjust the ``CurrentWorkingDirectory``, use :ref:`RUFF/osvvm/ChangeWorkingDirectory`. +Like ``cd``, :ref:`RUFF/osvvm/ChangeWorkingDirectory` allows either relative or absolute paths. + +.. code-block:: tcl + + ChangeWorkingDirectory src + analyze Axi4Manager.vhd + +If you need to determine a path relative to the ``CurrentWorkingDirectory``, use :ref:`RUFF/osvvm/JoinWorkingDirectory`. +In the following, the relative path used by :ref:`RUFF/osvvm/LinkLibraryDirectory` is: + +.. code-block:: tcl + + LinkLibraryDirectory [JoinWorkingDirectory RelativePath] + + +Structuring Project Files +************************* + +Including Scripts +================= + +We build our designs hierarchically. +Therefore our scripts need to be build hierarchically. +When one script calls another script, such as OsvvmLibraries.pro does, we use include. +The code for OsvvmLibraries.pro is as follows. +The ``if`` is Tcl and is only building the UART, AXI4, and DpRam if +their corresponding directories exist. + +.. code-block:: tcl + + include ./osvvm/osvvm.pro + include ./Common + + if {[DirectoryExists UART]} { + include ./UART + } + if {[DirectoryExists AXI4]} { + include ./AXI4 + } + if {[DirectoryExists DpRam]} { + include ./DpRam + } + +Note the paths specified to include are relative to OsvvmLibriaries +directory since that is where OsvvmLibraries.pro is located. Note +that the includes above only specify directory names. When this +happens, include looks for a file of the name build.pro or naming +pattern .pro. + +Include sets the tcl variables $::ARGC and $::ARGV (an array). +Rather than using these it is recommended to use tcl procedures. + + +Conditions in Project Files +*************************** + +.. _UG/Variables: + +Prefedined Variables +******************** + +.. _UG/HelperFunctions: + +Helper Functions +**************** + +.. _UG/Generics: + +Simulating with Generics +************************ + +To specify generics in a :ref:`RUFF/osvvm/simulate` or :ref:`RUFF/osvvm/RunTest` call, use the OSVVM's +:ref:`RUFF/osvvm/generic` function. Generic takes two parameters: the name of the generic and its value. It is applied +as shown below: + +.. code-block:: tcl + + simulate Tb_xMii1 [generic MII_INTERFACE MII] [generic MII_BPS BPS_10M] + RunTest Tb_xMii1.vhd [generic MII_INTERFACE RGMII] [generic MII_BPS BPS_1G] + +Calling generic this way allows OSVVM to set generics using the method required by each simulator. + +.. hint:: + + Note the square brackets are required and tell Tcl to call the function to create the arguments for + :ref:`RUFF/osvvm/simulate` or :ref:`RUFF/osvvm/RunTest`. + +.. versionchanged:: Release 2022.09 removed the necessity to put quotes around the options specified with simulate. + +.. _UG/Waveform: + +Waveforms +********* + +Adding other Wave Files +======================= + +To include wave files with names different from above, use the :ref:`RUFF/osvvm/DoWaves` function. DoWaves is called in +the call to :ref:`RUFF/osvvm/simulate` as shown below. + +.. code-block:: tcl + + library default + simulate Tb [DoWaves wave1.do] + simulate Tb [DoWaves wave1.do wave2.do] + +If the :file:`wave1.do` file is not in :file:`CurrentSimulationDirectory`, then it will need path information. + +In Aldec and Siemens, these are run via the simulator command line (via ``-do``). + +.. caution:: + + The method of running them may change in the future (and may use ``source``). + +.. hint:: + + Note the square brackets are required and tell Tcl to call the function to create the arguments for + :ref:`RUFF/osvvm/simulate` or :ref:`RUFF/osvvm/RunTest`. + +Saving Waveforms with GHDL and NVC +================================== + +The open source simulators GHDL and NVC run in a batch mode, but can save waveforms to see with a separate waveform +viewer like :term:`Gtkwave` or :term:`Surfer`. To save waveforms for GHDL and NVC, call :ref:`RUFF/osvvm/SetSaveWaves`. + +If you do not call :ref:`RUFF/osvvm/SetSaveWaves`, the *debug mode* is false. If you call :ref:`RUFF/osvvm/SetSaveWaves` +without a ``true`` or ``false`` value, the default is ``true``. + +.. code-block:: tcl + + SetSaveWaves + SetSaveWaves true + + +.. _UG/CodeCoverage: + +Code Coverage +************* + +Code coverage is a metric that tells us if certain parts of our design +have been exercised or not. Turning on code coverage with OSVVM is simple. +In the following example, we enable coverage options during analysis and +simulation separately. + +.. code-block:: tcl + + # File name: Dut.pro + SetCoverageAnalyzeEnable true + analyze Dut.vhd + SetCoverageAnalyzeEnable false + SetCoverageSimulateEnable true + analyze TbDut.vhd + simulate TbDut + SetCoverageSimulateEnable false + +Note that CoverageAnalyzeEnable is specifically turned off +before compiling the testbench so that the testbench is not +included in the coverage metrics. + +You can also set specific options by using SetCoverageAnalyzeOptions +and SetCoverageSimulateOptions. By default, OSVVM sets these options +so that statement, branch, and statemachine coverage is collected. + +When coverage is turned on for a build, coverage is collected for each test. +If there are multiple test suites in the build, +when a test suite completes execution, +the coverage for each test in the test suite is merged. +When a build completes the coverage from each test suite +is merged and an html coverage report is produced. + + +.. _UG/Debugging: + +Debugging +********* + +By default, OSVVM's scripting focuses on running regressions fast. Adding debugging information, logging signals, and/or +displaying waveforms will slow things down. In addition, by default, if one simulation crashes, the scripts will +continue and run the next simulation. + +Debug Mode +========== + +To add debugging information to your simulation, call :ref:`RUFF/osvvm/SetDebugMode`. If you do not call +:ref:`RUFF/osvvm/SetDebugMode`, the debug mode is false. If you call :ref:`RUFF/osvvm/SetDebugMode` without a ``true`` +or ``false`` value, the default is true. + +.. code-block:: tcl + + SetDebugMode true + +Stop on Error +============= + +Whether :ref:`RUFF/osvvm/analyze` or :ref:`RUFF/osvvm/simulate` (also :ref:`RUFF/osvvm/RunTest`) stop on a failure or +not is controlled by the internal variables ``AnalyzeErrorStopCount`` and ``SimulateErrorStopCount``. By default, these +variables are set to 0, which means do not stop. Setting them to a non-zero value, causes either +:ref:`RUFF/osvvm/analyze` or :ref:`RUFF/osvvm/simulate` to stop when the specified number of errors occur. Hence, to +stop after one error, set them as follows: + + .. code-block:: tcl + + set ::osvvm::AnalyzeErrorStopCount 1 + set ::osvvm::SimulateErrorStopCount 1 + +Logging Signal Values (for later display) +========================================= + +To log signals so they can be displayed after the simulation finishes, call :ref:`RUFF/osvvm/SetLogSignals`. If you do +not call :ref:`RUFF/osvvm/SetLogSignals`, the log signals mode is false. If you call :ref:`RUFF/osvvm/SetLogSignals` +without a ``true`` or ``false`` value, the default is true. + +.. code-block:: tcl + + SetLogSignals true + + +Interactive Mode +================ + +To do all of the above in one step, call :ref:`RUFF/osvvm/SetInteractiveMode`. If you call +:ref:`RUFF/osvvm/SetInteractiveMode` without a ``true`` or ``false`` value, the default is true. + +.. seealso:: + + :ref:`UG/Config/Override` + If you do not like the OSVVM default settings, you can add any of these to your :file:`LocalScriptDefaults.tcl`. + :ref:`UG/Config/HookFiles` + Also note that there are scripts that automatically run when you call a :ref:`RUFF/osvvm/simulate` or + :ref:`RUFF/osvvm/RunTest` command. |br| + You can use these scripts to display waveforms. + + +.. _UG/Configuration: + +Configuration +************* + +.. _UG/Config/Override: + +Override OSVVM Script Defaults +============================== + + + + +.. _UG/Config/HookFiles: + +Hook Files +========== + +.. #Scripts that Run during Simulate if they exist + ---------------------------------------------------- + +Often with simulations, we want to add a custom waveform file. This may be for all designs or just one particular +design. We may also need specific actions to be done when running on a particular simulator. + +When :ref:`RUFF/osvvm/simulate` (or :ref:`RUFF/osvvm/RunTest`) is called, it will source the following files in order, +if they exist: + +1. :file:`\.tcl` +2. :file:`\.tcl` +3. :file:`wave.do` +4. :file:`\.tcl` +5. :file:`\_\.tcl` +6. :file:`\.tcl` +7. :file:`\_\.tcl` + +:ToolVendor: is e.g. ``Aldec``, ``Cadence``, ``Siemens``, ``Synopsys``, ... +:ToolName: is e.g. ``ActiveHDL``, ``ModelSim``, ``QuestaSim``, ``RivieraPRO``, ``VCS``, ``Xcelium``, ... +:LibraryUnit: is the name specified to simulate. +:TestCaseName: is the name specified to :ref:`RUFF/osvvm/TestName`. + +.. seealso:: + + * :ref:`UG/Variables` + +.. attention:: + + Note that :file:`wave.do` will not run if you are running in a batch environment (such as ``vsim -c`` in QuestaSim). + +It will search for these files in the following directories: + +- :file:`OsvvmLibraries/Scripts` +- :file:`CurrentSimulationDirectory` +- :file:`CurrentWorkingDirectory` + +:CurrentSimulationDirectory: is the normalized path for the directory in which the simulator is running. +:CurrentWorkingDirectory: is the relative path to the directory of the script that is currently running. + +.. note:: + + Currently NVC and GHDL do not run any extra scripts since they are batch simulators. + + .. todo:: Recheck NVC, as it has an embedded TCL environment. + +.. _UG/Regression: + +Regression Testing OSVVM +************************ + +All OSVVM verification components (VCs) are delivered with their own regression test suite. There is also a +script, named :file:`RunAllTests.pro`, that runs all of the tests for that specific VC. + +To run the AXI4 Full verification component regression suite, use the :ref:`RUFF/osvvm/build` shown below. + +.. code-block:: tcl + + cd /temp + build ../OsvvmLibraries/AXI4/Axi4/RunAllTests.pro + +Everything in OSVVM is composed hierarchically. If you want to run all AXI4 (Axi4 Full, Axi4Lite, and AxiStream), +use the :ref:`RUFF/osvvm/build` shown below. + +.. code-block:: tcl + + cd /temp + build ../OsvvmLibraries/AXI4/RunAllTests.pro + +Similarly to run the tests for all VC in :file:`OsvvmLibraries` use the build shown below. + +.. code-block:: tcl + + cd /temp + build ../OsvvmLibraries/RunAllTests.pro + +.. hint:: + + For most VC and OsvvmLibraries, there is a :file:`RunDemoTests.pro` that runs a small selection of the VC test cases. + + .. code-block:: tcl + + cd /temp + build ../OsvvmLibraries/RunDemoTests.pro diff --git a/doc/UserGuide/index.rst b/doc/UserGuide/index.rst deleted file mode 100644 index 49f2140..0000000 --- a/doc/UserGuide/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _UG: - -User Guide -########## - - diff --git a/doc/UtilityLibrary/AlertLog.rst b/doc/UtilityLibrary/AlertLog.rst new file mode 100644 index 0000000..4b183e6 --- /dev/null +++ b/doc/UtilityLibrary/AlertLog.rst @@ -0,0 +1,5 @@ +.. _ALERT: + +AlertLog +######## + diff --git a/doc/UtilityLibrary/Coverage.rst b/doc/UtilityLibrary/Coverage.rst new file mode 100644 index 0000000..5cfdd4b --- /dev/null +++ b/doc/UtilityLibrary/Coverage.rst @@ -0,0 +1,5 @@ +.. _COV: + +Functional Coverage +################### + diff --git a/doc/UtilityLibrary/Random.rst b/doc/UtilityLibrary/Random.rst new file mode 100644 index 0000000..f768b51 --- /dev/null +++ b/doc/UtilityLibrary/Random.rst @@ -0,0 +1,5 @@ +.. _RAND: + +Constrained Random +################## + diff --git a/doc/VC/AXI4/index.rst b/doc/VC/AXI4/index.rst new file mode 100644 index 0000000..ac8385e --- /dev/null +++ b/doc/VC/AXI4/index.rst @@ -0,0 +1,4 @@ +.. _AXI4: + +AXI4 +#### diff --git a/doc/VC/DpRAM.rst b/doc/VC/DpRAM.rst new file mode 100644 index 0000000..8d4f3de --- /dev/null +++ b/doc/VC/DpRAM.rst @@ -0,0 +1,4 @@ +.. _DPRAM: + +DpRAM +##### diff --git a/doc/VC/Ethernet.rst b/doc/VC/Ethernet.rst new file mode 100644 index 0000000..183ca34 --- /dev/null +++ b/doc/VC/Ethernet.rst @@ -0,0 +1,4 @@ +.. _ETH: + +Ethernet +######## diff --git a/doc/VC/ModelIndependentTransactions.rst b/doc/VC/ModelIndependentTransactions.rst new file mode 100644 index 0000000..3658da1 --- /dev/null +++ b/doc/VC/ModelIndependentTransactions.rst @@ -0,0 +1,16 @@ +.. _MIT: + +Model Independent Transactions (MIT) +#################################### + +.. _MIT/Stream: + +Stream Interface Model Independent Transaction +********************************************** + + +.. _MIT/AddressBus: + +Address Bus Interface Model Independent Transaction +*************************************************** + diff --git a/doc/VC/SPI.rst b/doc/VC/SPI.rst new file mode 100644 index 0000000..b8942a8 --- /dev/null +++ b/doc/VC/SPI.rst @@ -0,0 +1,4 @@ +.. _SPI: + +SPI +### diff --git a/doc/VC/UART.rst b/doc/VC/UART.rst new file mode 100644 index 0000000..fdf7cc4 --- /dev/null +++ b/doc/VC/UART.rst @@ -0,0 +1,4 @@ +.. _UART: + +UART +#### diff --git a/doc/VC/WishBone.rst b/doc/VC/WishBone.rst new file mode 100644 index 0000000..2ba9649 --- /dev/null +++ b/doc/VC/WishBone.rst @@ -0,0 +1,4 @@ +.. _WB: + +WishBone +######## diff --git a/images/AlertReport.png b/doc/_static/images/AlertReport.png similarity index 100% rename from images/AlertReport.png rename to doc/_static/images/AlertReport.png diff --git a/images/BuildReport.png b/doc/_static/images/BuildReport.png similarity index 100% rename from images/BuildReport.png rename to doc/_static/images/BuildReport.png diff --git a/images/BuildReportWithCov.png b/doc/_static/images/BuildReportWithCov.png similarity index 100% rename from images/BuildReportWithCov.png rename to doc/_static/images/BuildReportWithCov.png diff --git a/images/BuildReport_SimulationTranscript.png b/doc/_static/images/BuildReport_SimulationTranscript.png similarity index 100% rename from images/BuildReport_SimulationTranscript.png rename to doc/_static/images/BuildReport_SimulationTranscript.png diff --git a/images/CoverageReport.png b/doc/_static/images/CoverageReport.png similarity index 100% rename from images/CoverageReport.png rename to doc/_static/images/CoverageReport.png diff --git a/images/DemoAlertReport.png b/doc/_static/images/DemoAlertReport.png similarity index 100% rename from images/DemoAlertReport.png rename to doc/_static/images/DemoAlertReport.png diff --git a/images/DemoBuildStatus.png b/doc/_static/images/DemoBuildStatus.png similarity index 100% rename from images/DemoBuildStatus.png rename to doc/_static/images/DemoBuildStatus.png diff --git a/images/DemoBuildSummaryReport.png b/doc/_static/images/DemoBuildSummaryReport.png similarity index 100% rename from images/DemoBuildSummaryReport.png rename to doc/_static/images/DemoBuildSummaryReport.png diff --git a/images/DemoCoverageReport.png b/doc/_static/images/DemoCoverageReport.png similarity index 100% rename from images/DemoCoverageReport.png rename to doc/_static/images/DemoCoverageReport.png diff --git a/images/DemoScoreboardReport.png b/doc/_static/images/DemoScoreboardReport.png similarity index 100% rename from images/DemoScoreboardReport.png rename to doc/_static/images/DemoScoreboardReport.png diff --git a/images/DemoSimTranscript.png b/doc/_static/images/DemoSimTranscript.png similarity index 100% rename from images/DemoSimTranscript.png rename to doc/_static/images/DemoSimTranscript.png diff --git a/images/DemoTestCaseDetailedReport.png b/doc/_static/images/DemoTestCaseDetailedReport.png similarity index 100% rename from images/DemoTestCaseDetailedReport.png rename to doc/_static/images/DemoTestCaseDetailedReport.png diff --git a/images/DemoTestCaseLinks.png b/doc/_static/images/DemoTestCaseLinks.png similarity index 100% rename from images/DemoTestCaseLinks.png rename to doc/_static/images/DemoTestCaseLinks.png diff --git a/images/DemoTestCaseSummaries.png b/doc/_static/images/DemoTestCaseSummaries.png similarity index 100% rename from images/DemoTestCaseSummaries.png rename to doc/_static/images/DemoTestCaseSummaries.png diff --git a/images/DemoTestSuiteSummary.png b/doc/_static/images/DemoTestSuiteSummary.png similarity index 100% rename from images/DemoTestSuiteSummary.png rename to doc/_static/images/DemoTestSuiteSummary.png diff --git a/images/DemoVHDLTranscript.png b/doc/_static/images/DemoVHDLTranscript.png similarity index 100% rename from images/DemoVHDLTranscript.png rename to doc/_static/images/DemoVHDLTranscript.png diff --git a/images/TestCase_SimulationTranscript.png b/doc/_static/images/TestCase_SimulationTranscript.png similarity index 100% rename from images/TestCase_SimulationTranscript.png rename to doc/_static/images/TestCase_SimulationTranscript.png diff --git a/images/TestReport_OsvvmTranscript.png b/doc/_static/images/TestReport_OsvvmTranscript.png similarity index 100% rename from images/TestReport_OsvvmTranscript.png rename to doc/_static/images/TestReport_OsvvmTranscript.png diff --git a/doc/build.sh b/doc/build.sh index 30bf86c..e767993 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -5,6 +5,8 @@ RUFF_TITLE="OSVVM Scripts" RUFF_NAMESPACES="::osvvm" RUFF_DIR="osvvm-scripts" +RUFF_SPHINX_PREFIX="RUFF" + # Sphinx settings SPHINX_BUILD_DIR="_build" @@ -50,6 +52,7 @@ DEBUG=0 COMMAND=1 CLEAN=0 RUFF=0 +POST=1 SPHINX=0 BUILDERS=() HTML=0 @@ -68,15 +71,18 @@ while [[ $# -gt 0 ]]; do COMMAND=3 RUFF=1 ;; + -n|--no-post-process) + POST=0 + ;; -s|--sphinx) COMMAND=3 SPHINX=1 ;; - --html) + -H|--html) HTML=1 BUILDERS+=("html") ;; - --latex) + -l|--latex) LATEX=1 BUILDERS+=("latex") ;; @@ -114,23 +120,24 @@ if [[ ${COMMAND} -le 1 ]]; then printf "%s\n" " ${ANSI_LIGHT_CYAN}$(basename "$0")${ANSI_NOCOLOR} [] [--clean] [--all] [--ruff] [--sphinx]" printf "\n" printf "%s\n" "${ANSI_CYAN}Common commands:${ANSI_NOCOLOR}" - printf "%s\n" " -h --help Print this help page" - printf "%s\n" " -c --clean Remove all generated files" + printf "%s\n" " -h --help Print this help page" + printf "%s\n" " -c --clean Remove all generated files" printf "\n" printf "%s\n" "${ANSI_CYAN}Steps:${ANSI_NOCOLOR}" - printf "%s\n" " -a --all Run all steps (--ruff --sphinx)." - printf "%s\n" " -r --ruff Extract code documentation from TCL code using Ruff!." - printf "%s\n" " -s --sphinx Build documentation using Sphinx." - printf "%s\n" " If not specified, build only HTML variant." - printf "%s\n" " --html Build HTML documentation using Sphinx." - printf "%s\n" " --latex Build LaTeX documentation using Sphinx." + printf "%s\n" " -a --all Run all steps (--ruff --sphinx)." + printf "%s\n" " -r --ruff Extract code documentation from TCL code using Ruff!." + printf "%s\n" " -n --no-post-process No post-processing of Ruff! generated files." + printf "%s\n" " -s --sphinx Build documentation using Sphinx." + printf "%s\n" " If not specified, build only HTML variant." + printf "%s\n" " -H --html Build HTML documentation using Sphinx." + printf "%s\n" " -l --latex Build LaTeX documentation using Sphinx." printf "\n" printf "%s\n" "${ANSI_CYAN}Verbosity:${ANSI_NOCOLOR}" - printf "%s\n" " -v --verbose Print verbose messages." - printf "%s\n" " -d --debug Print debug messages." + printf "%s\n" " -v --verbose Print verbose messages." + printf "%s\n" " -d --debug Print debug messages." printf "\n" printf "%s\n" "${ANSI_CYAN}Requirements:${ANSI_NOCOLOR}" - printf "%s\n" " -i --install Install / update required Python packages." + printf "%s\n" " -i --install Install / update required Python packages." exit ${COMMAND} fi @@ -206,30 +213,112 @@ EOF ls ${RUFF_DIR} | sed 's/^/ /' fi - printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ...\n" - #printf -- " ${ANSI_CYAN}Patching ${RUFF_DIR}/index.rst ...${ANSI_NOCOLOR}\n" - #sed -i -E 's/.rst$//g' ${RUFF_DIR}/index.rst # for page split - #sed -i -E 's/:maxdepth: .*$/:hidden:/g' ${RUFF_DIR}/index.rst # for page split - #sed -i -E 's/:caption: .*$//g' ${RUFF_DIR}/index.rst # for page split - #sed -i -E 's/ osvvm$//g' ${RUFF_DIR}/index.rst # for page split - - for rstFile in ${RUFF_DIR}/*.rst; do - printf -- " ${ANSI_CYAN}Patching ${rstFile} ...${ANSI_NOCOLOR}\n" - test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove intermediate 'Commands' heading${ANSI_NOCOLOR}\n" - sed -i -E 's/^Commands//g' ${rstFile} - sed -i -E 's/^========//g' ${rstFile} - - test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Correct index entry${ANSI_NOCOLOR}\n" - sed -i -E 's/ single: ::osvvm::/ single: ::osvvm; /g' ${rstFile} - - test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove links from headings${ANSI_NOCOLOR}\n" - sed -i -E 's/^``(\w+)``.*$/\1/g' ${rstFile} - #sed -i -E 's/-----------------------------------------------$//g' ${rstFile} # for pagesplit - sed -i -E 's/-----------------------------------------$//g' ${rstFile} # for single page - - test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove inline code markers from parameter names${ANSI_NOCOLOR}\n" - sed -i -E 's/^:``(\w+)``:/:\1:/g' ${rstFile} - done + if [[ ${POST} -eq 1 ]]; then + printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ...${ANSI_NOCOLOR}\n" + #printf -- " ${ANSI_CYAN}Patching ${RUFF_DIR}/index.rst ...${ANSI_NOCOLOR}\n" + #sed -i -E 's/.rst$//g' ${RUFF_DIR}/index.rst # for page split + #sed -i -E 's/:maxdepth: .*$/:hidden:/g' ${RUFF_DIR}/index.rst # for page split + #sed -i -E 's/:caption: .*$//g' ${RUFF_DIR}/index.rst # for page split + #sed -i -E 's/ osvvm$//g' ${RUFF_DIR}/index.rst # for page split + + for rstFile in ${RUFF_DIR}/*.rst; do + printf -- " ${ANSI_CYAN}Patching ${rstFile} ...${ANSI_NOCOLOR}\n" + + filename="${rstFile##*/}" + namespace="${filename%.*}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Insert index entry for '${namespace}' namespace${ANSI_NOCOLOR}\n" + sed -i -E "/^\.\. _r-${namespace}:$/a \\\n.. index::\n single: ${namespace}" "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove intermediate 'Commands' heading${ANSI_NOCOLOR}\n" + sed -i -E "/^\.\. _r-3a3a${namespace}.*Commands:/,/^========$/d" "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Correct index entry${ANSI_NOCOLOR}\n" + sed -i -E "/^\.\. index::/{N; N; s|\n\.\. index::||}" "${rstFile}" + sed -i -E "s| single: ${namespace} namespace;| single: ${namespace}; |g" "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Add readable label${ANSI_NOCOLOR}\n" + sed -i -E "s|^\.\. _r-3a3a(\w+)3a3a(\w+):|&\n.. _${RUFF_SPHINX_PREFIX}/\1/\2:| " "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove backticks from heading${ANSI_NOCOLOR}\n" + sed -i -E 's|^``(\w+)``$|\1|g' "${rstFile}" + sed -i -E 's|----$||g' "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Remove inline code markers from parameter names${ANSI_NOCOLOR}\n" + sed -i -E 's|^:``(\w+)``:|:\1:|g' "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Cleanup ReST roles${ANSI_NOCOLOR}\n" + sed -i -E 's|:ref:``([^`]*)``|:ref:`\1`|g' "${rstFile}" + sed -i -E 's|:file:``([^`]*)``|:file:`\1`|g' "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Fix todo directive${ANSI_NOCOLOR}\n" + sed -i '/^\.\. todo::/,/^\.\. seealso::/ s/^- / - /' "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Fix seealso directive${ANSI_NOCOLOR}\n" + sed -i '/^\.\. seealso::/,/^\.\. index::/ s/^- / - /' "${rstFile}" + + test $VERBOSE -eq 1 && printf -- " ${ANSI_LIGHT_CYAN}Move return value up${ANSI_NOCOLOR}\n" + awk -i inplace ' +function flush_buffers() { + # If we have a Return Value block, print it first + if (return_buf != "") { + printf "%s", return_buf; + } + # Then print the Description/Seealso/Middle block + if (desc_buf != "") { + printf "%s", desc_buf; + } + desc_buf = ""; return_buf = ""; + in_desc = 0; in_return = 0; +} + +# 1. Detect the start of the Description block +/^.. rubric:: Description/ { + flush_buffers(); # Safety flush in case of back-to-back procedures + in_desc = 1; + desc_buf = $0 ORS; + next; +} + +# 2. Detect the start of the Return value block +/^.. rubric:: Return value/ { + if (in_desc) { + in_desc = 0; + in_return = 1; + return_buf = $0 ORS; + next; + } + print; # If found outside a description context, print normally + next; +} + +# 3. Detect the end of the procedure (the index) +/^.. index::/ { + if (in_return) { + flush_buffers(); + } else if (in_desc) { + # If we reached index without finding a Return Value + printf "%s", desc_buf; + desc_buf = ""; + in_desc = 0; + } + print; + next; +} + +# 4. Collection Logic +in_desc { desc_buf = desc_buf $0 ORS; next } +in_return { return_buf = return_buf $0 ORS; next } + +# 5. Default Print +{ print } + +END { flush_buffers() } +' "${rstFile}" + done + else + printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ... ${ANSI_YELLOW}[SKIPPED]\n${ANSI_NOCOLOR}" + fi fi # Build documentation using Sphinx diff --git a/doc/index.rst b/doc/index.rst index 1cd66de..69b2f38 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,6 +1,21 @@ The OSVVM Simulator Script Library ################################## +.. image:: https://img.shields.io/badge/OSVVM-OSVVM--Scripts-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 + :alt: Sourcecode on GitHub + :height: 22 + :target: https://github.com/OSVVM/OSVVM-Scripts +.. image:: https://img.shields.io/badge/code-Apache%20License,%202.0-97ca00.svg?longCache=true&logo=Apache&labelColor=555555 + :alt: Code license + :height: 22 + :target: License.html +.. image:: https://img.shields.io/github/v/tag/OSVVM/OsvvmLibraries + :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest + :alt: GitHub Release +.. image:: https://img.shields.io/github/v/release/OSVVM/OsvvmLibraries + :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest + :alt: GitHub Release + The *OSVVM Simulator Script Library* provides a simple way to compile designs, run simulations, and use libraries. This scripting approach provides: @@ -10,8 +25,39 @@ This scripting approach provides: * Simple path management – everything is relative to the script location * Simple usage of libraries +This is an evolving approach. Input is welcome. + +.. _NEWS: + +News +**** + +Latest blog posts and news are available at the `OSVVM Blog `__. + +v2026.01 (upcoming) +=================== + +* tbd + +v2025.06a +========= + +* tbd + +v2025.06 +======== + +* tbd + +v2025.04 +======== + +* tbd +v2025.02 +======== +* tbd .. _CONTRIBUTORS: @@ -31,12 +77,12 @@ License .. only:: html - The ``::osvvm`` TCL namespace (source code) is licensed under `Apache License 2.0 `__. |br| + The ``::osvvm`` Tcl namespace (source code) is licensed under `Apache License 2.0 `__. |br| The accompanying documentation is licensed under `Creative Commons - Attribution 4.0 (CC-BY 4.0) `__. .. only:: latex - This ``::osvvm`` TCL namespace (source code) is licensed under **Apache License 2.0**. |br| + This ``::osvvm`` Tcl namespace (source code) is licensed under **Apache License 2.0**. |br| The accompanying documentation is licensed under **Creative Commons - Attribution 4.0 (CC-BY 4.0)**. @@ -46,17 +92,47 @@ License Installation QuickStartGuide + ToolSpecific + Support .. raw:: latex \part{Main Documentation} .. toctree:: - :caption: User Guide + :caption: OSVVM Utility Library + :hidden: + + UtilityLibrary/AlertLog + UtilityLibrary/Coverage + UtilityLibrary/Random + +.. toctree:: + :caption: Verification Components + :hidden: + + VC/AXI4/index + VC/DpRAM + VC/Ethernet + VC/SPI + VC/UART + VC/VideoBus + VC/WishBone + +.. toctree:: + :caption: Co-Simulation + :hidden: + + CoSim/index + CoSim/PCIe + +.. toctree:: + :caption: Scripting Guide :hidden: - UserGuide/index + UserGuide Reports/index + RequirementsTracking .. raw:: latex @@ -66,7 +142,8 @@ License :caption: References and Reports :hidden: - TCL Command Reference + VC/ModelIndependentTransactions + Tcl Command Reference YAML/index .. raw:: latex