Merge pull request #338 from umarcor/mixed-hdl

Add Mixed HDL Blink example

.github/tests.sh

@@ -6,6 +6,7 @@ TOOLCHAIN_PATH="${TOOLCHAIN_PATH:-$PWD/$(find fomu-toolchain-* -type d -maxdepth
 echo "TOOLCHAIN_PATH: $TOOLCHAIN_PATH"
 
 export PATH=$TOOLCHAIN_PATH/bin:$PATH
+export GHDL_PREFIX=$TOOLCHAIN_PATH/lib/ghdl
 
 echo '::group::RISC-V C Example'
 (
@@ -52,6 +53,26 @@ echo '::group::Verilog Blink (expanded) example for PVT board'
 )
 echo '::endgroup::'
 
+echo '::group::VHDL Blink example'
+(
+
+	set -x
+	cd vhdl/blink
+	make FOMU_REV=pvt
+	file blink.dfu
+)
+echo '::endgroup::'
+
+echo '::group::Mixed HDL Blink example'
+(
+
+	set -x
+	cd mixed-hdl/blink
+	make FOMU_REV=pvt
+	file blink.dfu
+)
+echo '::endgroup::'
+
 echo '::group::LiteX example for Hacker'
 (
 	set -x

README.md

@@ -42,6 +42,10 @@ The contents of this workshop is published at [workshop.fomu.im](https://worksho
   CPU section of the workshop](https://workshop.fomu.im/en/latest/riscv.html).
 - [verilog](./verilog) - The files required for the [Verilog on Fomu section
   of the workshop](https://workshop.fomu.im/en/latest/verilog.html).
+- [vhdl](./vhdl) - The files required for the [VHDL on Fomu section
+  of the workshop](https://workshop.fomu.im/en/latest/vhdl.html).
+- [mixed-hdl](./mixed-hdl) - The files required for the [Mixed HDL on Fomu section
+  of the workshop](https://workshop.fomu.im/en/latest/mixedhdl.html).
 
 # Development
 

board.mk

@@ -0,0 +1,21 @@
+# Different Fomu hardware revisions are wired differently and thus
+# require different configurations for yosys and nextpnr.
+# Configuration is performed by setting the environment variable FOMU_REV accordingly.
+ifeq ($(FOMU_REV),evt1)
+YOSYSFLAGS?= -D EVT=1
+PNRFLAGS  ?= --up5k --package sg48 --pcf ../../pcf/fomu-evt2.pcf
+else ifeq ($(FOMU_REV),evt2)
+YOSYSFLAGS?= -D EVT=1
+PNRFLAGS  ?= --up5k --package sg48 --pcf ../../pcf/fomu-evt2.pcf
+else ifeq ($(FOMU_REV),evt3)
+YOSYSFLAGS?= -D EVT=1
+PNRFLAGS  ?= --up5k --package sg48 --pcf ../../pcf/fomu-evt3.pcf
+else ifeq ($(FOMU_REV),hacker)
+YOSYSFLAGS?= -D HACKER=1
+PNRFLAGS  ?= --up5k --package uwg30 --pcf ../../pcf/fomu-hacker.pcf
+else ifeq ($(FOMU_REV),pvt)
+YOSYSFLAGS?= -D PVT=1
+PNRFLAGS  ?= --up5k --package uwg30 --pcf ../../pcf/fomu-pvt.pcf
+else
+$(error Unrecognized FOMU_REV value. must be "evt1", "evt2", "evt3", "pvt", or "hacker")
+endif

docs/background.rst

@@ -58,10 +58,9 @@ Turning code into gates
 
 Writing lookup tables is hard, so people have come up with abstract
 Hardware Description Languages (HDLs) we can use to describe them. The
-two most common languages are Verilog and VHDL. In the open source
-world, Verilog is more common. However, a modern trend is to embed an
-HDL inside an existing programming language, such as how Migen is
-embedded in Python, or SpinalHDL is embedded in Scala.
+two most common languages are Verilog and VHDL. However, a modern trend
+is to embed an HDL inside an existing programming language, such as how
+Migen is embedded in Python, or SpinalHDL is embedded in Scala.
 
 Here is an example of a Verilog module:
 

docs/hdl.rst

@@ -1,11 +1,47 @@
+.. _HDLs:
+
 Hardware Description Languages
 ------------------------------
 
 The two most common **H**\ ardware **D**\ escription **L**\ anguages are
-Verilog and VHDL (the toolchain we are using only supports Verilog).
+Verilog and VHDL.
+
+.. NOTE:: The pre-built toolchain we are releasing supports Verilog only.
+  However, `GHDL <https://github.com/ghdl>`_ can be usable as a VHDL frontend
+  for Yosys. See `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_.
+
+When writing HDL, a tool called ``yosys`` is used to convert the
+human readable verilog into a netlist representation, this is called
+*synthesis*. Once we have the netlist representation, a tool called
+``nextpnr`` performs an operation called *place and route* (P&R) which
+makes it something that will actually run on the FPGA. This is all
+done for you using the ``Makefiles`` in the subdirectories of ``verilog``
+or ``vhdl``.
+
+A big feature of ``nextpnr`` over its predecessor, is the fact that
+it is timing-driven. This means that a design will be generated with
+a given clock domain guaranteed to perform fast enough.
+
+When the ``make`` command runs ``nextpnr-ice40`` you will see something
+similar included in the output:
+
+::
+
+   Info: Max frequency for clock 'clk': 73.26 MHz (PASS at 12.00 MHz)
+
+This output example shows that we could run ``clk`` at up to 73.26
+MHz and it would still be stable (even though we only requested 12.00
+MHz). Note that there is some variation between designs depending on
+how the placer and router decided to lay things out, so your exact
+frequency numbers might be different from the ones shown in the code
+blocks of this documentation.
+
+Languages and generators
+========================
 
 .. toctree::
 
    verilog
+   vhdl
+   mixed-hdl
    migen
-   spinal

docs/index.rst

@@ -22,7 +22,7 @@ Table of Contents
 .. toctree::
    :maxdepth: 5
 
-   requirements
+   requirements/index
    background
    python
    riscv

docs/mixed-hdl.rst

@@ -0,0 +1,80 @@
+.. _HDLs:mixed:
+
+Mixed HDL on Fomu
+-----------------
+
+.. HINT:: It is strongly suggested to get familiar with :ref:`HDLs:Verilog` and :ref:`HDLs:VHDL`
+  examples before tinkering with these mixed language use cases.
+
+
+“Hello world!” - Blink a LED
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The canonical “Hello, world!” of hardware is to blink a LED. The
+directory ``mixedhdl/blink`` contains a VHDL + Verilog example of a blink
+project. This takes the 48 MHz clock and divides it down by a large
+number so you get an on/off pattern.
+
+Enter the ``mixedhdl/blink`` directory and build the demo by using ``make``:
+
+.. session:: shell-session
+
+   $ make FOMU_REV=$FOMU_REV
+   ...
+   Info: Max frequency for clock 'clk_generator.clko': 73.26 MHz (PASS at 12.00 MHz)
+
+   Info: Max delay posedge clk_generator.clko -> <async>: 3.15 ns
+
+   Info: Slack histogram:
+   Info:  legend: * represents 1 endpoint(s)
+   Info:          + represents [1,1) endpoint(s)
+   Info: [ 69683,  70208) |**
+   Info: [ 70208,  70733) |
+   Info: [ 70733,  71258) |**
+   Info: [ 71258,  71783) |**
+   Info: [ 71783,  72308) |**
+   Info: [ 72308,  72833) |**
+   Info: [ 72833,  73358) |
+   Info: [ 73358,  73883) |**
+   Info: [ 73883,  74408) |*
+   Info: [ 74408,  74933) |**
+   Info: [ 74933,  75458) |**
+   Info: [ 75458,  75983) |*
+   Info: [ 75983,  76508) |*
+   Info: [ 76508,  77033) |**
+   Info: [ 77033,  77558) |**
+   Info: [ 77558,  78083) |*
+   Info: [ 78083,  78608) |
+   Info: [ 78608,  79133) |*************************
+   Info: [ 79133,  79658) |**
+   Info: [ 79658,  80183) |***
+   22 warnings, 0 errors
+   icepack blink.asc blink.bit
+   cp blink.bit blink.dfu
+   dfu-suffix -v 1209 -p 70b1 -a blink.dfu
+   dfu-suffix (dfu-util) 0.9
+
+   Copyright 2011-2012 Stefan Schmidt, 2013-2014 Tormod Volden
+   This program is Free Software and has ABSOLUTELY NO WARRANTY
+   Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+   Suffix successfully added to file
+   $
+
+You can then load ``blink.dfu`` onto Fomu by using ``make load`` or the same
+``dfu-util -D`` command we’ve been using so far. You should see a blinking pattern of
+varying color on your Fomu, indicating your bitstream was successfully loaded.
+
+If you take a closer look at the sources in ``mixedhdl/blink``, you will find that
+modules/components ``blink`` and ``clkgen`` are written both in VHDL and Verilog.
+The Makefile uses ``blink.vhd`` and ``clkgen.v`` by default. However, any of the
+following cases produce the same result:
+
+- ``blink.vhd`` + ``clkgen.v``
+- ``blink.v`` + ``clkgen.vhdl``
+- ``blink.vhd`` + ``clkgen.vhdl``
+- ``blink.v`` + ``clkgen.v``
+
+You can modify variables `VHDL_SYN_FILES` and ``VERILOG_SYN_FILES`` in the Makefile
+for trying other combinations. For a better understanding, it is suggested to compare
+these modules with the single file solutions in :ref:`HDLs:Verilog` and :ref:`HDLs:VHDL`.