Various updates to the rules.

Author: LarsAsplund

docs/verification_components/user_guide.rst

@@ -95,98 +95,110 @@ The handle is given as an argument to the procedure calls to direct messages to
 VC and VCI Compliance Testing
 =============================
 
-VUnit establishes a standard for VCs and VCIs, designed around a set of rules that promote flexibility, reusability, interoperability,
-and future-proofing of VCs and VCIs.
+VUnit establishes a standard for VCs and VCIs, designed around a set of rules that promote flexibility,
+reusability, interoperability, and future-proofing of VCs and VCIs.
 
 Rule 1
 ------
 
-The file containing a VC entity shall include only one entity, and the file containing a VCI package shall include only one package.
+The file containing the VC entity shall contain only that entity, and the file containing the VCI package shall
+contain only that package.
 
-**Rationale**: This simplifies compliance testing, as the VC/VCI can be referenced by file name.
+**Rationale**: This structure simplifies compliance testing, as each VC or VCI can be directly referenced by its
+file name.
 
 Rule 2
 ------
 
-The function used to create a new instance of a VC (the constructor) shall have a name starting with ``new_``.
+A VC shall have only **one** generic, the *handle*, and it shall be of a record type containing **private** fields.
 
-**Rationale**: This naming convention allows the compliance test to easily identify the constructor and evaluate it against other applicable rules.
+**Rationale**: Using a record allows future updates to add and/or remove fields in the record without breaking
+backward compatibility.
+
+**Recommendation**: Mark the fields as private by using a naming convention and/or including comments. This minimizes
+the risk of users accessing fields directly.
 
 Rule 3
 ------
 
-A VC constructor shall include an ``id`` parameter, allowing the user to specify the VC's identity.
+The VC handle shall be created by a function, the *constructor*, which shall have a name beginning with ``new``.
 
-**Rationale**: This provides users control over the namespace assigned to the VC.
+**Rationale**: Using a constructor removes the need for users to directly access the private fields of the handle
+record. The naming convention also enables compliance tests to easily locate the constructor and verify it against
+other applicable rules.
 
 Rule 4
 ------
 
-The ``id`` parameter shall default to ``null_id``. If not overridden, the ``id`` shall follow the format ``<provider>:<VC name>:<n>``, where
-``<n>`` starts at 1 for the first instance of the VC and increments with each subsequent instance.
+The VC constructor shall include an ``id`` parameter of type ``id_t`` to enable the user to specify the VC's identity.
 
-**Rationale**: This structured format ensures clear identification while preventing name collisions when combining VCs from different providers.
+**Rationale**: This gives users control over the namespace assigned to the VC.
 
 Rule 5
 ------
 
-All identity-supporting objects associated with the VC (such as loggers, actors, and events) shall be assigned an identity within the namespace
-defined by the constructor’s ``id`` parameter.
+The ``id`` parameter shall default to ``null_id``. If not overridden, ``id`` shall be assigned a value on the format
+``<provider>:<VC name>:<n>``, where ``<n>`` starts at 1 for the first instance of the VC and increments with each
+additional instance.
 
-**Rationale**: This gives users control over these objects and allows for easy association of log messages with a specific VC instance.
+**Rationale**: This format ensures clear identification while preventing naming collisions when VCs from different
+providers are combined.
 
 Rule 6
 ------
 
-All checkers used by the VC shall report to the VC’s loggers.
+All identity-supporting objects associated with the VC (such as loggers, actors, and events) shall be assigned an
+identity within the namespace defined by the constructor’s ``id`` parameter.
 
-**Rationale**: This ensures that error messages are clearly linked to a specific VC instance.
+**Rationale**: This gives users control over these objects and simplifies the association of log messages with a
+specific VC instance.
 
 Rule 7
 ------
 
-A VC constructor shall include an ``unexpected_msg_type_policy`` parameter, allowing users to define the action taken when the VC receives an unexpected message type.
-
-**Rationale**: A VC actor subscribing to another actor may receive irrelevant messages, while VCs addressed directly should only receive messages they can process.
-
-Rule 10
--------
+All logging performed by the VC, including indirect logging (such that error logs from checkers), shall use the
+VUnit logging mechanism.
 
-A VC shall keep the ``test_runner_cleanup`` entry gate locked while it has unfinished work, and must unlock the gate at all other times.
+**Rationale**: Using a unified logging mechanism ensures consistency and compatibility across logging outputs
+from different VCs.
 
-**Rationale**: This prevents premature termination of the testbench.
-
-Rule 11
--------
+Rule 8
+------
 
-All fields in the handle returned by the constructor shall begin with the prefix ``p_``.
+Communication with the VC shall be based on VUnit message passing, and the VC actor’s identity shall match the
+``id`` parameter provided to the constructor.
 
-**Rationale**: This emphasizes that all fields are private, which simplifies future updates without breaking backward compatibility.
+**Rationale**: This ensures a consistent communication framework and enables the reuse of VCIs across multiple VCs.
 
-Rule 12
--------
+Rule 9
+------
 
-The standard configuration, ``std_cfg_t``, consisting of the required parameters for the constructor, shall be accessible through the handle via a ``get_std_cfg`` call.
+All VCs shall support the sync interface.
 
-**Rationale**: This enables reuse of common operations across multiple VCs.
+**Rationale**: The ability to verify if a VC is idle and to introduce delays between transactions are frequently
+needed features for VC users.
 
-Rule 13
+Rule 10
 -------
 
-A VC shall only have one generic.
+The VC constructor shall include an ``unexpected_msg_type_policy`` parameter, allowing users to specify the action
+taken when the VC receives an unexpected message type.
 
-**Rationale**: Representing a VC with a single object simplifies code management. Since all handle fields are private, future updates are less likely to break backward compatibility.
+**Rationale**: This policy enables flexibility in handling situations where a VC actor, subscribed to another actor,
+might receive unsupported messages, while VCs addressed directly should only receive supported messages.
 
-Rule 14
+Rule 11
 -------
 
-All VCs shall support the sync interface.
+The standard configuration (of type ``std_cfg_t``), which includes the required parameters for the constructor, shall
+be accessible by calling ``get_std_cfg`` with the VC handle.
 
-**Rationale**: Being able to verify whether a VC is idle and introduce delays between transactions is a common and useful feature for VC users.
+**Rationale**: This enables reuse of common functions across multiple VCs.
 
-Rule 15
+Rule 12
 -------
 
-A VC shall keep the ``test_runner_cleanup`` phase entry gate locked while there are pending operations.
+A VC shall keep the ``test_runner_cleanup`` phase entry gate locked as long as there are pending operations.
 
-**Rationale**: Locking the gate prevents the simulation from terminating prematurely.
+**Rationale**: Locking the gate ensures that the simulation does not terminate prematurely before all operations have
+completed.