From a1d4746ea7160a889afbc2a57b76b1b0d702390d Mon Sep 17 00:00:00 2001 From: umarcor Date: Tue, 9 Nov 2021 15:47:17 +0100 Subject: [PATCH] docs: reorganise 'HDL Libraries', add section 'Guides' --- docs/about.rst | 2 +- docs/blog/2018_02_12_vunit3.rst | 4 +- docs/check/user_guide.rst | 4 +- docs/com/user_guide.rst | 6 +- docs/conf.py | 1 + docs/data_types/user_guide.rst | 4 +- docs/examples.py | 1 + docs/hdl_libraries.rst | 97 ++++++++++++++++++--- docs/index.rst | 14 ++- docs/logging/user_guide.rst | 4 +- docs/release_notes/3.0.0.rst | 2 +- docs/run/user_guide.rst | 4 +- docs/verification_components/user_guide.rst | 12 +-- examples/vhdl/array_axis_vcs/run.py | 2 +- 14 files changed, 120 insertions(+), 37 deletions(-) diff --git a/docs/about.rst b/docs/about.rst index ce5d7e0d4..fdce6b590 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -84,7 +84,7 @@ Those are made available through the built-ins API, which is based on the librar Both the core and builtins are available in the public :ref:`python_interface` of VUnit. Details about how to execute a project are explained in :ref:`cli`. -Further info about the optional libraries is found in :ref:`vhdl_libraries`. +Further info about the optional libraries is found in :ref:`hdl_libraries`. Experimental co-simulation through GHDL's VHPIDIRECT is supported in `VUnit/cosim `__. diff --git a/docs/blog/2018_02_12_vunit3.rst b/docs/blog/2018_02_12_vunit3.rst index 99aa7f2b5..e716aed6c 100644 --- a/docs/blog/2018_02_12_vunit3.rst +++ b/docs/blog/2018_02_12_vunit3.rst @@ -75,7 +75,7 @@ Verification Components ----------------------- In VUnit 3.0 we have a *beta* version of a :ref:`verification -component ` library. Using the improved ``com`` message +component ` library. Using the improved ``com`` message passing it is very easy to create advanced verification components and we hope to get many pull requests from users for other bus types in the future. We've already seen some initiatives from the VUnit community @@ -93,7 +93,7 @@ Out of the box we provide the following verification components: - UART RX/TX - (B)RAM master -For more information see the :ref:`verification component library user guide `. +For more information see the :ref:`verification component library user guide `. Logging ------- diff --git a/docs/check/user_guide.rst b/docs/check/user_guide.rst index 6bcac19e8..ff0373c69 100644 --- a/docs/check/user_guide.rst +++ b/docs/check/user_guide.rst @@ -1,7 +1,7 @@ .. _check_library: -Check Library -============= +Check Library User Guide +======================== Introduction ------------ diff --git a/docs/com/user_guide.rst b/docs/com/user_guide.rst index cf18b7fd2..e4479dac5 100644 --- a/docs/com/user_guide.rst +++ b/docs/com/user_guide.rst @@ -1,8 +1,8 @@ .. _com_user_guide: -##################### -Communication Library -##################### +################################ +Communication Library User Guide +################################ ************ Introduction diff --git a/docs/conf.py b/docs/conf.py index 04da2c1b5..ed22fc649 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -109,6 +109,7 @@ intersphinx_mapping = { "python": ("https://docs.python.org/3.8/", None), "pytest": ("https://docs.pytest.org/en/latest/", None), + "osvb": ("https://umarcor.github.io/osvb", None), } # -- ExtLinks ----------------------------------------------------------------- diff --git a/docs/data_types/user_guide.rst b/docs/data_types/user_guide.rst index 623618037..dfde471a7 100644 --- a/docs/data_types/user_guide.rst +++ b/docs/data_types/user_guide.rst @@ -1,7 +1,7 @@ .. _data_types_library: -Data Types -########## +Data Types User Guide +##################### VUnit comes with a number of convenient data types included: diff --git a/docs/examples.py b/docs/examples.py index 9e66a2756..780654895 100644 --- a/docs/examples.py +++ b/docs/examples.py @@ -71,6 +71,7 @@ def _get_eg_doc(location: Path, ref): title = eg_doc.split("---", 1)[0][0:-1] return "\n".join( [ + f".. _examples:{location.parent.name}:{location.name}:\n", title, "-" * len(title), f":vunit_example:`➚ examples/{ref} <{ref!s}>`\n", diff --git a/docs/hdl_libraries.rst b/docs/hdl_libraries.rst index 2b546b43a..6094a7562 100644 --- a/docs/hdl_libraries.rst +++ b/docs/hdl_libraries.rst @@ -1,15 +1,90 @@ -.. _vhdl_libraries: +.. _hdl_libraries: -VHDL Libraries +HDL Libraries +############# + +VHDL +==== + +Builtins +-------- + +By default, VUnit provides bare minimal functionality for running testbenches. +In practice, most users want to use HDL utilities to reduce verbosity and improve reporting when writting tests. +VUnit includes several optional libraries in a group named *VHDL builtins* (see :meth:`add_vhdl_builtins() `): + +* :vunit_file:`core ` +* :vunit_file:`logging ` (see :ref:`logging_library`) +* :vunit_file:`string_ops ` +* :vunit_file:`check ` (see :ref:`check_library`) +* :vunit_file:`dictionary ` +* :vunit_file:`run ` (see :ref:`run_library`) +* :vunit_file:`path ` + +Most of the utilities are based on some internal data types providing dynamic arrays and queues (FIFOs). +See :ref:`data_types_library`. + +Communication +------------- + +The VUnit communication library (``com``) provides a high-level communication mechanism based on the +`actor model `__. + +See :meth:`add_com() ` and :ref:`com_user_guide`. + +.. NOTE:: + The Communication Library depends on the builtins, which are added implicitly. + +Verification Components +----------------------- + +.. note:: This library is released as a *BETA* version. This means non-backwards compatible changes are still likely + based on feedback from our users. + +The VUnit Verification Component Library (VCL) contains a number of useful +:ref:`Verification Components ` (VC) as well as a set of utilities for writing your own +verification component. +Verification components allow a better overview in the test bench by raising the abstraction level of bus transactions. +Even if you do not need the advanced features that VCs offer you may still benefit from using peer-verified models of an +AXI-bus instead of re-implementing it yourself. + +See :meth:`add_verification_components() ` and :ref:`vc_user_guide`. + +.. NOTE:: + The VCL depends on both the Communication Library and OSVVM, which are added implicitly. + +Random +------ + +VUnit provides random integer vector and pointer generation, based on built-in :ref:`Data Types ` +and OSVVM. + +See :meth:`add_random() `. + +OSVVM +----- + +VUnit includes the core of `OSVVM `__ as a submodule and internal dependency of optional +libraries such as Random or Verification Components. +However, it can be added explicitly through :meth:`add_osvvm() `. + +Moreover, multiple approaches are supported for using `OSVVMLibraries `__ in +VUnit. +See :ref:`OSVB: Examples » SISO AXI4 Stream `. + +JSON-for-VHDL +------------- + +VUnit includes `JSON-for-VHDL `__ as a submodule. +JSON-for-VHDL is an alternative to composite top-level generics, which supports any depth in the content structure. + +See :meth:`add_json4vhdl() `, :vunit_file:`json4vhdl.py ` and example +:ref:`JSON-for-VHDL `. + +System Verilog ============== -.. toctree:: - :maxdepth: 1 +Builtins +-------- - id/user_guide - logging/user_guide - check/user_guide - run/user_guide - com/user_guide - data_types/user_guide - verification_components/user_guide +See :meth:`add_verilog_builtins() ` and :vunit_file:`vunit_pkg.sv `. diff --git a/docs/index.rst b/docs/index.rst index d621025d8..063d1eb44 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -29,10 +29,22 @@ often"* approach through automation. :ref:`Read more ` testimonials/testimonials .. toctree:: - :caption: Documentation + :caption: Guides :hidden: user_guide + id/user_guide + logging/user_guide + check/user_guide + run/user_guide + com/user_guide + verification_components/user_guide + data_types/user_guide + +.. toctree:: + :caption: Reference + :hidden: + cli py/ui hdl_libraries diff --git a/docs/logging/user_guide.rst b/docs/logging/user_guide.rst index b8b40e3cc..8aa53079d 100644 --- a/docs/logging/user_guide.rst +++ b/docs/logging/user_guide.rst @@ -1,7 +1,7 @@ .. _logging_library: -Logging Library -=============== +Logging Library User Guide +========================== Introduction ------------ diff --git a/docs/release_notes/3.0.0.rst b/docs/release_notes/3.0.0.rst index afd32f007..1f58c21a0 100644 --- a/docs/release_notes/3.0.0.rst +++ b/docs/release_notes/3.0.0.rst @@ -1,4 +1,4 @@ -- *beta* version of a :ref:`verification component ` library. +- *beta* version of a :ref:`verification component ` library. - AXI read/write slaves - Memory model diff --git a/docs/run/user_guide.rst b/docs/run/user_guide.rst index 06627818d..2499b1cff 100644 --- a/docs/run/user_guide.rst +++ b/docs/run/user_guide.rst @@ -1,7 +1,7 @@ .. _run_library: -Run Library -=========== +Run Library User Guide +====================== Introduction ------------ diff --git a/docs/verification_components/user_guide.rst b/docs/verification_components/user_guide.rst index c2e5c3fb1..6ba1b35d1 100644 --- a/docs/verification_components/user_guide.rst +++ b/docs/verification_components/user_guide.rst @@ -1,18 +1,12 @@ -.. _vc_library: +.. _vc_user_guide: -Verification Component Library -=============================== +Verification Components User Guide +================================== .. NOTE:: This library is released as a *BETA* version. This means non-backwards compatible changes are still likely based on feedback from our users. -The VUnit Verification Component Library (VCL) contains a number of useful :ref:`Verification Components ` -(VC) as well as a set of utilities for writing your own verification component. -Verification components allow a better overview in the test bench by raising the abstraction level of bus transactions. -Even if you do not need the advanced features that VCs offer you may still benefit from using pre-verified models of an -AXI-bus instead of re-implementing it yourself. - Included verification components (VCs): - Avalon Memory-Mapped master diff --git a/examples/vhdl/array_axis_vcs/run.py b/examples/vhdl/array_axis_vcs/run.py index 049261e75..ba396e731 100644 --- a/examples/vhdl/array_axis_vcs/run.py +++ b/examples/vhdl/array_axis_vcs/run.py @@ -13,7 +13,7 @@ Shows how to use ``integer_array_t``, ``axi_stream_master_t`` and ``axi_stream_slave_t``. A CSV file is read, the content is sent in a row-major order to an AXI Stream buffer (FIFO) and it is received back to be saved in a different file. Further information can -be found in the :ref:`verification component library user guide `, +be found in the :ref:`verification component library user guide `, in subsection :ref:`Stream ` and in :vunit_file:`vhdl/verification_components/test/tb_axi_stream.vhd `. """