Various VPI examples

[bellaz89]

In this PR four VPI usage examples are added.

VPI examples

The directory contains some VPI usage examples:

1. helloworld: minimal VPI code example that runs a simulation, prints a message and exits.
2. access: signal read/write example on an adder component using vpi_put_value and vpi_get_value.
3. list: example on signal hierarchy iteration using vpi_iterateand vpi_scan.
4. timestep: shows how to run a simulation for an arbitrary number of timesteps.

to run a test, just go in an example directory and execute

sh run.sh

[bellaz89]

@umarcor Thank you for the feedback! I am waiting for your response :)

In the meanwhile, I tried to implement a part of your suggestions.

[umarcor]

I don't understand why I cannot reply to some of the previous (outdated) comments, but I can reply to some other. Hence, I think that the review and this comment might be a little messy. Hope we can understand each other...

So, do you suggest to put every common vhd file in the same directory?

The structure that we are following is that each new file that is added to the repo, is required for a reason. If two examples use a source which is almost the same except for a line or a few lines, we consider whether it can be shared by adding some parameter. Should doing so involve too much complexity, it is ok to duplicate very similar files.

Even if some examples contain similar or same code, I would not recommend moving them out of the particular example folder to limit the necessity to look around to the minimum (and IMHO it is very important in a documentation project).

Also, in this way the user loses the ability to compile/run a single test, so I discourage this solution. For code examples IMHO it is more important self-containment rather than code reuse.

We need to balance complexity and verbosity. On the one hand, we want intermediate and advanced users to pick any isolated example and run/use it directly. On the other hand, we want unexperienced users which are reading the docs in order (as a tutorial), not to be continuously diffing many files that look similar and which might or might not be the same.

We are currently handling this as subsections (groups of examples). So, in this PR the "atomic unit" is vpi/quickstart. The script that is guaranteed to work alone is vpi/quickstart/run.sh. Then, vpi/quickstart/access/run.sh might exist, and it might be completely independent, but this is not guaranteed. In some cases, you need to call the parent script first. In other cases, the parent script does execute the child explicitly.

[bellaz89]

Hi,

I think that I won't work anymore on this PR. Either because I don't believe that, given the scope of the PR, implementing more changes will lead to any quality improvement, and (more important) because I don't have more time to spend on this. So, take it as it is and do what you want with the PR. You can merge it and do the changes you prefer later, you can reject it or you can make it as a pending PR indefinitely. I am fine with whatever decision you will take.