Example: PicoRV32, and docs improvements

Author: angl-dev

docs/source/_static/images/domains.png

@@ -0,0 +1,45 @@
+Development Guide: Architecture
+===============================
+
+Domains
+-------
+
+The key challenge of PRGA is to make multiple tools work together seamlessly.
+PRGA tackles this challenge by dividing the architecture into three domains:
+the user domain, the logical domain, and the physical domain.
+
+.. image:: /_static/images/domains.png
+
+The figure above shows an IOB in different domains:
+
+User Domain
+^^^^^^^^^^^
+
+The figure to the left shows the IOB in the user domain. All instances in this
+domain are converted to `\<pb_type\>
+<http://docs.verilogtorouting.org/en/latest/arch/reference/#complex-blocks>`_
+s when generating `VPR <http://docs.verilogtorouting.org/en/latest/vpr/>`_ 's
+architecture description of the FPGA, and available to FPGA users. Each
+output port or input pin may be connected to more than one input port or
+output pin in this domain, indicating the configurability of these connections.
+These connections are converted to `\<interconnect\>
+<http://docs.verilogtorouting.org/en/latest/arch/reference/#interconnect>`_ tags
+when generating `VPR <http://docs.verilogtorouting.org/en/latest/vpr/>`_ 's
+architecture description.
+
+Logical Domain
+^^^^^^^^^^^^^^
+
+The figure in the middle shows the IOB in the logical domain. Configurable
+connections are implemented with switches. Configuration circuitry is also
+injected and connected.
+
+Most of the code of PRGA works in this domain.
+
+Physical Domain
+^^^^^^^^^^^^^^^
+
+Physical domain is used for RTL generation as well as backend processing. Note
+that in the figure shown above, the IO pad instance is not present in the
+physical domain. Each pin of this logical-only instance is mapped to a physical
+port, shown as the dashed lines in the figure.

docs/source/dev/arch.rst

@@ -27,6 +27,7 @@ Contents
 
    intro
    build_your_custom_fpga
+   dev/arch
    prga.py/modules
 
 

docs/source/index.rst

@@ -21,10 +21,32 @@ PRGA is dependent on the following third-party tools:
 Python
 ^^^^^^
 
-PRGA works with Python 2.7.x and Python 3.7.x. However, `Python 2.x will reach
-its end of life on January 1st, 2020
+PRGA works with Python 2.7.x and Python 3.7.x. However, Python 2.x will reach
+its end of life on `January 1st, 2020
 <https://www.python.org/doc/sunset-python-2/>`_ , so we recommend using Python
 3.7.x if possible.
 
-Installation
-------------
+
+Examples
+--------
+
+Examples are provided in the ``examples/`` directory. FPGA building examples are
+provided in the ``examples/fpga/`` directory, and RTL-to-verification examples
+are provided in the ``examples/target/`` directory.
+
+To build an FPGA, run the following commands:
+
+.. code-block:: bash
+
+    cd /path/to/prga/                           # cd to the root 
+    cd examples/fpga/tiny/k4_N2_8x8             # choose one FPGA building example
+    make                                        # build the FPGA!
+
+To implement a target design and simulate it with an FPGA design, run the
+following commands:
+
+.. code-block:: bash
+
+    cd /path/to/prga/                           # cd to the root 
+    cd examples/target/bcd2bin/tiny_k4_N2_8x8   # choose one design and one FPGA
+    make                                        # run all the way to verification

docs/source/intro.rst

@@ -0,0 +1 @@
+include ../../Makefile.in

examples/fpga/medium/frac_k6_N4_mem8K_42x34/Makefile

@@ -0,0 +1,140 @@
+# -*- encoding: ascii -*-
+
+from prga.api.context import *
+from prga.api.flow import *
+from prga.api.config import *
+
+from itertools import product
+
+def run():
+    width, height = 42, 34
+    context = ArchitectureContext('top', width, height, BitchainConfigCircuitryDelegate)
+
+    # 1. routing stuff
+    clk = context.create_global('clk', is_clock = True, bind_to_position = (0, 1))
+    context.create_segment('L1', 48, 1)
+    context.create_segment('L2', 16, 2)
+    context.create_segment('L4', 8, 4)
+
+    # 2. create IOB
+    iob = context.create_io_block('iob')
+    while True:
+        clkport = iob.create_global(clk)
+        outpad = iob.create_input('outpad', 1)
+        inpad = iob.create_output('inpad', 1)
+        ioinst = iob.instances['io']
+        iff = iob.instantiate(context.primitives['flipflop'], 'iff')
+        off = iob.instantiate(context.primitives['flipflop'], 'off')
+        iob.connect(clkport, iff.pins['clk'])
+        iob.connect(ioinst.pins['inpad'], iff.pins['D'])
+        iob.connect(iff.pins['Q'], inpad)
+        iob.connect(ioinst.pins['inpad'], inpad)
+        iob.connect(clkport, off.pins['clk'])
+        iob.connect(off.pins['Q'], ioinst.pins['outpad'])
+        iob.connect(outpad, ioinst.pins['outpad'])
+        iob.connect(outpad, off.pins['D'])
+        break
+
+    # 3. create tile
+    iotiles = {}
+    for orientation in iter(Orientation):
+        if orientation.is_auto:
+            continue
+        iotiles[orientation] = context.create_tile(
+                'io_tile_{}'.format(orientation.name), iob, 8, orientation)
+
+    # 5. create CLB
+    clb = context.create_logic_block('clb')
+    while True:
+        clkport = clb.create_global(clk, Orientation.south)
+        ceport = clb.create_input('ce', 1, Orientation.south)
+        srport = clb.create_input('sr', 1, Orientation.south)
+        cin = clb.create_input('cin', 1, Orientation.north)
+        for i in range(4):
+            inst = clb.instantiate(context.primitives['fraclut6sffc'], 'cluster{}'.format(i))
+            clb.connect(clkport, inst.pins['clk'])
+            clb.connect(ceport, inst.pins['ce'])
+            clb.connect(srport, inst.pins['sr'])
+            clb.connect(clb.create_input('ia' + str(i), 6, Orientation.west), inst.pins['ia'])
+            clb.connect(clb.create_input('ib' + str(i), 1, Orientation.west), inst.pins['ib'])
+            clb.connect(cin, inst.pins['cin'], pack_pattern = 'carrychain')
+            cin = inst.pins['cout']
+            clb.connect(inst.pins['oa'], clb.create_output('oa' + str(i), 1, Orientation.east))
+            clb.connect(inst.pins['ob'], clb.create_output('ob' + str(i), 1, Orientation.east))
+            clb.connect(inst.pins['q'], clb.create_output('q' + str(i), 1, Orientation.east))
+        clb.connect(cin, clb.create_output('cout', 1, Orientation.south), pack_pattern = 'carrychain')
+        break
+
+    # 6. create direct inter-block tunnels
+    context.create_direct_tunnel('carrychain', clb.ports['cout'], clb.ports['cin'], (0, 1))
+
+    # 7. create tile
+    clbtile = context.create_tile('clb_tile', clb)
+
+    # 8. create BRAM
+    bram = context.create_logic_block('bram', 1, 2)
+    while True:
+        clkport = bram.create_global(clk, Orientation.south, position = (0, 0))
+        addrport1 = bram.create_input('addr1', 10, Orientation.west, position = (0, 0))
+        dinport1 = bram.create_input('data1', 8, Orientation.west, position = (0, 0))
+        weport1 = bram.create_input('we1', 1, Orientation.west, position = (0, 0))
+        doutport1 = bram.create_output('out1', 8, Orientation.east, position = (0, 0))
+        addrport2 = bram.create_input('addr2', 10, Orientation.west, position = (0, 1))
+        dinport2 = bram.create_input('data2', 8, Orientation.west, position = (0, 1))
+        weport2 = bram.create_input('we2', 1, Orientation.west, position = (0, 1))
+        doutport2 = bram.create_output('out2', 8, Orientation.east, position = (0, 1))
+        inst = bram.instantiate(context.primitive_library.get_or_create_memory(10, 8, 
+            dualport = True), 'ram')
+        bram.auto_connect(inst)
+        break
+
+    # 9. create tile
+    bramtile = context.create_tile('bram_tile', bram)
+
+    # 10. create sub-array
+    subarray = context.create_array('subarray', 5, 4)
+    for x, y in product(range(5), range(4)):
+        if x == 2:
+            if y % 2 == 0:
+                subarray.instantiate_element(bramtile, (x, y))
+        else:
+            subarray.instantiate_element(clbtile, (x, y))
+
+    # 11. fill top-level array
+    for x in range(width):
+        for y in range(height):
+            if x == 0:
+                if y > 0 and y < height - 1:
+                    context.top.instantiate_element(iotiles[Orientation.west], (x, y))
+            elif x == width - 1:
+                if y > 0 and y < height - 1:
+                    context.top.instantiate_element(iotiles[Orientation.east], (x, y))
+            elif y == 0:
+                context.top.instantiate_element(iotiles[Orientation.south], (x, y))
+            elif y == height - 1:
+                context.top.instantiate_element(iotiles[Orientation.north], (x, y))
+            elif x % 5 == 1 and y % 4 == 1:
+                context.top.instantiate_element(subarray, (x, y))
+
+    # 12. flow
+    flow = Flow((
+        CompleteRoutingBox(BlockFCValue(BlockPortFCValue(0.25), BlockPortFCValue(0.1))),
+        CompleteSwitch(),
+        CompleteConnection(),
+        GenerateVerilog('rtl'),
+        InjectBitchainConfigCircuitry(),
+        GenerateVPRXML('vpr'),
+        CompletePhysical(),
+        ZeroingBRAMWriteEnable(),
+        ZeroingBlockPins(),
+        GenerateYosysResources('syn'),
+            ))
+
+    # 13. run flow
+    flow.run(context)
+
+    # 14. create a pickled version
+    context.pickle('ctx.pickled')
+
+if __name__ == '__main__':
+    run()

examples/fpga/medium/frac_k6_N4_mem8K_42x34/build.py

@@ -0,0 +1,31 @@
+TARGET := picorv32
+PICKLED_CONTEXT := $(FPGA_DIR)/ctx.pickled
+SIM_MAKEFILE := Makefile.sim
+PARTIAL_IOBINDING := io.partial
+
+.PHONY: all project
+all: $(SIM_MAKEFILE) $(PICKLED_CONTEXT)
+	make -f $(SIM_MAKEFILE)
+
+project: $(SIM_MAKEFILE) $(PICKLED_CONTEXT)
+
+clean:
+	if [ -f $(SIM_MAKEFILE) ]; then make -f $(SIM_MAKEFILE) cleanall; fi
+	rm -rf $(SIM_MAKEFILE) $(TARGET)_host_wrapper.v synth.ys io.pads
+
+$(SIM_MAKEFILE): $(PICKLED_CONTEXT) $(PARTIAL_IOBINDING) ../$(TARGET)_host.v ../$(TARGET).v
+	python -m prga_tools.bitchain.simproj \
+		--fix_io $(PARTIAL_IOBINDING) \
+		-t ../$(TARGET)_host.v --testbench_top picorv32_wrapper \
+		--testbench_plus_args firmware=../firmware.hex max_cycle=10000000 quiet \
+		-m ../$(TARGET).v --model_top picorv32_axi \
+		--model_parameters COMPRESSED_ISA=1 ENABLE_MUL=1 ENABLE_DIV=1 ENABLE_IRQ=1 ENABLE_TRACE=1 \
+		--makefile $@ \
+		$(PICKLED_CONTEXT)
+
+$(PICKLED_CONTEXT):
+	make -C $(FPGA_DIR)
+
+%:
+	if [ -f $(SIM_MAKEFILE) ]; then make -f $(SIM_MAKEFILE) $@; \
+		else echo "Simulation project not built yet. Run 'make project' first" && exit 1; fi