Support VHDL and mixed language designs

[umarcor]

Using GHDL as a frontend for Yosys allows synthesising VHDL, Verilog and/or mixed language designs. See https://im-tomu.github.io/fomu-workshop/mixed-hdl.html. It'd be interesting to test whether this extension supports those cases, and to enhance it otherwise.

[mithro]

@umarcor This would be great to add!

[nobodywasishere]

I have a very basic version of this up and running using GHDL on a branch here.

Basically what it does now is checks to see if the file is VHDL, and if it is, converts it to Verilog, and then continues through the rest of the normal process with the Verilog file instead. Here's an example of what the test page I added looks like:

GHDL / ghdl-yosys-plugin should also be added to conda / the conda env file. I also don't believe YoWASP supports ghdl-yosys-plugin, and so you'd have to use full-fledged Yosys for generation with VHDL. I could be wrong about this though. Constructive criticism welcome!

[mithro]

@daniellimws -- Look at this! It is super awesome!

[umarcor]

It is! Congrats @nobodywasishere!

In https://github.com/buildthedocs/docker we have some dockerfiles for having container images for documentation purposes. Those are used in GHDL, VUnit, btd, rodrigomelo9/FOSS-for-FPGAs, etc. We might add one image with Sphinx on top of hdlc/ghdl:yosys, so that anyone can use this extension in CI easily.

GitHub

buildthedocs/docker

Contribute to buildthedocs/docker development by creating an account on GitHub.

[mithro]

@umarcor - We have been using conda here too.

[daniellimws]

@nobodywasishere nice! Are you going to make a pull request for this soon?

[nobodywasishere]

@daniellimws Of course! I just wanted to sit on it for a few days to make sure I did it correctly and didn't miss anything. I've just reworked it a little bit and added more documentation to it.

[nobodywasishere]

Alright, so I'm reevaluating my approach in #72 as I believe there could be a better solution. The current approach is translating VHDL into Verilog and pass that along through the same pipeline; however that doesn't cover mixed HDL designs.

As I understand it now, mixed HDL designs only matter when -flatten is used, as a single entity / module should be self-contained in one language and one file. If -flatten is required though, this requires specifying all of the component/sub module files to Yosys. Verilog-only code currently gets around this by using preprocessor includes, but I don't believe such functionality exists between languages.

There are two possible solutions I can think of right now:

• Specify all other required files manually using an additional option (with a comma separated list). This may get really tedious for larger designs.

.. hdl-diagram:: path/to/top/file.vhdl
   :include: path/to/sub/file.il, path/to/other/file.v
   :type: netlistsvg
   :module: top
   :flatten:

• Specify a folder and include all valid files within the folder

.. hdl-diagram:: path/to/top/file.vhdl
   :include: path/to/sub/folder/
   :type: netlistsvg
   :module: top
   :flatten:

It may be that implementing both is the best solution for flexibility.

This is the Yosys command that takes multiple source files and produce a json (suitable for netlistsvg). The GHDL commands would be left out if there weren't any VHDL files included.

yosys -p 'ghdl {VHDL_files} -e; prep -top {top_name} -flatten; write_json {out.json}' {Verilog/RTLIL_files}

I've tested including both Verilog and RTLIL files into a VHDL top file using this command and it worked, so I believe it's the way forward.

Some thoughts:

• There should be a hdl_diagram_ghdl_std global config for setting the VHDL version for GHDL (= "93" or = "08") defaulting to "08"
• Need to come up with better self-contained mixed language examples (help would be appreciated)
• Need to figure out the best way for inputting a list of filepaths as a comma separated string will lead to issues
• Does the order in which files are passed to Yosys matter?

@mithro @umarcor @daniellimws Please let me know your thoughts or if I've missed something.

[umarcor]

@nobodywasishere, this repo is in SymbiFlow's organisation, which is lead by @mithro. One of his mottos is "publish fast and improve later; publish even before you think you are ready". Naturally, applying common sense. What I mean is: if #72 works, you can go ahead and ask it to be merged. No need to wait until the "ideal" solution is ready. That will allow some users to benefit from drawing VHDL designs (and provide feedback), while we solve the slightly more complex mixed HDL case. Of course, this is a very friendly comment, not a request.

There are two possible solutions I can think of right now:

* Specify all other required files manually using an additional option (with a comma separated list). This may get really tedious for larger designs.

* Specify a folder and include all valid files within the folder

It may be that implementing both is the best solution for flexibility.

I would go with:

.. hdl-diagram:: top
   :v: path/glob[.il], path/glob[.v]
   :vhdl: path/glob[.vhdl], path/glob[.vhd]
   :vhdl-std: 08
   :type: netlistsvg
   :flatten:

Where path/glob[*] represent strings to be processed as glob patterns with Python's Path.glob. It is up to the users to provide individual filenames, directories or specifying the extensions.

As you see, my suggestion is to remove the top field, and have it as the main argument.

This is the Yosys command that takes multiple source files and produce a json (suitable for netlistsvg). The GHDL commands would be left out if there weren't any VHDL files included.

yosys -p 'ghdl {VHDL_files} -e; prep -top {top_name} -flatten; write_json {out.json}' {Verilog/RTLIL_files}

I've tested including both Verilog and RTLIL files into a VHDL top file using this command and it worked, so I believe it's the way forward.

This is why I proposed fields :v: and :vhdl: above. It makes explicit which files does the user want to have passed in each of the places in the yosys command.

Two important notes:

• When ghdl * -e is used, it will try to decide the top level, by looking at the hierarchy of the sources. Depending on the use case, it might be necessary to tell it explicitly. Moreover, when the top level is a VHDL file, there is no problem with passing the top twice, once to GHDL and another time to -top. However, I'm not sure when Verilog is the top level and VHDL components are instantiated. I only tried it with instantiating a single VHDL component, which would be the top passed to GHDL. I think this will require more investigation. For now, we should just explain it.

• In VHDL the notion of logical libraries exists. When a design uses components from different libs, several calls to GHDL are required, before calling Yosys. Precisely, one ghdl analyse command is required for each logical library name (all the sources can be passed at once). Again, we don't need to handle this complexity yet. It's ok to explain that, for now, this extension works with all VHDL sources compiled to the same lib only.

  • If you/we wanted to support this, I believe that field :vhdl: would need to be a Dict[str,List[str]]. I don't know if that's supported in rst/Sphinx.

• There should be a hdl_diagram_ghdl_std global config for setting the VHDL version for GHDL (= "93" or = "08") defaulting to "08"

Apart from having it as a global default, I would support optionally specifying it per diagram. It needs to be the same for all the sources in one diagram, tho. GHDL does not support mixing stds yet.

• Need to come up with better self-contained mixed language examples (help would be appreciated)

I suggest picking https://github.com/im-tomu/fomu-workshop/tree/master/mixed-hdl/blink and removing the hard core instantiations. That is, remove the RGB driver and the clock buffer. You will be left with a top level that instantiates a counter. You have four combinations there.

• Need to figure out the best way for inputting a list of filepaths as a comma separated string will lead to issues

Why does a comma separated list of strings lead to issues?

• Does the order in which files are passed to Yosys matter?

For GHDL, it does (should) not. There might be some corner cases with the language, but for most designs the order should be guessed automatically. I believe it's the same with Yosys (Verilog).