Add better UDP docs. Refine implementation slightly

Author: amykyta3

docs/api/udp.rst

@@ -0,0 +1,104 @@
+.. _api_udp:
+
+User-Defined Properties
+=======================
+
+The SystemRDL standard allows users to extend components with custom properties.
+These UDPs are declared within the user's SystemRDL source code prior to use.
+Inevitably, these UDPs are processed by a downstream tool that has some
+well-defined semantics for these language extensions.
+This compiler provides an API that allows tool develoers to define additional
+validation for these properties.
+
+
+Pre-registering a UDP
+---------------------
+UDP semantics can be pre-loaded into the compiler namespace as a way to formalize
+extensions to SystemRDL that your tool supports.
+
+Registration of a UDP is done as follows:
+
+.. code-block:: python
+
+    from systemrdl.udp import UDPDefinition
+    from systemrdl.components import Field, Signal
+
+    # 1. Describe your UDP
+    class MyUDPDefinition(UDPDefinition):
+        name = "my_udp"
+        valid_components = {Field, Signal}
+        valid_type = int
+
+        # Optional callback that validates values assigned to 'my_udp'
+        def validate(self, node, value):
+            if(value == 42):
+                self.msg.error(
+                    "The value assigned to 'my_udp' cannot be 42! That number is reserved.",
+                    self.get_src_ref(node)
+                )
+
+    # 2. Register it with your RDLCompiler instance
+    rdlc.register_udp(MyUDPDefinition)
+
+The above definition is equivalent to the following SystemRDL:
+
+.. code-block:: systemrdl
+
+    property my_udp {
+        type = longint unsigned;
+        component = field | signal;
+    };
+
+
+Soft UDPs
+---------
+By default, :meth:`~systemrdl.RDLCompiler.register_udp()` registers
+UDPs as "soft" definitions. Soft UDP definitions behave as follows:
+
+* The UDP is not available to be used until it is explicitly defined in the
+  SystemRDL source. If a user attempts to use a soft UDP prior to it being
+  declared, the compiler will flag an error.
+* Upon definition, the user's declaration shall be equivalent to the
+  pre-registered definition. If the user's declaration does not match, the
+  compiler will flag an error.
+  This ensures that the user's declaration matches the expectations of your tool.
+* If the user's RDL source never defines the UDP, querying it via
+  ``node.get_property()`` will gracefully return ``None`` instead of a
+  ``LookupError`` exception. This simplifies how tool developers interact with
+  users' RDL code.
+* Once defined by the user in RDL source, the UDP is no longer considered
+  'soft', and can be assigned normally.
+
+
+.. important::
+    Although it may initially seem like more steps for the end-user, having them
+    declare the UDP in the RDL source is preferred over pre-declaring "hard"
+    UDPs within your tool.
+
+    Silently declaring hard UDPs not recommended since it encourages users to write
+    SystemRDL that uses UDP extensions that are not formally declared in the
+    RDL source. This bends the rules of the SystemRDL specification and hurts
+    the cross-vendor compatibility of your users' SystemRDL source code.
+
+    Using soft UDPs has the benefit of enforcing that the user
+    defines and uses UDPs correctly whilst not violating the official
+    SystemRDL language specification.
+
+
+The UDPDefinition descriptor
+----------------------------
+
+The full details of the ``UDPDefinition`` class is as follows:
+
+Class variables and methods that you can define
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: systemrdl.udp.UDPDefinition
+    :members: name, valid_components, valid_type, default_assignment, constr_componentwidth, validate, get_unassigned_default
+    :member-order: bysource
+
+Utilities
+^^^^^^^^^
+
+.. autoclass:: systemrdl.udp.UDPDefinition
+    :noindex:
+    :members: msg, get_src_ref

docs/index.rst

@@ -69,9 +69,10 @@ Links
 
 .. toctree::
    :hidden:
-   :caption: Class Reference
+   :caption: API Reference
 
    api/compiler
+   api/udp
    api/node
    api/walker
    api/component

systemrdl/__about__.py

@@ -1 +1 @@
-__version__ = "1.25.0-b2"
+__version__ = "1.25.0"

systemrdl/compiler.py

@@ -141,70 +141,13 @@ def register_udp(self, definition_cls: 'Type[UDPDefinition]', soft: bool=True) -
         """
         Pre-register a User Defined Property into the compiler.
 
-        UDP semantics can be pre-loaded into the compiler namespace as a way to formalize
-        extensions to SystemRDL that your tool supports. Registration of a UDP is done as follows:
-
-        .. code-block:: python
-
-            from systemrdl.udp import UDPDefinition
-            from systemrdl.components import Field, Signal
-
-            # 1. Describe your UDP
-            class MyUDPDefinition(UDPDefinition):
-                name = "my_udp"
-                valid_components = {Field, Signal}
-                valid_type = int
-
-                # Optional callback that validates values assigned to 'my_udp'
-                def validate(self, node, value):
-                    if(value == 42):
-                        self.msg.error(
-                            "Value of 'my_udp' cannot be 42! That number is reserved for philosophical reasons",
-                            self.get_src_ref(node)
-                        )
-
-            # 2. Register it with your RDLCompiler instance
-            rdlc.register_udp(MyUDPDefinition)
-
-        The above definition is equivalent to the following SystemRDL:
-
-        .. code-block:: systemrdl
-
-            property my_udp {
-                type = longint unsigned;
-                component = field | signal;
-            };
-
-        By default, UDPs are registered as "soft" definitions. Soft UDPs behave as follows:
-
-            * The UDP is not available to be used until it is explicitly defined in the SystemRDL source.
-            * Upon definition, the user's declaration shall be equivalent to the pre-loaded definition.
-            * If the user's RDL source never defines the UDP, querying it via ``node.get_property()``
-              will gracefully return ``None`` instead of a ``LookupError`` exception.
-            * Once defined by the user in RDL source, the UDP is no longer soft.
-
-        The full details of the ``UDPDefinition`` class is as follows:
-
-        .. autoclass:: systemrdl.udp.UDPDefinition
-            :members:
-
         Parameters
         ----------
         definition_cls: :class:`systemrdl.udp.UDPDefinition`
             Reference to the container class that defines your new UDP.
         soft: bool
             Override to False to register the UDP as a hard definition.
 
-            .. important::
-                Registering hard UDPs not recommended since it encourages users to write
-                SystemRDL that uses UDP extensions that are not formally
-                declared in the RDL source. This bends the rules of the SystemRDL
-                specification and hurts the cross-vendor compatibility of your SystemRDL.
-
-                Using soft UDPs has the benefit of enforcing that the user
-                defines and uses UDPs correctly whilst not violating the official
-                SystemRDL language specification.
-
 
         .. versionadded:: 1.25
         """

systemrdl/udp.py

@@ -7,14 +7,15 @@
     from .compiler import RDLEnvironment
     from .node import Node
     from .messages import MessageHandler
+    from .source_ref import SourceRefBase
 
 class UDPDefinition:
     """
     UDP definition descriptor class.
     """
 
-    #: UDP definition name
-    name = ""
+    #: User-defined property name
+    name = "" # type: str
 
     #: Set of :class:`~systemrdl.component.Component` types the UDP can be bound to.
     #: By default, the UDP can be bound to all components.
@@ -59,15 +60,34 @@ def __init__(self, env: 'RDLEnvironment') -> None:
 
     @property
     def msg(self) -> 'MessageHandler':
+        """
+        Reference to the compiler's message handler.
+        Use this to emit error messages from within :meth:`validate()`.
+        """
         return self.env.msg
 
+    def get_src_ref(self, node: 'Node') -> 'SourceRefBase':
+        """
+        Get the src_ref object for this property assignment.
+
+        This function is useful when emitting error messages from within :meth:`validate()`.
+        """
+        return node.inst.property_src_ref.get(self.name, node.inst.inst_src_ref)
+
     def validate(self, node: 'Node', value: Any) -> None:
         """
         Optional user-defined validation function.
 
         This function is called after design elaboration on every assignment
         of the user defined property. This provides a mechanism to further
         validate the value assigend to your user-defined property.
+
+        If the user-assigned value fails your validation test, be sure to flag
+        it as an error as follows:
+
+        .. code-block:: python
+
+            self.msg.error("My error message", self.get_src_ref(node))
         """
 
     def get_unassigned_default(self, node: 'Node') -> Any:
@@ -78,8 +98,8 @@ def get_unassigned_default(self, node: 'Node') -> Any:
 
         For convenience to developers, this callback allows you to specify an implied
         default value if the UDP was never explicitly assigned.
-        This only affects the behavior of Node.get_property() and does not
-        affect the semantics of SystemRDL during compilaton.
+        This only affects the behavior of :meth:`Node.get_property()` and does not
+        change the semantics of how SystemRDL is interpreted during compilaton.
         """
 
         # If a user-defined property is not explicitly assigned, then it