Learning VHDL with GHDL

[eine]

The documentation of GHDL contains a brief Quick Start Guide to introduce GHDL's CLI interface to users, but it does not contain an introduction to VHDL. There are many examples scattered in the repos:

• The testsuite of the main repo contains hundreds of reproducible examples. These are mostly undocumented, but most of them are small and are related to some public discussion.
• The examples and testsuite of ghdl-yosys-plugin contain tens of examples too. These use the plugin along with open source P&R and programming tools, such as nextpnr, icestorm, openocd, etc.
• Documented co-simulation examples about VPI and VHPIDIRECT are available in ghdl.github.io/ghdl-cosim.

However, since many users learn about both VHDL, GHDL and sometimes digital design at the same time, previous resources might be too harsh. The purpose of this document is to gather references to open/free (as in free beer) tutorials, guides, books, blog post, repositories, etc. which use VHDL (and optionally GHDL).

See also Talks, presentations and other communications about GHDL and Target projects for synthesis.

• IP databases and awesome lists:
  • opencores.org
  • librecores.org
  • hdl/awesome:
    • VHDL/awesome-vhdl
    • drom/awesome-hdl
    • fukatani/awesome-hdl
    • Vitorian/awesome-fpga
• VHDL Tutorial by Peter Ashenden (see Learning VHDL with GHDL #1291 (comment)).
• Book: VHDL Kompakt (German)
• Book: Free Range VHDL
• Book: datacipy.cz (Czech)
  • PDF, EPUB, MOBI
  • Materiály ke studiu a další
  • datacipy/VHDL
• nandland.com
  • VHDL Tutorials and Examples
• lauri.võsandi.com
  • Using GHDL to simulate VHDL
  • #GHDL
  • #VHDL
• dossmatik.de
  • dossmatik.de/vhdl
  • PDF: How to simulate an UART VHDL code with ghdl
  • PDF: GHDL simulate VHDL code with included Xilinx Library Unisim
• VHDL-2008: Why It Matters
• fpga4fun.com
• vhdlguide.com
  • Files – theory & examples
• vhdlwhiz.com: Basic VHDL Tutorials
• seas.upenn.edu/~ese171: VHDL Tutorial
• fpgatutorial.com/vhdl
• Rodrigo A. Melo:
  • Fundamentals of VHDL (Hardware Description Language) (slides, video)
  • FOSS (Free Open Source Software) for FPGA (slides, video)
  • VHDL for FPGA: Synthesis
  • VHDL for FPGA: Simulation
• Hipólito Guzmán:
  • sepagierm/sepa-practicas
  • edcmit/edc-practicas
• dev.to/targeted
  • Learning FPGA programming, key points for a software developer (part 1, the time)
  • Learning FPGA programming, key points for a software developer (part 2, registered logic)
  • Learning FPGA programming, key points for a software developer (part 3, code patterns and inferred behavior)
• bor.gs/vhdl: Apostila Aleatória de VHDL e GHDL
• TPU/RPU Series
  • Domipheus/TPU
  • Domipheus/RPU
  • Domipheus/ArtyS7-RPU-SoC
• Functional and formal verification
  • zipcpu.com: An Introduction to Formal Methods
  • tmeissner/psl_with_ghdl: examples of using PSL for functional and formal verification of VHDL with GHDL (and SymbiYosys)
  • tmeissner/vhdl_verification: examples and design pattern for VHDL verification
  • tmeissner/formal_hw_verification: trying to verify Verilog/VHDL designs with formal methods and tools
• Co-simulation with foreign languages/tools
  • ghdl.github.io/ghdl-cosim
    • Previous work and future ideas
    • List of open PRs
  • Asynchronous remote simulation using GHDL
  • Yann Guidon / YGDES:
    • VHDL library for gate-level verification
    • micro HTTP server in C
  • Virtual development boards:
    • gitlab.ensta-bretagne.fr/bollenth/ghdl-vpi-virtual-board
    • dbhi/vboard
• Code coverage with gcov
  • Evaluating VHDL Code Coverage Using GHDL and gcov
    • github.com/devsaurus/devsaurus.github.io/tree/master/ghdl_gco
  • Measuring code coverage with GHDL
• GHDL and OpenLane
  • britovski/adder (translation of staydh/adder)
  • antonblanchard/microwatt-caravel

Moreover, the following repositories (in case insensitive alphabetical order) might be useful for searching solutions to common designs/problems:

• alvieboy/ZPUino-HDL
• antonblanchard/microwatt
• benreynwar/htfft
• brimdavis/fpga_stuff
• brimdavis/yard-1
  • https://github.com/brimdavis/yard-1/tree/master/hdl/cores/m_uart
  • https://github.com/brimdavis/yard-1/tree/master/hdl/common/debounce
  • https://groups.io/g/fpga-cpu/message/660
  • https://github.com/brimdavis/yard-1/tree/master/verify
• daveshah1/CSI2Rx
• emard/ulx3s-misc
• https://github.com/fabioperez/space-invaders-vhdl
• hdl4fpga/hdl4fpga
• howerj/forth-cpu
• kevinpt/vhdl-extras
• kost/ulx3s-ghdl-examples
• marph91/icestick-remote
• marph91/icestick-uart
• marph91/pico-png
• marph91/pocket-cnn
• marph91/yaaes
• mbrobbel/capi-streaming-framework
• MiSTer-devel (?VHDL)
• MJoergen/nexys4ddr
• nkyparissas/Cellular_Automata_FPGA
• oetr/FPGA-I2C-Minion
• OSVVM/OSVVM
• Paebbels/JSON-for-VHDL
• Paebbels/PicoBlaze-Examples
• Paebbels/PicoBlaze-Library
• skordal/potato
• stnolting/neo430
• suoto/fpga_cores
• tmeissner/cryptocores
• tmeissner/libvhdl
• VLSI-EDA/PoC
• VUnit/vunit
• XarkLabs/BenEaterVHDL
• xesscorp/VHDL_Lib
• xupgit/VHDL
• yol/ethernet_mac

[Xiretza]

@Domipheus' VHDL CPU series comes to mind; it started out as a custom ISA CPU called TPU and was later spun off into a RISC-V CPU called RPU, complete with an Arty-S7 based SoC. The source repos haven't been updated with the blog in a while unfortunately, but they still contain a lot of great reference designs.

It's based entirely on Vivado, but at least the CPU should be fairly easy to port to ghdl if it doesn't work OOTB anyway.

[tgingold]

Should the content of this issue be moved on the wiki ?

[eine]

@tgingold, on the one hand, there is no "discussion" feature in the wiki. Hence, I thought that it would be good to have an issue for that purpose, regardless of the main message being later moved elsewhere. On the other hand, if we create ghdl/ghdl-examples, this can be the first README.

@Xiretza, thanks for the references. I added them above.

[tgingold]

Sure. So we can either: * create ghdl/ghdl-examples (or should it be ghdl/ghdl-tutorial ?) * or stay with a wiki page. Is it possible to submit a PR for a wiki page ? I don't think so, so having a list in a file would be simpler for updates. Any opinion ?

[eine]

Is it possible to submit a PR for a wiki page ? I don't think so, so having a list in a file would be simpler for updates.

The wiki is a git repo: https://github.com/ghdl/ghdl.wiki

However, there is no GUI to handle PRs. We would need to create a separate repo and keep it in sync with the wiki here. Anyway, I think that the wiki is currently open for anyone to edit, not just for maintainers/contributors.

create ghdl/ghdl-examples (or should it be ghdl/ghdl-tutorial ?)

I think it should be ghdl-examples, because I'd expect it to contain different types of resources:

• VHDL tutorials
• Specific guides about e.g. how to read binary files or code coverage
• PSL examples would be in-between a guide and a tutorial
• Makefiles, build script and assets for multiple P&R tools (nextpnr, Vivado, Quartus...)

Some examples might be elaborated as tutorials, but many others might be contributed as code sources only. Overall, I'd expect to put in ghdl-examples all the MWEs that are not just tests for ghdl or ghdl-yosys-plugin. Nonetheless, ghdl or ghdl-yosys-plugin can use ghdl-examples as part of their test suites.

[tgingold]

Ok, so I will create ghdl-examples.

Overall, I'd expect to put in ghdl-examples all the MWEs that are not just tests for ghdl or ghdl-yosys-plugin. Nonetheless, ghdl or ghdl-yosys-plugin can use ghdl-examples as part of their test suites.

We must be careful here. It would be nice if the examples are easily testable and tested, but it must not be a testsuite.

[brimdavis]

@eine I have some examples with simple self-contained testbenches on github that might be of use for this.

Combinatorial bit counting and testbench with simple makefile (mcode) flow:
https://github.com/brimdavis/fpga_stuff/tree/master/bit_count

The following pieces of my homebrew RISC processor repo were written long ago for a Windows box (originally VHDL Simili 1.5, later GHDL) and use a simple .bat file flow for an mcode simulator.

UART with self-checking testbench:
https://github.com/brimdavis/yard-1/tree/master/hdl/cores/m_uart

Switch debouncer:
https://github.com/brimdavis/yard-1/tree/master/hdl/common/debounce

-Brian

p.s. probably off-topic for 'starter' examples, but the YARD-1 processor instruction verification tests use an simple yet effective technique in which small assembly test programs including 'verify' directives are simulated on the processor and post-processed to implement simulation time assertions regarding processor state, as described here back in 2001:
https://groups.io/g/fpga-cpu/message/660
I'd probably implement the verification testbench differently now than 20 years ago, but it still gets the job done...
https://github.com/brimdavis/yard-1/tree/master/verify

[eine]

@brimdavis, nice to meet you and thanks a lot! I added your references to the list above. When repo ghdl-examples is created, I might further copy your previous message almost as is. I cannot learn each resource to write an accurate description myself, but I'd like to briefly describe the resources whose authors do step by. Precisely, your comments about some of the resources being written 20 years ago are very relevant, because they allow users to understand the context and which language features were available at that time.

Furthermore, the purpose is to gather resources for learning VHDL, which can be optionally and preferredly used with GHDL. However, neither do all resources need to be starters nor do all of them need to work with GHDL out of the box. With VHDL and GHDL one can never stop learning, so examples about 'intermediate' and 'advanced' features are much welcome too. Precisely, it is relatively easy to simulate any design (small or huge) with GHDL. However, we are lacking friendly resources related to other features: advanced verification methodologies/frameworks, formal verification, mixed-language synthesis, mixed-language simulation, mixed-signal simulation, code coverage, etc. Hence, your verification solution is very interesting for users to evaluate how to and how not to do it in 2020.

[kost]

I have lot of basic GHDL examples already available here:

https://github.com/kost/ulx3s-ghdl-examples

Feel free to take them. If there's any way I can make it more available for your needs - do let me know!

[eine]

@kost, thanks! I added it to the list above.

Feel free to take them. If there's any way I can make it more available for your needs - do let me know!

IMHO, it would be useful to have some minimal CI workflow that executes the examples. That allows new users to see what output they should expect when they execute them locally. There are multiple examples about how to setup GHDL in CI, with or without docker containers. Please, let us know if you want to discuss implementation alternatives.

[hackfin]

I forked some GHDL specifics off a Python/Jupyter notebook based playground (with Python being the general HDL), more or less for documentation purposes:

https://github.com/hackfin/hdlplayground

It's runnable as virtual machine in the pretty awesome mybinder.org service (hopefully for a while).
There's some MyHDL based Cosimulation framework in there to help with post-synth(map) simulation through yosys and test the GHDL yosys plugin.

From the current research it appears that the Binder approach of running HDL/synthesis from the browser is not too popular, but I think beginners might pick up on it, as one reads how-to instructions and executable example code 'inline (interactive step by step). So it can be used as a linear IDE. Plus there's kinda built-in testing framework to ensure that the examples reproduce.

However it's far from complete and there's not much activity expected to happen on this end, but plans are to move 'stable' examples into the notebooks for the future for better documentation/presentation.

[eine]

I added a couple of references to hackaday projects by Yann Guidon in the list above. Nonetheless, at ygdes.com users will find many VHDL related projects: CPUs (F-CPU, YASEP, YGREC), co-simulation extensions (http://ygdes.com/GHDL)...

[eine]

I added references to some blogs posts about "Learning FPGA programming, key points for a software developer":

• dev.to/targeted
  • Learning FPGA programming, key points for a software developer (part 1, the time)
  • Learning FPGA programming, key points for a software developer (part 2, registered logic)
  • Learning FPGA programming, key points for a software developer (part 3, code patterns and inferred behavior)

@targeted, how did you draw all those nice diagrams?

[targeted]

@eine
Thank you !
The tool I used is https://excalidraw.com/

[diogratia]

Peter Ashenden wrote an 82 page tutorial on VHDL to go with an Elsevier book on computer design in 2004 also found as a companion material for another book.

The VHDL Tutorial (PDF) is also found on the Internet Archive where it should remain available even should the book(s) become unavailable.

[eine]

I added the folowing references:

• Book: datacipy.cz (Czech)
  • Materiály ke studiu a další
  • datacipy/VHDL

I don't know a word of czech, so I mostly guessed that the book itself is not open/public (but it is rather cheap, ~15€), however, there are dozens of references for learning VHDL and a bunch of open source IP cores. I'd be glad if anyone could confirm.

[targeted]

@eine

I don't know a word of czech, so I mostly guessed that the book itself is not open/public (but it is rather cheap, ~15€), however, there are dozens of references for learning VHDL and a bunch of open source IP cores. I'd be glad if anyone could confirm.

From the pure similarity between Czech and Russian, this here https://datacipy.cz/
"E-book je dostupný pod volnou licencí CC jako PDF • EPUB • MOBI"
says that the e-book is available for download under free CC license.

Also in the book itself:
"Toto autorské dílo podléhá licenci Creative Commons BY-ND 3.0 CZ"

And from https://github.com/datacipy/VHDL
"Vše pod otevřenými licencemi MIT, pokud není uvedeno jinak (např. CC nebo GPL). "
Says that all the utilities that accompany the book are available under open MIT licenses, unless otherwise noted.

[eine]

@targeted, thanks so much for explaining. I added the links to PDF, EPUB and MOBI above. I'm glad I misunderstood the openness of the book 😅

@maly, congratulations on that very nice work!

[maly]

@eine Thank you a lot. And I, as the author, have to say @targeted is right: The whole book content is under the CC-BY-ND license. The code examples I wrote (published at https://github.com/datacipy/VHDL) are under the MIT license. Some libraries or entities are from other authors - like T80 - and they're licensed under their own licenses (mostly MIT / BSD / GPL / LGPL).

Let me say it is my third book (an "electronics trilogy"). The first one was about the gates, transistors, volts, sensors, etc. The second one was about the "computer building" (illustrated on the 8bit single board computers, based on CPUs 8085, 6502, and 6809) and "programming in assembler". And the whole trilogy is under the CC-BY-ND, all constructions and software are under MIT or CERN OHL...

Thank you, guys, for awesome work with the GHDL! It is a great tool, which allows me not to focus only on the Quartus IDE and embedded Multisim, but on the VHDL code and its testing itself.

[eine]

I added @rodrigomelo9's "Fundamentals of VHDL (Hardware Description Language)" (slides, video) at the Joint ICTP-IAEA School on FPGA-based SoC and its Applications for Nuclear and Related Instrumentation. Find other talks: http://indico.ictp.it/event/9443/other-view?view=ictptimetable.

[rodrigomelo9]

Thanks @eine. Today, I will give the second part, related to simulation and of course, GHDL :-D. Slides are already available.

Regards

[JC-LL]

Maybe you could add this marvelous tool, based on GHDL in the list.

https://gitlab.ensta-bretagne.fr/bollenth/ghdl-vpi-virtual-board

It allows to quickly play with a GHDL-based virtual board : LEDs, switches, buttons, seven segments.

Regards

[umarcor]

@JC-LL, such an interesting reference! Congratulations to Théotime for that nice work! I added it to https://ghdl.github.io/ghdl-cosim/vpi/examples/other.html and https://github.com/dbhi/vboard.

[umarcor]

Added a ref to xupgit/VHDL (Open Hardware 2015: TU Crete; Game of Life), authored by @nkyparissas. Also to nkyparissas/Cellular_Automata_FPGA, by the same author.

[umarcor]

Added a ref to a tutorial about GHDL and OpenLane based on the adder from the Quick Start Guide: britovski/adder (translation of staydh/adder).

/cc @britovski @staydh