diff --git a/OsvvmScriptsCore.tcl b/OsvvmScriptsCore.tcl index 93f9a43..1e4cbd4 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 @@ -1089,25 +1090,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 @@ -1473,7 +1476,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/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. diff --git a/doc/ToolSpecific.rst b/doc/ToolSpecific.rst new file mode 100644 index 0000000..a31bd97 --- /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 /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 + + +.. _SIM/Aldec: + +Aldec +***** + +.. _SIM/Aldec/ActiveHDL: + +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. + +.. _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 /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 + +.. _SIM/GHDL/Linux: +.. _SIM/GHDL/macOS: + +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`. + +.. _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/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..83ad268 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)**. @@ -46,6 +46,7 @@ License Installation QuickStartGuide + ToolSpecific .. raw:: latex @@ -66,7 +67,7 @@ License :caption: References and Reports :hidden: - TCL Command Reference + Tcl Command Reference YAML/index .. raw:: latex