Define categories and the included tools

[rodrigomelo9]

Hello @mithro and @eine.

I think that you both know very well the FOSS ecosystem, but I know that you have predilections :P (Verilog and VHDL, of course). Would you check the following categorized list and provide me opinions, suggestions, corrections, missing names, thoughts, advice, and so?

Simulation tools
* GHDL
* iVerilog
* Verilator
* GTKwave

Implementation tools
* GHDL
* ghdl-yosys-plugin
* IceStorm
* SimbiFlow
* Yosys

Verification frameworks
* cocotb
* OSVVM
* SymbiYosys
* UVVM
* Vunit

Project managers (or project management?)
* Apio
* Edalize
* HDLmake
* PyFPGA
* tsfpga

Package managers (or package management?)
* FuseSoC
* LiteX
* PoC

Development languages
* Chisel
* MyHDL
* nMigen
* SpinalHDL

Development Environments
* Apio-IDE
* Icestudio
* TerosHDL

Linters
* GHDL
* Verilator

Note: I am not sure about Linters, because for example the GHDL -s option is for syntax check, but I added this section thinking in that could be a lot of linter around.

My aim is to provide a common place where to start with FOSS for digital hardware design (I am an FPGA guy but is ok to include ASIC, let me know @mitro where to put the open PDK!).

Why? I have been working with FPGAs, using open-source tools, since 2006. I started to surf the available projects repositories almost a year ago and it seems difficult to be up-to-date and to know all the alternatives. I want to provide an easy starting point for newcomers. I was thinking about a presentation with these topics since the begin of the pandemic, but I think that this could be more useful. I have been conducting a survey on FPGA in Argentina (where I live), asking also about the employed open-source tools, and there were really few results. I want to change it. Moreover, precisely today, a new Argentinan iCE40 board (https://github.com/ciaa/Hardware/tree/master/PCB/EDU-FPGA) will be available to be acquired, so I think that is a good moment to start the FOSS for FPGAs promotion here.

Thanks for you time and please, let me know what do you think. Regars,
Rodrigo

PS: any other person is also welcome.

[mithro]

Maybe go and look at https://github.com/drom/awesome-hdl ?

Simulation tools

• GHDL
• iVerilog

• iVerilog / Icarus Verilog

• Verilator

• GTKwave

This is more a "waveform viewer" than anything specifically related to simulation tools. Similar to things like http://wavedrom.com/.

Implementation tools

• GHDL
• ghdl-yosys-plugin
• IceStorm
• SimbiFlow
• Yosys

It's SymbiFlow not SimbiFlow.

The implementation tools section is very confused. I think you want to think about it in term of "Language Frontend", "Synthesis", "Place and Route" and "Bitstream Generation".

See https://symbiflow.readthedocs.io/en/latest/introduction.html#eda-tooling-ecosystem and http://j.mp/openfpga-diagram

Verification frameworks

• cocotb
• OSVVM
• SymbiYosys
• UVVM
• Vunit

This seems fine.

Project managers (or project management?)

• Apio
• Edalize
• HDLmake
• PyFPGA
• tsfpga

I would call these more "Project / Toolchain managers"

Package managers (or package management?)

• FuseSoC
• LiteX
• PoC

I would call these "SoC generators".

Development languages

• Chisel
• MyHDL
• nMigen
• SpinalHDL

There are many more in this category.

Development Environments

• Apio-IDE
• Icestudio
• TerosHDL

Linters

• GHDL
• Verilator

• Verible - https://github.com/google/verible

[eine]

Hi @rodrigomelo9! Thanks a lot for pinging! Let me drop ideas and refs in no particular order:

@mithro has a few Google Docs documents where he is already doing a map of F(L)OSS EDA.

• Open Source (FOSS) FPGA (EDA) Tooling: Interchange Formats + Toolchain parts
• EDDA - "Conda for EDA tools": Conda based system for FPGA and ASIC Dev
• Python Libraries for EDA Toolchain Interfacing
• Status of SymbiFlow Flows
• SymbiFlow FPGA Tool Performance
• Open ASIC EDA Tooling Random Diagrams
• FPGA Tooling Common Interchange Formats

Several people have contributed to those in the last years. You will find very interesting info the documents and in the comments too. I believe that most (if not all) the tools you mentioned are already listed in those docs.

---

VUnit is strictly not a verification framework. It is a (regression) test management Python framework together with core VHDL and SystemVerilog libraries, and additional VHDL libraries for testing/verification. So, VUnit can be used with it's VHDL libs, with OSVVM, with UVVM, with UVM and/or with any other HDL verification framework. In fact, OSVVM is a submodule of VUnit, some prototypes exist for combining VUnit and cocotb, and users have reported combining VUnit and UVM.

---

• PoC. "To generalize all supported free and commercial vendor tool chains, PoC is shipped with a Python based infrastructure to offer a command line based frontend".
• vhdlref: "a usable language reference for writing VHDL (VHSIC Hardware Description Language) in a way that is concise, direct, and easy to understand for as many people as possible".
• nvc is a simulator for VHDL 2002, written in C.
• duh "is a suite of tools for packaging reusable hardware components and designs", written in JavaScript. See Reusing HW components with DUH flow - Aliaksei Chapyzhenka - ORConf 2019.
• hdl-component-manager: "Manage HDL code as components so they can shared as IP", written in Python.
• SigasiProjectCreator "Python classes that make it easy to generate a Sigasi Project from your own project specifications".
• autofpga: "An FPGA Design Automation routine", written in C++.
• YoWASP: "Unofficial WebAssembly-based packages for Yosys, nextpnr, and more".
• psl_with_ghdl: "A collection of examples of using PSL for functional and formal verification of VHDL designs with GHDL (and Yosys / SymbiYosys)".
• formal_hw_verification: "Tests and examples of using formal verification to check correctness of digital hardware designs".
• JSON-for-VHDL.
• fossi-foundation/wishbone
• Learning VHDL with GHDL
• OpenFPGA: "* the first open-source FPGA IP generator supporting highly-customizable homogeneous FPGA architectures*".
• uvm-python: "a port of SystemVerilog (SV) Universal Verification Methodology (UVM) 1.2 to Python and cocotb".
• uvm.io, a C++ kernel using DPI/VHPI/FLI.
• CXXRTL, a Yosys Simulation Backend.
• dbhi.github.io/qus. "qemu-user-static and docker: Build and execute OCI images for foreign architectures using QEMU’s user-mode emulation".
• eine/symbiflow-containers. See references.
• gtkwave
• sigrok/pulseview
  • Reading waveforms from HDL simulators with PulseView. See references.
• Data type exploration and visualization in arithmetic algorithms/circuits. See vcd_parser.
  • smlgit/fpbinary
• Co-simulación y verificación funcional con VHDL, C/C++ y Python/m. Although focused on co-simulation, I think that you might find these slides to be a good reference.
• spydrnet: "A flexible framework for analyzing and transforming netlists".
• netlistsvg: "draws an SVG schematic from a yosys JSON netlist".

---

Some pieces of TerosHDL are independent Python packages, even though the frontend is written in JavaScript (Atom) or TypeScript (VSCode). See TerosTechnology.

---

Instead of linters, I'd focus on parsers. More precisely, parsers that support semantic analysis, not only tokenization. That is the foundation for any linter, formatter, style checker, LSP... There are some interesting discussions in jeremiah-c-leary/vhdl-style-guide. See the following issues:

• Integration with current VHDL VSCode extensions jeremiah-c-leary/vhdl-style-guide#328
• Add keywords and tokens line attributes jeremiah-c-leary/vhdl-style-guide#312

Note the interactions of Carlos in that repo. That's because vhdl-style-guide is used in TerosHDL.

Note also that rust_hdl and pyVHDLParser are not explicitly abandoned, but are not being developed at the moment (due to lack of motivation and/or time).

Recently, there has been interest in GHDL's Python interface to libghdl. See:

• libghdl documentation ghdl/ghdl#1437
• update python interface test/example ghdl/ghdl#1449
• Provide initial skeleton for libghdl documentation. ghdl/ghdl#1445

Although very unpythonic, py-libghdl is the most complete VHDL parser. However, the only existing application I am aware of is GHDL's language server: https://github.com/ghdl/ghdl/tree/master/python/vhdl_langserver. Find clients at ghdl/ghdl-language-server. See also:

• https://ghdl.github.io/ghdl/internals/Overview.html
• https://ghdl.github.io/ghdl/using/py/libghdl.html
• https://ghdl.github.io/ghdl/gnatdoc/

Currently, GHDL removes comments, so it is not suitable as a formatter.

---

VSCode extensions exist for rust_hdl and for VUnit:

• https://marketplace.visualstudio.com/items?itemName=hbohlin.vhdl-ls
• https://marketplace.visualstudio.com/items?itemName=hbohlin.vunit-test-explorer

---

Overall, I'd suggest to build on top of the following. hdl/awesome can be redesigned from scratch if you wish, since it didn't gather any attention so far. We need to start putting content together, even though it takes some more effort than each creating a new repo.

• vhdl.github.io/news: "a social news website based on issues of a GitHub repository".
• hdl/awesome

You will find that the discussion in this issue will be very similar to the dialogues in gitter.im/vhdl/General during January regarding hdl/awesome.

---

You might want to get in touch with Susana, from susanacanel/proyectos-vhdl.

---

/cc @Paebbels @tmeissner @GlenNicholls @m-kru @jeremiah-c-leary @smgl9 @qarlosalberto @Nic30 @nobodywasishere @marph91 @suoto @ktbarrett @hackfin @Bochlin

EDIT

WRT other languages:

• Surelog.
• Silice

[rodrigomelo9]

@mithro

Maybe go and look at https://github.com/drom/awesome-hdl ?

Yep, thanks, I don't remember it.

This is more a "waveform viewer" than anything specifically related to simulation tools. Similar to things like

Yes, I know, but there are closely related (used together) and I had no other tool in mind such as http://wavedrom.com/.

It's SymbiFlow not SimbiFlow.

Sorry for that, I usually misspelling the name, maybe because I don't know what the Symbi part means :P

The implementation tools section is very confused. I think you want to think about it in term of "Language Frontend", "Synthesis", "Place and Route" and "Bitstream Generation".

I understand your point, but I am trying to create a few categories, to avoid to scare newcomers.

I would call these more "Project / Toolchain managers"
I would call these "SoC generators".

Ok, great!

Development languages
There are many more in this category.

Ok, I will investigate :P

Linters
* Verible - https://github.com/google/verible

Great.

Thanks :-D

[rodrigomelo9]

Hi @rodrigomelo9! Thanks a lot for pinging! Let me drop ideas and refs in no particular order:

wow @eine, a lot of ideas haha, is great. I will investigate them :-D

@mithro has a few Google Docs documents where he is already doing a map of F(L)OSS EDA.

Yep, I was surfing some of its documents. I want to put the focus on development tools, at least to start :P

VUnit is strictly not a verification framework...

I am not a Vunit user, but I understood something similar to what you mentioned. Anyway, I am trying to avoid hundred categories :P do you think that I could be better in another one?

Instead of linters, I'd focus on parsers...

I understand, but, I think that for newcomers, linter could be useful A parser is more related to the development of a tool.

Overall, I'd suggest to build on top of the following. hdl/awesome can be redesigned from scratch if you wish, since it didn't gather any attention so far. We need to start putting content together, even though it takes some more effort than each creating a new repo.

It is ok to me. I am thinking in to provide a readthedocs version (in fact, it will be the main version). What do you think?

I will check the other links :-D

Thanks a lot.

[Nic30]

I am planing to make an enormous table of features for each code generator, compiler, toolchain, SoC generator etc.
The problem is how to maintain such an information. I believe that the authors of other tools will ignore it if I just put it in to some repo of mine.

Is anyone else interested in such overview?

[rodrigomelo9]

Hi @Nic30. I think that is a good idea to join forces. The @eine repository was created to unify distributed info. You are right, a personal repository seems not the best idea. I don't know what about the HDL organization @eine? (it seems almost empty).

I believe that we can join forces, creating a "reduced" categorization (I hope :P) and sharing the info in a commonplace.

[eine]

I am not a Vunit user, but I understood something similar to what you mentioned. Anyway, I am trying to avoid hundred categories :P do you think that I could be better in another one?

@rodrigomelo9, the point is that there is some conflict with the meaning of "verification", as it is differently understood by "verification engineers", and "RTL designers targeting FPGAs". You will find an interesting discussion in the comments of https://www.linkedin.com/pulse/what-can-github-tell-us-hdl-industry-part-3-lars-asplund/. There is also some misunderstanding about "verification frameworks in Python" and "verification framework that use Python". Then, OSVVM is defined as a methodology. As long as those differences are explained, yes, I think it's ok to put all of them in "Testing/verification frameworks/methodologies/tools".

I understand, but, I think that for newcomers, linter could be useful A parser is more related to the development of a tool.

Agree. I just wanted to stress that there is increasing interest on having vhdl-style-guide updated with a more complete parser (which might be py-libghdl), so it is possible to provide a full featured linter for modern VHDL. By the same token, ghdl/ghdl#1449 is an experiment for updating Symbolator's parser, and for supporting generation of symbols for modern VHDL. I believe Symbolator is used in TerosHDL too.

It is ok to me. I am thinking in to provide a readthedocs version (in fact, it will be the main version). What do you think?

Is anyone else interested in such overview?

@rodrigomelo9, @Nic30 you are describing my motivation for proposing hdl/awesome and my frustration because it didn't catch up. Let me explain the critical features, IMHO:

• The foundation of hdl/awesome is to gather the resources in other existing awesome lists. Instead of putting all the content in a single file, the proposal was to create a different markdown file for each tool. This is similar to Rodrigo's approach.
• For each tool, there is some metadata defined in the Markdown frontmatter (repo URL, doc, URL, maintainers, release date, etc. Clicking on each item provides a more detailed view, with some text/description/body (markdown content). The idea of having a more detailed view was taken from https://github.com/ben-marshall/awesome-open-hardware-verification.
• Then, categories/tags allow users to browse the content according to their interests.
• Gohugo is used instead of Sphinx because Hugo is better suited for multiple categorizations, tags, and other semantic filters, RSS feedm etc. Also, markdown is native in Hugo, but an extension in Sphinx.

Then, a few weeks ago, we created vhdl/news. The idea is very similar, but instead of using markdown files and PRs, the content is written in the issues. The first comments/messages of issues with specific labels are read in CI, and the site is generated from them. Unfortunately, GitHub Issues are written in markdown but frontmatters are not supported. That's why a code block is used. See, for instance, VHDL/news#5. Note that reactions and other metadata from the issues are also read and displayed in the site.

I believe that the publishing approach of VHDL/news is more appealing. However, only the OP and maintainers can edit the entries. OTOH, using PRs allows anyone to modify the content, but it requires creating a fork/branch, etc. Hence, we might mix both approaches, if you want. Currently, comments from issues are not displayed in the site, but those could be added to.

@Nic30 if the features were described as fields in the metadata (frontmatter) of tools in certain categories, then the tables may be generated automatically. That would allow one or multiple tables to be automatically updated when new entries are submitted.

@rodrigomelo9, I believe that the description of each tool (according to the layout in this repo), fits exactly in hdl/awesome. However, if you want to write a kind of article or guide instead, you can keep a separated repo (this one), use Sphinx or any other static site generator you want, and just submit an entry/reference to vhdl/news for others to find your work. That'd introduce some fragmentation, but at least a hub (vhdl/news) would pick it.

---

From a technical point of view, please see dbhi.github.io/mdpaper. Summarizing, Sphinx/rst provide better features for cross-referencing multiple files, importing them, etc. However, the syntax is slightly awkward for Markdown users. Since Markdown is the default language in GitHub and GitLab issues, I think it is desirable to use it. I believe we don't really need many cross-references, because it is mostly a display of different projects. Anyway, please let me know what you think.

[eine]

The @eine repository was created to unify distributed info. You are right, a personal repository seems not the best idea. I don't know what about the HDL organization @eine? (it seems almost empty).

The HDL organization was created in January, IIRC. When talking about the "distributed" approach to an awesome list (a file per tool/project), we discussed whether to create vhdl/awesome, to update vhdl/awesome-vhdl, or to create a new repo which was not "constrained" to VHDL. Then, we registered HDL and created hdl/awesome. Similarly to org vhdl, hdl is open to anyone willing to share general purpose open source info related to HDLs. That is, if you want to write a Blog, Book, or some other type of document different from the current hdl/awesome proposal, you are invited to create a new repo in org hdl.

I believe that we can join forces, creating a "reduced" categorization (I hope :P) and sharing the info in a commonplace.

See February 2, 2020 4:10 AM and https://github.com/hdl/awesome/blob/develop/config.yml#L15-L42.

[rodrigomelo9]

@eine I don't want to add more fragmentation. I try to be vendor-agnostic (but I prefer Xilinx), language-agnostic (I have more experience with VHDL, but I have been working more in Verilog last years and using cocotb for testbenches/simulations).

I really like your idea about hdl/awesome, and I think that the @Nic30 idea can be constructed based on the collected and tagged data. However, I believe that it is yet not enough for a newcomer. My idea is:

• A few categories populated with FOSS to work with FPGA/ASIC (not to develop tools to work with).
• I will explain in each category, with an overview, the aim of each tool, with the main URLs (repo, doc).
• I will provide user guides (maybe not for all the tools, but I will try the most popular or at least what I know and contributions). The idea is to have small tutorials or crash-courses. Also, I want to show them performing similar tasks (inside of the same category). For example, probably I will use a counter as an example (VHDL, Verilog, other languages), its tesbenches or how to use the frameworks for that. These kinds of things.
• The main result will be a readthedocs (or similar, I have no idea about Hugo :P and I like readthedocs).

I don't know if github.com/hdl is the best place (mainly because it seems a little abandoned). But if there are plans to be used as a commonplace, I think that could be better than in my own user. Anyway, it could be moved at any time ;-)

I support any idea about to work together instead of fragmentation, so, please let me know if I can help and if you want to concrete the hdl/awesome idea.

[eine]

I will explain in each category, with an overview, the aim of each tool, with the main URLs (repo, doc).

@rodrigomelo9. This is what fits exactly in hdl/awesome. In hugo, categories/tags can have a description (markdown body) too. Hence, the description of each category, the overview of each tool, main URLs, number of stars, tags, authors/maintainers, funding, related projects, first released, last updated... All of that fits in hdl/awesome. If the template is missing any of those fields, we just need to add them.

I will provide user guides
The idea is to have small tutorials or crash-courses.

This is what falls out of the scope of hdl/awesome. This should be located in some external repo (say this one), shaped as a "blog" or "compenium of articles" (an Sphinx site). Then, you would add references to these articles in the corresponding entries in hdl/awesome. For example, in https://hdl.github.io/awesome/items/cocotb/ there would be a "References" section linking to your "user guide" or "tutorial" about cocotb. Technically, all you'd need to do is propose a PR modifiying https://github.com/hdl/awesome/blob/develop/content/items/cocotb.md and adding:

## References

- [Title of the tutorial](rofrigomelo9.github.io/FOSS-for-digital-HW-design/tutorials/cocotb)

That is, hdl/awesome would be just a database. Then, in you articles, you would reference to all the relevant entries in the database.

Also, I want to show them performing similar tasks (inside of the same category). For example, probably I will use a counter as an example (VHDL, Verilog, other languages), its tesbenches or how to use the frameworks for that. These kinds of things.

For this purpose, I created https://github.com/eine/vhdl-cfg. It is not exactly the same, but the idea is to pick a few "simple" examples in VHDL (a counter, an UART, a full adder, etc.) and "implement" them using several tools. The point is that all of those tools use the same HDL sources, but configuration files/strategies are different for each of them. Hence, users are forced to rewrite their configurations multiple times.

The idea would be to make all the examples actually runnable in CI (based on Docker images provided by the projects or from symbiflow-containers). See https://github.com/ghdl/ghdl-cosim for a taste of what I mean. The title of each example (https://ghdl.github.io/ghdl-cosim/vhpidirect/examples/index.html) is linked to the sources, and all of them are shown in CI: https://github.com/ghdl/ghdl-cosim/runs/1150183057?check_suite_focus=true#step:3:53.

I didn't propose moving vhdl-cfg to either org vhdl or hdl yet, because it is just a playground for now. But that's the kind of project that would fit.

The main result will be a readthedocs (or similar, I have no idea about Hugo :P and I like readthedocs).

You might want to have a look at buildthedocs/btd. See https://github.com/ghdl/ghdl-cosim/blob/master/.github/workflows/doc.yml#L8-L11. It's equivalent to readthedocs (Sphinx, same theme), but everything is handled in GitHub Actions and hosted in GitHub Pages, instead of relying on an external service.

I don't know if github.com/hdl is the best place (mainly because it seems a little abandoned). But if there are plans to be used as a commonplace, I think that could be better than in my own user. Anyway, it could be moved at any time ;-)

I'm good with using any other repo with better visibility and similar "neutral" conception. However, any location we choose is likely to feel abandoned until a few of us actually start adding content. OTOH, we need to be aware that none of this is a priority for most of the community. It would useful for it to exist, and it would be so helpful for newcomers, but almost no one will spend time on actually updating the docs (awesome lists), not even the entries of the projects they maintain. That's a sad reality, but we need to deal with it.

I support any idea about to work together instead of fragmentation, so, please let me know if I can help and if you want to concrete the hdl/awesome idea.

I believe that the starting point would be to discuss the fields in the frontmatter (metadata) of each tool. See https://raw.githubusercontent.com/hdl/awesome/develop/content/items/cocotb.md. Which fields are you missing there? Which metadata do you want to provide which is not possible ATM?

The same about categories: https://github.com/hdl/awesome/blob/develop/config.yml#L15-L42. The description of each category is currently a string. Is that enough? Do you want descriptions of categories to be "full markdown bodies"? What about the list of categories? There are 8 main categories (Libraries, IP Cores, Frameworks, Verification, Tools, Services, Resources and Conferences). Which would you remove? Which would you add? Note that, in your articles/blog/site, you build your own story. So, even if more categories exist in hdl/awesome, you can introduce and talk about the subset that you consider more important.

Meanwhile, you can fork the repo, and add some content. Each entry is a markdown file: https://github.com/hdl/awesome/tree/develop/content/items. As soon as you push any change, CI should trigger and you should see it served at rodrigomelo.github.io/awesome. There was some build error due to renamed icon, but I fixed it some hours ago.

[rodrigomelo9]

@eine

Ok about the differences between hdl/awesome and this repository. I like the idea of hdl/awesome ;-)

Regards https://github.com/eine/vhdl-cfg, I thought about something similar between PyFPGA and others, such as edalize, hdlmake, tsfpga, and so. The problem is, in my opinion, that a developer of the project must be in charge of the example. In another situation, it could be not a fair comparison.

HDL could be a great "neutral" place. I understand the point about to deal with not a lot of attention, and that is not a priority. But I think that it will be useful.

I think that readthedocs is enough for this project, but I can evaluate the alternatives that you suggest.

Ok about hdl/awesome. I will open some issues to discuss categories and metadata.

See you and again, thanks a lot for your time in this issue :-P

[m-kru]

@rodrigomelo9 there is also FuseSoc Verification Automation

[rodrigomelo9]

Thanks @m-kru

It definitely must be in hdl/awesome, but I am not sure about if in this repo. I mean, the aim is to be a starting point for newcomers and CI seems to be an advanced topic for me (maybe because I am not an expert on that :P). I will add, at the introduction, references and small guides about some topics which are not specific for HDL tools, instead, they are common to any kind of projects (the Linux command shell, git, docker, make, and so). Maybe CI must be added there and then a CI helpers section. Let me know your thoughts about that and if you want to help on that.

Another missing topic/section is about documentation. Of course, is a vital point of a project, but is not exactly particularly related to an HDL project... I don't know. Maybe I will add it in the future or if I found contributors :P

[m-kru]

@rodrigomelo9 Well, it is your choice. However, please note that it is not only about CI. It allows running tests locally with single line command. I remember when I was a newcomer, and each time I had to write Makefiles and add non-obvious flags to commands.

[hackfin]

Just a few comments, I haven't been following all the details:

• Generally, an up to date entry point for all different experience users: good thing, but keeping it up to date manually is often of limited 'life time'.
• Keeping documentation in sync with sources/howtos is challenging. There's numerous projects that turned out very puzzling for beginners, as sources have evolved but the docs not been updated.

One very elegant solution to this gordian knot I found in Jupyter Notebooks which can be auto-tested by the CI to make sure the examples always work. The NB environment is a bit heavy weight, but what you get:

• Docker container with tested reference environment: run locally or in the cloud through mybinder.org
• github displays the notebooks for a quick lookup
• Open doors to the python world of data acquisition/visualization
• Save a LOT of hassle with different software environments/installations

There are a few examples incl. the autotesting setup in this entry point:
https://github.com/hackfin/hdlplayground/blob/master/index.ipynb

The only missing thing, if you'd want to code VHDL/Verilog inside the notebook environment is a kernel enhancement like done for other languages, plus you'd have to define what actually happens when you hit the 'Run' button on a VHDL source (syntax check, analysis...)

Forgot to mention: The Jupyter Notebook actually serves as a programmable IDE, so you can simulate/synthesize/download to your target (ECP5 only for now) when running the container locally.

[rodrigomelo9]

@m-kru thanks again, I need to think about how to deal with the complexity of projects which directly depends on other projects. Maybe notes inside of the main project. Let me see.

@hackfin I thought the following to deal with that:

• In the tutorials, I will recommend using an updated Docker environment.
• I will add a shell script to reproduce the tutorial and check with CI periodically against new versions.

It could be not possible in all the cases, but yes in a lot of them.

[eine]

I thought about something similar between PyFPGA and others, such as edalize, hdlmake, tsfpga, and so.

See eine/vhdl-cfg#1. Note that I jumped some steps. That's what I would like to achieve after adding explicit examples that illustrate current limitations. However, as you might imagine, I'm kind of forced to properly learning each tool first. And time is a very limited resource.

I think that readthedocs is enough for this project, but I can evaluate the alternatives that you suggest.

Sure it is! I would suggest to have a look at BuildTheDocs only. That's if you want to avoid handling credentials/projects in readthedocs.org. If you are ok with using an external service, then forget about BTD.

See you and again, thanks a lot for your time in this issue :-P

You are welcome, and thanks for bringing the attention to these issues. As said, it's hard to get the community involved in general documentation chores (for obvious reasons), so any effort in that direction is really wecolme.

---

WRT to CI, I beg to disagree. It is a critical issue, not optional anymore. Regardless of using VUnit, OSVVM, UVVM, UVM, cocotb, fsva, py-uvm... having a set of tests that can be executed either locally or in a CI service is nowadays a requirement. Those with +20y in the area can get along if they are busy, but all newcomers should take it as a foundation. While I agree with it being orthogonal to hardware design, there are enough specific details in the HDL workflow that make it deserve attention:

• In VUnit we created a section about it: http://vunit.github.io/ci/intro.html. See also VUnit/tdd-intro.
• In https://github.com/ghdl/docker/blob/master/USE_CASES.md there is a brief guide. See also https://github.com/ghdl/ghdl/wiki/Ideas:-Documentation.
• In the context of Librecores, Oleg has been some years working on Jenkins:
  • ORCONF 2016 https://www.youtube.com/watch?v=scZbmkRGWsY
  • ORCONF 2017 https://www.youtube.com/watch?v=FX7_6d5yAg4
  • ORCONF 2019 https://www.youtube.com/watch?v=QiBq7wGTmrA
• fpga-knife (@qarlosalberto's upstream seems to be gone...).
• Some old refs of mine: https://github.com/eine/hwd-ide/wiki/Continuous-Integration-(CI).

As far as I am aware, Carlos' diagram is the most accurate representation of what's actually being used in the industry. Gitlab, Docker, VUnit, Vivado, ModelSim, code coverage (gcov, lcov), Doxygen, etc. Those are the most mentioned tools in GHDL's and VUnit's chats, even though most users cannot actually share the scripts they use for plumbing (which is what vhdl-cfg is about).

Moreover, installing vendor tools (Vivado, ModelSim, Precision, Riviera-PRO, etc.) in containers is a whole new area with "fun" issues, specially regarding management of licenses. That's true for Icecube2 too.

Another area of "fun with containers" is executing GUI tools. That's true for WSL2 too. x11docker and runx can help with providing a consistent UX across platforms. That's kind of a niche feature in the conext of (hyped) kubernetes and huge container deployments, but a basic feature for visualization of waveforms. In fact, not all tools support unattended installs. mviereck/x11docker#201 is about graphically installing EDA tools in docker containers.

Anyway, I agree that it is very difficult to write documentation about these features, without moving too far away from the context (HDL design). I'd say that the main point is for designers to know that they should provide tests using some test manager (VUnit, cocotb, fsva, OSVVM's TCL scripts...). Then, they only need to understand that doing so allows anyone to reproduce them anywhere (anyone might be themselves in the future).

---

For documentation generation, I believe that dbhi.github.io/mdpaper is an adequate place to discuss it. See the Introduction. See also the reference to sphinxcontrib-vhdldomain in section Sphinx: Drawbacks.