peakrdl-busdecoder 0.6.7__tar.gz → 0.6.8__tar.gz

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peakrdl-busdecoder
-Version: 0.6.7
+Version: 0.6.8
 Summary: Generate a SystemVerilog bus decoder from SystemRDL for splitting CPU interfaces to multiple sub-address spaces
 Author: Arnav Sacheti
 License: LGPLv3

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/api.rst

@@ -15,10 +15,11 @@ implementation from SystemRDL source.
 .. code-block:: python
     :emphasize-lines: 2-4, 29-33
 
+    import sys
+
     from systemrdl import RDLCompiler, RDLCompileError
     from peakrdl_busdecoder import BusDecoderExporter
-    from peakrdl_busdecoder.cpuif.axi4lite import AXI4Lite_Cpuif
-    from peakrdl_busdecoder.udps import ALL_UDPS
+    from peakrdl_busdecoder.cpuif.axi4lite import AXI4LiteCpuif
 
     input_files = [
         "PATH/TO/my_register_block.rdl"
@@ -27,10 +28,6 @@ implementation from SystemRDL source.
     # Create an instance of the compiler
     rdlc = RDLCompiler()
 
-    # Register all UDPs that 'busdecoder' requires
-    for udp in ALL_UDPS:
-        rdlc.register_udp(udp)
-
     try:
         # Compile your RDL files
         for input_file in input_files:
@@ -46,5 +43,5 @@ implementation from SystemRDL source.
     exporter = BusDecoderExporter()
     exporter.export(
         root, "path/to/output_dir",
-        cpuif_cls=AXI4Lite_Cpuif
+        cpuif_cls=AXI4LiteCpuif
     )

peakrdl_busdecoder-0.6.8/docs/architecture.rst

@@ -0,0 +1,54 @@
+Bus Decoder Architecture
+========================
+
+The generated RTL is a pure bus-routing layer. It accepts a single CPU interface
+on the slave side and fans transactions out to a set of child interfaces on the
+master side. No register storage or field logic is generated.
+
+Although you do not need to know the inner workings to use the exporter, the
+sections below explain the structure of the generated module and how it maps to
+SystemRDL hierarchy.
+
+
+CPU Interface Adapter
+---------------------
+Each supported CPU interface protocol (APB3, APB4, AXI4-Lite) provides a small
+adapter that translates the external bus protocol into internal request/response
+signals. These internal signals are then used by the address decoder and fanout
+logic.
+
+If you write a custom CPU interface, it must implement the internal signals
+described in :ref:`cpuif_protocol`.
+
+
+Address Decode
+--------------
+The address decoder computes per-child select signals based on address ranges.
+The decode boundary is controlled by ``max_decode_depth``:
+
+* ``0``: Decode all the way down to leaf registers
+* ``1`` (default): Decode only top-level children
+* ``N``: Decode down to depth ``N`` from the top-level
+
+This allows you to choose whether the bus decoder routes to large blocks (e.g.,
+child addrmaps) or to smaller sub-blocks.
+
+
+Fanout to Child Interfaces
+--------------------------
+For each decoded child, the bus decoder drives a master-side CPU interface.
+All address, data, and control signals are forwarded to the selected child.
+
+Arrayed children can be kept as arrays or unrolled into discrete interfaces using
+``--unroll``. This only affects port structure and naming; decode semantics are
+unchanged.
+
+
+Fanin and Error Handling
+------------------------
+Read and write responses are muxed back from the selected child to the slave
+interface. If no child is selected for a transaction, the decoder generates an
+error response on the slave interface.
+
+The exact error signaling depends on the chosen CPU interface protocol (e.g.,
+``PSLVERR`` for APB, ``RRESP/BRESP`` for AXI4-Lite).

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/conf.py

@@ -32,9 +32,7 @@ author = "Arnav Sacheti"
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
-    "sphinxcontrib.wavedrom",
 ]
-render_using_wavedrompy = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -42,7 +40,7 @@ templates_path = ["_templates"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "dev_notes", "dev_notes/**"]
 
 
 # -- Options for HTML output -------------------------------------------------

peakrdl_busdecoder-0.6.8/docs/configuring.rst

@@ -0,0 +1,38 @@
+.. _peakrdl_cfg:
+
+Configuring PeakRDL-BusDecoder
+==============================
+
+If using the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_,
+some aspects of the ``busdecoder`` command can be configured via the PeakRDL
+TOML file.
+
+All busdecoder-specific options are defined under the ``[busdecoder]`` heading.
+
+.. data:: cpuifs
+
+    Mapping of additional CPU Interface implementation classes to load.
+    The mapping's key indicates the cpuif's name.
+    The value is a string that describes the import path and cpuif class to
+    load.
+
+    For example:
+
+    .. code-block:: toml
+
+        [busdecoder]
+        cpuifs.my-cpuif-name = "my_cpuif_module:MyCPUInterfaceClass"
+
+
+Command-Line Options
+--------------------
+
+The following options are available on the ``peakrdl busdecoder`` command:
+
+* ``--cpuif``: Select the CPU interface (``apb3``, ``apb3-flat``, ``apb4``,
+  ``apb4-flat``, ``axi4-lite``, ``axi4-lite-flat``)
+* ``--module-name``: Override the generated module name
+* ``--package-name``: Override the generated package name
+* ``--addr-width``: Override the slave address width
+* ``--unroll``: Unroll arrayed children into discrete interfaces
+* ``--max-decode-depth``: Control how far the decoder descends into hierarchy

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/cpuif/apb.rst

@@ -20,7 +20,7 @@ Both APB3 and APB4 standards are supported.
 APB3
 ----
 
-Implements the register block using an
+Implements the bus decoder using an
 `AMBA 3 APB <https://developer.arm.com/documentation/ihi0024/b/Introduction/About-the-AMBA-3-APB>`_
 CPU interface.
 
@@ -29,19 +29,19 @@ The APB3 CPU interface comes in two i/o port flavors:
 SystemVerilog Interface
     * Command line: ``--cpuif apb3``
     * Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
-    * Class: :class:`peakrdl_busdecoder.cpuif.apb3.APB3_Cpuif`
+    * Class: :class:`peakrdl_busdecoder.cpuif.apb3.APB3Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
     * Command line: ``--cpuif apb3-flat``
-    * Class: :class:`peakrdl_busdecoder.cpuif.apb3.APB3_Cpuif_flattened`
+    * Class: :class:`peakrdl_busdecoder.cpuif.apb3.APB3CpuifFlat`
 
 
 APB4
 ----
 
-Implements the register block using an
+Implements the bus decoder using an
 `AMBA 4 APB <https://developer.arm.com/documentation/ihi0024/d/?lang=en>`_
 CPU interface.
 
@@ -50,10 +50,10 @@ The APB4 CPU interface comes in two i/o port flavors:
 SystemVerilog Interface
     * Command line: ``--cpuif apb4``
     * Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
-    * Class: :class:`peakrdl_busdecoder.cpuif.apb4.APB4_Cpuif`
+    * Class: :class:`peakrdl_busdecoder.cpuif.apb4.APB4Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
     * Command line: ``--cpuif apb4-flat``
-    * Class: :class:`peakrdl_busdecoder.cpuif.apb4.APB4_Cpuif_flattened`
+    * Class: :class:`peakrdl_busdecoder.cpuif.apb4.APB4CpuifFlat`

peakrdl_busdecoder-0.6.8/docs/cpuif/axi4lite.rst

@@ -0,0 +1,33 @@
+.. _cpuif_axi4lite:
+
+AMBA AXI4-Lite
+==============
+
+Implements the bus decoder using an
+`AMBA AXI4-Lite <https://developer.arm.com/documentation/ihi0022/e/AMBA-AXI4-Lite-Interface-Specification>`_
+CPU interface.
+
+The AXI4-Lite CPU interface comes in two i/o port flavors:
+
+SystemVerilog Interface
+    * Command line: ``--cpuif axi4-lite``
+    * Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
+    * Class: :class:`peakrdl_busdecoder.cpuif.axi4lite.AXI4LiteCpuif`
+
+Flattened inputs/outputs
+    Flattens the interface into discrete input and output ports.
+
+    * Command line: ``--cpuif axi4-lite-flat``
+    * Class: :class:`peakrdl_busdecoder.cpuif.axi4lite.AXI4LiteCpuifFlat`
+
+
+Protocol Notes
+--------------
+The AXI4-Lite adapter is intentionally simplified:
+
+* AW and W channels must be asserted together for writes. The adapter does not
+  support decoupled address/data for writes.
+* Only a single outstanding transaction is supported. Masters should wait for
+  the corresponding response before issuing the next request.
+* Burst transfers are not supported (single-beat transfers only), consistent
+  with AXI4-Lite.

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/cpuif/customizing.rst

@@ -29,15 +29,15 @@ Rather than rewriting a new CPU interface definition, you can extend and adjust
 
 .. code-block:: python
 
-    from peakrdl_busdecoder.cpuif.axi4lite import AXI4Lite_Cpuif
+    from peakrdl_busdecoder.cpuif.axi4lite import AXI4LiteCpuif
 
-    class My_AXI4Lite(AXI4Lite_Cpuif):
+    class My_AXI4Lite(AXI4LiteCpuif):
         @property
         def port_declaration(self) -> str:
             # Override the port declaration text to use the alternate interface name and modport style
             return "axi4_lite_interface.Slave_mp s_axil"
 
-        def signal(self, name:str) -> str:
+        def signal(self, name: str, node=None, indexer=None) -> str:
             # Override the signal names to be lowercase instead
             return "s_axil." + name.lower()
 
@@ -72,7 +72,7 @@ you can define your own.
 
 2. Create a Python class that defines your CPUIF
 
-    Extend your class from :class:`peakrdl_busdecoder.cpuif.CpuifBase`.
+    Extend your class from :class:`peakrdl_busdecoder.cpuif.BaseCpuif`.
     Define the port declaration string, and provide a reference to your template file.
 
 3. Use your new CPUIF definition when exporting.

peakrdl_busdecoder-0.6.8/docs/cpuif/internal_protocol.rst

@@ -0,0 +1,71 @@
+.. _cpuif_protocol:
+
+Internal CPUIF Protocol
+=======================
+
+Internally, the bus decoder uses a small set of common request/response signals
+that each CPU interface adapter must drive. This protocol is intentionally simple
+and supports a single outstanding transaction at a time. The CPU interface logic
+is responsible for holding request signals stable until the transaction completes.
+
+
+Signal Descriptions
+-------------------
+
+Request
+^^^^^^^
+cpuif_req
+    When asserted, a read or write transfer is in progress. Request signals must
+    remain stable until the transfer completes.
+
+cpuif_wr_en
+    When asserted alongside ``cpuif_req``, denotes a write transfer.
+
+cpuif_rd_en
+    When asserted alongside ``cpuif_req``, denotes a read transfer.
+
+cpuif_wr_addr / cpuif_rd_addr
+    Byte address of the write or read transfer, respectively.
+
+cpuif_wr_data
+    Data to be written for the write transfer.
+
+cpuif_wr_byte_en
+    Active-high byte-enable strobes for writes. Some CPU interfaces do not
+    provide byte enables and may drive this as all-ones.
+
+
+Read Response
+^^^^^^^^^^^^^
+cpuif_rd_ack
+    Single-cycle strobe indicating a read transfer has completed.
+    Qualifies ``cpuif_rd_err`` and ``cpuif_rd_data``.
+
+cpuif_rd_err
+    Indicates that the read transaction failed. The CPU interface should return
+    an error response if possible.
+
+cpuif_rd_data
+    Read data. Sampled on the same cycle that ``cpuif_rd_ack`` is asserted.
+
+
+Write Response
+^^^^^^^^^^^^^^
+cpuif_wr_ack
+    Single-cycle strobe indicating a write transfer has completed.
+    Qualifies ``cpuif_wr_err``.
+
+cpuif_wr_err
+    Indicates that the write transaction failed. The CPU interface should return
+    an error response if possible.
+
+
+Transfers
+---------
+
+Transfers have the following characteristics:
+
+* Only one outstanding transaction is supported.
+* The CPU interface must hold ``cpuif_req`` and request parameters stable until
+  the corresponding ``cpuif_*_ack`` is asserted.
+* Responses shall arrive in the same order as requests.

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/cpuif/introduction.rst

@@ -2,16 +2,17 @@ Introduction
 ============
 
 The CPU interface logic layer provides an abstraction between the
-application-specific bus protocol and the internal register file logic.
-When exporting a design, you can select from a variety of popular CPU interface
-protocols. These are described in more detail in the pages that follow.
+application-specific bus protocol and the internal bus decoder logic.
+When exporting a design, you can select from supported CPU interface protocols.
+These are described in more detail in the pages that follow.
 
 
 Bus Width
 ^^^^^^^^^
-The CPU interface bus width is automatically determined from the contents of the
-design being exported. The bus width is equal to the widest ``accesswidth``
-encountered in the design.
+The CPU interface bus width is inferred from the contents of the design.
+It is intended to be equal to the widest ``accesswidth`` encountered in the
+design. If the exported addrmap contains only external components, the width
+cannot be inferred and will default to 32 bits.
 
 
 Addressing
@@ -32,5 +33,6 @@ For example, consider a fictional AXI4-Lite device that:
 - If care is taken to align the global address offset to the size of the device,
   creating a relative address is as simple as pruning down address bits.
 
-By default, the bit-width of the address bus will be the minimum size to span the contents
-of the register block. If needed, the address width can be overridden to a larger range.
+By default, the bit-width of the address bus will be the minimum size to span the
+contents of the decoded address space. If needed, the address width can be
+overridden to a larger range using ``--addr-width``.

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/index.rst

@@ -1,28 +1,34 @@
 Introduction
 ============
 
-PeakRDL-BusDecoder is a free and open-source bus decoder generator for hierarchical register address maps.
-This code generator translates your SystemRDL register description into a synthesizable 
-SystemVerilog RTL module that decodes CPU interface transactions and routes them to 
-multiple sub-address spaces (child addrmaps). This is particularly useful for:
+PeakRDL-BusDecoder is a free and open-source bus decoder generator for hierarchical
+SystemRDL address maps. It produces a synthesizable SystemVerilog RTL module that
+accepts a single CPU interface (slave side) and fans transactions out to multiple
+child address spaces (master side).
+
+This tool **does not** generate register storage or field logic. It is strictly a
+bus-routing layer that decodes addresses and forwards requests to child blocks.
+
+This is particularly useful for:
 
 * Creating hierarchical register maps with multiple sub-components
 * Splitting a single CPU interface bus to serve multiple independent register blocks
-* Organizing large register designs into logical sub-address spaces
+* Organizing large address spaces into logical sub-regions
 * Implementing address decode logic for multi-drop bus architectures
 
 The generated bus decoder provides:
 
 * Fully synthesizable SystemVerilog RTL (IEEE 1800-2012)
-* Support for many popular CPU interface protocols (AMBA APB, AXI4-Lite, and more)
+* A top-level slave CPU interface and per-child master CPU interfaces
 * Address decode logic that routes transactions to child address maps
-* Configurable pipelining options for designs with fast clock rates
-* Broad support for SystemRDL 2.0 features
+* Support for APB3, APB4, and AXI4-Lite (plus plugin-defined CPU interfaces)
+* Configurable decode depth and array unrolling
 
 
 Quick Start
 -----------
-The easiest way to use PeakRDL-BusDecoder is via the  `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_:
+The easiest way to use PeakRDL-BusDecoder is via the
+`PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_:
 
 .. code-block:: bash
 
@@ -32,6 +38,20 @@ The easiest way to use PeakRDL-BusDecoder is via the  `PeakRDL command line tool
     # Export!
     peakrdl busdecoder atxmega_spi.rdl -o busdecoder/ --cpuif axi4-lite
 
+The exporter writes two files:
+
+* A SystemVerilog module (the bus decoder)
+* A SystemVerilog package (constants like data width and per-child address widths)
+
+Key command-line options:
+
+* ``--cpuif``: Select the CPU interface (``apb3``, ``apb3-flat``, ``apb4``, ``apb4-flat``, ``axi4-lite``, ``axi4-lite-flat``)
+* ``--module-name``: Override the generated module name
+* ``--package-name``: Override the generated package name
+* ``--addr-width``: Override the slave address width
+* ``--unroll``: Unroll arrayed children into discrete interfaces
+* ``--max-decode-depth``: Control how far the decoder descends into hierarchy
+
 
 Looking for VHDL?
 -----------------
@@ -55,10 +75,8 @@ Links
 
     self
     architecture
-    hwif
     configuring
     limitations
-    faq
     licensing
     api
 
@@ -69,29 +87,5 @@ Links
     cpuif/introduction
     cpuif/apb
     cpuif/axi4lite
-    cpuif/avalon
-    cpuif/passthrough
     cpuif/internal_protocol
     cpuif/customizing
-
-.. toctree::
-    :hidden:
-    :caption: SystemRDL Properties
-
-    props/field
-    props/reg
-    props/addrmap
-    props/signal
-    props/rhs_props
-
-.. toctree::
-    :hidden:
-    :caption: Other SystemRDL Features
-
-    rdl_features/external
-
-.. toctree::
-    :hidden:
-    :caption: Extended Properties
-
-    udps/intro

peakrdl_busdecoder-0.6.8/docs/limitations.rst

@@ -0,0 +1,47 @@
+Known Limitations
+=================
+
+The busdecoder exporter intentionally focuses on address decode and routing.
+Some SystemRDL features are ignored, and a few are explicitly disallowed.
+
+
+Address Alignment
+-----------------
+All address offsets and array strides must be aligned to the CPU interface data
+bus width (in bytes). Misaligned offsets/strides are rejected.
+
+
+Wide Registers
+--------------
+If a register is wider than its ``accesswidth`` (a multi-word register), its
+``accesswidth`` must match the CPU interface data width. Multi-word registers
+with a smaller accesswidth are not supported.
+
+
+Fields Spanning Sub-Words
+-------------------------
+If a field spans multiple sub-words of a wide register:
+
+* Software-writable fields must have write buffering enabled
+* Fields with ``onread`` side-effects must have read buffering enabled
+
+These rules are enforced to avoid ambiguous multi-word access behavior.
+
+
+External Boundary References
+----------------------------
+Property references are not allowed to cross the internal/external boundary of
+the exported addrmap. References must point to components that are internal to
+the busdecoder being generated.
+
+CPU Interface Reset Location
+----------------------------
+Only ``cpuif_reset`` signals instantiated at the top-level addrmap (or above)
+are honored. Nested ``cpuif_reset`` signals are ignored.
+
+
+Unsupported Properties
+----------------------
+The following SystemRDL properties are explicitly rejected:
+
+* ``sharedextbus`` on addrmap/regfile components

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/docs/requirements.txt

@@ -1,3 +1,2 @@
 pygments-systemrdl
-sphinxcontrib-wavedrom
 sphinx-book-theme

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "peakrdl-busdecoder"
-version = "0.6.7"
+version = "0.6.8"
 requires-python = ">=3.10"
 dependencies = [
     "jinja2~=3.1",
@@ -55,7 +55,6 @@ Documentation = "https://peakrdl-busdecoder.readthedocs.io/"
 docs = [
     "pygments-systemrdl>=1.3.0",
     "sphinx-book-theme>=1.1.4",
-    "sphinxcontrib-wavedrom>=3.0.4",
 ]
 test = [
     "parameterized>=0.9.0",

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/src/peakrdl_busdecoder/design_scanner.py

@@ -44,3 +44,14 @@ class DesignScanner(RDLListener):
             self.ds.has_external_addressable = True
             if not isinstance(node, RegNode):
                 self.ds.has_external_block = True
+
+    def enter_Reg(self, node: RegNode) -> None:
+        if node.external and node != self.top_node:
+            return
+
+        accesswidth = node.get_property("accesswidth")
+        if accesswidth is None:
+            return
+
+        if accesswidth > self.ds.cpuif_data_width:
+            self.ds.cpuif_data_width = accesswidth

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/src/peakrdl_busdecoder.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peakrdl-busdecoder
-Version: 0.6.7
+Version: 0.6.8
 Summary: Generate a SystemVerilog bus decoder from SystemRDL for splitting CPU interfaces to multiple sub-address spaces
 Author: Arnav Sacheti
 License: LGPLv3

{peakrdl_busdecoder-0.6.7 → peakrdl_busdecoder-0.6.8}/src/peakrdl_busdecoder.egg-info/SOURCES.txt

@@ -24,19 +24,15 @@ docs/api.rst
 docs/architecture.rst
 docs/conf.py
 docs/configuring.rst
-docs/faq.rst
-docs/hwif.rst
 docs/index.rst
 docs/licensing.rst
 docs/limitations.rst
 docs/requirements.txt
 docs/cpuif/apb.rst
-docs/cpuif/avalon.rst
 docs/cpuif/axi4lite.rst
 docs/cpuif/customizing.rst
 docs/cpuif/internal_protocol.rst
 docs/cpuif/introduction.rst
-docs/cpuif/passthrough.rst
 docs/dev_notes/Alpha-Beta Versioning
 docs/dev_notes/Hierarchy-and-Indexing
 docs/dev_notes/Program Flow
@@ -58,13 +54,6 @@ docs/diagrams/wbuf.png
 docs/img/err.svg
 docs/img/ok.svg
 docs/img/warn.svg
-docs/props/addrmap.rst
-docs/props/field.rst
-docs/props/reg.rst
-docs/props/rhs_props.rst
-docs/props/signal.rst
-docs/rdl_features/external.rst
-docs/udps/intro.rst
 hdl-src/README.md
 hdl-src/apb3_intf.sv
 hdl-src/apb4_intf.sv