Reorganize, update README, add refs, and add vpi/quickstart #21
Conversation
umarcor
force-pushed
the
reorganize
branch
3 times, most recently
from
ba2b8fc to
0e9b7fb
Compare
| because, as the name suggests, it is a direct interface. However, on the one hand VHPIDIRECT requires modification of | ||
| VHDL sources, which might not be possible or desirable in certain contexts. On the other hand, VPI/VHPI allow use cases | ||
| which are not yet possible with VHPIDIRECT, such as controlling execution time steps. It is suggested to read the quick | ||
| start examples of both interfacing mechanisms, in order to get a feel of the differences. |
There was a problem hiding this comment.
a feel for the differences.
| The latest version was published in 2019: `1076-2019 - IEEE Standard for VHDL Language Reference Manual <https://ieeexplore.ieee.org/document/8938196>`_. | ||
|
|
||
| Some vendors support C programming interfaces similar to VHPI. For example, Mentor Graphics' ModelSim/QuestaSim supports a | ||
| Foreign Language Interface (FLI) that provides functions to have procedural access to information within the simulator, ``vsim``. These allow to traverse the hierarchy, get/set values and control a simulation run. See `Using ModelSim Foreign Language Interface for c – VHDL CoSimulation and for Simulator Control on Linux x86 Platform <https://opencores.org/usercontent/doc/1380917197>`_ and `github.com/andrepool/fli <https://github.com/andrepool/fli>`_. |
There was a problem hiding this comment.
These functions allow (traversing)[traversal of] the hierarchy, (getting/setting)[read/write access of] values and (controlling)[control over] a simulation run.
| function. Upon existence of ``main``, execution of the simulation is triggered by calling ``ghdl_main``. | ||
|
|
||
| This is the most basic example of such usage. ``ghdl_main`` is declared as ``extern`` in C, and arguments ``argc`` and |
There was a problem hiding this comment.
Suggestion:
providing a custom program entrypoint (main function), wherein the execution of the simulation....
Below is the most basic example...
There was a problem hiding this comment.
I agree with the first part. However, "Below" is not exactly correct, because "This" means the section itself. That is, the header is :cosimtree:basic <vhpidirect/quickstart/wrapping/basic> and "this" means that example, not the code block below. I rewrote it to "This example shows the most basic of such usage", but it sounds weird to me. What do you think?
| ------------------------------------------------------- | ||
|
|
||
| Although most of the provided examples are written in C, VHPIDIRECT can be used with any language that supports a | ||
| C-alike compile and link model. |
|
|
||
| This example shows how to time the execution of a simulation from either C or Ada. In both cases, function ``clock`` is | ||
| used to get the time before and after calling ``ghdl_main``. Regarding the build procedure, it is to be noted that C | ||
| sources are elaborated with :option:`-e`, because GHDL allows to pass parameters (in this case, additional C sources) |
There was a problem hiding this comment.
allows passing parameters
| @@ -71,8 +137,8 @@ numbers. Subprogram declaration requirements are detailed under the :ref:`COSIM: | |||
| While sharing variables through packages in VHDL 1993 is flexible, in VHDL 2008 protected types need to be used. | |||
| However, GHDL allows to relax some rules of the LRM through :option:`-frelaxed`. | |||
|
|
|||
| This example shows multiple alternatives to share variables through packages, depending on the target version of the standard. | |||
| Three different binaries are built from the same entity, using: | |||
| This example shows multiple alternatives to share variables through packages, depending on the target version of the | |||
There was a problem hiding this comment.
Suggestion:
This examples showcases multiple ways of sharing variables through...
| This is the most minimal example, where a single callback is registered at the beginning of the simulation. The callback just | ||
| prints ``Hello!``. Then, the simulation is executed as usual. | ||
|
|
||
| VPI allows to register callbacks at multiple events and to optionally delay their execution after the event is triggered. |
There was a problem hiding this comment.
allows registering/allows one to register
There was a problem hiding this comment.
Should it be "and optionally delaying" too?
- VPI allows registering callbacks at multiple events and to optionally delay their
- VPI allows one to register callbacks at multiple events and to optionally delay their
- VPI allows registering callbacks at multiple events and optionally delaying their
| Examples | ||
| ######## | ||
|
|
||
| TBC | ||
| A very brief description of how to use VPI is that ``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. |
Not late at all! The PR was merged fast so that some info about VPI was available and to have the Quick Start reorganized. But it is ok to have the review now, and I'm grateful for it. I created a local branch and will add it to the next PR I open. I added you as a coauthor of these fixes.
Me too! It is very little for now, but we'll improve it with time. |
In this PR, multiple comments from the reviews of #19 and from #1 are applied.
.gitignoreis updated.@RocketRoss, would you mind reviewing for language issues?