Documentation

[eine]

The format of hdl-prj.json is currently undocumented. This is expected, since it is in a very early development stage and it is subject to change very frequently. However, since it is the only approach to set GHDL options (such as --std), it might be frustrating for new users to try this tool without any reference. We'll use this issue to collect pieces of information to allow any user to have a hopefully satisfying first experience.

---

Example hdl-prj.json file for VUnit's examples/vhdl/array_axis_vcs:

{
    "options": {
        "ghdl_analysis": [
            "--std=08",
            "-Pvunit_out/ghdl/libraries/osvvm",
            "-Pvunit_out/ghdl/libraries/vunit_lib"
        ]
    },
    "files": [
        { "file": "src/fifo.vhd", "language": "vhdl" },
        { "file": "src/axis_buffer.vhd", "language": "vhdl" },
        { "file": "src/test/tb_axis_loop.vhd", "language": "vhdl" }
    ]
}

NOTE: VUnit sources must be compiled (by executing python run.py -c) for ghdl-ls to find the definitions.

---

At some point it might be useful to provide a json-schema.

---

A link to a demo in play-with-docker would let users try the VSC extension without a local docker installation.

[suzizecat]

If I might add my cent, it would be nice to mention this file somewhere in a readme and provide a small example such as the one just above.

I just looked for mentions of it for around an hour 😅

[tgingold]

PR for docs are also welcome 😃

[suzizecat]

@tgingold You got me on this one.
Could you tell me where (probably in some source file ?) can I find if there is more options to use in this json file ?
Moreover, as of today, what can this extension provide ? Only syntax checking or some more stuff ?
(I'm not familiar with neither VSCode or ghdl)

[tgingold]

Could you tell me where (probably in some source file ?) can I find if there is more options to use in this json file ?

I think that the example shows all the features, but you can have a look at workspace.py (the project file is read during __init__)

Moreover, as of today, what can this extension provide ? Only syntax checking or some more stuff ?

Slightly more: semantic checks, navigation (go to definition).

[eine]

@suzizecat, let me step in, please.

(I'm not familiar with neither VSCode or ghdl)

GHDL is a piece of software that is one of a kind. It is a tool written in Ada by @tgingold during the last 15-20 years. Initially, it was meant to be a simulator/compiler. As such, what it basically does is to analyze VHDL sources, elaborate them and integrate everything along with a runtime library that handles timing during execution/simulation. However, the fact that VHDL as a language is so difficult to parse, makes GHDL unique. Precisely, GHDL has the best open/free source support for VHDL 2008, and it is comparable/better than many closed/commercial tools. As a matter if fact, the VHDL standarization group uses GHDL to discuss new features.

As a result, there have been multiple requests during these almost two decades asking @tgingold whether GHDL could provide other VHDL-related features for development, such as syntactic/semantic analysis (linting), synthesis, 'transpilation' (from one version of VHDL to another one, typically for backwards compatibility), generation of C-compatible sources (kind of what Verilator does), etc.

Specially during the last six months, @tgingold has been (re)working on some of these so useful/demanded but somehow 'hidden' features of the existing GHDL codebase. The main point is that all of those demanded features are possible and 'almost' available, but there is no public structured API for them. Unfortunately, diving into GHDL's codebase requires a very good knowledge not only about VHDL and hardware design, but also about compilers and relatively deep software architecture. Therefore, Tristan is making a huge effort to provide prototypes using other languages/environments which are more familiar to us (other users of all kinds). This repository is the result of that effort. Another result, is the experimental ghdl --synth feature, which is tightly related to tgingold/ghdlsynth-beta.

Recently, we updated the README in https://github.com/ghdl/ghdl#project-structure, to partially explain this context to new users. The path that connects GHDL with your question is as follows:

• Some of the features of GHDL are available as a shared library, which is named libghdl*.so on GNU/Linux. This shared library is built along with GHDL, by default.
• There is a Python package/library that allows developers/users to interact with the shared library. That is https://github.com/ghdl/ghdl/tree/master/python/libghdl.
• Then, in this repo, there is LSP server written in Python which interacts with libghdl-py to use libghdl*.so.
• Last, there are multiple clients (for now, one for VSCode and another one for Emacs) that use the LSP server.

However, don't panic! This is just so that you understand that all this pieces of software are related to each other, and that they implement basically the same features in different languages/standarized interfaces. Hence, you can look at GHDL's documentation (https://ghdl.readthedocs.io) and try to use whatever you see by kind of ignoring that multiple intermediate 'glue' packages exist between the 'core' of GHDL and whichever 'frontend' you are using.

Could you tell me where (probably in some source file ?) can I find if there is more options to use in this json file ?

You can start with options for analysis (ghdl -a in the CLI):

• https://ghdl.readthedocs.io/en/latest/using/InvokingGHDL.html#analysis-a
• https://ghdl.readthedocs.io/en/latest/using/InvokingGHDL.html#ghdl-options

Most, if not all, of those should be accepted in the ghdl_analysis field of the JSON. That's how I added the -P<DIRECTORY> above: https://ghdl.readthedocs.io/en/latest/using/InvokingGHDL.html#cmdoption-ghdl-p-directory

The source code where the JSON file is loaded is https://github.com/ghdl/ghdl-language-server/blob/master/ghdl-ls/vhdl_langserver/workspace.py As you see, function read_project is used to read the content of the JSON and load it to self._prj. Then, in set_options_from_project, libghdl.set_option() is used (which is how you tell libghdl-py to tell the shared library).

Moreover, as of today, what can this extension provide ? Only syntax checking or some more stuff ?

Tristan encourages users to use the tools and report whatever error/inconsistency we might find. He is actually quite clever and fast at understanding the underlying issue, so he is usually able to quickly reply explaining whether it will be a quick fix or if that feature will take longer. Most of the times, he will fix the issue on his own before you are able to understand what happened (@pepijndevos dixit).

For now, I have tried:

• Syntax checking/highlighting.
• A list/tree of symbols/entities/archs is shown in the bottom block of the sidebar.
• Go to declaration/definition works. This is true even accross 'external' libraries. That's what the example above allows.
• I'd say that some partial code completion too. It suggests types when you start writting std_.... But I don't know how much of that is because of VSCode and how much depends on the extension.

Furthermore, you can find a list of Tristan's ideas in https://github.com/ghdl/ghdl-language-server/blob/master/TODO

---

Nevertheless, I think that both Tristan and me have a blurry view of this VSCode extension, in the sense that we have ideas for it that probably do not belong here but rather in a sibling/child extension. This is because some of the ideas are relative to managing HDL designs/projects as a whole, which would include not only LSP features, but also simulation and/or synthesis. This is where the format of the hdl-prj.json comes in place. As you might imagine already, currently hdl-prj.json is just a JSON representation of the CLI arguments that you would provide to ghdl -a. There is no more 'design effort' put into it, or in it's name. This is the motivation for it to be undocumented and for this issue to exist.

The main point here is: do we want to design and maintain some new independent JSON schema to manage projects of (V)HDL sources? I think we agree that the format should be generic enough so that multiple tools can use it. Should some other tool already provide a JSON format that suits our needs, we'd probably discuss using or extending that instead. Some possibilities are:

• VUnit's JSON export: http://vunit.github.io/cli.html#json-export
• edalize's ghdl options: https://edalize.readthedocs.io/en/latest/edam/api.html#ghdl

---

Summarizing, any contribution is welcome. If you want to propose adding a sentence/note and a ref in the README, that's ok. If you want to dive into the code and find out which features/options are supported and which not, that's ok too. None of us are experts in the NodeJS/Electron/JavaScript/TypeScript ecosystem, so any knowledge related to VSCode itself and to the extension is very valuable (see #11 and #5). Should you be using any other editor (say vim), instructions about how you set it up would be great. Just bear the context in mind.

If you have any background in (V)HDL design, your thoughts about this comments would be very valuable too. I.e., do you know what you are looking for or are you learning while you explore new tools? Just out of curiosity, how did you install/try this? Did you compile it or did you use the docker image?

EDIT

Of course, you are free to copy parts of this message to some GUIDE.md or PRIMER.md. I think that someone 'new' write such a short document can be more clarying for other new users than having us do it.

[suzizecat]

Thanks for this (astonishingly) detailed reply !
The main purpose of my question was to know if there is some integration of go to definition stuff, completions and so on because on my setup, I "only" have the syntactic checks which seems to work. No "go to" between files nor completion above what I would expect from VSCode (in particular between files).

I was also wondering if this could also describe "builds" commands, but since this whole language server thingy is, as far as I understand, something to perform code analysis in order to help the code edition, I'm not sure that this is is purpose and within its scope.

The source code where the JSON file is loaded is https://github.com/ghdl/ghdl-language-server/blob/master/ghdl-ls/vhdl_langserver/workspace.py As you see, function read_project is used to read the content of the JSON and load it to self._prj. Then, in set_options_from_project, libghdl.set_option() is used (which is how you tell libghdl-py to tell the shared library).

I'll have a look, thanks for the details !

For my background, I'm currently working at STMicroelectronics doing what is called Clock and Reset Domain Crossings verification. Those are structural checks which basically allows you to detect issues when an asynchronous signal reach a flop without any proper structure to prevent a metastability generation/propagation. I'll gladly add some more details if you wish to.
When a colleague ranted about our tools being... let say wonky, I wondered if there wasn't any open source stuff which might allows HDL analysis and the possibility to try out a proof of concept of structural check "for fun" (on my free time). Then I found GHDL which looked interesting due to being able to perform VHDL analysis (even though not really adapted for a Python/C/C++ guy like me). Then I saw something about a "thing" to improve VHDL development using VSCode which looked promising and there I am !

I have tried this because, while I studied VHDL, I wasn't able to find a decent VHDL editor, let aside an opensource one. Therefore being stuck with Xilinx stuff which is basically a notepad ++/gedit with syntactic issues reported... When I saw a stuff linked with what looked like a nice VHDL elaboration and test tool, I gave it a shot !

So I'm learning while exploring tools (I tried to give a shot to Alliance which use some very outdated technologies by now and is therefore hard to setup, use... )

I compiled the whole GHDL stuff on Ubuntu 19.04 with GCC in order to get the libraries for the ghdl-ls (the hard way, it seems) but the explanations were quite good and it wasn't too much trouble. (One point tho, The current GCC master is in version 10 which kind of break GHDL compilation which doesn't recognize a right GCC version above 9. Might open something about that). It was a little bit painful to make the LS works with VSC due to the latest (10, what a coincidence) version of nodeJS being incompatible with the npm version in repositories (which recognize until 9 too) and some issue with ghdl libghdl/__init__.py not finding my lib path (line 54). So I hacked something which I'll probably share when I find a moment.

I tried GHDL for a very little bit of time but I have to say that I'm pretty satisfied which the small bits I have tested so far (a wonky student design and a not less wonky testbench which kind of worked) and the fact that the tool is pretty straightforward with source reading is very nice.

Finally, to add some stuff on the probably huge pile of GHDL feature that might be interesting :

• Having a way to access a structural representation of the design (to have structural checks). Not sure that this doesn't require synthesis though.
• Maybe have a look at the IEEE 1685 "IP-XACT" standard which is used to describe huge designs and provide setups

And one for the completion stuff :

• It would be awesome (unless it is already here and I screwed my setup somewhere) to have the completion adding the generic map and port map sections filled up with the generic and signals names when instantiating a module.

I will try to have a look at the json reader to get some documentation out when I'll have some time.

Thanks again for the detailed reply !

[eine]

Thanks for this (astonishingly) detailed reply !

You are welcome!

The main purpose of my question was to know if there is some integration of go to definition stuff, completions and so on because on my setup, I "only" have the syntactic checks which seems to work. No "go to" between files nor completion above what I would expect from VSCode (in particular between files).

As you might have tried already, this is supported. However, all the files need to be defined in the hdl-prj.json file or you need to open them once in VSCode, so that they are automatically analized.

I was also wondering if this could also describe "builds" commands, but since this whole language server thingy is, as far as I understand, something to perform code analysis in order to help the code edition, I'm not sure that this is is purpose and within its scope.

With "builds" commands do you mean to e.g. 'analize and elaborate a bunch of files and then simulate an entity'? If so, this is what I meant when I said that we have a blurry view. Yes, we want to have that feature. However, we are unsure about this fitting a 'language server extension'. This is where references to VUnit and edalize come in place. See also olofk/fusesoc#301.

For my background, I'm currently working at STMicroelectronics doing what is called Clock and Reset Domain Crossings verification. Those are structural checks which basically allows you to detect issues when an asynchronous signal reach a flop without any proper structure to prevent a metastability generation/propagation. I'll gladly add some more details if you wish to.

I'd be glad to know some details about the 'testbench infrastructure' you have. Is everything written in VHDL? How do you feed data in/out of the testbench? Which features do you need which you don't have a free/open source alternative for? Do you make heavy use of assertions?

On the one hand, this is pure curiosity. On the other hand, there have been some recent efforts to do formal verification with VHDL, by using GHDL and yosys: http://pepijndevos.nl/2019/08/15/open-source-formal-verification-in-vhdl.html Although it is an extremely experimental feature, I wonder if this can be useful to you.

When a colleague ranted about our tools being... let say wonky,

I have tried this because, while I studied VHDL, I wasn't able to find a decent VHDL editor, let aside an opensource one. Therefore being stuck with Xilinx stuff which is basically a notepad ++/gedit with syntactic issues reported...

I believe that many of GHDL users can feel that pain... I was super excited when Tristan created this repo a few months ago. I expected it to be quite buggy, and it is. But it already provides many more features than I have ever had in a VHDL editor. Starting with VHDL 2008 support and 'go to'.

I wondered if there wasn't any open source stuff which might allows HDL analysis and the possibility to try out a proof of concept of structural check "for fun" (on my free time).

As said, GHDL supports all the versions of VHDL pretty well. So, as long as you can describe the structural checks in VHDL, you should be good. It seems that such checks would rely on GHDL's core, and not on LSP features.

Then I found GHDL which looked interesting due to being able to perform VHDL analysis (even though not really adapted for a Python/C/C++ guy like me).

Although GHDL seems an alien to Python/C/C++ people, I believe there is very good reason for that: the VHDL language was originally based on Ada. Hence, there are sintactic and semantic similarities between the language used to write the compiler and the target language to be compiled. Nevertheless, since GCC and LLVM backends are supported, integration of GHDL with C/C++ programs is actually very good.

Furthermore, there are multiple mechanisms to co-execute VHDL along with modules/functions/components written in any language than can map to C signatures. The most known is VPI, which allows to access all the internal signals of a design at runtime. However, I find VHPIDIRECT easier to use. You can have a brief idea of how this works in https://ghdl.readthedocs.io/en/latest/using/Foreign.html Precisely, it is possible to co-execute VHDL, C and Python (through ctypes) by using VHPIDIRECT. There are some screencasts in VUnit/vunit#476, where the Python part is a flask server and a JavaScript frontend is used. As you see, it allows to provide an interactive custom GUI for GHDL simulations. If you are interested on this, I can provide you references to github projects of different complexity.

Last, a python library exists, which allows to interact with the shared library that provides many of the core features of GHDL. However, this is mostly for developing tools on top of GHDL. I believe you don't want to dive into it yet.

Then I saw something about a "thing" to improve VHDL development using VSCode which looked promising and there I am !

As said, the VSCode part needs some love. If you are a VSCode user, do not hesitate to write down all the UX suggestions you might think of.

When I saw a stuff linked with what looked like a nice VHDL elaboration and test tool, I gave it a shot !

It is actually quite fun that you found GHDL because of the LSP features. I think that most of GHDL users might not be aware of it yet :D

I compiled the whole GHDL stuff on Ubuntu 19.04 with GCC in order to get the libraries for the ghdl-ls (the hard way, it seems) but the explanations were quite good and it wasn't too much trouble.

That's the hardest way, yes :D. If you only want LSP features, you can use mcode backend, which reduces the build to ./configure && make && make install. For simulation only, mcode will work well too. If you want to generate executable binaries from your designs, you should use LLVM backend. GCC backend is only suggested if you want code converage (lcov), since it is not supported with other backends.

The main point here is that GHDL with mcode backend is somewhere between 5-10MB, and with GCC backend it is >500MB. So, because of compilation time and disk usage, GCC is not worth, unless you really need coverage.

(One point tho, The current GCC master is in version 10 which kind of break GHDL compilation which doesn't recognize a right GCC version above 9. Might open something about that).

Yes, it seems that support for GCC 9 or GCC 10 needs to be fixed. You might want to either comment in ghdl/ghdl#883 or open a new issue.

It was a little bit painful to make the LS works with VSC due to the latest (10, what a coincidence) version of nodeJS being incompatible with the npm version in repositories (which recognize until 9 too)

I had to 'fight' with this issue too. In the end, I decided to install the default 'npm' and let it install the default nodejs (which is 8). In case they might be useful for you, these are the dockerfiles we use to test this repo in CI and to generate ghdl/ext:ls-debian and ghdl/ext:ls-ubuntu images:

• https://github.com/ghdl/docker/blob/master/dockerfiles/ls_debian_base to generate ghdl/build:ls-* and ghdl/run:ls-* images.
• https://github.com/ghdl/docker/blob/master/dockerfiles/ls_debian to actually build ghdl/ext:* images.

BTW, when GitHub Actions are publicly available, it will be possible to download latest *.VSIX files.

and some issue with ghdl libghdl/__init__.py not finding my lib path (line 54). So I hacked something which I'll probably share when I find a moment.

I think we need some more context to understand this. There have been many recent changes to how libraries are found/defined. Therefore, it'd be helful if you could open a specific issue about it.

• Having a way to access a structural representation of the design (to have structural checks).

This is a very very demanded feature, but not easy to implement. GHDL does have all the structural representation, of course:

• Some CLI options are provided. In https://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=disp-tree#export-hierarchy-and-references, you will find --disp-tree, --xref-html and --file-to-xml.
• It is possible to use VPI to extract all the structure, and to display status of each element during simulation.
• The VSCode extension shows a tree view of the entities, architectures, loops, etc. found in the file which is open. Maybe this can be extended to 'follow refs', so you can expand all the hierarchy when browing the top entity.
• There is GHDL: a complete VHDL parser ghdl#111, which is a long discussion about multiple GUI features that users would like. Some of the info is gathered in https://github.com/1138-4EB/hwd-ide/wiki. The most advanced prototypes are probably those of Nic30 (e.g. https://github.com/Nic30/hwtIde/). However, I think that it uses his own parser based on ANTLR.

I think that the main stopper for having an structural representation which is somehow interactive is that a good understanding of GHDL's AST is required. Moreover, this changes quite frequently. This knowledge is significantly different from libraries to design GUI applications. Thinking about a 2D or 3D representation (as 2D layers) of the design, the complexity of routing/layout algorithms is added. Hence, it is difficult that some person has the knowledge, the time and the interest to implement some tool.

Not sure that this doesn't require synthesis though.

I'd say that it requires analysis and elaboration, but not synthesis. However, currently generics are a runtime option. Therefore, it might be difficult to elaborate a structural view without using same values for them. @tgingold has commented that he is going to make it an elaboration option only, in the future.

• Maybe have a look at the IEEE 1685 "IP-XACT" standard which is used to describe huge designs and provide setups

I think that this kind of task is better handled by some external tool, which can feed not only GHDL but also other vendor tools. For example, olofk/fusesoc, which uses edalize, and which shares features with VUnit. You'll see that 'IP-XACT' is mentioned in the README. Note that you can currently use GHDL with fusesoc/edalize for simulation (not for synthesis yet).

• It would be awesome (unless it is already here and I screwed my setup somewhere) to have the completion adding the generic map and port map sections filled up with the generic and signals names when instantiating a module.

I think this is a specific enhancement request that deserves a new issue. However, note my comments about the scope of this extension. I don't want to prevent you from opening issues. Just be careful to put some indicator, cross-reference, or just mention in the issues that you feel might be partially out of scope.

BTW, you might want to have a look at TerosTechnology/terosHDL. It contains many GHDL-based features that I'd like to see in a VSCode extension. However, it is based on Atom.