Paebbels/ruff 3.0b1

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 <RUFF/osvvm/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 {

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/

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:`\<script-name\>.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 <library-name>`
+ Make this library the active library. Create it if it does not exist.
+:tclcode:`analyze <VHDL-file>`
+ Compile (aka analyze) the design into the active library.
+:tclcode:`simulate <test-name>`
+ Simulate (aka elaborate + run) the design using the active library.
+:tclcode:`include <script-name>.pro`
+ Include another project script.
+:tclcode:`build <script-name>.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.

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 <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
+
+   .. tab-item:: Siemens Visualizer
+      :sync: Visualizer
+
+      TODO
+
+      .. code-block:: tcl
+
+         source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
+
+   .. tab-item:: Siemens EDA Questa / QuestaSim
+      :sync: Questa
+
+      TODO
+
+      .. code-block:: tcl
+
+         source <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
+
+   .. tab-item:: Siemens EDA ModelSim
+      :sync: ModelSim
+
+      TODO
+
+      .. code-block:: tcl
+
+         source <path-to-OsvvmLibraries>/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 <path-to-OsvvmLibraries>/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 <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
+
+To simplify the startup process, put :file:`source <path-to-OsvvmLibraries>/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 <path-to-OsvvmLibraries>/OsvvmLibraries/Scripts/StartUp.tcl
+
+To simplify this, put :file:`source <path-to-OsvvmLibraries>/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
+===