Added blog on VHDL configurations.

Author: LarsAsplund

docs/blog/2023_08_26_vhdl_configurations.rst

@@ -0,0 +1,159 @@
+:tags: VUnit, OSVVM, configurations
+:author: lasplund
+:excerpt: 1
+
+Improved Support for VHDL Configurations and OSVVM
+==================================================
+
+For quite some time, several initiatives have been underway to improve the integration between VUnit and OSVVM. Examples
+of these efforts are the `external logging framework integration feature
+<https://vunit.github.io/logging/user_guide.html#external-logging-framework-integration>`__ and the OSVVM pull request
+`#81 <https://github.com/OSVVM/OSVVM/pull/81>`__.
+
+Another example is the introduction of support for top-level VHDL configurations which serves several purposes, for
+example:
+
+1.  Enabling the selection of the Device Under Test (DUT) to be used in a VUnit testbench.
+2.  Direct support for running conventional OSVVM testbenches within the VUnit framework.
+
+In this blog, we will primarily focus on top-level configurations but before delving into the specifics of these use cases, we will describe how VUnit addressed these issues in the past.
+
+Selecting DUT Using Generics
+----------------------------
+
+Sometimes the VHDL DUT comes in different variants (architectures) and there is a need to verify all of these with the
+same testbench. It could be an FPGA and an ASIC implementation or an RTL and a behavioral architecture. Before
+supporting VHDL configurations, VUnit addressed this issue with a combination of generics and an if-generate statement
+as showed in the example below. For the purpose of this blog, we have removed the complexities typically found in
+real-world designs and chosen to focus on the fundamental principles. Thus, we will use a simple variable-width
+flip-flop as the DUT for our demonstrations.
+
+.. raw:: html
+    :file: img/vhdl_configuration/selecting_dut_with_generics.html
+
+This approach is straightforward: simply copy and paste the flip-flop instantiation, but modify the architecture to use
+based on the ``dut_arch`` generic. While the approach is simple it also introduces code duplication which can be a bit
+dangerous. In this case, since the copies are placed adjacent to each other, the risk of inadvertently changing one
+without updating the other is somewhat mitigated.
+
+If your DUT has numerous ports, you can consider leveraging the VHDL-2019 interface construct as a means to raise the
+level of abstraction and reduce code duplication. This approach allows for a more concise representation of the design,
+provided your simulator supports the latest VHDL standard.
+
+.. NOTE::
+    There is a proposed update to the VHDL standard related to this topic as it would fully remove the code duplication.
+    `Issue #235 <https://gitlab.com/IEEE-P1076/VHDL-Issues/-/issues/235>`__ proposes that a string should be possible
+    to use when specifying the architecture in an entity instantiation, i.e. ``"rtl"`` or ``"behavioral"`` rather than
+    ``rtl`` or ``behavioral``. In our example we would simply have a single entity instantiation which architecture is
+    specified with the ``dut_arch`` generic.
+
+The various settings of the ``dut_arch`` generic are handled with a VUnit configuration in the Python run script.
+Initially, the use of both VUnit and VHDL configuration concepts may appear confusing, but we will soon see that a VHDL
+configuration is a special case of the broader VUnit configuration concept. In this example, we are also testing the DUT
+with multiple ``width`` settings. Note how we can use the ``product`` function from ``itertools`` to iterate over all
+combinations of ``dut_arch`` and ``width``. This is equivalent to two nested loops over these generics but scales better
+as the number of generics to combine increases.
+
+.. raw:: html
+    :file: img/vhdl_configuration/create_vunit_configuration_for_selecting_dut.html
+
+If we list all the tests, we will see that there are four for each test
+case in the testbench, one for each combination of ``dut_arch`` and ``width``:
+
+.. raw:: html
+    :file: img/vhdl_configuration/tb_selecting_dut_with_generics_stdout.html
+
+Selecting DUT Using VHDL Configurations
+---------------------------------------
+
+When using VHDL configurations we need three ingredients in our testbench
+
+1. A component declaration for the DUT. In the example below it has been
+   placed in the declarative part of the testbench architecture but it
+   can also be placed in a separate package.
+2. A component instantiation of the declared component. Note that the
+   ``component`` keyword is optional and can be excluded.
+3. A configuration declaration for each DUT architecture
+
+.. raw:: html
+    :file: img/vhdl_configuration/selecting_dut_with_vhdl_configuration.html
+
+Instead of assigning a generic to select our architecture, we now specify which VHDL configuration our VUnit configuration should use:
+
+.. raw:: html
+    :file: img/vhdl_configuration/create_vunit_configuration_for_selecting_dut_with_a_vhdl_configuration.html
+
+Incorporating VHDL configurations within VUnit configurations brings forth another advantage. From a VHDL point of view,
+VHDL configurations are linked to entities, such as the testbench entity in our scenario. However, a VUnit configuration
+can also be applied to specific test cases, opening up the possibility of using VHDL configurations at that finer level
+of granularity. For instance, consider a situation where we have an FPGA and an ASIC implementation/architecure that
+differ only in the memory IPs they use. In such a case, it might be sufficient to simulate only one of the architectures
+for the test cases not involving memory operations.
+
+To illustrate this using the flip-flop example, let's create a test where we set ``width`` to 32 and exclusively
+simulate it using the RTL architecture:
+
+.. raw:: html
+    :file: img/vhdl_configuration/vhdl_configuration_on_a_test_case.html
+
+Now, we have an additional entry in our list of tests:
+
+.. raw:: html
+    :file: img/vhdl_configuration/tb_selecting_dut_with_vhdl_configuration_stdout.html
+
+Choosing between VHDL configurations and generics is primarily a matter of personal preference. The generic approach led
+us to multiple direct entity instantiations and code duplication. However, the configuration approach demands a
+component declaration, which essentially duplicates the DUT entity declaration. Additionally, VHDL configuration
+declarations are also necessary.
+
+Selecting Test Runner Using VHDL Configurations
+-----------------------------------------------
+
+In the previous examples, the VUnit test cases were located in a process called ``test_runner`` residing alongside the
+DUT. This is the most straightforward arrangement, as it provides the test cases with direct access to the DUT's
+interface. An alternative approach involves encapsulating ``test_runner`` within an entity, which is subsequently
+instantiated within the testbench. Such a ``test_runner`` entity needs access to the ``runner_cfg`` and ``width``
+generics, in addition to the ``clk_period`` constant and the interface ports of the DUT.
+
+.. raw:: html
+    :file: img/vhdl_configuration/test_runner_entity.html
+
+Note that the runner configuration generic is called ``nested_runner_cfg`` and not ``runner_cfg``. The reason is that
+``runner_cfg`` is the signature used to identify a testbench, the top-level of a simulation. The ``test_runner`` entity
+is not a simulation top-level and must not be mistaken as such.
+
+We can now replace the testbench ``test_runner`` process and watchdog with an instantiation of this component:
+
+.. raw:: html
+    :file: img/vhdl_configuration/test_runner_component_instantiation.html
+
+Having relocated ``test_runner`` into an entity, we can have VHDL configurations selecting which test runner to use, and
+let each such test runner represent a single test. This setup is the conventional methodology seen in OSVVM
+testbenches. With VUnit's extended support for VHDL configurations, it becomes possible to keep that structure when
+adding VUnit capabilities. For example, this is the architecture for the reset test:
+
+.. raw:: html
+    :file: img/vhdl_configuration/test_reset_architecture_of_test_runner.html
+
+.. NOTE::
+    When using several configurations to select what test runner to use, each test runner can only contain a single test, i.e. no test cases specified by the use of the ``run`` function are allowed.
+
+Below are the two configurations that select this particular test along with one of the ``rtl`` and ``behavioral``
+architectures for the DUT:
+
+.. raw:: html
+    :file: img/vhdl_configuration/test_reset_configurations.html
+
+This example highlights a drawback of VHDL configurations: every combination of architectures to use in a test has to be
+manually created. When we use generics and if generate statements to select architectures, we create all combinations
+**programatically** in the Python script using the ``itertools.product`` function. Despite this, Python can continue to
+play a role in alleviating certain aspects of the combinatorial workload:
+
+.. raw:: html
+    :file: img/vhdl_configuration/create_vunit_configuration_for_selecting_dut_and_runner_with_a_vhdl_configuration.html
+
+.. raw:: html
+    :file: img/vhdl_configuration/tb_selecting_test_runner_with_vhdl_configuration_stdout.html
+
+That concludes our discussion for now. As always, we highly value your feedback and appreciate any insights you might have to offer.
+

docs/news.d/179.feature.rst

@@ -0,0 +1 @@
+Added support for simulating top-level VHDL configurations.

docs/news.d/951.feature.rst

@@ -0,0 +1 @@
+Added support for simulating top-level VHDL configurations.

examples/vhdl/vhdl_configuration/dff.vhd

@@ -32,16 +32,6 @@ begin
   end process;
 end;
 
-configuration dff_rtl of tb_selecting_dut_with_vhdl_configuration is
-  for tb
-    for test_fixture
-      for dut : dff
-        use entity work.dff(rtl);
-      end for;
-    end for;
-  end for;
-end;
-
 architecture behavioral of dff is
 begin
   process
@@ -51,12 +41,3 @@ begin
   end process;
 end;
 
-configuration dff_behavioral of tb_selecting_dut_with_vhdl_configuration is
-  for tb
-    for test_fixture
-      for dut : dff
-        use entity work.dff(behavioral);
-      end for;
-    end for;
-  end for;
-end;

examples/vhdl/vhdl_configuration/run.py

@@ -20,18 +20,18 @@
 # pure VHDL configuration. For example, by running with different generic values.
 tb = lib.test_bench("tb_selecting_dut_with_vhdl_configuration")
 
-for vhdl_configuration_name in ["dff_rtl", "dff_behavioral"]:
+for dut_architecture in ["rtl", "behavioral"]:
     for width in [8, 16]:
         tb.add_config(
-            name=f"{vhdl_configuration_name}_{width}",
+            name=f"{dut_architecture}_{width}",
             generics=dict(width=width),
-            vhdl_configuration_name=vhdl_configuration_name,
+            vhdl_configuration_name=dut_architecture,
         )
 
 # A top-level VHDL configuration is bound to an entity, i.e. the testbench. However,
 # when handled as part of VUnit configurations it can also be applied to a
 # single test case
-tb.test("Test reset").add_config(name="dff_rtl_32", generics=dict(width=32), vhdl_configuration_name="dff_rtl")
+tb.test("Test reset").add_config(name="rtl_32", generics=dict(width=32), vhdl_configuration_name="rtl")
 
 
 # If the test runner is placed in a component instantiated into the testbench, different architectures of that
@@ -44,12 +44,14 @@
 # is to put each test suite in its own testbench and make the test fixture a component reused between the testbenches.
 # That approach do not require any VHDL configurations.
 tb = lib.test_bench("tb_selecting_test_runner_with_vhdl_configuration")
-for vhdl_configuration_name in ["test_reset", "test_state_change"]:
-    for width in [8, 16]:
-        tb.add_config(
-            name=f"{vhdl_configuration_name}_{width}",
-            generics=dict(width=width),
-            vhdl_configuration_name=vhdl_configuration_name,
-        )
+for test_case_name in ["test_reset", "test_state_change"]:
+    for dut_architecture in ["rtl", "behavioral"]:
+        vhdl_configuration_name = f"{test_case_name}_{dut_architecture}"
+        for width in [8, 16]:
+            tb.add_config(
+                name=f"{vhdl_configuration_name}_{width}",
+                generics=dict(width=width),
+                vhdl_configuration_name=vhdl_configuration_name,
+            )
 
 vu.main()

examples/vhdl/vhdl_configuration/tb_selecting_dut_with_vhdl_configuration.vhd

@@ -75,7 +75,7 @@ begin
   begin
     clk <= not clk after clk_period / 2;
 
-    dut : dff
+    dut : component dff
       generic map(
         width => width
       )
@@ -87,3 +87,24 @@ begin
       );
   end block;
 end architecture;
+
+configuration rtl of tb_selecting_dut_with_vhdl_configuration is
+  for tb
+    for test_fixture
+      for dut : dff
+        use entity work.dff(rtl);
+      end for;
+    end for;
+  end for;
+end;
+
+configuration behavioral of tb_selecting_dut_with_vhdl_configuration is
+  for tb
+    for test_fixture
+      for dut : dff
+        use entity work.dff(behavioral);
+      end for;
+    end for;
+  end for;
+end;
+

examples/vhdl/vhdl_configuration/tb_selecting_test_runner_with_vhdl_configuration.vhd

@@ -43,8 +43,20 @@ architecture tb of tb_selecting_test_runner_with_vhdl_configuration is
     );
   end component;
 
+  component dff is
+    generic(
+      width : positive := width
+    );
+    port(
+      clk : in std_logic;
+      reset : in std_logic;
+      d : in std_logic_vector(width - 1 downto 0);
+      q : out std_logic_vector(width - 1 downto 0)
+    );
+  end component;
+
 begin
-  test_runner_inst : test_runner
+  test_runner_inst : component test_runner
     generic map(
       clk_period => clk_period,
       width => width,
@@ -61,7 +73,7 @@ begin
   begin
     clk <= not clk after clk_period / 2;
 
-    dut : entity work.dff(rtl)
+    dut : component dff
       generic map(
         width => width
       )

examples/vhdl/vhdl_configuration/test_reset.vhd

@@ -28,10 +28,30 @@ begin
   test_runner_watchdog(runner, 10 * clk_period);
 end;
 
-configuration test_reset of tb_selecting_test_runner_with_vhdl_configuration is
+configuration test_reset_behavioral of tb_selecting_test_runner_with_vhdl_configuration is
   for tb
     for test_runner_inst : test_runner
       use entity work.test_runner(test_reset_a);
     end for;
+
+    for test_fixture
+      for dut : dff
+        use entity work.dff(behavioral);
+      end for;
+    end for;
+  end for;
+end;
+
+configuration test_reset_rtl of tb_selecting_test_runner_with_vhdl_configuration is
+  for tb
+    for test_runner_inst : test_runner
+      use entity work.test_runner(test_reset_a);
+    end for;
+
+    for test_fixture
+      for dut : dff
+        use entity work.dff(rtl);
+      end for;
+    end for;
   end for;
 end;

examples/vhdl/vhdl_configuration/test_state_change.vhd

@@ -34,10 +34,30 @@ begin
   test_runner_watchdog(runner, 10 * clk_period);
 end;
 
-configuration test_state_change of tb_selecting_test_runner_with_vhdl_configuration is
+configuration test_state_change_behavioral of tb_selecting_test_runner_with_vhdl_configuration is
   for tb
     for test_runner_inst : test_runner
       use entity work.test_runner(test_state_change_a);
     end for;
+
+    for test_fixture
+      for dut : dff
+        use entity work.dff(behavioral);
+      end for;
+    end for;
+  end for;
+end;
+
+configuration test_state_change_rtl of tb_selecting_test_runner_with_vhdl_configuration is
+  for tb
+    for test_runner_inst : test_runner
+      use entity work.test_runner(test_state_change_a);
+    end for;
+
+    for test_fixture
+      for dut : dff
+        use entity work.dff(rtl);
+      end for;
+    end for;
   end for;
 end;