Merge pull request #261 from YosysHQ/pygeneric

Python API for generic architecture

10 files changed, 201 insertions, 0 deletions

diff --git a/generic/examples/.gitignore b/generic/examples/.gitignore
new file mode 100644
index 00000000..38e95de5
--- /dev/null
+++ b/generic/examples/.gitignore
@@ -0,0 +1,3 @@
+blinky.fasm
+__pycache__
+*.pyc
diff --git a/generic/examples/README.md b/generic/examples/README.md
new file mode 100644
index 00000000..9fd106d9
--- /dev/null
+++ b/generic/examples/README.md
@@ -0,0 +1,14 @@
+# Generic Architecture Example
+
+This contains a simple, artificial, example of the nextpnr generic API.
+
+ - simple.py procedurally generates a simple FPGA architecture with IO at the edges,
+   logic slices in all other tiles, and interconnect only between adjacent tiles
+ 
+ - simple_timing.py annotates cells with timing data (this is a separate script that must be run after packing)
+
+ - write_fasm.py uses the nextpnr Python API to write a FASM file for a design
+
+ - bitstream.py uses write_fasm.py to create a FASM ("FPGA assembly") file for the place-and-routed design
+
+ - Run simple.sh to build an example design on the FPGA above
\ No newline at end of file
diff --git a/generic/examples/__init__.py b/generic/examples/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/generic/examples/__init__.py
diff --git a/generic/examples/bitstream.py b/generic/examples/bitstream.py
new file mode 100644
index 00000000..1ab94f0c
--- /dev/null
+++ b/generic/examples/bitstream.py
@@ -0,0 +1,17 @@
+from write_fasm import *
+from simple_config import K
+
+# Need to tell FASM generator how to write parameters
+# (celltype, parameter) -> ParameterConfig
+param_map = {
+	("GENERIC_SLICE", "K"): ParameterConfig(write=False),
+	("GENERIC_SLICE", "INIT"): ParameterConfig(write=True, numeric=True, width=2**K),
+	("GENERIC_SLICE", "FF_USED"): ParameterConfig(write=True, numeric=True, width=1),
+
+	("GENERIC_IOB", "INPUT_USED"): ParameterConfig(write=True, numeric=True, width=1),
+	("GENERIC_IOB", "OUTPUT_USED"): ParameterConfig(write=True, numeric=True, width=1),
+	("GENERIC_IOB", "ENABLE_USED"): ParameterConfig(write=True, numeric=True, width=1),
+}
+
+with open("blinky.fasm", "w") as f:
+	write_fasm(ctx, param_map, f)
\ No newline at end of file
diff --git a/generic/examples/blinky.v b/generic/examples/blinky.v
new file mode 100644
index 00000000..b7cb1b86
--- /dev/null
+++ b/generic/examples/blinky.v
@@ -0,0 +1,9 @@
+module top(input clk, output reg [7:0] leds);
+
+reg [25:0] ctr;
+always @(posedge clk)
+	ctr <= ctr + 1'b1;
+
+assign leds = ctr[25:18];
+
+endmodule
\ No newline at end of file
diff --git a/generic/examples/simple.py b/generic/examples/simple.py
new file mode 100644
index 00000000..9339b68a
--- /dev/null
+++ b/generic/examples/simple.py
@@ -0,0 +1,72 @@
+from simple_config import *
+
+def is_io(x, y):
+	return x == 0 or x == X-1 or y == 0 or y == Y-1
+
+for x in range(X):
+	for y in range(Y):
+		# Bel port wires
+		for z in range(N):
+			ctx.addWire(name="X%dY%dZ%d_CLK" % (x, y, z), type="BEL_CLK", x=x, y=y)
+			ctx.addWire(name="X%dY%dZ%d_Q" % (x, y, z), type="BEL_Q", x=x, y=y)
+			for i in range(K):
+				ctx.addWire(name="X%dY%dZ%d_I%d" % (x, y, z, i), type="BEL_I", x=x, y=y)
+		# Local wires
+		for l in range(Wl):
+			ctx.addWire(name="X%dY%d_LOCAL%d" % (x, y, l), type="LOCAL", x=x, y=y)
+		# Create bels
+		if is_io(x, y):
+			if x == y:
+				continue
+			for z in range(2):
+				ctx.addBel(name="X%dY%d_IO%d" % (x, y, z), type="GENERIC_IOB", loc=Loc(x, y, z), gb=False)
+				ctx.addBelInput(bel="X%dY%d_IO%d" % (x, y, z), name="I", wire="X%dY%dZ%d_I0" % (x, y, z))
+				ctx.addBelInput(bel="X%dY%d_IO%d" % (x, y, z), name="EN", wire="X%dY%dZ%d_I1" % (x, y, z))
+				ctx.addBelOutput(bel="X%dY%d_IO%d" % (x, y, z), name="O", wire="X%dY%dZ%d_Q" % (x, y, z))
+		else:
+			for z in range(N):
+				ctx.addBel(name="X%dY%d_SLICE%d" % (x, y, z), type="GENERIC_SLICE", loc=Loc(x, y, z), gb=False)
+				ctx.addBelInput(bel="X%dY%d_SLICE%d" % (x, y, z), name="CLK", wire="X%dY%dZ%d_CLK" % (x, y, z))
+				for k in range(K):
+					ctx.addBelInput(bel="X%dY%d_SLICE%d" % (x, y, z), name="I[%d]" % k, wire="X%dY%dZ%d_I%d" % (x, y, z, k))
+				ctx.addBelOutput(bel="X%dY%d_SLICE%d" % (x, y, z), name="Q", wire="X%dY%dZ%d_Q" % (x, y, z))
+
+for x in range(X):
+	for y in range(Y):
+		# Pips driving bel input wires
+		# Bel input wires are driven by every Si'th local with an offset
+		def create_input_pips(dst, offset, skip):
+			for i in range(offset % skip, Wl, skip):
+				src = "X%dY%d_LOCAL%d" % (x, y, i)
+				ctx.addPip(name="X%dY%d.%s.%s" % (x, y, src, dst), type="BEL_INPUT",
+					srcWire=src, dstWire=dst, delay=ctx.getDelayFromNS(0.05), loc=Loc(x, y, 0))
+		for z in range(N):
+			create_input_pips("X%dY%dZ%d_CLK" % (x, y, z), 0, Si)
+			for k in range(K):
+				create_input_pips("X%dY%dZ%d_I%d" % (x, y, z, k), k % Si, Si)
+
+		# Pips from bel outputs to locals
+		def create_output_pips(dst, offset, skip):
+			for i in range(offset % skip, N, skip):
+				src = "X%dY%dZ%d_Q" % (x, y, i)
+				ctx.addPip(name="X%dY%d.%s.%s" % (x, y, src, dst), type="BEL_OUTPUT",
+					srcWire=src, dstWire=dst, delay=ctx.getDelayFromNS(0.05), loc=Loc(x, y, 0))
+		# Pips from neighbour locals to locals
+		def create_neighbour_pips(dst, nx, ny, offset, skip):
+			if nx < 0 or nx >= X or ny < 0 or ny >= Y:
+				return
+			for i in range(offset % skip, Wl, skip):
+				src = "X%dY%d_LOCAL%d" % (nx, ny, i)
+				ctx.addPip(name="X%dY%d.%s.%s" % (x, y, src, dst), type="NEIGHBOUR",
+					srcWire=src, dstWire=dst, delay=ctx.getDelayFromNS(0.05), loc=Loc(x, y, 0))
+		for l in range(Wl):
+			dst = "X%dY%d_LOCAL%d" % (x, y, l)
+			create_output_pips(dst, l % Sq, Sq)
+			create_neighbour_pips(dst, x-1, y-1, (l + 1) % Sl, Sl)
+			create_neighbour_pips(dst, x-1, y, (l + 2) % Sl, Sl)
+			create_neighbour_pips(dst, x-1, y+1, (l + 2) % Sl, Sl)
+			create_neighbour_pips(dst, x, y-1, (l + 3) % Sl, Sl)
+			create_neighbour_pips(dst, x, y+1, (l + 4) % Sl, Sl)
+			create_neighbour_pips(dst, x+1, y-1, (l + 5) % Sl, Sl)
+			create_neighbour_pips(dst, x+1, y, (l + 6) % Sl, Sl)
+			create_neighbour_pips(dst, x+1, y+1, (l + 7) % Sl, Sl)
\ No newline at end of file
diff --git a/generic/examples/simple.sh b/generic/examples/simple.sh
new file mode 100755
index 00000000..8ae903f9
--- /dev/null
+++ b/generic/examples/simple.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -ex
+yosys -p "tcl ../synth/synth_generic.tcl 4 blinky.json" blinky.v
+${NEXTPNR:-../../nextpnr-generic} --pre-pack simple.py --pre-place simple_timing.py --json blinky.json --post-route bitstream.py
diff --git a/generic/examples/simple_config.py b/generic/examples/simple_config.py
new file mode 100644
index 00000000..dfb38f1c
--- /dev/null
+++ b/generic/examples/simple_config.py
@@ -0,0 +1,15 @@
+# Grid size including IOBs at edges
+X = 12
+Y = 12
+# SLICEs per tile
+N = 8
+# LUT input count
+K = 4
+# Number of local wires
+Wl = N*(K+1) + 8 
+# 1/Fc for bel input wire pips
+Si = 4
+# 1/Fc for Q to local wire pips
+Sq = 4
+# ~1/Fc local to neighbour local wire pips
+Sl = 8
\ No newline at end of file
diff --git a/generic/examples/simple_timing.py b/generic/examples/simple_timing.py
new file mode 100644
index 00000000..a955c8d7
--- /dev/null
+++ b/generic/examples/simple_timing.py
@@ -0,0 +1,15 @@
+for cname, cell in ctx.cells:
+	if cell.type != "GENERIC_SLICE":
+		continue
+	if cname in ("$PACKER_GND", "$PACKER_VCC"):
+		continue
+	K = int(cell.params["K"])
+	if cell.params["FF_USED"] == "1":
+		ctx.addCellTimingClock(cell=cname, port="CLK")
+		for i in range(K):
+			ctx.addCellTimingSetupHold(cell=cname, port="I[%d]" % i, clock="CLK",
+				setup=ctx.getDelayFromNS(0.2), hold=ctx.getDelayFromNS(0))
+		ctx.addCellTimingClockToOut(cell=cname, port="Q", clock="CLK", clktoq=ctx.getDelayFromNS(0.2))
+	else:
+		for i in range(K):
+			ctx.addCellTimingDelay(cell=cname, fromPort="I[%d]" % i, toPort="Q", delay=ctx.getDelayFromNS(0.2))
\ No newline at end of file
diff --git a/generic/examples/write_fasm.py b/generic/examples/write_fasm.py
new file mode 100644
index 00000000..1f279b63
--- /dev/null
+++ b/generic/examples/write_fasm.py
@@ -0,0 +1,52 @@
+from collections import namedtuple
+
+"""
+	write:   set to True to enable writing this parameter to FASM
+
+	numeric: set to True to write this parameter as a bit array (width>1) or
+	         single bit (width==1) named after the parameter. Otherwise this
+	         parameter will be written as `name.value`
+
+	width:   width of numeric parameter (ignored for non-numeric parameters)
+	
+	alias:   an alternative name for this parameter (parameter name used if alias
+	         is None)
+"""
+ParameterConfig = namedtuple('ParameterConfig', 'write numeric width alias')
+
+# FIXME use defaults= once Python 3.7 is standard
+ParameterConfig.__new__.__defaults__ = (False, True, 1, None)
+
+
+"""
+Write a design as FASM
+
+    ctx:      nextpnr context
+    paramCfg: map from (celltype, parametername) -> ParameterConfig describing how to write parameters
+    f:        output file
+"""
+def write_fasm(ctx, paramCfg, f):
+	for nname, net in sorted(ctx.nets, key=lambda x: str(x[1].name)):
+		print("# Net %s" % nname, file=f)
+		for wire, pip in sorted(net.wires, key=lambda x: str(x[1])):
+			if pip.pip != "":
+				print("%s" % pip.pip, file=f)
+		print("", file=f)
+	for cname, cell in sorted(ctx.cells, key=lambda x: str(x[1].name)):
+		print("# Cell %s at %s" % (cname, cell.bel), file=f)
+		for param, val in sorted(cell.params, key=lambda x: str(x)):
+			cfg = paramCfg[(cell.type, param)]
+			if not cfg.write:
+				continue
+			fasm_name = cfg.alias if cfg.alias is not None else param
+			if cfg.numeric:
+				if cfg.width == 1:
+					if int(val) != 0:
+						print("%s.%s" % (cell.bel, fasm_name), file=f)
+				else:
+					# Parameters with width >32 are direct binary, otherwise denary
+					binval = val if cfg.width > 32 else "{:0{}b}".format(int(val), cfg.width)
+					print("%s.%s[%d:0] = %d'b%s" % (cell.bel, fasm_name, cfg.width-1, cfg.width, binval), file=f)
+			else:
+				print("%s.%s.%s" % (cell.bel, fasm_name, val), file=f)
+		print("", file=f)
\ No newline at end of file