Documentation!

- A lot of documentation updates!
- Add an actual example
- Made specifying top_def_name optional when calling compile()
- Fix probable issues with multi-file compile.
- Split Node.get_path() to implement path segments as a separate step.
- Add equality method to Node

README.md

@@ -2,7 +2,16 @@
 
 # SystemRDL Compiler
 
-Parse and elaborate back-end for [SystemRDL 2.0](http://accellera.org/downloads/standards/systemrdl)
+The `systemrdl-compiler` module implements a generic compiler front-end for
+Accellera's [SystemRDL 2.0](http://accellera.org/downloads/standards/systemrdl)
+register description language. The goal of this project is to provide a free and
+open compiler that lowers the barrier to entry to using an industry standard
+register description language.
+
+By providing an elaborated register model that is easy to traverse and query,
+it should be far easier to write custom register space view generators.
+
+![overview](doc/img/overview.svg)
 
 ## Documentation
 See the [SystemRDL Compiler Documentation](http://systemrdl-compiler.readthedocs.io/en/latest) for more details

docs/api/component.rst

@@ -0,0 +1,55 @@
+
+Component
+=========
+
+Base classes
+------------
+
+Component
+^^^^^^^^^
+.. autoclass:: systemrdl.component.Component
+    :members:
+
+AddressableComponent
+^^^^^^^^^^^^^^^^^^^^
+.. autoclass:: systemrdl.component.AddressableComponent
+    :members:
+
+VectorComponent
+^^^^^^^^^^^^^^^
+.. autoclass:: systemrdl.component.VectorComponent
+    :members:
+
+
+Component Types
+---------------
+
+Signal
+^^^^^^
+.. autoclass:: systemrdl.component.Signal
+    :members:
+
+Field
+^^^^^
+.. autoclass:: systemrdl.component.Field
+    :members:
+
+Reg
+^^^
+.. autoclass:: systemrdl.component.Reg
+    :members:
+
+Regfile
+^^^^^^^
+.. autoclass:: systemrdl.component.Regfile
+    :members:
+
+Addrmap
+^^^^^^^
+.. autoclass:: systemrdl.component.Addrmap
+    :members:
+
+Mem
+^^^
+.. autoclass:: systemrdl.component.Mem
+    :members:

docs/api/messages.rst

@@ -0,0 +1,16 @@
+
+Messages
+========
+
+Exceptions
+----------
+.. autoclass:: systemrdl.messages.RDLCompileError
+    :members:
+
+Message Handling
+----------------
+.. autoclass:: systemrdl.messages.MessagePrinter
+    :members:
+
+.. autoclass:: systemrdl.messages.MessageContext
+    :members:

docs/api/node.rst

@@ -1,3 +1,4 @@
+.. _api_node:
 
 Node
 ====

docs/api/types.rst

@@ -0,0 +1,91 @@
+
+Types
+=====
+
+Once compiled, SystemRDL types are mapped to Python types as follows:
+
+.. list-table:: 
+    :header-rows: 1
+
+    *   - SystemRDL Type
+        - Python Type
+
+    *   - ``longint unsigned``
+        - ``int``
+
+    *   - ``bit``
+        - ``int``
+
+    *   - ``boolean``
+        - ``bool``
+
+    *   - ``string``
+        - ``str``
+
+    *   - ``accesstype``
+        - :class:`~systemrdl.rdltypes.AccessType`
+
+    *   - ``onreadtype``
+        - :class:`~systemrdl.rdltypes.OnReadType`
+
+    *   - ``onwritetype``
+        - :class:`~systemrdl.rdltypes.OnWriteType`
+
+    *   - ``addressingtype``
+        - :class:`~systemrdl.rdltypes.AddressingType`
+
+    *   - ``precedencetype``
+        - :class:`~systemrdl.rdltypes.PrecedenceType`
+
+    *   - ``intr`` property modifier
+        - :class:`~systemrdl.rdltypes.InterruptType`
+
+    *   - User-defined ``enum``
+        - :class:`~systemrdl.rdltypes.UserEnum`
+
+    *   - User-defined ``struct``
+        - :class:`~systemrdl.rdltypes.UserStruct`
+
+    *   - arrays
+        - ``list``
+
+    *   - Component ``ref``
+        - :class:`~systemrdl.node.Node` if queried using :meth:`Node.get_property() <systemrdl.node.Node.get_property>`
+
+Reserved Enumeration Types
+--------------------------
+
+.. autoclass:: systemrdl.rdltypes.AccessType
+    :members:
+
+.. autoclass:: systemrdl.rdltypes.OnReadType
+    :members:
+
+.. autoclass:: systemrdl.rdltypes.OnWriteType
+    :members:
+
+.. autoclass:: systemrdl.rdltypes.AddressingType
+    :members:
+
+.. autoclass:: systemrdl.rdltypes.PrecedenceType
+    :members:
+
+.. autoclass:: systemrdl.rdltypes.InterruptType
+    :members:
+
+Enumerations
+------------
+.. autoclass:: systemrdl.rdltypes.UserEnum
+    :members:
+
+    .. autoattribute:: rdl_desc
+    .. autoattribute:: rdl_name
+
+.. autofunction:: systemrdl.rdltypes.is_user_enum
+
+Structures
+----------
+.. autoclass:: systemrdl.rdltypes.UserStruct
+    :members:
+
+.. autofunction:: systemrdl.rdltypes.is_user_struct

docs/api/walker.rst

@@ -0,0 +1,14 @@
+
+Walker/Listener
+===============
+
+Walker
+------
+.. autoclass:: systemrdl.walker.RDLWalker
+    :members:
+
+Listener
+--------
+.. autoclass:: systemrdl.walker.RDLListener
+    :members:
+    :undoc-members:

docs/conf.py

@@ -34,8 +34,27 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
+    'sphinx.ext.inheritance_diagram',
 ]
 
+
+inheritance_graph_attrs = dict(
+    #rankdir = "TB",
+    #size = '"6.0, 8.0"',
+    #fontsize = 14,
+    #ratio = 'compress'
+)
+
+inheritance_node_attrs = dict(
+    #shape='ellipse',
+    #fontsize=14,
+    #height=0.75,
+    color='"#6AB0DE"',
+    fillcolor='"#E7F2FA"',
+    style='"rounded, filled"'
+)
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = [] #['_templates']
 
@@ -163,4 +182,3 @@
 ]
 
 
-

docs/examples.rst

@@ -0,0 +1,70 @@
+
+Examples
+==================================
+
+Print Compiled Hierarchy
+------------------------
+
+This example walks through a simple program that:
+
+* Compiles one or more RDL files provided from the command line
+* Elaborates the design register model
+* Uses the walker/listener traversal method to print a hierarchical text
+  representation of the register model
+
+The full example code can be found in the ``systemrdl-conpiler`` repository at:
+``examples/print_hierarchy.py``
+
+
+
+Walkthrough
+^^^^^^^^^^^
+
+First, a few classes are imported, and a list of requested input files collected
+from the command line arguments.
+
+.. literalinclude:: ../examples/print_hierarchy.py
+    :lines: 11-15
+
+Next, an instance of the compiler object is created. This represents a single
+compilation scope.
+
+.. literalinclude:: ../examples/print_hierarchy.py
+    :lines: 18-19
+
+All the input files are compiled into the root scope, and then elaborated.
+Since no top-level component name was specified in the ``elaborate`` call, the
+last ``addrmap`` component definition is automatically chosen.
+
+If the RDL file contains any syntax or semantic errors, the compile and elaborate
+steps will raise an :class:`~systemrdl.messages.RDLCompileError` exception. It is recommended to wrap
+this in a try/except block.
+
+.. literalinclude:: ../examples/print_hierarchy.py
+    :lines: 22-31
+
+For this example, we want to print out some information about the register model.
+This listener class defines callbacks that will output an indented tree view of the
+register model. For ``field`` components, some additional information is printed
+about the bit range, and software access policy.
+
+.. literalinclude:: ../examples/print_hierarchy.py
+    :lines: 34-52
+
+Finally, the a walker is created, and is used to traverse the elaborated register
+model. At each node, the listener callbacks are executed.
+
+.. literalinclude:: ../examples/print_hierarchy.py
+    :lines: 55-58
+
+
+
+Output
+^^^^^^
+
+Below is the example's output if it is run with the SPI controller RDL file:
+
+.. literalinclude:: print_hierarchy_spi.stdout
+    :language: none
+    :prepend: $ cd examples/
+              $ print_hierarchy.py atxmega_spi.rdl