quickstart/logicvector example (Bounded)

[radonnachie]

umarcor/ghdl/pull/1

This PR adds an example of unconstrained std_(u)logic_vectors. It leans on a selection of needed bits from ghdl.h, as an introduction to that header. I thought this was a good idea because the AccArray example could be documented to show how a bounded logic array (logic vector) can be written from the example's integer array.

Currently crashes, but I left that as is because a patch may be on its way soon (ghdl/ghdl/issues/1224).

---

• Addition of example 'accarray', "Access to array". Actually, I'd further split it into 3 different examples:
  • ...
  • ...
  • A last one to show how to handle logic types. Since most of the signals in HDL designs are directly or indirectly std_logic or std_logic_vector, I believe it deserves a specific example. In fact, there might be multiple ways to handle the representation in C.

[umarcor]

I think that this should also be split in two. I know... at first I thought I would add 2 examples only, and they ended up being 9. In you case, we have 5.

It's ok to show how to pass constrainted std_logic_vectors, instead of std_logic only. However, the introduction to using ghdl.h should be a separate example. So, this example would be split into quickstart/logicvector (this PR) and cinterface/intro (new PR agains header). This is mostly because I expect the example about std_logic_vectors alone to be extended in the future with conversions of the C types, to match other HDL kernels.

[umarcor]

You are fast! See comments below.

[umarcor]

Looks good! Just a couple of minor style issues, the missing addition to the docs, and we are done!

[umarcor]

Please, see comments regarding the content in the docs, and we are done!

[radonnachie]

An important addition was the HINT that explains the mismatch between integer and boolean arguments between the getVectorSize declarations in C and VHDL, respectively.

I feel that the HINT makes it okay to leave the discrepancy in there. Really I wanted the VHDL arguments to be limited to [0, 1] which is why I started with a boolean. But I didnt want to have to include <bool.h> in C to make it match

[umarcor]

I'm copying the plan from #6 (comment) here, for better exposal:

• Quick Start
  • random
  • math
  • customc
  • package (vhpidirect: add 'quickstart/package' #7)
  • sharedvar (quickstart/sharedvar Example (Set Package shared variable) #4)
• Wrapping
  • basic
  • time
• Linking
  • bind
• Shared
  • shlib
  • dlopen
  • shghdl
• Arrays
  • intvector
    • Define from C only (Add packageless intvector examples (#5 a + c) #11)
      • without main
      • with main
    • Define from VHDL only (Add packageless intvector generic example (#5 c) #12)
  • logicvector (quickstart/logicvector example (Bounded) #6)
  • matrices (quickstart/matrices: 2D constrained/bound array of reals/doubles #10)
  • genpkgs (cinterface/accarraygen example (Bounded by Generic Package - VHDL 2008) #5)
• C interface
  • intro (cinterface/intro Example (Header intro) #8)
  • demo (Updated Header: std_u/logic, N Dim unconstrained arrays. #3)

So, #4 is only dependent on #7, and I can work on finishing it.

Then, the chain would be:

• Add packageless intvector examples (#5 a + c) #11 & Add packageless intvector generic example (#5 c) #12 (both merged into Add packageless intvector examples (#5 a + c) #11 first).
• quickstart/logicvector example (Bounded) #6 (this). It's ready. We just need to wait for Add packageless intvector examples (#5 a + c) #11 to be merged first, in order to update references accordingly.
• quickstart/matrices: 2D constrained/bound array of reals/doubles #10, is almost ready too.
• cinterface/accarraygen example (Bounded by Generic Package - VHDL 2008) #5 will need some cleanup after all the previous steps are stabilized.
• cinterface/intro Example (Header intro) #8 and Updated Header: std_u/logic, N Dim unconstrained arrays. #3, we'll see after all the others are done.

I'll finish #12 and merge it into #11 then, High Priority

Great! But not "high priority", just "priority". We do this to learn and have fun! We can finish it today or next year. No hurry at all ;)

Then I need to dive into #10 with a keen eye.

Do not hesitate to ask. To understand what's going on with the VUnit subexample, you might find the following slides useful: https://github.com/umarcor/MSEA/blob/master/doc/2020_03/main.pdf. See the first diagram of slide 23.

Of course, I MUST update those slides as soon as we are done pushing all these "new" examples.

[radonnachie]

Also hosted https://ghdl-cosim.readthedocs.io/en/logicvectors/vhpidirect/examples/arrays.html#logicvector

[umarcor]

See comment about reordering the content in the docs. You can also leave it as is. Change it only if you are going to fix the other minor issues in some rebase.

[umarcor]

Good! To be merged right after #12 #15.