update examples build system

examples/README.md

@@ -0,0 +1,34 @@
+# examples
+
+Simple examples showing the usage of this plugin.
+
+## Contents
+
+- *ecp5_versa*: Elaborate Mixed-Language ECP5 example with UART, I2C and PLL support. This shows how to include Verilog for synthesis
+- *ice40hx8k*: Very simple LED demonstration
+- *icestick/leds*: A lot of LED animations and examples
+- *icestick/uart*: A loopback UART Transceiver module
+- *icezum*: Small demo for the [IceZUM](https://github.com/FPGAwars/icezum) board
+
+## Usage
+
+```bash
+make all
+```
+
+All examples use `makefile` for compilation.
+Simply run `make` to generate a bitstream.
+You can then program a board manually or using `make prog`
+Programming from the docker container may only work on linux.
+See the repository's main README for more details.
+
+In case you don't have all tools installed on your machine you can use tools from the official docker container.
+Simply use `make USE_DOCKER=1`.
+Be aware that currently only images for `amd64` exist.
+
+The makefiles are split up in a way that each example project only defines variables and imports the `tools.mk` and `common.mk` makefiles in this directory.
+These contain all build targets.
+
+Note: these example project are somewhat opinionated with regard to style, structure, and usage.
+Your own projects don't have to follow these examples.
+The plugin can be adapted to virtually any yosys workflow.

examples/common.mk

@@ -0,0 +1,68 @@
+# Common makefile for GHDL synthesis
+
+PLUGIN_LIB = ../../library
+
+ifneq ($(VERILOG_FILES),)
+MAYBE_READ_VERILOG = read_verilog $(VERILOG_FILES);
+endif
+
+# agnostic synthesis
+%.json: $(VHDL_SYN_FILES)
+	$(YOSYS) -m $(GHDLSYNTH) -p \
+		"ghdl $(GHDL_FLAGS) $(GHDL_GENERICS) $^ -e $(TOPLEVEL); \
+		$(MAYBE_READ_VERILOG) \
+		synth_$(PLATFORM) \
+		-top $(TOPLEVEL)$(TOPLEVEL_PARAMETER) -json $@" 2>&1
+
+# ECP pouting
+%.config: %.json
+	$(NEXTPNR) --json $< --lpf $(LPF_DEF) \
+		--textcfg $@ $(NEXTPNR_FLAGS) --package $(PACKAGE)
+
+# ECP packing
+%.svf: %.config
+	$(ECPPACK) --svf $*.svf $< $@
+
+# ICE routing
+%.asc: %.json
+	$(NEXTPNR) --$(DEVICE) --json $< \
+	--package $(PACKAGE) --pcf $(PCF_DEF) \
+	--asc $@ $(NEXTPNR_FLAGS)
+
+# ICE packing
+%.bin: %.asc
+	$(ICEPACK) $< $@
+
+ifeq ($(PLATFORM), ecp5)
+
+# ECP5 bitstream target
+bitstream: $(PROJ).svf
+
+# ECP programming
+prog: $(PROJ).svf
+	$(OPENOCD) -f $(OPENOCD_JTAG_CONFIG) -f $(OPENOCD_DEVICE_CONFIG) \
+		-c "transport select jtag; init; svf $<; exit"
+
+else ifeq ($(PLATFORM), ice40)
+
+# ICE bitstream target
+bitstream: report $(PROJ).bin
+
+# ICE programming
+prog: $(PROJ).bin
+	$(ICEPROG) $<
+
+# ICE timing report
+report: $(PROJ).asc
+	$(ICETIME) -d $(DEVICE) -mtr [email protected] $<
+endif
+
+clean:
+	rm -rf ./*.json ./*.asc ./*.bin ./report.txt ./*.work-obj93.cf \
+		./*.work-obj08.cf ./*.config ./*.svf $(LOCAL_LIB)
+
+all: bitstream
+
+.PRECIOUS: %.json %.config
+.PHONY: bitstream report clean all
+.DEFAULT: all

examples/ecp5_versa/Makefile

@@ -1,50 +1,44 @@
-LIB = ../../library
 
-GHDL ?= ghdl
+USE_DOCKER?=
 
-GHDL_FLAGS = -Plib
+PROJ ?= versa_ecp5_top
+TOPLEVEL ?= versa_ecp5_top
 
-CLK_FREQ = 25000000
+VHDL_SYN_FILES = versa_ecp5_top.vhdl pll_mac.vhd
+VHDL_SYN_FILES += soc_iomap_pkg.vhdl
+VHDL_SYN_FILES += uart.vhdl uart_tx.vhdl uart_rx.vhdl fifobuf.vhdl
 
-GHDL_GENERICS=-gCLK_FREQUENCY=$(CLK_FREQ)
-LPF = versa_ecp5.lpf
+LPF_DEF = versa_ecp5.lpf
 PACKAGE = CABGA381
+
 NEXTPNR_FLAGS = --um5g-45k --freq 100
 NEXTPNR_FLAGS += --lpf-allow-unconstrained
+
 OPENOCD_JTAG_CONFIG = ../../openocd/ecp5-versa.cfg
 OPENOCD_DEVICE_CONFIG = ../../openocd/LFE5UM5G-45F.cfg
 
-WORKDIR = work
-# Files to synthesize:
-VHDL_SYN_FILES = versa_ecp5_top.vhdl pll_mac.vhd
-VHDL_SYN_FILES += soc_iomap_pkg.vhdl
-VHDL_SYN_FILES += uart.vhdl uart_tx.vhdl uart_rx.vhdl fifobuf.vhdl
+VERILOG_FILES = $(PLUGIN_LIB)/wrapper/primitives.v
+VERILOG_FILES += $(PLUGIN_LIB)/wrapper/bram.v
 
-TOPLEVEL = versa_ecp5_top
-TOPLEVEL_PARAMETER =
+GHDL_FLAGS = -Plib
+PLATFORM = ecp5
 
-VERILOG_FILES = $(LIB)/wrapper/primitives.v
-VERILOG_FILES += $(LIB)/wrapper/bram.v
+LOCAL_LIB=./lib
 
-SVFFILE = versa_ecp5_top.svf
-DEPENDENCIES = lib/ecp5um-std93.cf
+include ../tools.mk
+include ../common.mk
 
-all: $(SVFFILE)
+# this project requires verilog wrappers to enable vendor black-box components
+# these are defined in project-root/library
+# the following targets compile these wrappers into a project specific directory
 
-include ../docker.mk
-include ../ghdlsynth.mk
+# NOTE: if you're using VHDL-2008 you MUST rename the file suffix to "-std08.cf"
 
 lib:
 	mkdir $@
 
-lib/ecp5um-std93.cf: $(LIB)/ecp5u/components.vhdl | lib
+$(LOCAL_LIB)/ecp5um-std93.cf: $(PLUGIN_LIB)/ecp5u/components.vhdl | lib
 	$(GHDL) -i --workdir=$(dir $@) --work=ecp5um $<
 
+DEPENDENCIES = $(LOCAL_LIB)/ecp5um-std93.cf
 pll_mac.vhd: $(DEPENDENCIES)
-
-prog: $(SVFFILE)
-	$(OPENOCD) -f $(OPENOCD_JTAG_CONFIG) -f $(OPENOCD_DEVICE_CONFIG) \
-		-c "transport select jtag; init; svf $<; exit"
-
-clean:
-	rm -fr lib work *.json *.svf *.config *-report.txt

examples/ice40hx8k/Makefile

@@ -0,0 +1,20 @@
+
+USE_DOCKER?=
+
+PROJ ?= leds
+TOPLEVEL ?= leds
+
+VHDL_SYN_FILES = leds.vhdl
+
+# choose one implementation
+VHDL_SYN_FILES += spin1.vhdl
+# VHDL_SYN_FILES += spin2.vhdl
+
+PCF_DEF = pinmap.pcf
+PACKAGE = ct256
+
+PLATFORM = ice40
+DEVICE = hx8k
+
+include ../tools.mk
+include ../common.mk

examples/icestick/leds/Makefile

@@ -1,4 +1,8 @@
-PROJ = blink
+
+USE_DOCKER?=
+
+# choose one project to build
+PROJ ?= blink
 #PROJ = fixed1
 #PROJ = multi1
 #PROJ = multi2
@@ -9,26 +13,15 @@ PROJ = blink
 #PROJ = spin1
 #PROJ = spin2
 
-PIN_DEF = leds.pcf
-DEVICE = hx1k
-
-all: $(PROJ).bin
+TOPLEVEL ?= leds
 
-%.json: leds.vhdl %.vhdl
-	yosys -m ghdl -p 'ghdl $^ -e leds; synth_ice40 -json $@'
+VHDL_SYN_FILES = leds.vhdl ./*.vhdl
 
-%.asc: %.json
-	nextpnr-ice40 --package $(DEVICE) --pcf $(PIN_DEF) --json $< --asc $@
+PCF_DEF = leds.pcf
+PACKAGE = tq144
 
-%.bin: %.asc
-	icepack $< $@
-
-prog: $(PROJ).bin
-	iceprog $<
-
-clean:
-	rm -f $(PROJ).json $(PROJ).asc $(PROJ).bin
-
-.SECONDARY:
+PLATFORM = ice40
+DEVICE = hx1k
 
-.PHONY: all prog clean
+include ../../tools.mk
+include ../../common.mk

examples/icestick/uart/Makefile

@@ -0,0 +1,18 @@
+
+USE_DOCKER?=
+
+PROJ ?= uart
+TOPLEVEL ?= uart_top
+
+VHDL_SYN_FILES = ./hdl/*.vhd
+
+PCF_DEF = ./syn/constraints/uart.pcf
+PACKAGE = tq144
+
+PLATFORM = ice40
+DEVICE = hx1k
+
+NEXTPNR_FLAGS=--pcf-allow-unconstrained
+
+include ../../tools.mk
+include ../../common.mk

examples/icestick/uart/README.md

@@ -7,5 +7,5 @@ Configuration: 115200 8N1
 - syn: Contains the scripts and constraints for synthesis.
 
 ## Usage
-- `cd syn && ./synth.sh`
-- configure and open putty or another serial terminal and type something
+- `make all prog`
+- configure and open putty or another serial terminal and type something

examples/icezum/Makefile

@@ -1,23 +1,16 @@
-PROJ ?= blink
-PIN_DEF = icezum.pcf
-DEVICE = hx1k
-
-all: report bin
 
-json: $(PROJ).vhdl
-	yosys -m ghdl -p 'ghdl $(PROJ).vhdl -e $(PROJ); synth_ice40 -json $@'
+USE_DOCKER?=
 
-asc: $(PIN_DEF) json
-	nextpnr-ice40 --$(DEVICE) --json json --pcf $(PIN_DEF) --asc $@
+PROJ ?= blink
+TOPLEVEL ?= blink
 
-bin: asc
-	icepack $< $@
+VHDL_SYN_FILES = ./*.vhdl
 
-report: asc
-	icetime -d $(DEVICE) -mtr $@ $<
+PCF_DEF = icezum.pcf
+PACKAGE = tq144
 
-clean:
-	rm -f json asc bin report work-obj93.cf
+PLATFORM = ice40
+DEVICE = hx1k
 
-.SECONDARY:
-.PHONY: all prog clean
+include ../tools.mk
+include ../common.mk