From 6f38f4be183f64e40a8a0c035318e34141721af0 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Feb 2026 23:52:45 +0100 Subject: [PATCH 1/9] doc: Updated build.sh for Ruff! 3.0b1. --- OsvvmScriptsCore.tcl | 41 ++++++++++---------- doc/Glossary.rst | 9 ++++- doc/build.sh | 89 ++++++++++++++++++++++++++------------------ doc/index.rst | 6 +-- 4 files changed, 84 insertions(+), 61 deletions(-) diff --git a/OsvvmScriptsCore.tcl b/OsvvmScriptsCore.tcl index 79aa6bc..6341c86 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 @@ -1100,25 +1101,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` + # * VHDL `*.vhd`/`*.vhdl` + # * Verilog `*.v` + # * SystemVerilog `*.sv` + # + # :ref:`ghdl::analyze ` variable AnalyzeErrorCount variable AnalyzeErrorStopCount variable ConsecutiveAnalyzeErrors @@ -1501,7 +1504,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 { diff --git a/doc/Glossary.rst b/doc/Glossary.rst index c571ee6..bb09bae 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -6,5 +6,10 @@ Glossary OSVVM tbd - TCL - tbd + Tcl + Tool Command Language + + .. rubric:: Further reading + + * https://en.wikipedia.org/wiki/Tcl + * https://www.tcl-lang.org/ diff --git a/doc/build.sh b/doc/build.sh index 30bf86c..8bc0a7e 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -50,6 +50,7 @@ DEBUG=0 COMMAND=1 CLEAN=0 RUFF=0 +POST=1 SPHINX=0 BUILDERS=() HTML=0 @@ -68,15 +69,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 +118,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 +211,40 @@ 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}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}" + 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..8ccda2d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -31,12 +31,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)**. @@ -66,7 +66,7 @@ License :caption: References and Reports :hidden: - TCL Command Reference + Tcl Command Reference YAML/index .. raw:: latex From f5373783527b0482da897368d5cf129a1fee01d1 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Feb 2026 23:54:48 +0100 Subject: [PATCH 2/9] doc: Started tool specify section. --- doc/ToolSpecific.rst | 155 +++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + 2 files changed, 156 insertions(+) create mode 100644 doc/ToolSpecific.rst diff --git a/doc/ToolSpecific.rst b/doc/ToolSpecific.rst new file mode 100644 index 0000000..b5b7e9e --- /dev/null +++ b/doc/ToolSpecific.rst @@ -0,0 +1,155 @@ +.. _SIM: + +Simulator Specifics +################### + +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 /OsvvmLibraries/Scripts/StartUp.tcl + + .. tab-item:: Siemens Visualizer + :sync: Visualizer + + TODO + + .. code-block:: tcl + + source /OsvvmLibraries/Scripts/StartUp.tcl + + .. tab-item:: Siemens EDA Questa / QuestaSim + :sync: Questa + + TODO + + .. code-block:: tcl + + source /OsvvmLibraries/Scripts/StartUp.tcl + + .. tab-item:: Siemens EDA ModelSim + :sync: ModelSim + + TODO + + .. code-block:: tcl + + source /OsvvmLibraries/Scripts/StartUp.tcl + + +Aldec +***** + +Active-HDL +========== + +Initialize the OSVVM Script environment with the following commands: + +.. code-block:: tcl + + scripterconf -tcl + do -tcl /OsvvmLibraries/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. + + +Riviera-PRO +=========== + +AMD (Xilinx) +************ + +xSim +==== + + +Cadence +******* + +Xcelium +======= + + +GHDL +**** + +GHDL on Windows in MSYS2/UCRT64 +=============================== + +Initialize the OSVVM Script environment within **tclsh**: + +.. code-block:: tcl + + winpty tclsh + source /OsvvmLibraries/Scripts/StartUp.tcl + +To simplify the startup process, put :file:`source /OsvvmLibraries/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 + +GHDL on Linux/macOS +=================== + +Initialize the OSVVM Script environment within **tclsh**: + +.. code-block:: tcl + + rlwrap tclsh + source /OsvvmLibraries/Scripts/StartUp.tcl + +To simplify this, put :file:`source /OsvvmLibraries/Scripts/StartUp.tcl` in the :file:`.tclshrc` +file and in Bash add ``alias gsim='rlwrap tclsh'`` to your :file:`.bashrc`. + + +NVC +*** + +NVC on Windows in MSYS2/UCRT64 +============================== + +NVC on Linux +============ + +Siemens EDA +*********** + +ModelSim +======== + + +Questa / QuestaSim +================== + + +Visualizer +========== + + +Synopsys +******** + +VCS +=== diff --git a/doc/index.rst b/doc/index.rst index 8ccda2d..83ad268 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -46,6 +46,7 @@ License Installation QuickStartGuide + ToolSpecific .. raw:: latex From 1739bdbb0a659d5bce1eeda511daaa4c0c5e2755 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 12 Feb 2026 23:55:23 +0100 Subject: [PATCH 3/9] doc: Added QuickStart sections. --- doc/QuickStartGuide.rst | 80 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/doc/QuickStartGuide.rst b/doc/QuickStartGuide.rst index 4749aed..988b3ae 100644 --- a/doc/QuickStartGuide.rst +++ b/doc/QuickStartGuide.rst @@ -52,3 +52,83 @@ 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. From c44e31daf751436d15af4cde2373e9183f15570e Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Fri, 13 Feb 2026 01:17:16 +0100 Subject: [PATCH 4/9] doc: Added cards per vendor. --- doc/ToolSpecific.rst | 74 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/doc/ToolSpecific.rst b/doc/ToolSpecific.rst index b5b7e9e..a31bd97 100644 --- a/doc/ToolSpecific.rst +++ b/doc/ToolSpecific.rst @@ -3,6 +3,45 @@ 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 ************** @@ -45,9 +84,13 @@ Quick Overview source /OsvvmLibraries/Scripts/StartUp.tcl +.. _SIM/Aldec: + Aldec ***** +.. _SIM/Aldec/ActiveHDL: + Active-HDL ========== @@ -65,27 +108,40 @@ Want to avoid doing this every time? For ActiveHDL, edit :file:`/script/startup. 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 =============================== @@ -110,6 +166,9 @@ console window with a Tcl shell and pre-loaded OSVVM Script environment. 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 =================== @@ -123,33 +182,48 @@ Initialize the OSVVM Script environment within **tclsh**: To simplify this, put :file:`source /OsvvmLibraries/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 === From a280e16a1b4700af652b7d5a6a980b07498488b7 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sat, 14 Feb 2026 21:06:13 +0100 Subject: [PATCH 5/9] doc: Move more sections from README. --- doc/Glossary.rst | 34 ++++++- doc/Installation.rst | 93 +++++++++++++++++-- doc/Reports.rst | 40 ++++++++ doc/Reports/index.rst | 6 -- doc/Support.rst | 20 ++++ doc/ToolSpecific.rst | 18 ++-- doc/UserGuide.rst | 201 ++++++++++++++++++++++++++++++++++++++++ doc/UserGuide/index.rst | 6 -- doc/build.sh | 5 + doc/index.rst | 20 +++- 10 files changed, 410 insertions(+), 33 deletions(-) create mode 100644 doc/Reports.rst delete mode 100644 doc/Reports/index.rst create mode 100644 doc/Support.rst create mode 100644 doc/UserGuide.rst delete mode 100644 doc/UserGuide/index.rst diff --git a/doc/Glossary.rst b/doc/Glossary.rst index bb09bae..1493882 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -3,13 +3,41 @@ Glossary .. glossary:: + GTKWave + tbd + + .. rubric:: Further reading + + * GitHub: https://github.com/gtkwave/gtkwave + * Website: https://gtkwave.github.io/gtkwave/ |br| https://gtkwave.sourceforge.net/ + 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 - Tool Command Language + **T**ool **C**ommand **L**anguage + + .. rubric:: Further reading + + * Wikipedia: https://en.wikipedia.org/wiki/Tcl + * Website: https://www.tcl-lang.org/ + + YAML + **Y**AML **A**in't **M**arkup **L**anguage .. rubric:: Further reading - * https://en.wikipedia.org/wiki/Tcl - * https://www.tcl-lang.org/ + * Wikipedia: https://en.wikipedia.org/wiki/YAML + * Website: https://yaml.org/ diff --git a/doc/Installation.rst b/doc/Installation.rst index c74cddb..685e7a8 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -3,17 +3,96 @@ Installation/Updates #################### -Clone OSVVM Libraries -********************* +.. image:: https://img.shields.io/badge/OSVVM-OsvvmLibraries-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 + :alt: Sourcecode on GitHub + :height: 22 + :target: https://github.com/OSVVM/OsvvmLibraries +.. 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 on https://github.com/OSVVM. It's components are split into multiple Git repositories, +which be used individually or as a group. The all-in-one repository is called +`OsvvmLibraries `__. -Download OSVVM Libraries -************************ OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page. -On GitHub, all OSVVM libraries are a submodule of the repository OsvvmLibraries. Download all OSVVM libraries using -``git clone`` with the ``–recursive`` flag: +Clone OsvvmLibraries +******************** + +OsvvmLibraries summarizes 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 `__ + + +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 - git clone --recursive https://github.com/osvvm/OsvvmLibraries + cd /lib + git submodule add https://github.com/OSVVM/OsvvmLibraries.git + git submodule update --init --recursive + +.. seealso:: + + Git Documentation: `git submodule add `__ + + +Register Individual VCs as Git Submodule +**************************************** + +.. todo:: + + describe individual submodule workflow + +Updating OSVVM or OSVVM Components +********************************** + +.. todo:: + + describe update process using Git + + +Download OSVVM Libraries +************************ + +.. image:: https://img.shields.io/github/v/release/OSVVM/OsvvmLibraries + :target: https://github.com/OSVVM/OsvvmLibraries/releases/latest + :alt: GitHub Release + +OsvvmLibraries is also offered as an archive at https://github.com/OSVVM/OsvvmLibraries/releases/latest + +* ``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. + + +Business Continuity Planning +**************************** + +.. todo: + + describe fork structure + + 1. fork on GitHub + 2. mirror to local Git server (e.g. GitLab) + 3. clone to local machine + diff --git a/doc/Reports.rst b/doc/Reports.rst new file mode 100644 index 0000000..f1fcb9f --- /dev/null +++ b/doc/Reports.rst @@ -0,0 +1,40 @@ +.. _RPT: + +Reports (HTML) +############## + +Overview +******** + + + +Build Index +*********** + + + +Build Summary Report +******************** + + +Testcase Summary +**************** + + +AlertLog Report +*************** + + + +Reports (XML) +############# + +JUnit Test Summary Report +************************* + + +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 deleted file mode 100644 index 3fdcbca..0000000 --- a/doc/Reports/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _RPT: - -Reports -####### - - diff --git a/doc/Support.rst b/doc/Support.rst new file mode 100644 index 0000000..408b801 --- /dev/null +++ b/doc/Support.rst @@ -0,0 +1,20 @@ + +.. _SUPPORT: + +Support +####### + +.. todo:: + + * Gitter + * GitHub issues + * osvvm blog + * osvvm forum + + +Reporting Bugs +************** + +Suggesting Enhancements +*********************** + diff --git a/doc/ToolSpecific.rst b/doc/ToolSpecific.rst index a31bd97..9a9a16b 100644 --- a/doc/ToolSpecific.rst +++ b/doc/ToolSpecific.rst @@ -54,7 +54,7 @@ Quick Overview .. code-block:: tcl - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl .. tab-item:: Siemens Visualizer :sync: Visualizer @@ -63,7 +63,7 @@ Quick Overview .. code-block:: tcl - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl .. tab-item:: Siemens EDA Questa / QuestaSim :sync: Questa @@ -72,7 +72,7 @@ Quick Overview .. code-block:: tcl - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl .. tab-item:: Siemens EDA ModelSim :sync: ModelSim @@ -81,7 +81,7 @@ Quick Overview .. code-block:: tcl - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl .. _SIM/Aldec: @@ -99,7 +99,7 @@ Initialize the OSVVM Script environment with the following commands: .. code-block:: tcl scripterconf -tcl - do -tcl /OsvvmLibraries/Scripts/StartUp.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. @@ -150,9 +150,9 @@ Initialize the OSVVM Script environment within **tclsh**: .. code-block:: tcl winpty tclsh - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl -To simplify the startup process, put :file:`source /OsvvmLibraries/Scripts/StartUp.tcl` into +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. @@ -177,9 +177,9 @@ Initialize the OSVVM Script environment within **tclsh**: .. code-block:: tcl rlwrap tclsh - source /OsvvmLibraries/Scripts/StartUp.tcl + source /Scripts/StartUp.tcl -To simplify this, put :file:`source /OsvvmLibraries/Scripts/StartUp.tcl` in the :file:`.tclshrc` +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: diff --git a/doc/UserGuide.rst b/doc/UserGuide.rst new file mode 100644 index 0000000..089a968 --- /dev/null +++ b/doc/UserGuide.rst @@ -0,0 +1,201 @@ +.. _UG: + +User Guide +########## + + +Structuring Project Files +************************* + + + + +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/Debugging: + +Debugging +********* + + + + + + +.. _UG/Configuration: + +Configuration +************* + + + + + + +.. _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/build.sh b/doc/build.sh index 8bc0a7e..d47b24b 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" @@ -235,6 +237,9 @@ EOF 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}" diff --git a/doc/index.rst b/doc/index.rst index 83ad268..1015b0a 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-OsvvmLibraries-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 + :alt: Sourcecode on GitHub + :height: 22 + :target: https://github.com/OSVVM/OsvvmLibraries +.. 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: @@ -47,6 +62,7 @@ License Installation QuickStartGuide ToolSpecific + Support .. raw:: latex @@ -56,8 +72,8 @@ License :caption: User Guide :hidden: - UserGuide/index - Reports/index + UserGuide + Reports .. raw:: latex From 8971ac4197a44b06661e142865a862360d13a448 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 15 Feb 2026 00:22:34 +0100 Subject: [PATCH 6/9] doc: Moved more sections from README into new locations. --- doc/Installation.rst | 32 ++- doc/QuickStartGuide.rst | 21 ++ doc/Reports.rst | 40 --- doc/Reports/HTML.rst | 230 ++++++++++++++++++ doc/Reports/XML.rst | 27 ++ doc/Reports/YAML.rst | 7 + doc/Reports/index.rst | 38 +++ doc/RequirementsTracking.rst | 10 + doc/Support.rst | 41 +++- doc/UserGuide.rst | 223 ++++++++++++++++- .../_static/images}/AlertReport.png | Bin .../_static/images}/BuildReport.png | Bin .../_static/images}/BuildReportWithCov.png | Bin .../BuildReport_SimulationTranscript.png | Bin .../_static/images}/CoverageReport.png | Bin .../_static/images}/DemoAlertReport.png | Bin .../_static/images}/DemoBuildStatus.png | Bin .../images}/DemoBuildSummaryReport.png | Bin .../_static/images}/DemoCoverageReport.png | Bin .../_static/images}/DemoScoreboardReport.png | Bin .../_static/images}/DemoSimTranscript.png | Bin .../images}/DemoTestCaseDetailedReport.png | Bin .../_static/images}/DemoTestCaseLinks.png | Bin .../_static/images}/DemoTestCaseSummaries.png | Bin .../_static/images}/DemoTestSuiteSummary.png | Bin .../_static/images}/DemoVHDLTranscript.png | Bin .../images}/TestCase_SimulationTranscript.png | Bin .../images}/TestReport_OsvvmTranscript.png | Bin doc/index.rst | 38 ++- 29 files changed, 644 insertions(+), 63 deletions(-) delete mode 100644 doc/Reports.rst create mode 100644 doc/Reports/HTML.rst create mode 100644 doc/Reports/XML.rst create mode 100644 doc/Reports/YAML.rst create mode 100644 doc/Reports/index.rst create mode 100644 doc/RequirementsTracking.rst rename {images => doc/_static/images}/AlertReport.png (100%) rename {images => doc/_static/images}/BuildReport.png (100%) rename {images => doc/_static/images}/BuildReportWithCov.png (100%) rename {images => doc/_static/images}/BuildReport_SimulationTranscript.png (100%) rename {images => doc/_static/images}/CoverageReport.png (100%) rename {images => doc/_static/images}/DemoAlertReport.png (100%) rename {images => doc/_static/images}/DemoBuildStatus.png (100%) rename {images => doc/_static/images}/DemoBuildSummaryReport.png (100%) rename {images => doc/_static/images}/DemoCoverageReport.png (100%) rename {images => doc/_static/images}/DemoScoreboardReport.png (100%) rename {images => doc/_static/images}/DemoSimTranscript.png (100%) rename {images => doc/_static/images}/DemoTestCaseDetailedReport.png (100%) rename {images => doc/_static/images}/DemoTestCaseLinks.png (100%) rename {images => doc/_static/images}/DemoTestCaseSummaries.png (100%) rename {images => doc/_static/images}/DemoTestSuiteSummary.png (100%) rename {images => doc/_static/images}/DemoVHDLTranscript.png (100%) rename {images => doc/_static/images}/TestCase_SimulationTranscript.png (100%) rename {images => doc/_static/images}/TestReport_OsvvmTranscript.png (100%) diff --git a/doc/Installation.rst b/doc/Installation.rst index 685e7a8..932bd42 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -3,25 +3,27 @@ Installation/Updates #################### -.. image:: https://img.shields.io/badge/OSVVM-OsvvmLibraries-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 +.. 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/OsvvmLibraries + :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 on https://github.com/OSVVM. It's components are split into multiple Git repositories, -which be used individually or as a group. The all-in-one repository is called +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 `__. +See :ref:`INSTALL/Download` for downloadable archives. -OSVVM is available as either a git repository OSVVM Libraries or a zip file from osvvm.org Downloads Page. + +.. _INSTALL/Clone: Clone OsvvmLibraries ******************** -OsvvmLibraries summarizes all OSVVM repositories into a single parent repository, which has OSVVM's components +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. @@ -34,6 +36,8 @@ When cloning ensure to append the ``–recursive`` flag. Git Documentation: `git clone `__ +.. _INSTALL/Submodule: + Register OsvvmLibraries as Git Submodule **************************************** @@ -51,6 +55,8 @@ OSVVM as a submodule into that project. The following commands assume, OSVVM get Git Documentation: `git submodule add `__ +.. _INSTALL/IndividualSubmodules: + Register Individual VCs as Git Submodule **************************************** @@ -58,6 +64,9 @@ Register Individual VCs as Git Submodule describe individual submodule workflow + +.. _INSTALL/Updating: + Updating OSVVM or OSVVM Components ********************************** @@ -66,6 +75,8 @@ Updating OSVVM or OSVVM Components describe update process using Git +.. _INSTALL/Download: + Download OSVVM Libraries ************************ @@ -85,6 +96,14 @@ OsvvmLibraries is also offered as an archive at https://github.com/OSVVM/OsvvmLi 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 **************************** @@ -95,4 +114,3 @@ Business Continuity Planning 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 988b3ae..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 ********************************************* @@ -132,3 +143,13 @@ API. The script API is created using Tcl procedures. 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.rst b/doc/Reports.rst deleted file mode 100644 index f1fcb9f..0000000 --- a/doc/Reports.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _RPT: - -Reports (HTML) -############## - -Overview -******** - - - -Build Index -*********** - - - -Build Summary Report -******************** - - -Testcase Summary -**************** - - -AlertLog Report -*************** - - - -Reports (XML) -############# - -JUnit Test Summary Report -************************* - - -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/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 new file mode 100644 index 0000000..7cea53e --- /dev/null +++ b/doc/Reports/index.rst @@ -0,0 +1,38 @@ +.. _RPT: + +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 index 408b801..b72e8d9 100644 --- a/doc/Support.rst +++ b/doc/Support.rst @@ -4,17 +4,40 @@ Support ####### -.. todo:: +Get support for OSVVM at `osvvm.org `__. - * Gitter - * GitHub issues - * osvvm blog - * osvvm forum +See also the following resources. -Reporting Bugs -************** +.. topic:: OSVVM Forum -Suggesting Enhancements -*********************** + 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/UserGuide.rst b/doc/UserGuide.rst index 089a968..3a1287f 100644 --- a/doc/UserGuide.rst +++ b/doc/UserGuide.rst @@ -1,13 +1,136 @@ .. _UG: -User Guide -########## +Scripting Guide +############### + +Overview +******** + +.. todo:: + + anaylze + simulate + + build + testsuite + testcase + + context + + +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). + +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 @@ -51,7 +174,7 @@ Calling generic this way allows OSVVM to set generics using the method required Waveforms ********* -Adding Other Wave Files +Adding other Wave Files ======================= To include wave files with names different from above, use the :ref:`RUFF/osvvm/DoWaves` function. DoWaves is called in @@ -76,7 +199,7 @@ In Aldec and Siemens, these are run via the simulator command line (via ``-do``) 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 +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 @@ -91,14 +214,103 @@ without a ``true`` or ``false`` value, the default is ``true``. 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: @@ -106,7 +318,10 @@ Debugging Configuration ************* +.. _UG/Config/Override: +Override OSVVM Script Defaults +============================== 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/index.rst b/doc/index.rst index 1015b0a..d22a1f7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,10 +1,10 @@ The OSVVM Simulator Script Library ################################## -.. image:: https://img.shields.io/badge/OSVVM-OsvvmLibraries-EDB74E.svg?longCache=true&logo=GitHub&labelColor=333333 +.. 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/OsvvmLibraries + :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 @@ -25,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: @@ -73,7 +104,8 @@ License :hidden: UserGuide - Reports + Reports/index + RequirementsTracking .. raw:: latex From 71149caaece10887f561462d42653fb515447b06 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 15 Feb 2026 19:57:59 +0100 Subject: [PATCH 7/9] doc: Documented first library related functions. --- OsvvmScriptsCore.tcl | 46 +++++++++++++++++++++-- doc/AXI4/index.rst | 4 ++ doc/AlertLog.rst | 5 +++ doc/Glossary.rst | 17 +++++++-- doc/Installation.rst | 2 +- doc/ModelIndependentTransactions.rst | 4 ++ doc/UserGuide.rst | 55 +++++++++++++++++++++++++++- doc/build.sh | 16 ++++++-- doc/index.rst | 15 +++++++- 9 files changed, 151 insertions(+), 13 deletions(-) create mode 100644 doc/AXI4/index.rst create mode 100644 doc/AlertLog.rst create mode 100644 doc/ModelIndependentTransactions.rst diff --git a/OsvvmScriptsCore.tcl b/OsvvmScriptsCore.tcl index 6341c86..9b3e300 100644 --- a/OsvvmScriptsCore.tcl +++ b/OsvvmScriptsCore.tcl @@ -971,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 @@ -1121,8 +1140,7 @@ proc analyze {FileName args} { # * Verilog `*.v` # * SystemVerilog `*.sv` # - # :ref:`ghdl::analyze ` - variable AnalyzeErrorCount + variable AnalyzeErrorCount variable AnalyzeErrorStopCount variable ConsecutiveAnalyzeErrors @@ -1838,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/AXI4/index.rst b/doc/AXI4/index.rst new file mode 100644 index 0000000..ac8385e --- /dev/null +++ b/doc/AXI4/index.rst @@ -0,0 +1,4 @@ +.. _AXI4: + +AXI4 +#### diff --git a/doc/AlertLog.rst b/doc/AlertLog.rst new file mode 100644 index 0000000..4b183e6 --- /dev/null +++ b/doc/AlertLog.rst @@ -0,0 +1,5 @@ +.. _ALERT: + +AlertLog +######## + diff --git a/doc/Glossary.rst b/doc/Glossary.rst index 1493882..35866e1 100644 --- a/doc/Glossary.rst +++ b/doc/Glossary.rst @@ -11,8 +11,13 @@ Glossary * 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 + **O**\ pen-**S**\ ource **V**\ HDL **V**\ erification **M**\ ethodology .. rubric:: Further reading @@ -27,15 +32,21 @@ Glossary * Website: https://surfer-project.org/ Tcl - **T**ool **C**ommand **L**anguage + **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 + **Y**\ AML **A**\ in't **M**\ arkup **L**\ anguage .. rubric:: Further reading diff --git a/doc/Installation.rst b/doc/Installation.rst index 932bd42..6179bad 100644 --- a/doc/Installation.rst +++ b/doc/Installation.rst @@ -13,7 +13,7 @@ Installation/Updates 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 `__. +`OsvvmLibraries `__. **OSVVM-Scripts** is part of **OsvvmLibraries**. See :ref:`INSTALL/Download` for downloadable archives. diff --git a/doc/ModelIndependentTransactions.rst b/doc/ModelIndependentTransactions.rst new file mode 100644 index 0000000..30982ea --- /dev/null +++ b/doc/ModelIndependentTransactions.rst @@ -0,0 +1,4 @@ +.. _MIT: + +Model Independent Transactions +############################## diff --git a/doc/UserGuide.rst b/doc/UserGuide.rst index 3a1287f..a8af0e4 100644 --- a/doc/UserGuide.rst +++ b/doc/UserGuide.rst @@ -1,7 +1,7 @@ .. _UG: -Scripting Guide -############### +User Guide +########## Overview ******** @@ -17,6 +17,23 @@ Overview 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 ************** @@ -47,6 +64,40 @@ To compile all of the OSVVM libraries, use build as shown below. 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 ************************ diff --git a/doc/build.sh b/doc/build.sh index d47b24b..b33b9f9 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -241,11 +241,21 @@ EOF 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}" + 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}" + 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}" done else printf -- "${ANSI_MAGENTA}[BUILD] Patch ReST files ... ${ANSI_YELLOW}[SKIPPED]\n${ANSI_NOCOLOR}" diff --git a/doc/index.rst b/doc/index.rst index d22a1f7..d67522c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -100,7 +100,19 @@ License \part{Main Documentation} .. toctree:: - :caption: User Guide + :caption: OSVVM Utility Library + :hidden: + + AlertLog + +.. toctree:: + :caption: Verification Components + :hidden: + + AXI4/index + +.. toctree:: + :caption: Scripting Guide :hidden: UserGuide @@ -115,6 +127,7 @@ License :caption: References and Reports :hidden: + ModelIndependentTransactions Tcl Command Reference YAML/index From d59b669f8c1d05e218bd214bb0a6b7566a91b3bb Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 15 Feb 2026 20:29:03 +0100 Subject: [PATCH 8/9] doc: Idea on an all-in-one documentation. --- doc/CoSim/PCIe.rst | 4 ++++ doc/CoSim/index.rst | 4 ++++ doc/ModelIndependentTransactions.rst | 4 ---- doc/{ => UtilityLibrary}/AlertLog.rst | 0 doc/UtilityLibrary/Coverage.rst | 5 +++++ doc/UtilityLibrary/Random.rst | 5 +++++ doc/{ => VC}/AXI4/index.rst | 0 doc/VC/DpRAM.rst | 4 ++++ doc/VC/Ethernet.rst | 4 ++++ doc/VC/ModelIndependentTransactions.rst | 16 ++++++++++++++++ doc/VC/SPI.rst | 4 ++++ doc/VC/UART.rst | 4 ++++ doc/VC/WishBone.rst | 4 ++++ doc/index.rst | 21 ++++++++++++++++++--- 14 files changed, 72 insertions(+), 7 deletions(-) create mode 100644 doc/CoSim/PCIe.rst create mode 100644 doc/CoSim/index.rst delete mode 100644 doc/ModelIndependentTransactions.rst rename doc/{ => UtilityLibrary}/AlertLog.rst (100%) create mode 100644 doc/UtilityLibrary/Coverage.rst create mode 100644 doc/UtilityLibrary/Random.rst rename doc/{ => VC}/AXI4/index.rst (100%) create mode 100644 doc/VC/DpRAM.rst create mode 100644 doc/VC/Ethernet.rst create mode 100644 doc/VC/ModelIndependentTransactions.rst create mode 100644 doc/VC/SPI.rst create mode 100644 doc/VC/UART.rst create mode 100644 doc/VC/WishBone.rst 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/ModelIndependentTransactions.rst b/doc/ModelIndependentTransactions.rst deleted file mode 100644 index 30982ea..0000000 --- a/doc/ModelIndependentTransactions.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. _MIT: - -Model Independent Transactions -############################## diff --git a/doc/AlertLog.rst b/doc/UtilityLibrary/AlertLog.rst similarity index 100% rename from doc/AlertLog.rst rename to doc/UtilityLibrary/AlertLog.rst 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/AXI4/index.rst b/doc/VC/AXI4/index.rst similarity index 100% rename from doc/AXI4/index.rst rename to doc/VC/AXI4/index.rst 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/doc/index.rst b/doc/index.rst index d67522c..69b2f38 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -103,13 +103,28 @@ License :caption: OSVVM Utility Library :hidden: - AlertLog + UtilityLibrary/AlertLog + UtilityLibrary/Coverage + UtilityLibrary/Random .. toctree:: :caption: Verification Components :hidden: - AXI4/index + 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 @@ -127,7 +142,7 @@ License :caption: References and Reports :hidden: - ModelIndependentTransactions + VC/ModelIndependentTransactions Tcl Command Reference YAML/index From b94ce4098441f4b4822eef1e44490771c62f8fa3 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Sun, 22 Feb 2026 19:55:33 +0100 Subject: [PATCH 9/9] Updated rewrites for Ruff! output. --- doc/build.sh | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/doc/build.sh b/doc/build.sh index b33b9f9..e767993 100755 --- a/doc/build.sh +++ b/doc/build.sh @@ -256,6 +256,65 @@ EOF 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}"