Previous work and future ideas

[umarcor]

This repository was created by merging the following resources:

• ghdl/ghdl-systemc-fosdem16 (add readme and slides, add note about ghdl/ghdl-cosim ghdl-systemc-fosdem16#1).
• The content from section using/Foreign.rst and examples/README.rst (doc: split 'Interfacing to other languages' to ghdl/ghdl-cosim ghdl#1216).
• Examples gathered in https://github.com/eine/hwd-ide/tree/develop/examples/VHPI.
• @RocketRoss, contributed a PR to the initial version of this repo ([archive] Read through alterations umarcor/ghdl-cosim#1).

In fact, #1 in the commit history corresponds to umarcor#1 or ghdl/ghdl-systemc-fosdem16#1.

This issue is just a placeholder for consistency and to acknowledge the references.

Refs:

• Simulation models compiled with -shared do not exit cleanly upon failure ghdl#803
• Enhancements to VHPIDIRECT: C APIs ghdl#1053
• doc: add VHPIDIRECT demo ghdl#1059
• Second call of ghdl_main() aborts ghdl#1184
• Pass Toplevel generic to ghdl_main() ghdl#1185
• Update Foreign.rst to reflect my learnings ghdl#1195
• doc: update tips/hints related to VHPIDIRECT ghdl#1202
• Simulation models compiled with -shared abort upon failure when loaded from Python on Linux ghdl#1623

Ideas:

• Packages and shared variables / protected types (ghdl/ghdl#1059).
• Pipes
• X11 windows (vhpidirect: add 'arrays/matrices/framebuffer' #20)
• Environment variables
• Exit codes (vhpidirect: add 'wrapping/exitcb' #15)
• VPI examples
• Execute SystemC example in CI
• Document -o (it applies to all commands that perform a link, so: -e, --elab-run, --link, -c, -m...) (Update documentation ghdl#1290)
• How to cosimulate remotely: run the main software application in a device and execute the simulation in a different device. This can be done with multiple languages (C/C++, Python, Golang, Rust, etc.) and with a bunch of libraries/frameworks (gRPC, ZeroMQ, etc.). See hackfin/ghdlex, dbhi/gRPC, VUnitCoSim VUnit/vunit#568 and Proposal for a more comprehensive approach to VUnit co-simulation VUnit/vunit#603.
• How to integrate GHDL with other HDL simulators (Verilog (iverilog), SystemC (verilator)). See subdir systemc, March 26, 2020 7:04 PM and mixing VHDL-2008 with other standards? ghdl#908.
• How to execute a GHDL simulation as a built-in function in Octave/Matlab through mkoctfile. Conversely, how to execute built-in functions of Octave from VHDL. WIP: https://github.com/umarcor/cosim/tree/future/examples.
  • The same, but applied to Python through ctypes. WIP: VUnit/cosim.
• Coarse grained mixed-signal (Digital/Analog) simulation with Xyce. In the future, GHDL might include a built-in solver for analog modules. See Digital/Analog simulation ghdl#1052.
• Guidelines for users willing to contribute to GHDL's codebase with regard to Enhancements to VHPIDIRECT: C APIs ghdl#1053 and Simulation models compiled with -shared do not exit cleanly upon failure ghdl#803.
  • Specially, how to use gdb in order to get the internal prototypes that GHDL uses for variables, signals, structures, pointers, entities, etc.
• Bind printf as an alternative to suoto/hdl_string_format?

Examples:

• Existing 'Quick Start' examples are based on vhpidirect. However, there are some features which are used there and not shown in the examples yet.
  • ghdl.free.fr/site/uploads/Main/vhpidirect.zip
• 2D array of std_logic
• ygdes.com/GHDL
• dossmatik_UART
• cviehb/ghdl-tutorial
• ghdlex (by @hackfin, now available at hackfin/ghdlex).
  • Using GHDL for interactive simulation under Linux
  • section5.ch/doc/ghdlex
• dbhi/vboard
• VZMQ - ZeroMQ communication with VHDL simulation in GHDL
• VPI
  • vpi-ex-ghdl. I think that these examples were published by Tristan many years ago.
  • cocotb
  • CO-SIMULATION BETWEEN CλASHAND TRADITIONAL HDLS
  • VHDL support in SpinalSim using GHDL as a backend SpinalHDL/SpinalHDL#146
  • MyHDL:
    • MyHDL: VHDL Cosimulation with GHDL
    • Modifications to GHDL VPI Examples
    • vpi-ex-myhdl, might be the same code as in the previous one.
    • dev.myhdl.org/resources/ideas/vhdl-cosim
• ACMIX, A Methodology and Toolset to Enable SystemC and VHDL Co-simulation, ieeexplore.ieee.org/document/4208939
• FOSSEE/nghdl

[bellaz89]

Hi! I am the co-writer of the (still unreleased) GHDL backend for SpinalHDL (SpinalHDL/SpinalHDL#146)

To write the support, one of the most useful reference I found is a master thesis about Clash co-simulation integration . The SpinalHDL GHDL integration is mostly based on it. I think it is a very well written work.

[umarcor]

Hi @bellaz89! As you see, this repository was created a few days ago, and we've been busy uploading all the initial content/examples. I wanted to let it settle down a bit before pinging you explicitly. Anyway, since you already came by (thanks!), let's go ahead:

Although @RocketRoss and myself are currently focused on uploading content related to VHPIDIRECT and the C interface, I acknowledge that most (if not all) non-trivial existing projects do use VPI instead. To name a few: the Clash integration you refed, your own VPIInteropREPL (for SpinalHDL), cocotb (for Python), MyHDL, ACMIX (for SystemC), etc. In fact, that's why section https://ghdl.github.io/ghdl-cosim/vpi/examples/index.html exists. That's where we'd like to add resources related to VPI. As far as I am aware, there is little to none VPI-specific content in the main docs. Link, compile and load options are explained, but there are no further explanations or examples. Furthermore, to be honest, I am not sure about sections "Wrapping a simulation", "Linking objects files" and "Dynamic loading" being exclusive to VHPIDIRECT/Cinterface. Those might be common to any co-simulation approach with GHDL.

Hence, it would be awesome if you wanted to contribute a PR with an initial version of section VPI, where you added a brief description of VPIInteropREPL, along with any other reference that you might consider relevant. I think that the point now is to have info gathered, rather than having very detailed explanations. In the long term, it'd be interesting to know whether VPIInteropREPL can be used with cocotb or MyHDL too, or if execution models are too different.

Refs:

• vpi-ex-ghdl. I think that these examples where published by Tristan many years ago.
• ACMIX, A Methodology and Toolset to Enable SystemC and VHDL Co-simulation, https://ieeexplore.ieee.org/document/4208939
• MyHDL:
  • Modifications to GHDL VPI Examples
  • vpi-ex-myhdl, might be the same code as in the previous one.
  • http://dev.myhdl.org/resources/ideas/vhdl-cosim/

[bellaz89]

Hi! :)
Sure, right now I don't have so much time to work on this (I have the SpinalHDL-GHDL cosim to finish and document and I also my 'real' work XD), however, I think it is a nice idea to share this kind of information.

Right now VPIInteropREPL is a bit out of date because I am continuing the development on SpinalHDL's ghdl branch. Once It is finished, that code can be used to update VPIInteropREPL. Since the wrapper interface is created using SWIG, it could be possible to add the support of several languages (Python/Octave/Ruby/Tcl.. etc for example).

[radonnachie]

Very interested in expanding my knowledge to cover VPI, will be looking to make some time for an investigation once the current VHPI PRs are completed

[bellaz89]

Recent bugfixes/enhancements in the GHDL-VPI interface resulted in the addition of several VPI usage examples in GHDL testbenches directory:

• gna/issue1226 shows how to simulate an arbitrary number of steps.
• gna/issue1233 shows how to iterate through top entity nets.
• gna/issue1256 shows how to read/write enums (but the approach can be used for others unstructured type signals)

These tests and in particular the last one, are a good starting point to develop VPI based co-simulation code and can be added to documentation as examples since they are quite simple to understand.

[umarcor]

@bellaz89, actually, there are other several examples in the testsuite:

# grep -l -r ./testsuite/ -e "vpi-compile"
./testsuite/gna/issue1226/testsuite.sh
./testsuite/gna/issue1228/testsuite.sh
./testsuite/gna/issue1233/testsuite.sh
./testsuite/gna/issue1256/testsuite.sh
./testsuite/gna/issue450/testsuite.sh
./testsuite/gna/issue531/testsuite.sh
./testsuite/gna/issue98/testsuite.sh

By the same token:

# grep -l -r ./testsuite/ -e "VHPIDIRECT"
./testsuite/gna/bug021/sim_pkg.vhd
./testsuite/gna/bug026/xb.vhd
./testsuite/gna/bug092/t.vhdl
./testsuite/gna/bug092/t2.vhdl
./testsuite/gna/bug097/tb.vhdl
./testsuite/gna/issue1229/pkg.vhdl
./testsuite/gna/issue1252/pkg.vhdl
./testsuite/gna/issue152/ax_wb_pli_pkg.vhdl
./testsuite/gna/issue797/pkg_c.vhdl

[bellaz89]

Hi,

I know the existence of these examples and I used them as a reference to write the SpinalHDL-GHDL bindings. However, until now, there were no examples of how to ask GHDL to advance the simulation time through VPI. Believe me, it is very difficult to find a simple example on how to do that on the internet, and understand it from cocotb is quite a challenge. Therefore, since I wrote these three reproducers (1226,1233, 1256), and given that from what I understand the ghdl-cosim aim is to document/give example on GHDL foreign programming interface, I thought that It would be very helpful to point you to these three testbenches. I think that including them in the documentation could help many people to avoid wasting their time trying to understand how to advance the GHDL simulation time with VPI like I did :P.

BTW I think I will write some PR :)

Edit:
See pull request #19

[umarcor]

@bellaz89, the point is that there are dozens of undocumented and independent examples about VHPIDIRECT and/or VPI. All the references in this issue contain one or multiple examples of different complexity. Some are simpler, others are frameworks, but almost each of them has features which are very difficult to find on the internet. Each of them is likely to be very useful for a subset of users.

The purpose of this repo is not only to gather references (to make them easier to find), but also to explain them (to make them easier to understand), and to have a fine-grained test suite (to find issues in different platforms/backends). For gathering only, this issue exists. On top of that, explaining implies thinking about a coherent and easy-going path that takes any new user from zero to the most complex examples. With "zero" I mean "no knowledge about co-simulation with GHDL". Users are expected to be familiar with, VHDL, GHDL, C and GCC.

how to ask GHDL to advance the simulation time through VPI.

I believe this is a very interesting example. Precisely, this is currently not possible/documented with VHPIDIRECT/Cinterface. Hence, it is one of the motivations to recommend using VPI instead.

However, ATM there is absolutely no documentation about VPI. Not a single line. Before introducing any of the examples you propose, I believe that at least one should exist about how to do nothing other than building and running a simulation with an VPI module. For instance, a very relevant difference compared to VHPIDIRECT is that VPI needs vpi_user.h. At the same time, according to your examples, VPI modules need to be built as a shared library; which is just one of the multiple possibilities with VHPIDIRECT. Since I want to learn about VPI too, I'm ok with helping/co-authoring the example(s) that are missing until yours fit. Nonetheless, I'd like to know if you are ok with looking at the VPI section as a whole, and not just adding independent examples.

See pull request #19

I will have a look!

[bellaz89]

@umarcor

@bellaz89, the point is that there are dozens of undocumented and independent examples about VHPIDIRECT and/or VPI. All the references in this issue contain one or multiple examples of different complexity. Some are simpler, others are frameworks, but almost each of them has features that are very difficult to find on the internet. Each of them is likely to be very useful for a subset of users.

Hi! Yes, sorry, I realize I was a bit unclear in my first message about why I think these references are valuable for me. That's why after thinking about that I opened a PR to explicitly give a set of examples that can be understood with basic programming/VHDL skills and that covers the most basic use of VPI one can do.

The purpose of this repo is not only to gather references (to make them easier to find), but also to explain them (to make them easier to understand), and to have a fine-grained test suite (to find issues in different platforms/backends). For gathering only, this issue exists. On top of that, explaining implies thinking about a coherent and easy-going path that takes any new user from zero to the most complex examples. With "zero" I mean "no knowledge about co-simulation with GHDL". Users are expected to be familiar with, VHDL, GHDL, C and GCC.

how to ask GHDL to advance the simulation time through VPI.

I believe this is a very interesting example. Precisely, this is currently not possible/documented with VHPIDIRECT/Cinterface. Hence, it is one of the motivations to recommend using VPI instead.

However, ATM there is absolutely no documentation about VPI. Not a single line. Before introducing any of the examples you propose, I believe that at least one should exist about how to do nothing other than building and running a simulation with an VPI module. For instance, a very relevant difference compared to VHPIDIRECT is that VPI needs vpi_user.h. At the same time, according to your examples, VPI modules need to be built as a shared library; which is just one of the multiple possibilities with VHPIDIRECT. Since I want to learn about VPI too, I'm ok with helping/co-authoring the example(s) that are missing until yours fit. Nonetheless, I'd like to know if you are ok with looking at the VPI section as a whole, and not just adding independent examples.

See pull request #19

I will have a look!

I fully agree that giving full and free documentation that covers many aspects/usage of VPI is something that would be very nice to have. However, this is going to take much more effort than giving a basic set of examples because VPI is a complex API with many details I am not aware of. So I think that this can be taken as a long term task that can be updated from time to time (also because my job doesn't allow me to spend a lot of time on hobby projects... so I can't give a 100% assurance that I will be able to follow it). Even if just giving an organized basic set of VPI examples couldn't be enough for complete newcomers, they may be still valuable for people that have knowledge above basic skills but find it hard to understand how to make VPI work in practice.

Thank you for reviewing my PR!

[umarcor]

That's why after thinking about that I opened a PR to explicitly give a set of examples that can be understood with basic programming/VHDL skills and that covers the most basic use of VPI one can do.

In fact, as you saw after I reviewed your PR, I believe that the set of examples that you proposed is nice and more than enough. I'm not expecting/requesting any more than that. Let's just make a little effort for the "story" to be easier to understand/follow.

I fully agree that giving full and free documentation that covers many aspects/usage of VPI is something that would be very nice to have. However, this is going to take much more effort than giving a basic set of examples

This repo is not "a tutorial about VPI", but "a tutorial about using VPI with GHDL". Anything which is related to GHDL or VPI only does not belong in here. However, we need to acknowledge/reference it. For example:

VPI (and VHPI) are complex APIs. Compared to VHPIDIRECT, these provide advanced features, at the cost of having to learn/understand many more details. Since this is the user and reference manual for GHDL, it does not contain an introduction to VPI/VHPI. Thus, the reader should have at least a basic knowledge of them. A good knowledge of the reference manuals (usually called LRM) is a plus. Please read X, Y and Z if you are not familiar with VPI/VHPI yet.

The one-liner introduction to VPI is that C header vpi_user.h provides dozens of functions to scan/navigate the hierarchy of the elaborated hardware design, and it allows to set callbacks for specific events/signals. Hence, unlike VHPIDIRECT, when using VPI/VHPI, VHDL sources are agnostic to the existence of C sources.

VPI is a complex API with many details I am not aware of.

Writing the docs is an exercise for us to learn too. We need to point which details we are not sure about. We will either find the answer or add some note/warning acknowledging that we don't know it. Nonetheless, if questions arise while we write the examples, new users are likely to ask the same questions in the future.

So I think that this can be taken as a long term task that can be updated from time to time

I believe it is a mid-term task. If we open the door to adding examples with sources that are partially inconsistent, and we allow to contribute them without proper documentation, there is a serious risk that those will never be completed. It is ok to keep PRs open and to enhance them as spare time allows to. When they are merged, we need to assume that the content might not be updated in weeks, months or years.

Even if just giving an organized basic set of VPI examples couldn't be enough for complete newcomers, they may be still valuable for people that have knowledge above basic skills but find it hard to understand how to make VPI work in practice.

I think that people with skills slightly above the basic will have no issues with finding either this thread or the open PRs. They don't really need the docs. We can make it more explicit by adding some note either to the site or to the README:

This repository was created recently and multiple existing examples are not published yet. See issue #1 and the list of open Pull Requests for on-going work.

By the same token, we can add "Contributing guidelines", to suggest potential contributors different levels of commitment:

• Add a reference to this issue.
• Propose a PR with working or non-working examples, and with/without complete docs.
• Propose a PR with working examples and complete docs matching the overall learning path.

[miree]

Hi,

I just found this repository and I would like to advertise my solution to VHDL/Verilog cosimulation using GHDL and Verilator.
It uses a code generator that generates glue-code to integrate Verilog modules (processed with Verialtor) with a GHDL simulation using VHPIDIRECT.

https://github.com/miree/gvi

I find it very convenient and it might be useful to others as well. Perhaps a link to this code generator (or even the code generator itself) could be integrated into this repository to make people aware of it.

[tgingold]

Thank you for the message. This is an interesting way to do cosimulation with verilog! Do not hesitate to create a pull-request to add a reference to your project in the README.