[Rel] Release 0.3.5

* Added support for frame-based programming protocol
* Added support for memory initialization (ROMs!)
* Changed API so programming protocol may be selected after VPR/Yosys script
  generation, decoupling design space exploration with physical implementation
* Improved bitstream generation to a more generic FASM format and more flexible
  assembler
* Added "Magic" bitstream checker based on the Magic programming protocol to
  help debugging the bitstream loading process for other protocols
* Example scripts and documentation updated to match the modifications above

docs/source/prga.py/prga.app.app.rst

@@ -0,0 +1,7 @@
+prga.app.app module
+===================
+
+.. automodule:: prga.app.app
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.app.rst

@@ -0,0 +1,16 @@
+prga.app package
+================
+
+.. automodule:: prga.app
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   prga.app.app
+   prga.app.softregs

docs/source/prga.py/prga.app.softregs.rst

@@ -0,0 +1,7 @@
+prga.app.softregs module
+========================
+
+.. automodule:: prga.app.softregs
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.passes.materialization.rst

@@ -0,0 +1,7 @@
+prga.passes.materialization module
+==================================
+
+.. automodule:: prga.passes.materialization
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.passes.proginsertion.rst

@@ -0,0 +1,7 @@
+prga.passes.proginsertion module
+================================
+
+.. automodule:: prga.passes.proginsertion
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.passes.rst

@@ -23,6 +23,8 @@ Submodules
    prga.passes.annotation
    prga.passes.base
    prga.passes.flow
+   prga.passes.materialization
+   prga.passes.proginsertion
    prga.passes.rtl
    prga.passes.translation
    prga.passes.yosys

docs/source/prga.py/prga.prog.frame.lib.rst

@@ -0,0 +1,7 @@
+prga.prog.frame.lib module
+==========================
+
+.. automodule:: prga.prog.frame.lib
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.prog.frame.protocol.rst

@@ -0,0 +1,7 @@
+prga.prog.frame.protocol module
+===============================
+
+.. automodule:: prga.prog.frame.protocol
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.prog.frame.rst

@@ -0,0 +1,16 @@
+prga.prog.frame package
+=======================
+
+.. automodule:: prga.prog.frame
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   prga.prog.frame.lib
+   prga.prog.frame.protocol

docs/source/prga.py/prga.prog.rst

@@ -12,6 +12,7 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   prga.prog.frame
    prga.prog.magic
    prga.prog.pktchain
    prga.prog.scanchain

docs/source/prga.py/prga.rst

@@ -13,12 +13,14 @@ Subpackages
    :maxdepth: 4
 
    prga.algorithm
+   prga.app
    prga.core
    prga.integration
    prga.netlist
    prga.passes
    prga.prog
    prga.renderer
+   prga.system
    prga.tools
 
 Submodules

docs/source/prga.py/prga.system.rst

@@ -0,0 +1,7 @@
+prga.system package
+===================
+
+.. automodule:: prga.system
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.tools.bitgen.frame.rst

@@ -0,0 +1,7 @@
+prga.tools.bitgen.frame module
+==============================
+
+.. automodule:: prga.tools.bitgen.frame
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/prga.py/prga.tools.bitgen.rst

@@ -13,6 +13,8 @@ Submodules
    :maxdepth: 4
 
    prga.tools.bitgen.common
+   prga.tools.bitgen.frame
    prga.tools.bitgen.magic
    prga.tools.bitgen.pktchain
    prga.tools.bitgen.scanchain
+   prga.tools.bitgen.util

docs/source/prga.py/prga.tools.bitgen.util.rst

@@ -0,0 +1,7 @@
+prga.tools.bitgen.util module
+=============================
+
+.. automodule:: prga.tools.bitgen.util
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/tutorial/bring_your_own_ip.rst

@@ -31,6 +31,15 @@ implementation of `PicoSoC`_.
 .. _PicoRV32: https://github.com/cliffordwolf/picorv32
 .. _PicoSoC: https://github.com/cliffordwolf/picorv32/tree/master/picosoc
 
+.. image:: /_static/images/picosoc.PNG
+   :width: 600px
+   :alt: PicoSoC implemented on an FPGA with a hard PicoRV32 core
+   :align: center
+
+Figure created by `VPR`_.
+
+.. _VPR: https://verilogtorouting.org/
+
 Describe custom primitives
 --------------------------
 

docs/source/tutorial/build_your_custom_fpga.rst

@@ -1,3 +1,4 @@
+
 Build Your Custom FPGA
 ======================
 
@@ -16,22 +17,15 @@ layout and routing resources. It also stores and manages all created/generated
 modules and other information about the FPGA, which are later used by the
 RTL-to-bitstream flow.
 
-To create a `Context` object, call the ``new_context`` class method of a
-configuration circuitry class, for example, `Scanchain`. This is because
-different configuration circuitry needs to initialize the `Context` object
-differently. For example, the configuration cell in a SRAM-based configuration
-circuitry are SRAM cells, while the `Scanchain` configuration circuitry simply
-uses D-Flipflops.
-
 .. code-block:: python
 
     from prga import *
     from itertools import product
     
     import sys
 
-    # Use single-bit scanchain configuration circuitry
-    ctx = Scanchain.new_context()
+    # create a new context
+    ctx = Context()
 
 After creating the `Context` object, we can start to describe our custom FPGA.
 Here, we first describe the routing resources in the FPGA: the routing wire
@@ -66,8 +60,8 @@ a memory module:
 
 .. code-block:: python
     
-    # create a memory primitive:    name,         addr width,   data width
-    memory = ctx.create_memory(     "dpram_a8d8", 8,            8).commit()
+    # create a memory primitive: addr width,   data width
+    memory = ctx.create_memory(  8,            8 )
 
 PRGA also provides API for adding and using arbitrary Verilog modules in the FPGA,
 for example `Context.build_primitive`. Multi-modal primitives are also supported
@@ -280,45 +274,27 @@ and switch box slots:
     # commit the top-level array
     top = builder.fill( pattern ).auto_connect().commit()
 
-Auto-complete the architecture, generate RTL and other files
+Generate Yosys and VPR scripts
 ------------------------------------------------------------
 
-PRGA uses `Jinja2`_ for generating most files. `Jinja2`_ is a templating
-language/framework for Python. It is fast, lightweight, and also compatible with
-plain text.
-
-To set up a `Jinja2`_ environment, call the ``new_renderer`` method of the same
-configuration circuitry class used to create the `Context`. This points the
-`Jinja2`_ environment to the correct directories to look for Verilog and other
-templates.
+After describing the desired FPGA architecture, we can generate the scripts for
+our RTL-to-bitstream flow.
+Specifically, PRGA generates the `Yosys`_ scripts for synthesizing an
+application for the custom FPGA, and the `VPR`_ scripts for placing and routing
+the synthesized application.
 
-.. _Jinja2: https://jinja.palletsprojects.com/en/2.11.x/
-
-.. code-block:: python
-    
-    renderer = Scanchain.new_renderer()
+.. _Yosys: http://www.clifford.at/yosys
+.. _VPR: https://verilogtorouting.org/
 
 PRGA adopts a pass-based flow to complete, modify, optimize the FPGA
 architecture as well as generate all files for the architecture. A `Flow` object
 is used to manage and run all the passes. It also checks and resolves the
-dependences between the passes. For example, the `VerilogCollection` pass
-requires `Translation` as a dependency. Even if a `Translation` pass is
-added after a `VerilogCollection` pass, it will be executed before the
-`VerilogCollection` pass.
+dependences between the passes.
 
 .. code-block:: python
 
     flow = Flow(
 
-        # This pass converts user-defined modules to Verilog modules
-        Translation(),
-
-        # Analyze how configurable connections are implemented with switches
-        SwitchPathAnnotation(),
-
-        # This pass inserts configuration circuitry into the FPGA
-        Scanchain.InsertProgCircuitry(),
-
         # This pass generates the architecture specification for VPR to place
         # and route designs onto this FPGA
         VPRArchGeneration("vpr/arch.xml"),
@@ -327,16 +303,73 @@ added after a `VerilogCollection` pass, it will be executed before the
         # to place and route designs onto this FPGA
         VPR_RRG_Generation("vpr/rrg.xml"),
 
-        # This pass create Verilog rendering tasks in the renderer.
-        VerilogCollection('rtl'),
-
         # This pass analyzes the primitives in the FPGA and generates synthesis
         # script for Yosys
         YosysScriptsCollection(r, "syn"),
         )
 
     # Run the flow on our context
-    flow.run(ctx, renderer)
+    flow.run(ctx)
+
+After this step, PRGA should generate the following files:
+
+.. code-block:: bash
+
+    +- syn/
+    |   +- m_adder.lib.v        # behavioral model for logic primitive "adder"
+    |   +- m_adder.techmap.v    # technology mapping rules for logic primitve "adder"
+    |   |
+    |   +- m_ram_1r1w.lib.v     # behavioral model for the block RAM primitive
+    |   +- memory.techmap.v     # technology mapping rules for the block RAM primitive
+    |   +- bram.rule            # block RAM inference rules for Yosys
+    |   |
+    |   +- read_lib.tcl         # Yosys script for reading in the primitives as lib cells
+    |   +- synth.tcl            # Yosys script for synthesizing an application
+    |
+    +- vpr/
+        +- arch.xml             # VPR's architecture description
+        +- rrg.xml              # VPR's routing resource graph
+
+Auto-complete the architecture, generate RTL, and serialize the context
+-----------------------------------------------------------------------
+
+.. PRGA uses `Jinja2`_ for generating most files. `Jinja2`_ is a templating
+   language/framework for Python. It is fast, lightweight, and also compatible with
+   plain text.
+
+.. _Jinja2: https://jinja.palletsprojects.com/en/2.11.x/
+
+We have not yet chosen the programming protocol for the custom FPGA until this
+point in our script.
+This is intended to facilitate early and fast design-space exploration before
+diving into the vast physical optimization space.
+
+To choose the programming protocol and then implement the abstract FPGA
+architecture with synthesizable RTL, run the following pases:
+
+.. code-block:: python
+
+    flow = Flow(
+
+        # This pass chooses the programming protocol, and adds protocol-specific
+        # designs into the context
+        Materialization("scanchain", chain_width = 1),
+
+        # This pass converts user-defined modules to Verilog modules
+        Translation(),
+
+        # Analyze how configurable connections are implemented with switches
+        SwitchPathAnnotation(),
+
+        # This pass inserts configuration circuitry into the FPGA
+        ProgCircuitryInsertion(),
+
+        # This pass create Verilog rendering tasks in the renderer.
+        VerilogCollection('rtl'),
+        )
+
+    # Run the flow on our context
+    flow.run(ctx)
 
 After running the flow, all the models and information about our FPGA are stored
 in the context, and all the file are generated. As the final step, we make a

docs/source/workflow.rst

@@ -129,27 +129,32 @@ conflict and ordering between ``Pass`` es.
 
 Here's a list of the most commonly used ``Pass`` es:
 
+- `VPRArchGeneration` and `VPR_RRG_Generation`: These two passes
+  generate the VPR architecture specification and routing resource graph
+  specification, respectively.
+- `YosysScriptsCollection`: This pass inspects the `Context` object and
+  creates `Yosys`_ script generation tasks, including the main synthesis script,
+  technology mapping script, block RAM inferrence script, and so on.
+- `Materialization`: This pass adds the :ref:`design<arch:Module View>` view of
+  the :ref:`arch:Logic Primitive` s.
+  Certain primitives may be implemented differently on different programming
+  protocols, while some primitives are not supported by all programming
+  protocols.
+  For example, initializable memories that may be used as ROMs are only
+  supported by the `Frame`-based programming protocol.
 - `Translation`: This pass generates the :ref:`design<arch:Module View>` view for modules in
   the :ref:`abstract<arch:Module View>` view by linking :ref:`arch:Logic Primitive` s and implementing the
   abstract configuratble connections with switch modules.
 - `SwitchPathAnnotation`: This pass analyzes the switch modules instantiated
   in the :ref:`design<arch:Module View>` view, and annotate the MUX/BUFFER paths back to the
   :ref:`abstract<arch:Module View>` view.
-  This information is used by ``FASM`` metadata generation during `VPR`_ script
-  generation.
-- ``*.InsertProgCircuitry``: This pass inserts configuration memory into the
+  This information is used later by the bitstream generator.
+- `ProgCircuitryInsertion`: This pass inserts configuration memory into the
   :ref:`design<arch:Module View>` view.
   This pass is specific to configuration circuitry types, e.g.
-  `Scanchain.InsertProgCircuitry` and `Pktchain.InsertProgCircuitry`.
-- `VPRArchGeneration` and `VPR_RRG_Generation`: These two passes
-  generate the VPR architecture specification and routing resource graph
-  specification, respectively.
-- `VerilogCollection`: This pass inspects the `Context` object and creates
+  `Scanchain`, `Pktchain` and `Frame`, and only available after
   RTL generation tasks for all the modules in a `FileRenderer` object.
   RTL Verilog files are generated based on the :ref:`design<arch:Module View>` views.
-- `YosysScriptsCollection`: This pass inspects the `Context` object and
-  creates `Yosys`_ script generation tasks, including the main synthesis script,
-  technology mapping script, block RAM inferrence script, and so on.
 
 File Rendering
 ^^^^^^^^^^^^^^

examples/app/bcd2bin/frame_k4_N2_8x8/Makefile

@@ -0,0 +1,9 @@
+COMP ?= vcs
+CONFIG := config/config.${COMP}.yaml
+PROJECTS := app tests
+
+$(PROJECTS): $(CONFIG)
+	python -O -m prga.tools.wizard $<
+
+clean:
+	rm -rf $(PROJECTS)