From 3173d9e0bc3fc3a6b6abe1296190867c3154cf5a Mon Sep 17 00:00:00 2001
From: Patrick Lehmann <Patrick.Lehmann@plc2.de>
Date: Tue, 6 Dec 2022 00:44:33 +0100
Subject: Enhanced SimpleEntity with code comments.

---
 testsuite/pyunit/SimpleEntity.vhdl     | 63 +++++++++++++++++++++++-----------
 testsuite/pyunit/dom/SimpleEntity.py   |  4 +--
 testsuite/pyunit/libghdl/Initialize.py |  8 ++---
 3 files changed, 49 insertions(+), 26 deletions(-)

diff --git a/testsuite/pyunit/SimpleEntity.vhdl b/testsuite/pyunit/SimpleEntity.vhdl
index 931599086..bdeae47e1 100644
--- a/testsuite/pyunit/SimpleEntity.vhdl
+++ b/testsuite/pyunit/SimpleEntity.vhdl
@@ -1,32 +1,55 @@
-library ieee;
-use     ieee.std_logic_1164.all;
-use     ieee.numeric_std.all;
+-- Author: Patrick Lehmann
+--
+-- A generic counter module used in the StopWatch example.
+--
+library IEEE;
+use     IEEE.std_logic_1164.all;
+use     IEEE.numeric_std.all;
 
-entity entity_1 is
+use     work.Utilities.all;
+
+-- Generic modulo N counter
+--
+-- This component implements a generic modulo N counter with synchronous reset
+-- and enable. It generates a wrap-around strobe signal when it roles from
+-- MODULO-1 back to zero.
+--
+-- .. hint::
+--
+--    A modulo N counter counts binary from zero to N-1.
+--
+-- This component uses VHDL-2008 features like readback of ``out`` ports.
+entity Counter is
 	generic (
-		FREQ : real     := (100.0 * 1024.0 * 1024.0);
-		BITS : positive := 8
+		MODULO : positive;                             -- Modulo value.
+		BITS   : natural := log2(MODULO)               -- Number of expected output bits.
 	);
 	port (
-	  Clock: in  std_logic;
-	  Reset: in  std_logic := '0';
-	  Q:     out std_logic_vector(BITS - 1 downto 0)
+		Clock      : in  std_logic;                    -- Component clock
+		Reset      : in  std_logic;                    -- Component reset (synchronous)
+		Enable     : in  std_logic;                    -- Component enable (synchronous)
+
+		Value      : out unsigned(BITS - 1 downto 0);  -- Current counter value
+		WrapAround : out std_logic                     -- Strobe output on change from MODULO-1 to zero
 	);
-end entity entity_1;
+end entity;
 
-architecture behav of entity_1 is
-	signal Reset_n : std_logic;
-begin
-	Reset_n <= (not Reset);
 
-	process(Clock)
+-- Synthesizable and simulatable variant of a generic counter.
+architecture rtl of Counter is
+	signal CounterValue : unsigned(log2(MODULO) - 1 downto 0) := (others => '0');
+begin
+	process (Clock)
 	begin
 		if rising_edge(Clock) then
-			if Reset_n = '0' then
-				Q <= (others => '0');
-			else
-				Q <= std_logic_vector(unsigned(Q) + 1);
+			if ((Reset or WrapAround) = '1') then
+				CounterValue <= (others => '0');
+			elsif (Enable = '1') then
+				CounterValue <= CounterValue + 1;
 			end if;
 		end if;
 	end process;
-end architecture behav;
+
+	Value      <= resize(CounterValue, BITS);
+	WrapAround <= Enable when (CounterValue = MODULO - 1) else '0';
+end architecture;
diff --git a/testsuite/pyunit/dom/SimpleEntity.py b/testsuite/pyunit/dom/SimpleEntity.py
index 68f702410..7e19c2d17 100644
--- a/testsuite/pyunit/dom/SimpleEntity.py
+++ b/testsuite/pyunit/dom/SimpleEntity.py
@@ -67,7 +67,7 @@ class SimpleEntity(TestCase):
         design.Documents.append(document)
 
         self.assertEqual(1, len(design.Documents[0].Entities))
-        self.assertEqual("entity_1", design.Documents[0].Entities[0].Identifier)
+        self.assertEqual("Counter", design.Documents[0].Entities[0].Identifier)
 
     def test_Architecture(self):
         design = Design()
@@ -75,4 +75,4 @@ class SimpleEntity(TestCase):
         design.Documents.append(document)
 
         self.assertEqual(1, len(design.Documents[0].Architectures))
-        self.assertEqual("behav", design.Documents[0].Architectures[0].Identifier)
+        self.assertEqual("rtl", design.Documents[0].Architectures[0].Identifier)
diff --git a/testsuite/pyunit/libghdl/Initialize.py b/testsuite/pyunit/libghdl/Initialize.py
index 2fd09965b..7e3ace869 100644
--- a/testsuite/pyunit/libghdl/Initialize.py
+++ b/testsuite/pyunit/libghdl/Initialize.py
@@ -52,17 +52,17 @@ class Instantiate(TestCase):
             if nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Entity_Declaration:
                 entityName = self.getIdentifier(libraryUnit)
                 self.assertEqual(
+                    "counter",
                     entityName,
-                    "entity_1",
-                    "expected entity name 'e1', got '{}'".format(entityName),
+                    "expected entity name 'counter', got '{}'".format(entityName),
                 )
 
             elif nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Architecture_Body:
                 architectureName = self.getIdentifier(libraryUnit)
                 self.assertEqual(
+                    "rtl",
                     architectureName,
-                    "behav",
-                    "expected architecture name 'behav', got '{}'".format(
+                    "expected architecture name 'rtl', got '{}'".format(
                         architectureName
                     ),
                 )
-- 
cgit v1.2.3