quickstart/sharedvar Example (Set Package shared variable)

[radonnachie]

umarcor/ghdl/pull/1

An example on how to package VHDL functions that are foreign C functions.

I suspect I will learn a better way to use an int access than to .all it.
I think that it may be a little more than what was requested, but isn't too much.

I also hope that I nailed the location for it. 🙋

---

• Addition of example 'accarray', "Access to array". Actually, I'd further split it into 3 different examples:
  • A first one to just show that foreign procedures/functions can be defined in a package. All existing examples now do define them in the arch. The example would be as easy as having a simple C function and using it from two different entities/modules/components.

---

./run.sh
Analyze cAccess.vhd ent1.vhd ent2.vhd tb.vhd
Compile cSharedVar.o
Build tb with cSharedVar.o
Execute tb
tb.vhd:18:5:@0ms:(report note): Testbench setting c_Var to -1.
C-side print of int: -1
ent1.vhd:10:9:@0ms:(report note): Entity1 setting c_Var to 1.
C-side print of int: 1
ent2.vhd:10:9:@0ms:(report note): Entity2 setting c_Var to 2.
C-side print of int: 2

[radonnachie]

I plan on pushing documentation soon-ish

[umarcor]

Please, add new tests to CI. Just ensure that a run.sh exists, and add the subdir/location to https://github.com/umarcor/ghdl-cosim/blob/master/.github/workflows/test.yml#L21-L29

Overall, I think that this example is too complicated because there is a race between both entities to write and read the shared variable and new users might be distracted. The point should be (only) how to declare a foreign resource in a package. Hence, I'd suggest to define printInt(int n) in C and remove getInt_prt and the shared variable from the example.

Actually, you might want to keep this PR as is, and open another simpler one. It makes sense to explain how to use a package in one example, and explain when a shared variable is required in a different example. Then, #5 would be a third step about how to use arrays as shared variables.

From this point of view, I believe that the location of the three examples would be quickstart/package, quickstart/sharedvar and quickstart/accarray.

You can delay writing the corresponding documentation until the examples are written. Specially because we have yet to decide the specific number and content.

[radonnachie]

Please, add new tests to CI.

Was wondering how to do that. Thanks. Will update PRs

[umarcor]

I'd say I had already written this, but I cannot find where: note that you can open all PRs against master in ghdl/ghdl-cosim, which will make them more visible to other users. You do need to open PRs here when you are targeting feature branches which are only available in my fork. I will review the PRs regardless of where you open them. Already said in #9

Regarding the content of this PR, please, see comments below.

[umarcor]

We are almost there... I think you can add the modification to the docs in the next iteration.

[radonnachie]

ugh, sorry you had to go through that. I've enabled rendering of whitespace and found a quick way to assess my files. I'll be more consistent now!

[umarcor]

@RocketRoss, if you are ok, I will take care of finishing this PR, so you can focus on others.

[radonnachie]

Sure thing. I've lost a little steam. Let me try pick up the pace again!

To be honest, when it comes to the documentation, I am now lost on how the references between cosim's docs and ghdl's docs work. I understood being able to reference labels like .. _An_example_label: with :ref:An_example_label, but the directory manner you use escapes me. Is it okay if I just keep adding labels everywhere I want to reference?

[umarcor]

To be honest, when it comes to the documentation, I am now lost on how the references between cosim's docs and ghdl's docs work.

The trick to get that is https://github.com/umarcor/ghdl-cosim/blob/master/doc/conf.py#L130-L133. So, essentially, we can cross-reference as if they where local labels. Should a conflict exist, we can specify which "domain" to use. See http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html. To find the labels to other sections of the main docs, you need to check the rst sources at https://github.com/ghdl/ghdl/tree/master/doc.

I understood being able to reference labels like .. _An_example_label: with :ref:An_example_label, but the directory manner you use escapes me.

I don't understand what you mean with the directory manner.

Is it okay if I just keep adding labels everywhere I want to reference?

Yes. In the worst case, I can let you know if there is any redundancy, while reviewing.

[radonnachie]

Superseded by #13