Create example designs for the new IR

docs/source/developers_guide/ir-examples.md

@@ -0,0 +1,62 @@
+# Examples for Internal Representation
+
+There are four examples in `examples/ir_examples` showcasing specific features of Topwrap which we want to take into consideration while creating the new internal representation.
+
+## Simple
+
+This is a simple non-hierarchical example that uses two IPs. Inside, there are two LFSR RNGs constantly generating pseudorandom numbers on their outputs. They are both connected to a multiplexer that selects which generator's output should be passed to the `rnd_bit` external output port. The specific generator is selected using the `sel_gen` input port.
+
+This example features:
+- IP core parameters
+- variable width ports
+
+```{kpm_iframe}
+:dataflow: ../../build/kpm_jsons/data_ir_examples_simple.json
+:spec: ../../build/kpm_jsons/spec_ir_examples_simple.json
+```
+
+## Interface
+
+This is another simple example using two IPs, this time with an interface. The design consists of a streamer IP and a receiver IP. They both are connected using the AXI4Stream interface. The receiver then passes the data to an external inout port.
+
+This example features:
+- usage of interface ports
+- port slicing
+- constant value connected to a port
+- an Inout port
+
+```{kpm_iframe}
+:dataflow: ../../build/kpm_jsons/data_ir_examples_interface.json
+:spec: ../../build/kpm_jsons/spec_ir_examples_interface.json
+```
+
+## Hierarchical
+
+This is an example of a hierarchical design. The top-level features standard external ports `clk` and `rst`, a `btn` input that represents an input from a physical button, and `disp0..2` outputs that go to an imaginary 3-wire-controlled display. All these ports are connected to a processing hierarchy `proc`. Inside this hierarchy we can see the `btn` input going into a "debouncer" IP, its output going into a 4-bit counter, the counter's sum arriving into an encoder as the input number, and the display outputs from the encoder further lifted to the parent level. The encoder itself is a hierarchy, though an empty one with only the ports defined. The 4-bit counter is also a hierarchy that can be further explored. It consists of a variable width adder IP and a flip-flop register IP.
+
+This example features:
+- hierarchies of more than one depth
+
+```{kpm_iframe}
+:dataflow: ../../build/kpm_jsons/data_ir_examples_hierarchical.json
+:spec: ../../build/kpm_jsons/spec_ir_examples_hierarchical.json
+```
+
+## Interconnect
+
+This is an example of our interconnect generation feature. The design features 3 IP cores: a memory core (`ips/mem.yaml`), a digital signal processor (`ips/dsp.yaml`) and a CPU (`ips/cpu.yaml`). All of them are connected to a wishbone interconnect where both the CPU and an external interface `ext_manager` act as managers and drive the bus. DSP and MEM are subordinates, one available at address 0x0, the other at 0x10000.
+
+Note that while this specific example uses a "wishbone_roundrobin" interconnect, we still aim to support other types of them in the future.
+Each one will have its own schema for the "params" section so make sure not to hardcode the parameters' keys or values.
+
+This example features:
+- usage of interface ports
+- interconnect usage
+
+:::{note}
+No KPM example for this one since interconnects are still irrepresentable in it.
+:::
+
+## Other
+
+Something that was not taken into account previously, because we don't support it yet, and it's impossible to represent in either format, is a feature/syntax that would allow us to dynamically change the collection of ports/interfaces an IP/hierarchy has. Similarly to how we can control the width of a port using a parameter (like in the "simple" example).

docs/source/index.md

@@ -33,4 +33,5 @@ developers_guide/parsing
 developers_guide/examples
 developers_guide/future_enhancements
 developers_guide/inline_kpm_howto
+developers_guide/ir-examples
 ```

examples/ir_examples/README.md

@@ -0,0 +1,8 @@
+# Examples for internal representation
+
+These examples represent different feature sets that are important for us in Topwrap.
+They are used to gather requirements for our internal data format based on features we want to support and on the syntax of other independent external formats like IP-XACT.
+
+More information about them is available in the documentation at https://antmicro.github.io/topwrap/developers_guide/ir-examples.md
+
+Copyright (c) 2024 [Antmicro](https://antmicro.com)

examples/ir_examples/hierarchical/Makefile

@@ -0,0 +1,13 @@
+# Copyright (c) 2024 Antmicro <www.antmicro.com>
+# SPDX-License-Identifier: Apache-2.0
+
+JSONS = kpm_spec.json kpm_dataflow.json
+
+all: $(JSONS)
+
+$(JSONS):
+	topwrap specification ips/*.yaml
+	topwrap dataflow -d design.yaml ips/*.yaml
+
+clean:
+	rm -f $(JSONS)

examples/ir_examples/hierarchical/design.yaml

@@ -0,0 +1,98 @@
+design:
+  hierarchies:
+    proc:
+      design:
+        hierarchies:
+          4-bit counter:
+            design:
+              parameters:
+                D-flipflop:
+                  WIDTH: 4
+                adder:
+                  WIDTH: 4
+              ports:
+                D-flipflop:
+                  D:
+                  - adder
+                  - sum
+                  Q: sum
+                  clk: impulse
+                  rst: rst
+                adder:
+                  a:
+                  - D-flipflop
+                  - Q
+                  b: impulse
+            external:
+              ports:
+                in:
+                - impulse
+                - rst
+                out:
+                - sum
+            ips:
+              D-flipflop:
+                file: ips/d_ff.yaml
+              adder:
+                file: ips/adder.yaml
+          encoder:
+            external:
+              ports:
+                in:
+                - number
+                - clk
+                out:
+                - enc0
+                - enc1
+                - enc2
+        parameters:
+          debouncer:
+            GRACE: 1000
+        ports:
+          4-bit counter:
+            impulse:
+            - debouncer
+            - filtered_out
+            rst: rst
+          debouncer:
+            clk: clk
+            in: btn
+          encoder:
+            clk: clk
+            enc0: enc0
+            enc1: enc1
+            enc2: enc2
+            number:
+            - 4-bit counter
+            - sum
+      external:
+        ports:
+          in:
+          - btn
+          - clk
+          - rst
+          out:
+          - enc0
+          - enc1
+          - enc2
+      ips:
+        debouncer:
+          file: ips/debouncer.yaml
+  ports:
+    proc:
+      btn: btn
+      clk: clk
+      enc0: disp0
+      enc1: disp1
+      enc2: disp2
+      rst: rst
+external:
+  ports:
+    in:
+    - clk
+    - btn
+    - rst
+    out:
+    - disp0
+    - disp1
+    - disp2

examples/ir_examples/hierarchical/ips/adder.yaml

@@ -0,0 +1,11 @@
+name: adder
+
+parameters:
+  WIDTH: 4
+
+signals:
+  in:
+    - [a, WIDTH-1, 0]
+    - [b, WIDTH-1, 0]
+  out:
+    - [sum, WIDTH-1, 0]

examples/ir_examples/hierarchical/ips/d_ff.yaml

@@ -0,0 +1,12 @@
+name: D-flipflop
+
+parameters:
+  WIDTH: 4
+
+signals:
+  in:
+    - clk
+    - rst
+    - [D, WIDTH-1, 0]
+  out:
+    - [Q, WIDTH-1, 0]

examples/ir_examples/hierarchical/ips/debouncer.yaml

@@ -0,0 +1,11 @@
+name: debouncer
+
+parameters:
+  GRACE: 1000
+
+signals:
+  in:
+    - clk
+    - in
+  out:
+    - filtered_out

examples/ir_examples/interconnect/Makefile

@@ -0,0 +1,13 @@
+# Copyright (c) 2024 Antmicro <www.antmicro.com>
+# SPDX-License-Identifier: Apache-2.0
+
+JSONS = kpm_spec.json kpm_dataflow.json
+
+all: $(JSONS)
+
+$(JSONS):
+	topwrap specification ips/*.yaml
+	topwrap dataflow -d design.yaml ips/*.yaml
+
+clean:
+	rm -f $(JSONS)

examples/ir_examples/interconnect/design.yaml

@@ -0,0 +1,63 @@
+external:
+  ports:
+    in:
+      - clk
+      - rst
+  interfaces:
+    in:
+      - ext_manager
+
+ips:
+  cpu:
+    file: ips/cpu.yaml
+  wb_pass:
+    file: ips/wb_passthrough.yaml
+  mem:
+    file: ips/mem.yaml
+  dsp:
+    file: ips/dsp.yaml
+
+design:
+  ports:
+    cpu: &clkrst
+      clk: clk
+      rst: rst
+    mem: *clkrst
+    dsp: *clkrst
+
+  parameters:
+    mem:
+      WIDTH: 8
+      DEPTH: 0xFFFF
+    wb_pass:
+      DW: 8
+
+  interfaces:
+    wb_pass:
+      wb_in: ext_manager
+
+  interconnects:
+    wishbone_bus:
+      clock: clk
+      reset: rst
+      type: wishbone_roundrobin
+
+      params:
+        addr_width: 32
+        data_width: 8
+        granularity: 8
+        features: [err, stall]
+
+      managers:
+        cpu: [bus_manager]
+        wb_pass: [wb_out]
+
+      subordinates:
+        mem:
+          bus:
+            address: 0
+            size: 0xFFFF
+        dsp:
+          bus:
+            address: 0x10000
+            size: 0xFF

examples/ir_examples/interconnect/ips/cpu.yaml

@@ -0,0 +1,23 @@
+name: example_cpu
+
+signals:
+  in:
+    - clk
+    - rst
+
+interfaces:
+  bus_manager:
+    type: wishbone
+    mode: manager
+    signals:
+      out:
+        cyc: o_wb_cyc
+        stb: o_wb_stb
+        adr: [o_wb_adr, 31, 0]
+        dat_w: [o_wb_dat, 7, 0]
+        we: o_wb_we
+      in:
+        dat_r: [i_wb_dat, 7, 0]
+        ack: i_wb_ack
+        stall: i_wb_stall
+        err: i_wb_err

examples/ir_examples/interconnect/ips/dsp.yaml

@@ -0,0 +1,27 @@
+name: dsp_block
+
+signals:
+  in:
+    - clk
+    - rst
+
+parameters:
+  WIDTH: 8
+  RESOLUTION: 1024
+
+interfaces:
+  bus:
+    type: wishbone
+    mode: subordinate
+    signals:
+      in:
+        cyc: i_cyc
+        stb: i_stb
+        adr: [i_adr, 7, 0]
+        dat_w: [i_dat, WIDTH-1, 0]
+        we: i_we
+      out:
+        dat_r: [o_dat, WIDTH-1, 0]
+        ack: o_ack
+        stall: o_stall
+        err: o_err

examples/ir_examples/interconnect/ips/mem.yaml

@@ -0,0 +1,27 @@
+name: memory_block
+
+signals:
+  in:
+    - clk
+    - rst
+
+parameters:
+  WIDTH: 32
+  DEPTH: 0
+
+interfaces:
+  bus:
+    type: wishbone
+    mode: subordinate
+    signals:
+      in:
+        cyc: i_cyc
+        stb: i_stb
+        adr: [i_adr, 31, 0]
+        dat_w: [i_dat, WIDTH-1, 0]
+        we: i_we
+      out:
+        dat_r: [o_dat, WIDTH-1, 0]
+        ack: o_ack
+        stall: o_stall
+        err: o_err